About Thingsee Messages

Thingsee Message specification is a collection of message content that defines various different use-cases and scenarios for things. This specification has been created as a standalone specification without strict requirements or restrictions from any cloud platform, messaging protocol or transport. Thingsee Messages are used by Thingsee devices to pass sensor data and events to 3rd party cloud systems.

Thingsee Message is a JSON structure that follows a defined pattern for wrapping sensor data and application content. The specification also contains CoAP/CBOR data structure where all the values are encoded as integers with multiplier information. In a typical setup, JSON is used as an application layer data format whereas CBOR is used by the things. Conversion between these two formats is done in the Thingsee Operations Cloud.

All messages are designed to use Thingsee Message Properties as a common set of properties for both JSON and CBOR. JSON is used as a specification format and CBOR conversion table is provided as an appendix.

Thingsee Message has support for two message formats. JSON is used as application format and in those devices where data size is not critical. In data and power critical things we always use CBOR data to reduce required bandwidth to a minimum.

Thingsee Messages

Thingsee Message is a JSON/CBOR formatted data with the following structure. Thingsee Messages are always sent as an array of JSON objects.

Thingsee Message header

[{
    "tsmId"      : Number, // Thingsee Message ID, required
    "tsmEv"      : Number, // Thingsee event-type, required
    "tsmTs"      : Number, // UTC timestamp in seconds, required
    "tsmTuid"    : String, // Thing ID, required
    "tsmDstTuid" : String, // Destination, optional
    "tsmGw"      : String, // Gateway ID, optional
    < profile specific data as root-level items >
}]

A message identifier (tsmId) defines Thingsee Message in a context of the application profile. This information is mandatory in every Thingsee Message, but it can default to 0 (undefined) in such cases where app & cloud doesn’t require that information. This is typical in R&D products and setups where only limited types of devices are connected to a cloud system. This information is meant to be used by the cloud or the app to identify the context of the message, and to validate expected fields within the message payload.

Thingsee Message Id is transferred as an integer, and constructed as [profileId N digits] + [dataId 3 digits]. The range of the dataId is from 100 to 999.

Profile Id

A profileId is used to describe purpose or product for the message. New profileIds are allocated based on need as new products or new product versions are created. The profiles are designed so that they all form an independent set of features for a single application. A firmware can combine messages from multiple different Thingsee Message profiles, for example in cases where the sensor device combines hardware components and capabilities from two previously different sensor products.

Data Id

A dataId is defined as

  • xx000 = no data, just header content
  • xx001 - 099 = reserved
  • xx100 - 999 = < profileId-specific messageId allocation >

A dataId defines actual message-data within the profileId. The profileId owner can freely allocate these based on the messaging, use-case and capabilities of the developed sensor device. For example, Thingsee Vehicletracker may define that dataId = 222 equals to data content

Vehicletracker example

{
  "lat"          : Number,
  "lon"          : Number,
  "engineStatus" : Number,
  "fuelLevel"    : Number
}

An event type (tsmEv) is an identifier for an event which causes the data to be sent. These events are profile specific and defined in a context of a specific profile. The event tells a reason why the message was sent.

an eventId is defined as

  • 000 = no event
  • 001 - 099 = system-wide common events. See Available tsmEv Values for more info.
  • 100 - 999 = < profileId-specific eventId allocation >

For example, Thingsee Vehicletracker may define eventIds in the scope of the Thingsee Vehicletracker profile as

  • 100 = driving, stream data every 30 seconds when the vehicle is moving
  • 110 = came to an area, the event sent when the vehicle enters geofence area
  • 120 = left from an area, event sent when the vehicle leaves geofence area
  • 130 = engine on, the event sent when the engine is turned on
  • 140 = engine off, the event sent when the engine is turned off

eventIds 100,110,120 may use same dataId (222) and there can be another dataId defined for the engine on/off events.

 Vehicletracker example

[{
    "tsmId"        : 99222,       // Thingsee tracker 99, dataId 222
    "tsmEv"        : 110,         // Enter geofence event
    "tsmTs"        : 1492603998,
    "tsmTuid"      : "TSONE123456",
    "lat"          : 65.123456789,
    "lon"          : 24.123456789,
    "engineStatus" : 1,
    "fuelLevel"    : 87
}]

A message timestamp (tsmTs) is a UTC timestamp when an event occurred. One millisecond resolution can be used by using decimal numbers (may be affected by JSON float conversion).

Exception: tsmTs may not be present in messages sent with tsmEv : 18 (Network disconnected). In this case, tsmTs is created by the cloud.

A thing identifier (tsmTuid) is an identifier of a thing. Typically this is the serial number or some other unique id within a thing. This identifier is created during the manufacturing process and it is stored in Thingsee Master Inventory.

Identify sensor type

You can use the first six characters from tsmTuid to identify sensor-type

PrefixGroupDescription
XXXX00R&D, pre-productionThingseeGATEWAY 2G EU Wirepas
XXXX03R&D, pre-productionThingseeENVIRONMENT Wirepas
XXXX04R&D, pre-productionThingseeDISTANCE Wirepas
XXXX06R&D, pre-productionThingseePRESENCE Wirepas
XXXX10R&D, pre-productionThingseeANGLE Wirepas
XXXX13R&D, pre-productionThingseePRESENCE (rev2) Wirepas
XXXX16R&D, pre-productionThingseeGATEWAY LAN
XXXX18R&D, pre-productionThingseeENVIRONMENT RUGGED Wirepas
TSGW01Haltian OyThingseeGATEWAY 2G EU Wirepas
TSGW05Haltian OyThingseeGATEWAY LAN Wirepas
TSTF02Haltian OyThingseeDISTANCE Wirepas
TSPR02Haltian OyThingseePRESENCE Wirepas
TSPR04Haltian OyThingseePRESENCE (hw rev2) Wirepas
TSPD02Haltian OyThingseeENVIRONMENT Wirepas
TSPD04Haltian OyThingseeENVIRONMENT (hw rev2) Wirepas
TSPD05Haltian OyThingseeENVIRONMENT RUGGED Wirepas
TSAN01Haltian OyThingseeANGLE Wirepas

A thing destination identifier (tsmDstTuid) is used when a Thingsee message is targeted for a specific thing (a gateway or a sensor device). This field is optional in Thingsee Messages but required for Thingsee Command Messages where the message is sent to a specific thing. For instance, this field can be used to send a mesh-network firmware update (destination is a gateway) or a single sensor parameter update within a mesh-network (destination is a sensor).

A gateway identifier (tsmGw) is an identifier of the gateway device sending the data. This identifier is the TUID of the gateway device and managed and constructed in a similar way to sensor TUID. Note that tsmGw is not static information and a sensor may switch between different gateways depending on how the network is constructed and extending. Therefore do not use this information to identify installations, locations or customers especially if multiple logically different installations are installed nearby.

A gateway timestamp (tsmGwTs) is a UTC timestamp when gateway received a message. One millisecond resolution can be used by using decimal numbers (may be affected by JSON float conversion). This field is optional in Thingsee Messages and is mainly used for diagnostics purposes for benchmarking mesh network performance.

A cloud timestamp (tsmCloudTs) is a UTC timestamp when TSOPS cloud received a message. One millisecond resolution can be used by using decimal numbers (may be affected by JSON float conversion). This field is optional in Thingsee Messages and is mainly used for diagnostics purposes for benchmarking cloud connectivity performance.

Thingsee Command Messages

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 behaviour 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 Services API or via Thingsee applications. Thingsee Command Messages are structurally 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.

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

Example for configuring sensor intervals

[{
  "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

 Sensor response to a command message

[{
  "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.

Thingsee Operation Cloud (current release) doesn’t have automated retry or rerouting mechanism thus it is the client responsibility to resend any configuration message if the client assumes that it has been lost. Automated retry with APIs for monitoring commands, will be added to Thingsee Operations release 2019.

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

Customer CloudCustomer CloudCustomer Data EndpointCustomer Data EndpointThingsee Operations CloudThingsee Operations CloudGatewayGatewaySensorSensorCommand Message (TUID:TSEXAMPLE123456789)Locate TSEXAMPLE123456789Send to the gatewaySend to TSEXAMPLE123456789Handle commandEcho responseEcho responseDetect command response

This website uses cookies for visitor traffic analysis. By using the website, you agree with storing the cookies on your computer.More information