Thingsee (message) commands

Thingsee Commands are special Thingsee messages with the purpose of sending configurations or commands to a gateway or a specific sensor device. A typical use of this communication is when a cloud or an application wants to change different threshold values, or change the behavior of the sensor device for data- or power-optimization purposes.

Structurally the commands are the same as Thingsee messages, but they carry data that either the gateway or the sensor device can process and act on. Thingsee Commands are sent using Thingsee Open Services API or via Thingsee applications. Thingsee Command Messages are structurally the same as Thingsee Messages for sensor event data and they are part of the same address-space (tsmId(s)).

Each product profile may contain these Thingsee Command Messages as part of their Thingsee Message specification as they use the same address space as the rest of tsmIds.

Send Thingsee Command Message via Thingsee Open Services API

Thingsee Command Messages can be sent by using Thingsee Open Services API that comes with the Thingsee Operations Cloud. The API is a HTTPS REST API that can be used to send, for example following message to the sensor

  "tsmId"      : 1500, //ID of message content
  "tsmEv"      : 30,   //config update request
  "tsmTs"      : 1492603998, //message timestamp
  "tsmDstTuid" : "TSPOD6789", //destination thing
  "transactionId"       : 1,
  "measurementInterval" : 10,
  "reportInterval"      : 60

All the tsm headers are used the same way as in other Thingsee Messages with an exception of having tsmDstTuid instead of tsmTuid.

A transactionId is allocated by the client and returned by the sensor as a response to successful handling of the command message. This property can be used to map requests and responses by the client so that the client can follow and monitor multiple different commands without otherwise knowing the request/response pairs.

In the example above, measurementInterval and reportInterval contains parameters for changing the sensor application behaviour. A sensor will respond by echoing the same message back to the client through the normal Thingsee message communication pipeline with the same transactionId.

Response from the device

  "tsmId"      : 1500, //ID of message content
  "tsmEv"      : 31,   //config update response
  "tsmTs"      : 1503714007, //message timestamp
  "tsmTuid"    : "TSPOD6789", //originating thing
  "transactionId"       : 1,
  "measurementInterval" : 10,
  "reportInterval"      : 60

The device will echo the same configuration content back to the client so that the client can update its status and confirm that the new parameters have been set.

A typical sequence of changing configuration (from a client perspective)

  participant CUS as YourCloud
  participant CUSD as YourDataEndpoint
	participant TSOPS as ThingseeOperationsCloud
	participant GWY as Gateway
  participant SEN as Sensor
  CUS->>TSOPS : Command Message (TUID:TSEXAMPLE123456789)
  TSOPS->>TSOPS : Locate TSEXAMPLE123456789
  TSOPS->>GWY : Send to the gateway
  GWY->>SEN : Send to TSEXAMPLE123456789
  SEN->>SEN : Handle command
  SEN-->>GWY : Echo response
  GWY-->>TSOPS : Echo response
  TSOPS-->>CUSD : Detect command response