Telemetry config
A telemetry configuration defines the following criteria:
- The bindings between namedTelemetryCollections, telemetry items, and the IoT data. When a telemetry config updates, the bindings update.
- Criteria to lookup the normalization script that normalizes the raw IoT data
A telemetry config is owned by a namespace and you can only have one telemetry config per namespace.
Telemetry config schema#
When you define your telemetry config, refer to the following data structure with reference to the following table:
{ "_name": "", "_userType": "", "_configData": { "_bindings": [ { "collectionDesc": { "<property>": "<value>" }, "query": { "<property>": "<value>" } } ], "_normalizationScript":{ "<property>": "<value>" } }, "_namespaces": [ "" ], "_shortName": "", "_description": ""}| Property | Type | Description | Required |
|---|---|---|---|
_name | String | Name your telemetry configuration in long form with a maximum of 100 characters. | Required |
_userType | String | Enter a new or shared custom type with a maximum of 100 characters. | Required |
_configData | Object | Pass an object with your config data. | Required |
- ._bindings | Array of Object | Pass an array that contains your bindings query objects. Pass an empty array or omit the property to look up all collections. | Required |
- .collectionDesc | Object | Pass an object that contains a key-value pair to target a named telemetry collection. | Required |
- .query | Object | Pass an object that contains a key-value pair to target the telemetry items you want to look up. | Required |
- ._normalizationScript | Object | Pass an object that contains a key-value pair to target your normalization script. If there is more than one match, the latest version returns. | Required |
_namespaces | Array of String | Enter the namespace that you want to own the telemetry configuration. | Required |
_shortName | String | Give your telemetry configuration an abbreviated name with a maximum of 22 characters. | Required |
_description | String | Enter a description for the telemetry configuration | Required |
Example#
{ "_name": "Telemetry Config - 1", "_userType": "telemetry_config", "_configData": { "_bindings": [ { "collectionDesc": { "_userType": "air_quality_sensors" }, "query": { "building-unit": "lab" } }, { "collectionDesc": { "_userType": "temperature-sensors" }, "query": { "floor": "floor-3" } } ], "_normalizationScript": { "_userType": "telemetry_parser_script" } }, "_namespaces": [ "automation_3E4tpXPu" ], "_shortName": "telconfig", "_description": "Telemetry Config for project A"}During TelemetryConfig creation:#
- Telemetry items are identified using the query defined in the bindings.
- Bindings are created using the telemetry ID, source ID (a unique identifier for the sensor), namespace, and the telemetry collection. These bindings are cached by source ID and namespace.
When a message arrives at the Telemetry Worker:#
- A normalization script is invoked with the raw message (assumed the raw message would have device id)
- The script transforms the raw message into a Readings object (from the Item service), which includes the source ID.
- The system retrieves bindings using the source ID and namespace.
- It then identifies the corresponding telemetry collection and routes the readings accordingly.
APIs#
To post a telemetry config object to the item service, use Create Telemetry Config API.
To get, update, and delete telemetry configs on the platform, use the following APIs: