Skip to main content

Generic Sensor Messages

Messages for requesting and receiving information about generic sensors on devices, including batteries, radio levels, accelerometers, buttons, etc.

SensorReadCmd​

Description: Client request to have a device return the current value for a sensor

Introduced In Spec Version: 3

Last Updated In Spec Version: 3

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to read data from.
  • SensorIndex (unsigned int): Index of sensor on device to read data from (index relates to position of sensor in SensorReadCmd message attributes).
  • SensorType (string): Type of sensor, used as confirmation of context, must match value in SensorReadCmd message attributes.

Expected Response:

  • SensorReading message with matching Id on successful request.
  • Error message on value or message error.

Flow Diagram:

Serialization Example:

[
  {
    "SensorReadCmd": {
      "Id": 1,
      "DeviceIndex": 0,
      "SensorIndex": 0,
      "SensorType": "Pressure"
    }
  }
]

SensorReading​

Description: Server response when data is read (in response to SensorReadCmd) or received (after SensorSubscribe) from a device sensor.

Introduced In Spec Version: 3

Last Updated In Spec Version: 3

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to read data from.
  • SensorIndex (unsigned int): Index of sensor on device that data was read from (index relates to position of sensor in SensorReadCmd message attributes).
  • SensorType (string): Type of sensor.
  • Data (array of signed int): Array of signed integers representing data. Signed integers are used due to varying return values (for instance, RSSI is negative, battery is [0, 100], buttons are [0, 1], etc...). Information on formatting/units of measurement/etc may be included in feature descriptors.

Serialization Example:

[
  {
    "SensorReading": {
      "Id": 1,
      "DeviceIndex": 0,
      "SensorIndex": 0,
      "SensorType": "Pressure",
      "Data": [591]
    }
  }
]

SensorSubscribeCmd​

Description: Client request to have the server subscribe and send all data that comes in from a device sensor that is not explicitly read. Usually useful for Bluetooth notify endpoints, or other streaming data endpoints.

Note: Only the Subscribe command will show up in the MessageAttributes portion of DeviceAdded or DeviceList. It is assumed that if Subscribe can happen, Unsubscribe can also happen, so the information is not duplicated. Having the Subscribe command in the MessageAttributes implies that Unsubscribe will also work.

Introduced In Spec Version: 3

Last Updated In Spec Version: 3

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to read data from.
  • SensorIndex (unsigned int): Index of sensor on device to read data from (index relates to position of sensor in SensorReadCmd message attributes).
  • SensorType (string): Type of sensor, used as confirmation of context, must match value in SensorReadCmd message attributes.

Expected Response:

  • Ok if subscription is successful, followed by SensorReading messages on all new readings.
  • Error message on value or message error.

Flow Diagram:

Serialization Example:

[
  {
    "SensorSubscribeCmd": {
      "Id": 1,
      "DeviceIndex": 0,
      "SensorIndex": 0,
      "SensorType": "Pressure"
    }
  }
]

SensorUnsubscribeCmd​

Description: Client request to have the server unsubscribe from a device sensor to which it had previously subscribed.

Note: Only the Subscribe command will show up in the MessageAttributes portion of DeviceAdded or DeviceList. It is assumed that if Subscribe can happen, Unsubscribe can also happen, so the information is not duplicated. Having the Subscribe command in the MessageAttributes implies that Unsubscribe will also work.

Introduced In Spec Version: 3

Last Updated In Spec Version: 3

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to read data from.
  • SensorIndex (unsigned int): Index of sensor on device to read data from (index relates to position of sensor in SensorReadCmd message attributes).
  • SensorType (string): Type of sensor, used as confirmation of context, must match value in SensorReadCmd message attributes.

Expected Response:

  • Ok if unsubscription is successful.
  • Error message on value or message error.

Flow Diagram:

Serialization Example:

[
  {
    "SensorUnsubscribeCmd": {
      "Id": 1,
      "DeviceIndex": 0,
      "SensorIndex": 0,
      "SensorType": "Pressure"
    }
  }
]