ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2024-12-18 20:57:53 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[API] Support dynamic telemetry metadata (#1941)

Browse Source 
* [API] Support dynamic telemetry metadata

Add support for dynamic telemetry metadata via custom telemetry
metadata providers.  

The metadata provider API should be considered unstable in it's
current invocation.

* Perform deprecation checking at runtime
* SWG uses telemetry metadata provider
* Don't throw with no matched metadata provider
* Update API docs
* Add license header
* Combine metadata providers with general telemetry providers
* Replace `TelemetryAPI.canProvideTelemetry` with
`TelemetryAPI.isTelemetryObject`.  
* CanProvideTelemetry is deprecated
* Change SWG inputs to numberfield
This commit is contained in:
Pete Richards 2018-03-21 14:18:08 -07:00 committed by Andrew Henry
parent 00fb071fe2
commit 8db75bf41e
19 changed files with 689 additions and 324 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
API.md
View File

@ -1,3 +1,57 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [Building Applications With Open MCT](#building-applications-with-open-mct)
- [Scope and purpose of this document](#scope-and-purpose-of-this-document)
- [Building From Source](#building-from-source)
- [Starting an Open MCT application](#starting-an-open-mct-application)
- [Plugins](#plugins)
- [Defining and Installing a New Plugin](#defining-and-installing-a-new-plugin)
- [Domain Objects and Identifiers](#domain-objects-and-identifiers)
- [Object Attributes](#object-attributes)
- [Domain Object Types](#domain-object-types)
- [Root Objects](#root-objects)
- [Object Providers](#object-providers)
- [Composition Providers](#composition-providers)
- [Adding Composition Providers](#adding-composition-providers)
- [Default Composition Provider](#default-composition-provider)
- [Telemetry API](#telemetry-api)
- [Integrating Telemetry Sources](#integrating-telemetry-sources)
- [Telemetry Metadata](#telemetry-metadata)
- [Values](#values)
- [Value Hints](#value-hints)
- [The Time Conductor and Telemetry](#the-time-conductor-and-telemetry)
- [Telemetry Providers](#telemetry-providers)
- [Telemetry Requests](#telemetry-requests)
- [Request Strategies **draft**](#request-strategies-draft)
- [`latest` request strategy](#latest-request-strategy)
- [`minmax` request strategy](#minmax-request-strategy)
- [Telemetry Formats **draft**](#telemetry-formats-draft)
- [Registering Formats](#registering-formats)
- [Telemetry Data](#telemetry-data)
- [Telemetry Datums](#telemetry-datums)
- [Limit Evaluators **draft**](#limit-evaluators-draft)
- [Telemetry Visualization APIs **draft**](#telemetry-visualization-apis-draft)
- [Time API](#time-api)
- [Time Systems and Bounds](#time-systems-and-bounds)
- [Defining and Registering Time Systems](#defining-and-registering-time-systems)
- [Getting and Setting the Active Time System](#getting-and-setting-the-active-time-system)
- [Time Bounds](#time-bounds)
- [Clocks](#clocks)
- [Defining and registering clocks](#defining-and-registering-clocks)
- [Getting and setting active clock](#getting-and-setting-active-clock)
- [Stopping an active clock](#stopping-an-active-clock)
- [Clock Offsets](#clock-offsets)
- [Time Events](#time-events)
- [List of Time Events](#list-of-time-events)
- [The Time Conductor](#the-time-conductor)
- [Time Conductor Configuration](#time-conductor-configuration)
- [Example conductor configuration](#example-conductor-configuration)
- [Included Plugins](#included-plugins)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Building Applications With Open MCT
## Scope and purpose of this document
@ -154,7 +208,7 @@ registry.
eg.
```javascript
openmct.types.addType('my-type', {
openmct.types.addType('example.my-type', {
name: "My Type",
description: "This is a type that I added!",
creatable: true
@ -162,8 +216,9 @@ openmct.types.addType('my-type', {
```
The `addType` function accepts two arguments:
* A `string` key identifying the type. This key is used when specifying a type
for an object.
* A `string` key identifying the type. This key is used when specifying a type
for an object. We recommend prefixing your types with a namespace to avoid
conflicts with other plugins.
* An object type specification. An object type definition supports the following
attributes
* `name`: a `string` naming this object type
@ -194,7 +249,7 @@ To do so, use the `addRoot` method of the object API.
eg.
```javascript
openmct.objects.addRoot({
namespace: "my-namespace",
namespace: "example.namespace",
key: "my-key"
});
```
@ -235,13 +290,12 @@ It is expected that the `get` function will return a
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
that resolves with the object being requested.
In future, object providers will support other methods to enable other operations
with persistence stores, such as creating, updating, and deleting objects.
In future, object providers will support other methods to enable other operations with persistence stores, such as creating, updating, and deleting objects.
## Composition Providers
The _composition_ of a domain object is the list of objects it contains, as shown
(for example) in the tree for browsing. Open MCT provides a
The _composition_ of a domain object is the list of objects it contains, as
shown (for example) in the tree for browsing. Open MCT provides a
[default solution](#default-composition-provider) for composition, but there
may be cases where you want to provide the composition of a certain object
(or type of object) dynamically.
@ -255,7 +309,7 @@ Composition Provider:
```javascript
openmct.composition.addProvider({
appliesTo: function (domainObject) {
return domainObject.type === 'my-type';
return domainObject.type === 'example.my-type';
},
load: function (domainObject) {
return Promise.resolve(myDomainObjects);
@ -273,8 +327,9 @@ These identifiers will be used to fetch Domain Objects from an [Object Provider]
### Default Composition Provider
The default composition provider applies to any domain object with a `composition`
property. The value of `composition` should be an array of identifiers, e.g.:
The default composition provider applies to any domain object with a
`composition` property. The value of `composition` should be an array of
identifiers, e.g.:
```javascript
var domainObject = {
@ -295,13 +350,17 @@ var domainObject = {
## Telemetry API
The Open MCT telemetry API provides two main sets of interfaces-- one for integrating telemetry data into Open MCT, and another for developing Open MCT visualization plugins utilizing telemetry API.
The Open MCT telemetry API provides two main sets of interfaces-- one for
integrating telemetry data into Open MCT, and another for developing Open MCT
visualization plugins utilizing the telemetry API.
The APIs for visualization plugins are still a work in progress and docs may change at any time. However, the APIs for integrating telemetry metadata into Open MCT are stable and documentation is included below.
The APIs for visualization plugins are still a work in progress and docs may
change at any time. However, the APIs for integrating telemetry metadata into
Open MCT are stable and documentation is included below.
### Integrating Telemetry Sources
There are two main tasks for integrating telemetry sources-- describing telemetry objects with relevant metadata, and then providing telemetry data for those objects. You'll use an [Object Provider](#object-providers) to provide objects with the necessary [Telemetry Metadata](#telemetry-metadata), and then register a [Telemetry Provider](#telemetry-providers) to retrieve telemetry data for those objects.
There are two main tasks for integrating telemetry sources-- describing telemetry objects with relevant metadata, and then providing telemetry data for those objects. You'll use an [Object Provider](#object-providers) to provide objects with the necessary [Telemetry Metadata](#telemetry-metadata), and then register a [Telemetry Provider](#telemetry-providers) to retrieve telemetry data for those objects. Alternatively, you can register a telemetry metadata provider to provide the necessary telemetry metadata.
For a step-by-step guide to building a telemetry adapter, please see the
[Open MCT Tutorials](https://github.com/nasa/openmct-tutorial).
@ -355,7 +414,7 @@ attribute | type | flags | notes
--- | --- | --- | ---
`key` | string | required | unique identifier for this field.
`hints` | object | required | Hints allow views to intelligently select relevant attributes for display, and are required for most views to function. See section on "Value Hints" below.
`name` | string | optional | a human readible label for this field. If omitted, defaults to `key`.
`name` | string | optional | a human readable label for this field. If omitted, defaults to `key`.
`source` | string | optional | identifies the property of a datum where this value is stored. If omitted, defaults to `key`.
`format` | string | optional | a specific format identifier, mapping to a formatter. If omitted, uses a default formatter. For enumerations, use `enum`. For timestamps, use `utc` if you are using utc dates, otherwise use a key mapping to your custom date format.
`units` | string | optional | the units of this value, e.g. `km`, `seconds`, `parsecs`
@ -383,7 +442,7 @@ In order for the time conductor to work, there will always be an active "time sy
#### Telemetry Providers
Telemetry providers are responsible for providing historical and real time telemetry data for telemetry objects. Each telemetry provider determines which objects it can provide telemetry for, and then must implement methods to provide telemetry for those objects.
Telemetry providers are responsible for providing historical and real-time telemetry data for telemetry objects. Each telemetry provider determines which objects it can provide telemetry for, and then must implement methods to provide telemetry for those objects.
A telemetry provider is a javascript object with up to four methods:
@ -391,6 +450,10 @@ A telemetry provider is a javascript object with up to four methods:
* `subscribe(domainObject, callback, options)` required if `supportsSubscribe` is implemented. Establish a subscription for realtime data for the given domain object. Should invoke `callback` with a single telemetry datum every time data is received. Must return an unsubscribe function. Multiple views can subscribe to the same telemetry object, so it should always return a new unsubscribe function.
* `supportsRequest(domainObject, options)` optional. Must be implemented to provide historical telemetry. Should return `true` if the provider supports historical requests for the given domain object.
* `request(domainObject, options)` required if `supportsRequest` is implemented. Must return a promise for an array of telemetry datums that fulfills the request. The `options` argument will include a `start`, `end`, and `domain` attribute representing the query bounds. For more request properties, see Request Properties below.
* `supportsMetadata(domainObject)` optional. Implement and return `true` for objects that you want to provide dynamic metadata for.
* `getMetadata(domainObject)` required if `supportsMetadata` is implemented. Must return a valid telemetry metadata definition that includes at least one valueMetadata definition.
* `supportsLimits(domainObject)` optional. Implement and return `true` for domain objects that you want to provide a limit evaluator for.
* `getLimitEvaluator(domainObject)` required if `supportsLimits` is implemented. Must return a valid LimitEvaluator for a given domain object.
Telemetry providers are registered by calling `openmct.telemetry.addProvider(provider)`, e.g.
@ -398,14 +461,15 @@ Telemetry providers are registered by calling `openmct.telemetry.addProvider(pro
openmct.telemetry.addProvider({
supportsRequest: function (domainObject, options) { /*...*/ },
request: function (domainObject, options) { /*...*/ },
supportsSubscribe: function (domainObject, callback, options) { /*...*/ },
subscribe: function (domainObject, callback, options) { /*...*/ }
})
```
Note: it is not required to implement all of the methods on every provider. Depending on the complexity of your implementation, it may be helpful to instantiate and register your realtime, historical, and metadata providers separately.
#### Telemetry Requests
Telemetry requests support time bounded queries. A call to a _Telemetry Provider_'s `request` function will include an `options` argument. These are simply javascript objects with attributes for the request parameters. An example of a telemetry request object with a start and end time is included below:
```javascript
{
start: 1487981997240,
@ -414,7 +478,54 @@ Telemetry requests support time bounded queries. A call to a _Telemetry Provider
}
```
#### Telemetry Formats
In this case, the `domain` is the currently selected time-system, and the start and end dates are valid dates in that time system.
The response to a telemetry request is an array of telemetry datums.
These datums must be sorted by `domain` in ascending order.
#### Request Strategies **draft**
To improve performance views may request a certain strategy for data reduction. These are intended to improve visualization performance by reducing the amount of data needed to be sent to the client. These strategies will be indicated by additional parameters in the request options. You may choose to handle them or ignore them.
Note: these strategies are currently being tested in core plugins and may change based on developer feedback.
##### `latest` request strategy
This request is a "depth based" strategy. When a view is only capable of
displaying a single value (or perhaps the last ten values), then it can
use the `latest` request strategy with a `size` parameter that specifies
the number of results it desires. The `size` parameter is a hint; views
must not assume the response will have the exact number of results requested.
example:
```javascript
{
start: 1487981997240,
end: 1487982897240,
domain: 'utc',
strategy: 'latest',
size: 1
}
```
This strategy says "I want the lastest data point in this time range". A provider which recognizes this request should return only one value-- the latest-- in the requested time range. Depending on your back-end implementation, performing these queries in bulk can be a large performance increase. These are generally issued by views that are only capable of displaying a single value and only need to show the latest value.
##### `minmax` request strategy
example:
```javascript
{
start: 1487981997240,
end: 1487982897240,
domain: 'utc',
strategy: 'minmax',
size: 720
}
```
MinMax queries are issued by plots, and may be issued by other types as well. The aim is to reduce the amount of data returned but still faithfully represent the full extent of the data. In order to do this, the view calculates the maximum data resolution it can display (i.e. the number of horizontal pixels in a plot) and sends that as the `size`. The response should include at least one minimum and one maximum value per point of resolution.
#### Telemetry Formats **draft**
Telemetry format objects define how to interpret and display telemetry data.
They have a simple structure:
@ -484,6 +595,17 @@ The key-value pairs of this object are described by the telemetry metadata of
a domain object, as discussed in the [Telemetry Metadata](#telemetry-metadata)
section.
#### Limit Evaluators **draft**
Limit evaluators allow a telemetry integrator to define how limits should be
applied to telemetry from a given domain object. For an example of a limit
evaluator, take a look at `examples/generator/SinewaveLimitProvider.js`.
### Telemetry Consumer APIs **draft**
The APIs for requesting telemetry from Open MCT -- e.g. for use in custom views -- are currently in draft state and are being revised. If you'd like to experiement with them before they are finalized, please contact the team via the contact-us link on our website.
## Time API
Open MCT provides API for managing the temporal state of the application.
@ -591,7 +713,7 @@ openmct.time.bounds({start: now - ONE_HOUR, now);
To respond to bounds change events, listen for the [`'bounds'`](#time-events)
event.
## Clocks
### Clocks
The Time API can be set to follow a clock source which will cause the bounds
to be updated automatically whenever the clock source "ticks". A clock is simply
@ -610,7 +732,7 @@ be defined to tick on some remote timing source.
The values provided by clocks are simple `number`s, which are interpreted in the
context of the active [Time System](#defining-and-registering-time-systems).
### Defining and registering clocks
#### Defining and registering clocks
A clock is an object that defines certain required metadata and functions:
@ -724,7 +846,7 @@ __Note:__ Setting the clock offsets will trigger an immediate bounds change, as
new bounds will be calculated based on the `currentValue()` of the active clock.
Clock offsets are only relevant when a clock source is active.
## Time Events
### Time Events
The Time API is a standard event emitter; you can register callbacks for events using the `on` method and remove callbacks for events with the `off` method.
@ -766,7 +888,7 @@ The events emitted by the Time API are:
* `clockOffsets`: The new [clock offsets](#clock-offsets).
## The Time Conductor
### The Time Conductor
The Time Conductor provides a user interface for managing time bounds in Open
MCT. It allows a user to select from configured time systems and clocks, and to set bounds and clock offsets.

108
example/generator/GeneratorMetadataProvider.js Normal file
View File

@ -0,0 +1,108 @@
define([
'lodash'
], function (
_
) {
var METADATA_BY_TYPE = {
'generator': {
values: [
{
key: "name",
name: "Name"
},
{
key: "utc",
name: "Time",
format: "utc",
hints: {
domain: 1
}
},
{
key: "yesterday",
name: "Yesterday",
format: "utc",
hints: {
domain: 2
}
},
{
key: "sin",
name: "Sine",
hints: {
range: 1
}
},
{
key: "cos",
name: "Cosine",
hints: {
range: 2
}
}
]
},
'example.state-generator': {
values: [
{
key: "name",
name: "Name"
},
{
key: "utc",
name: "Time",
format: "utc",
hints: {
domain: 1
}
},
{
key: "state",
source: "value",
name: "State",
format: "enum",
enumerations: [
{
value: 0,
string: "OFF"
},
{
value: 1,
string: "ON"
}
],
hints: {
range: 1
}
},
{
key: "value",
name: "Value",
hints: {
range: 2
}
}
]
}
}
function GeneratorMetadataProvider() {
}
GeneratorMetadataProvider.prototype.supportsMetadata = function (domainObject) {
return METADATA_BY_TYPE.hasOwnProperty(domainObject.type);
};
GeneratorMetadataProvider.prototype.getMetadata = function (domainObject) {
return _.extend(
{},
domainObject.telemetry,
METADATA_BY_TYPE[domainObject.type]
);
};
return GeneratorMetadataProvider;
});

87
example/generator/SinewaveLimitCapability.js
View File

@ -1,87 +0,0 @@
/*****************************************************************************
* Open MCT, Copyright (c) 2014-2017, United States Government
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open MCT is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
* Open MCT includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
/*global define*/
define(
[],
function () {
"use strict";
var RED = 0.9,
YELLOW = 0.5,
LIMITS = {
rh: {
cssClass: "s-limit-upr s-limit-red",
low: RED,
high: Number.POSITIVE_INFINITY,
name: "Red High"
},
rl: {
cssClass: "s-limit-lwr s-limit-red",
high: -RED,
low: Number.NEGATIVE_INFINITY,
name: "Red Low"
},
yh: {
cssClass: "s-limit-upr s-limit-yellow",
low: YELLOW,
high: RED,
name: "Yellow High"
},
yl: {
cssClass: "s-limit-lwr s-limit-yellow",
low: -RED,
high: -YELLOW,
name: "Yellow Low"
}
};
function SinewaveLimitCapability(domainObject) {
return {
limits: function (range) {
return LIMITS;
},
evaluate: function (datum, range) {
range = range || 'sin';
if (datum[range] > RED) {
return LIMITS.rh;
}
if (datum[range] < -RED) {
return LIMITS.rl;
}
if (datum[range] > YELLOW) {
return LIMITS.yh;
}
if (datum[range] < -YELLOW) {
return LIMITS.yl;
}
}
};
}
SinewaveLimitCapability.appliesTo = function (model) {
return model.type === 'generator';
};
return SinewaveLimitCapability;
}
);

88
example/generator/SinewaveLimitProvider.js Normal file
View File

@ -0,0 +1,88 @@
/*****************************************************************************
* Open MCT, Copyright (c) 2014-2017, United States Government
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open MCT is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
* Open MCT includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
/*global define*/
define([
], function (
) {
var RED = 0.9,
YELLOW = 0.5,
LIMITS = {
rh: {
cssClass: "s-limit-upr s-limit-red",
low: RED,
high: Number.POSITIVE_INFINITY,
name: "Red High"
},
rl: {
cssClass: "s-limit-lwr s-limit-red",
high: -RED,
low: Number.NEGATIVE_INFINITY,
name: "Red Low"
},
yh: {
cssClass: "s-limit-upr s-limit-yellow",
low: YELLOW,
high: RED,
name: "Yellow High"
},
yl: {
cssClass: "s-limit-lwr s-limit-yellow",
low: -RED,
high: -YELLOW,
name: "Yellow Low"
}
};
function SinewaveLimitProvider() {
}
SinewaveLimitProvider.prototype.supportsLimits = function (domainObject) {
return domainObject.type === 'generator';
};
SinewaveLimitProvider.prototype.getLimitEvaluator = function (domainObject) {
return {
evaluate: function (datum, valueMetadata) {
var range = valueMetadata ? valueMetadata.key : 'sin'
if (datum[range] > RED) {
return LIMITS.rh;
}
if (datum[range] < -RED) {
return LIMITS.rl;
}
if (datum[range] > YELLOW) {
return LIMITS.yh;
}
if (datum[range] < -YELLOW) {
return LIMITS.yl;
}
}
};
};
return SinewaveLimitProvider;
});

133
example/generator/plugin.js
View File

@ -23,31 +23,17 @@
define([
"./GeneratorProvider",
"./SinewaveLimitCapability",
"./StateGeneratorProvider"
"./SinewaveLimitProvider",
"./StateGeneratorProvider",
"./GeneratorMetadataProvider"
], function (
GeneratorProvider,
SinewaveLimitCapability,
StateGeneratorProvider
SinewaveLimitProvider,
StateGeneratorProvider,
GeneratorMetadataProvider
) {
var legacyExtensions = {
"capabilities": [
{
"key": "limit",
"implementation": SinewaveLimitCapability
}
]
};
return function(openmct){
//Register legacy extensions for things not yet supported by the new API
Object.keys(legacyExtensions).forEach(function (type){
var extensionsOfType = legacyExtensions[type];
extensionsOfType.forEach(function (extension) {
openmct.legacyExtension(type, extension)
})
});
openmct.types.addType("example.state-generator", {
name: "State Generator",
@ -70,47 +56,7 @@ define([
],
initialize: function (object) {
object.telemetry = {
duration: 5,
values: [
{
key: "name",
name: "Name"
},
{
key: "utc",
name: "Time",
format: "utc",
hints: {
domain: 1
}
},
{
key: "state",
source: "value",
name: "State",
format: "enum",
enumerations: [
{
value: 0,
string: "OFF"
},
{
value: 1,
string: "ON"
}
],
hints: {
range: 1
}
},
{
key: "value",
name: "Value",
hints: {
range: 2
}
}
]
duration: 5
}
}
});
@ -125,63 +71,58 @@ define([
form: [
{
name: "Period",
control: "textfield",
control: "numberfield",
cssClass: "l-input-sm l-numeric",
key: "period",
required: true,
property: [
"telemetry",
"period"
],
pattern: "^\\d*(\\.\\d*)?$"
]
},
{
name: "Amplitude",
control: "textfield",
control: "numberfield",
cssClass: "l-input-sm l-numeric",
key: "amplitude",
required: true,
property: [
"telemetry",
"amplitude"
],
pattern: "^\\d*(\\.\\d*)?$"
]
},
{
name: "Offset",
control: "textfield",
control: "numberfield",
cssClass: "l-input-sm l-numeric",
key: "offset",
required: true,
property: [
"telemetry",
"offset"
],
pattern: "^\\d*(\\.\\d*)?$"
]
},
{
name: "Data Rate (hz)",
control: "textfield",
control: "numberfield",
cssClass: "l-input-sm l-numeric",
key: "dataRateInHz",
required: true,
property: [
"telemetry",
"dataRateInHz"
],
pattern: "^\\d*(\\.\\d*)?$"
]
},
{
name: "Phase (radians)",
control: "textfield",
control: "numberfield",
cssClass: "l-input-sm l-numeric",
key: "phase",
required: true,
property: [
"telemetry",
"phase"
],
pattern: "^\\d*(\\.\\d*)?$"
]
}
],
initialize: function (object) {
@ -190,48 +131,14 @@ define([
amplitude: 1,
offset: 0,
dataRateInHz: 1,
phase: 0,
values: [
{
key: "name",
name: "Name"
},
{
key: "utc",
name: "Time",
format: "utc",
hints: {
domain: 1
}
},
{
key: "yesterday",
name: "Yesterday",
format: "utc",
hints: {
domain: 2
}
},
{
key: "sin",
name: "Sine",
hints: {
range: 1
}
},
{
key: "cos",
name: "Cosine",
hints: {
range: 2
}
}
]
phase: 0
};
}
});
openmct.telemetry.addProvider(new GeneratorProvider());
openmct.telemetry.addProvider(new GeneratorMetadataProvider());
openmct.telemetry.addProvider(new SinewaveLimitProvider());
};
});

2
platform/features/layout/src/FixedController.js
View File

@ -464,7 +464,7 @@ define(
function filterForTelemetryObjects(objects) {
return objects.filter(function (object) {
return self.openmct.telemetry.canProvideTelemetry(object);
return self.openmct.telemetry.isTelemetryObject(object);
});
}

4
platform/features/layout/test/FixedControllerSpec.js
View File

@ -150,13 +150,13 @@ define(
[
'subscribe',
'request',
'canProvideTelemetry',
'isTelemetryObject',
'getMetadata',
'limitEvaluator',
'getValueFormatter'
]
);
mockTelemetryAPI.canProvideTelemetry.andReturn(true);
mockTelemetryAPI.isTelemetryObject.andReturn(true);
mockTelemetryAPI.request.andReturn(Promise.resolve([]));
testGrid = [123, 456];

4
platform/features/table/src/controllers/TelemetryTableController.js
View File

@ -399,14 +399,14 @@ define(
var compositionApi = this.openmct.composition;
function filterForTelemetry(objects) {
return objects.filter(telemetryApi.canProvideTelemetry.bind(telemetryApi));
return objects.filter(telemetryApi.isTelemetryObject.bind(telemetryApi));
}
/*
* If parent object is a telemetry object, subscribe to it. Do not
* test composees.
*/
if (telemetryApi.canProvideTelemetry(this.domainObject)) {
if (telemetryApi.isTelemetryObject(this.domainObject)) {
return Promise.resolve([this.domainObject]);
} else {
/*

8
platform/features/table/test/controllers/TelemetryTableControllerSpec.js
View File

@ -91,7 +91,7 @@ define(
mockScope.domainObject = mockDomainObject;
mockTelemetryAPI = jasmine.createSpyObj("telemetryAPI", [
"canProvideTelemetry",
"isTelemetryObject",
"subscribe",
"getMetadata",
"commonValuesForHints",
@ -117,7 +117,7 @@ define(
return formatter;
});
mockTelemetryAPI.canProvideTelemetry.andReturn(false);
mockTelemetryAPI.isTelemetryObject.andReturn(false);
mockTimeout = jasmine.createSpy("timeout");
mockTimeout.andReturn(1); // Return something
@ -199,7 +199,7 @@ define(
mockComposition.load.andReturn(Promise.resolve(mockChildren));
mockCompositionAPI.get.andReturn(mockComposition);
mockTelemetryAPI.canProvideTelemetry.andCallFake(function (obj) {
mockTelemetryAPI.isTelemetryObject.andCallFake(function (obj) {
return obj.identifier.key === mockTelemetryObject.identifier.key;
});
@ -287,7 +287,7 @@ define(
mockChildren = mockChildren.concat(mockTelemetryChildren);
mockComposition.load.andReturn(Promise.resolve(mockChildren));
mockTelemetryAPI.canProvideTelemetry.andCallFake(function (object) {
mockTelemetryAPI.isTelemetryObject.andCallFake(function (object) {
if (object === mockTelemetryObject) {
return false;
} else {

10
src/adapter/bundle.js
View File

@ -31,7 +31,8 @@ define([
'./policies/AdapterCompositionPolicy',
'./policies/AdaptedViewPolicy',
'./runs/AlternateCompositionInitializer',
'./runs/TimeSettingsURLHandler'
'./runs/TimeSettingsURLHandler',
'./runs/TypeDeprecationChecker'
], function (
legacyRegistry,
ActionDialogDecorator,
@ -43,7 +44,8 @@ define([
AdapterCompositionPolicy,
AdaptedViewPolicy,
AlternateCompositionInitializer,
TimeSettingsURLHandler
TimeSettingsURLHandler,
TypeDeprecationChecker
) {
legacyRegistry.register('src/adapter', {
"extensions": {
@ -107,6 +109,10 @@ define([
}
],
runs: [
{
implementation: TypeDeprecationChecker,
depends: ["types[]"]
},
{
implementation: AlternateCompositionInitializer,
depends: ["openmct"]

47
src/adapter/runs/TypeDeprecationChecker.js Normal file
View File

@ -0,0 +1,47 @@
/*****************************************************************************
* Open openmct, Copyright (c) 2014-2018, United States Government
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open openmct is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
* Open openmct includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
/* global console */
define([
], function (
) {
function checkForDeprecatedFunctionality(typeDef) {
if (typeDef.hasOwnProperty('telemetry')) {
console.warn(
'DEPRECATION WARNING: Telemetry data on type ' +
'registrations will be deprecated in a future version, ' +
'please convert to a custom telemetry metadata provider ' +
'for type: ' + typeDef.key
);
}
}
function TypeDeprecationChecker(types) {
types.forEach(checkForDeprecatedFunctionality);
}
return TypeDeprecationChecker;
});

128
src/api/telemetry/DefaultMetadataProvider.js Normal file
View File

@ -0,0 +1,128 @@
/*****************************************************************************
* Open openmct, Copyright (c) 2014-2018, United States Government
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open openmct is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
* Open openmct includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
define([
'lodash'
], function (
_
) {
/**
* This is the default metadata provider; for any object with a "telemetry"
* property, this provider will return the value of that property as the
* telemetry metadata.
*
* This provider also implements legacy support for telemetry metadata
* defined on the type. Telemetry metadata definitions on type will be
* depreciated in the future.
*/
function DefaultMetadataProvider(openmct) {
this.openmct = openmct;
}
/**
* Applies to any domain object with a telemetry property, or whose type
* definition has a telemetry property.
*/
DefaultMetadataProvider.prototype.supportsMetadata = function (domainObject) {
return !!domainObject.telemetry || !!this.typeHasTelemetry(domainObject);
};
/**
* Retrieves valueMetadata from legacy metadata.
* @private
*/
function valueMetadatasFromOldFormat(metadata) {
var valueMetadatas = [];
valueMetadatas.push({
key: 'name',
name: 'Name'
});
metadata.domains.forEach(function (domain, index) {
var valueMetadata = _.clone(domain);
valueMetadata.hints = {
domain: index + 1
};
valueMetadatas.push(valueMetadata);
});
metadata.ranges.forEach(function (range, index) {
var valueMetadata = _.clone(range);
valueMetadata.hints = {
range: index,
priority: index + metadata.domains.length + 1
};
if (valueMetadata.type === 'enum') {
valueMetadata.key = 'enum';
valueMetadata.hints.y -= 10;
valueMetadata.hints.range -= 10;
valueMetadata.enumerations =
_.sortBy(valueMetadata.enumerations.map(function (e) {
return {
string: e.string,
value: +e.value
};
}), 'e.value');
valueMetadata.values = _.pluck(valueMetadata.enumerations, 'value');
valueMetadata.max = _.max(valueMetadata.values);
valueMetadata.min = _.min(valueMetadata.values);
}
valueMetadatas.push(valueMetadata);
});
return valueMetadatas;
}
/**
* Returns telemetry metadata for a given domain object.
*/
DefaultMetadataProvider.prototype.getMetadata = function (domainObject) {
var metadata = domainObject.telemetry || {};
if (this.typeHasTelemetry(domainObject)) {
var typeMetadata = this.typeService.getType(domainObject.type).typeDef.telemetry;
_.extend(metadata, typeMetadata);
if (!metadata.values) {
metadata.values = valueMetadatasFromOldFormat(metadata);
}
}
return metadata;
};
/**
* @private
*/
DefaultMetadataProvider.prototype.typeHasTelemetry = function (domainObject) {
if (!this.typeService) {
this.typeService = this.openmct.$injector.get('typeService');
}
return !!this.typeService.getType(domainObject.type).typeDef.telemetry;
};
return DefaultMetadataProvider;
});

20
src/api/telemetry/LegacyTelemetryProvider.js
View File

@ -141,17 +141,20 @@ define([
return capability.subscribe(callbackWrapper, request);
};
LegacyTelemetryProvider.prototype.limitEvaluator = function (domainObject) {
LegacyTelemetryProvider.prototype.supportsLimits = function (domainObject) {
var oldObject = this.instantiate(
utils.toOldFormat(domainObject),
utils.makeKeyString(domainObject.identifier));
var limitEvaluator = oldObject.getCapability("limit");
utils.makeKeyString(domainObject.identifier)
);
return oldObject.hasCapability("limit");
};
if (!limitEvaluator) {
return {
evaluate: function () {}
};
}
LegacyTelemetryProvider.prototype.getLimitEvaluator = function (domainObject) {
var oldObject = this.instantiate(
utils.toOldFormat(domainObject),
utils.makeKeyString(domainObject.identifier)
);
var limitEvaluator = oldObject.getCapability("limit");
return {
evaluate: function (datum, property) {
@ -166,6 +169,7 @@ define([
openmct.telemetry.legacyProvider = provider;
openmct.telemetry.requestProviders.push(provider);
openmct.telemetry.subscriptionProviders.push(provider);
openmct.telemetry.limitProviders.push(provider);
};
});

109
src/api/telemetry/TelemetryAPI.js
View File

@ -3,7 +3,7 @@
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open MCT is licensed under the Apache License, Version 2.0 (the
* Open openmct is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
@ -14,20 +14,22 @@
* License for the specific language governing permissions and limitations
* under the License.
*
* Open MCT includes source code licensed under additional open source
* Open openmct includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
/*global console*/
define([
'./TelemetryMetadataManager',
'./TelemetryValueFormatter',
'./DefaultMetadataProvider',
'../objects/object-utils',
'lodash'
], function (
TelemetryMetadataManager,
TelemetryValueFormatter,
DefaultMetadataProvider,
objectUtils,
_
) {
@ -122,7 +124,6 @@ define([
*/
/**
* An interface for retrieving telemetry data associated with a domain
* object.
@ -131,15 +132,29 @@ define([
* @augments module:openmct.TelemetryAPI~TelemetryProvider
* @memberof module:openmct
*/
function TelemetryAPI(MCT) {
this.MCT = MCT;
function TelemetryAPI(openmct) {
this.openmct = openmct;
this.requestProviders = [];
this.subscriptionProviders = [];
this.metadataProviders = [new DefaultMetadataProvider(this.openmct)];
this.limitProviders = [];
this.metadataCache = new WeakMap();
this.formatMapCache = new WeakMap();
this.valueFormatterCache = new WeakMap();
}
/**
* Return true if the given domainObject is a telemetry object. A telemetry
* object is any object which has telemetry metadata-- regardless of whether
* the telemetry object has an available telemetry provider.
*
* @param {module:openmct.DomainObject} domainObject
* @returns {boolean} true if the object is a telemetry object.
*/
TelemetryAPI.prototype.isTelemetryObject = function (domainObject) {
return !!this.findMetadataProvider(domainObject);
};
/**
* Check if this provider can supply telemetry data associated with
* this domain object.
@ -151,6 +166,11 @@ define([
* @memberof module:openmct.TelemetryAPI~TelemetryProvider#
*/
TelemetryAPI.prototype.canProvideTelemetry = function (domainObject) {
console.warn(
'DEPRECATION WARNING: openmct.telemetry.canProvideTelemetry ' +
'will not be supported in future versions of Open MCT. Please ' +
'use openmct.telemetry.isTelemetryObject instead.'
);
return !!this.findSubscriptionProvider(domainObject) ||
!!this.findRequestProvider(domainObject);
};
@ -170,6 +190,12 @@ define([
if (provider.supportsSubscribe) {
this.subscriptionProviders.unshift(provider);
}
if (provider.supportsMetadata) {
this.metadataProviders.unshift(provider);
}
if (provider.supportsLimits) {
this.limitProviders.unshift(provider);
}
};
/**
@ -196,18 +222,36 @@ define([
return this.requestProviders.filter(supportsDomainObject)[0];
};
/**
* @private
*/
TelemetryAPI.prototype.findMetadataProvider = function (domainObject) {
return this.metadataProviders.filter(function (p) {
return p.supportsMetadata(domainObject);
})[0];
};
/**
* @private
*/
TelemetryAPI.prototype.findLimitEvaluator = function (domainObject) {
return this.limitProviders.filter(function (p) {
return p.supportsLimits(domainObject);
})[0];
};
/**
* @private
*/
TelemetryAPI.prototype.standardizeRequestOptions = function (options) {
if (!options.hasOwnProperty('start')) {
options.start = this.MCT.time.bounds().start;
options.start = this.openmct.time.bounds().start;
}
if (!options.hasOwnProperty('end')) {
options.end = this.MCT.time.bounds().end;
options.end = this.openmct.time.bounds().end;
}
if (!options.hasOwnProperty('domain')) {
options.domain = this.MCT.time.timeSystem().key;
options.domain = this.openmct.time.timeSystem().key;
}
};
@ -300,12 +344,15 @@ define([
*/
TelemetryAPI.prototype.getMetadata = function (domainObject) {
if (!this.metadataCache.has(domainObject)) {
if (!this.typeService) {
this.typeService = this.MCT.$injector.get('typeService');
var metadataProvider = this.findMetadataProvider(domainObject);
if (!metadataProvider) {
return;
}
var metadata = metadataProvider.getMetadata(domainObject);
this.metadataCache.set(
domainObject,
new TelemetryMetadataManager(domainObject, this.typeService)
new TelemetryMetadataManager(metadata)
);
}
return this.metadataCache.get(domainObject);
@ -343,7 +390,7 @@ define([
TelemetryAPI.prototype.getValueFormatter = function (valueMetadata) {
if (!this.valueFormatterCache.has(valueMetadata)) {
if (!this.formatService) {
this.formatService = this.MCT.$injector.get('formatService');
this.formatService = this.openmct.$injector.get('formatService');
}
this.valueFormatterCache.set(
valueMetadata,
@ -375,7 +422,7 @@ define([
* @param {Format} format the
*/
TelemetryAPI.prototype.addFormat = function (format) {
this.MCT.legacyExtension('formats', {
this.openmct.legacyExtension('formats', {
key: format.key,
implementation: function () {
return format;
@ -385,7 +432,9 @@ define([
/**
* Get a limit evaluator for this domain object.
* Limit Evaluators help you evaluate limit and alarm status of individual telemetry datums for display purposes without having to interact directly with the Limit API.
* Limit Evaluators help you evaluate limit and alarm status of individual
* telemetry datums for display purposes without having to interact directly
* with the Limit API.
*
* This method is optional.
* If a provider does not implement this method, it is presumed
@ -397,8 +446,34 @@ define([
* @method limitEvaluator
* @memberof module:openmct.TelemetryAPI~TelemetryProvider#
*/
TelemetryAPI.prototype.limitEvaluator = function () {
return this.legacyProvider.limitEvaluator.apply(this.legacyProvider, arguments);
TelemetryAPI.prototype.limitEvaluator = function (domainObject) {
return this.getLimitEvaluator(domainObject);
};
/**
* Get a limit evaluator for this domain object.
* Limit Evaluators help you evaluate limit and alarm status of individual
* telemetry datums for display purposes without having to interact directly
* with the Limit API.
*
* This method is optional.
* If a provider does not implement this method, it is presumed
* that no limits are defined for this domain object's telemetry.
*
* @param {module:openmct.DomainObject} domainObject the domain
* object for which to evaluate limits
* @returns {module:openmct.TelemetryAPI~LimitEvaluator}
* @method limitEvaluator
* @memberof module:openmct.TelemetryAPI~TelemetryProvider#
*/
TelemetryAPI.prototype.getLimitEvaluator = function (domainObject) {
var provider = this.findLimitEvaluator(domainObject);
if (!provider) {
return {
evaluate: function () {}
};
}
return provider.getLimitEvaluator(domainObject);
};
return TelemetryAPI;

22
src/api/telemetry/TelemetryAPISpec.js
View File

@ -1,3 +1,25 @@
/*****************************************************************************
* Open MCT, Copyright (c) 2014-2018, United States Government
* as represented by the Administrator of the National Aeronautics and Space
* Administration. All rights reserved.
*
* Open MCT is licensed under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0.
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
* Open MCT includes source code licensed under additional open source
* licenses. See the Open Source Licenses file (LICENSES.md) included with
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
define([
'./TelemetryAPI'
], function (

67
src/api/telemetry/TelemetryMetadataManager.js
View File

@ -27,51 +27,6 @@ define([
_
) {
function valueMetadatasFromOldFormat(metadata) {
var valueMetadatas = [];
valueMetadatas.push({
key: 'name',
name: 'Name'
});
metadata.domains.forEach(function (domain, index) {
var valueMetadata = _.clone(domain);
valueMetadata.hints = {
domain: index + 1
};
valueMetadatas.push(valueMetadata);
});
metadata.ranges.forEach(function (range, index) {
var valueMetadata = _.clone(range);
valueMetadata.hints = {
range: index,
priority: index + metadata.domains.length + 1
};
if (valueMetadata.type === 'enum') {
valueMetadata.key = 'enum';
valueMetadata.hints.y -= 10;
valueMetadata.hints.range -= 10;
valueMetadata.enumerations =
_.sortBy(valueMetadata.enumerations.map(function (e) {
return {
string: e.string,
value: +e.value
};
}), 'e.value');
valueMetadata.values = _.pluck(valueMetadata.enumerations, 'value');
valueMetadata.max = _.max(valueMetadata.values);
valueMetadata.min = _.min(valueMetadata.values);
}
valueMetadatas.push(valueMetadata);
});
return valueMetadatas;
}
function applyReasonableDefaults(valueMetadata, index) {
valueMetadata.source = valueMetadata.source || valueMetadata.key;
valueMetadata.hints = valueMetadata.hints || {};
@ -119,24 +74,14 @@ define([
}
/**
* Utility class for handling telemetry metadata for a domain object.
* Wraps old format metadata to new format metadata.
* Provides methods for interrogating telemetry metadata.
* Utility class for handling and inspecting telemetry metadata. Applies
* reasonable defaults to simplify the task of providing metadata, while
* also providing methods for interrogating telemetry metadata.
*/
function TelemetryMetadataManager(domainObject, typeService) {
this.metadata = domainObject.telemetry || {};
function TelemetryMetadataManager(metadata) {
this.metadata = metadata;
if (this.metadata.values) {
this.valueMetadatas = this.metadata.values;
} else {
var typeMetadata = typeService
.getType(domainObject.type).typeDef.telemetry;
_.extend(this.metadata, typeMetadata);
this.valueMetadatas = valueMetadatasFromOldFormat(this.metadata);
}
this.valueMetadatas = this.valueMetadatas.map(applyReasonableDefaults);
this.valueMetadatas = this.metadata.values.map(applyReasonableDefaults);
}
/**

2
src/plugins/summaryWidget/SummaryWidgetsCompositionPolicy.js
View File

@ -32,7 +32,7 @@ define(
var parentType = parent.getCapability('type');
var newStyleChild = child.useCapability('adapter');
if (parentType.instanceOf('summary-widget') && !this.openmct.telemetry.canProvideTelemetry(newStyleChild)) {
if (parentType.instanceOf('summary-widget') && !this.openmct.telemetry.isTelemetryObject(newStyleChild)) {
return false;
}

2
src/plugins/summaryWidget/src/ConditionManager.js
View File

@ -191,7 +191,7 @@ define ([
telemetryMetadata,
self = this;
if (telemetryAPI.canProvideTelemetry(obj)) {
if (telemetryAPI.isTelemetryObject(obj)) {
self.compositionObjs[objId] = obj;
self.telemetryMetadataById[objId] = {};

4
src/plugins/summaryWidget/test/ConditionManagerSpec.js
View File

@ -178,7 +178,7 @@ define(['../src/ConditionManager'], function (ConditionManager) {
mockTelemetryAPI = jasmine.createSpyObj('telemetryAPI', [
'request',
'canProvideTelemetry',
'isTelemetryObject',
'getMetadata',
'subscribe',
'triggerTelemetryCallback'
@ -188,7 +188,7 @@ define(['../src/ConditionManager'], function (ConditionManager) {
resolve(mockTelemetryValues[obj.identifer.key]);
});
});
mockTelemetryAPI.canProvideTelemetry.andReturn(true);
mockTelemetryAPI.isTelemetryObject.andReturn(true);
mockTelemetryAPI.getMetadata.andCallFake(function (obj) {
return mockMetadataManagers[obj.identifier.key];
});