Telemetry

One of the major functionalities of Ability-enabled devices is sending data to the cloud. This way, all the measurements/events, etc. that you device produces may be provided to the end-users via some web interface.

To publish telemetry messages to the cloud, your module needs to send values via the {topics_messages_out}/type={telemetry type} topic. {telemetry type} may be one of the following: timeSeries, alarm, event. If the type is not set, it defaults to timeSeries. Sections below will present the format of the payloads that should be used.

Payloads

Setting the correct {telemetry type} in the topic name is one part of the specification. The other one is to have the correct payload. Note that telemetry messages may be sent in batches. Use that functionality whenever you can to limit the amount of messages (and bytes) sent to the cloud.

Make sure that the payload you're sending conforms to your type definition's dataTypes. Read more about it here.

timeSeries

Use it to send telemetry data associated with one or more variables. Variable with this name must be defined in the corresponding type, and the value must comply with the data type definition. Mandatory: objectId, model, timestamp (time in ISO 8601 standard), value, variable and optional: quality.

A module can send a single data point on behalf of a single device:

{
    "objectId": "2e57962f-2b6c-43c0-8fd8-c0d50d140011",
    "model": "abb.ability.custom.model",
    "timestamp": "2017-11-08T15:12:19.473Z",
    "value": 1.5,
    "variable": "CabinetState.SafetyChain.ES2",
    "quality": 1
}

or an array of data points on behalf of one ore more devices:

[
  {
    "objectId": "2e57962f-2b6c-43c0-8fd8-c0d50d140011",
    "model": "abb.ability.device",
    "timestamp": "2017-11-08T15:12:19.473Z",
    "value": "1.0",
    "variable": "CabinetState.SafetyChain.ES2",
    "quality": 1
 },
 {
    "objectId": "2e57962f-2b6c-43c0-8fd8-c0d50d140888",
    "model": "abb.ability.device",
    "timestamp": "2017-11-09T18:12:12.473Z",
    "value": "23",
    "variable": "CabinetState.Temperature1",
    "quality": 2
 }
]

alarm

Use it to send telemetry data associated with one or more alarms. Value must conform to a payload definition of the alarm in the corresponding type. Mandatory: objectId, model, alarm, timestamp (time in ISO 8601 standard), value and optional quality.

{
  "objectId": "c0b4336b-fa23-4a7f-b92b-d971d8b041cd",
  "model": "abb.ability.device",
  "alarm": "motorTempHigh",
  "alarmKey": "alarms.variables.mainComputer.fans.right",
  "timestamp": "2017-11-09T12:34:23.020Z",
  "value": {
     ...
  },
  "quality": 1
}

event

Use it to send telemetry data associated with one or more events. Value must conform to a payload definition of the event in the corresponding type. Mandatory: objectId, model, event, timestamp (time in ISO 8601 standard), value and optional quality.

{
  "objectId": "c0b4336b-fa23-4a7f-b92b-d971d8b041cd",
  "model": "abb.ability.device",
  "timestamp": "2017-11-09T12:34:23.020Z",
  "event": "171900",
  "value": {
     ...
  },
  "quality": 1
}

Whenever you're sending some data, make sure that it conforms to the dataType that you have specified in your type definition. Otherwise, the message will be rejected.

Example

Let's assume that we have the following type definition:

{
  "typeId": "abb.physicalSensor.device",
  "model": "abb.ability.device",
  "version": "1.0.0",
  "unique": [
    "serialNumber"
  ],
  "properties": {
    "serialNumber": {
      "dataType": "string",
      "isMandatory": true
    },
  },
  "variables": {
    "voltage": {
      "dataType": "number"
    },
    "current": {
      "dataType": "number"
    }
  }
}

An object of this type could be a child device of some Ability Edge module. The module would send the telemetry messages to the cloud on behalf of this device. Here's how it could be sending the voltage values:

Topic: modules/simpledotnetmodule/messages/events/type=timeSeries

Payload:

{
    "objectId": "24b742cb-a318-4052-8ac9-e184bbb27953",
    "model": "abb.ability.device",
    "timestamp": "2021-01-08T12:24:14.135Z",
    "value": 5.1,
    "variable": "voltage"
}

The objectId would be set to the objectId of the device (an instance of "abb.physicalSensor.device") that the module is reading the data from.

References

Warm Path Data Schemas