Skip to main content
Version: v5.2

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": ""
}
PropertyTypeDescriptionRequired
_nameStringName your telemetry configuration in long form with a maximum of 100 characters.Required
_userTypeStringEnter a new or shared custom type with a maximum of 100 characters.Required
_configDataObjectPass an object with your config data.Required
   - ._bindingsArray of ObjectPass an array that contains your bindings query objects. Pass an empty array or omit the property to look up all collections.Required
     - .collectionDescObjectPass an object that contains a key-value pair to target a named telemetry collection.Required
     - .queryObjectPass an object that contains a key-value pair to target the telemetry items you want to look up.Required
   - ._normalizationScriptObjectPass 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
_namespacesArray of StringEnter the namespace that you want to own the telemetry configuration.Required
_shortNameStringGive your telemetry configuration an abbreviated name with a maximum of 22 characters.Required
_descriptionStringEnter a description for the telemetry configurationRequired

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: