Thingsee Message Header

Thingsee Message is a JSON/CBOR formatted data with the following structure.

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

tsmId

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

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

tsmEv

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

  • 0 = no event
  • 1 – 99 = common events
  • 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
  • 111 = left from an area, event sent when the vehicle leaves geofence area
  • 120 = engine on, the event sent when the engine is turned on
  • 121 = engine off, the event sent when the engine is turned off
[{
    "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
}]

Common tsmEv values

Event Id Name Description
0 No event Event data is not applicable or is unknown.
1 Reserved Reserved
2 Reserved Reserved
3 Reserved Reserved
4 Reserved Reserved
5 Reserved Reserved
6 Reserved Reserved
7 State change event is used for events that happen as result of change of state.
8 Key event is used for reactive events, for example, sensor triggered events or key presses on human interface.
9 Threshold event is used for events that happen as result of exceeding configured threshold.
10 Timed event is used for streaming event that is send using defined interval. The interval may vary from seconds to hours to days, and it is typically set by the sensor or the gateway device.
11 Thing powered ON can be sent when a thing boots up
12 Thing powered OFF can be sent when a things is being powered off
13 Thing controlled reset occured can be sent when a thing performed controller reset
14 Thing uncontrolled reset occured can be sent when a thing performed uncontrolled reset
15 Thing firmware updated can be sent when a thing has performed firmware update
16 Thing software configuration updated can be sent when a thing has updated its software configuration data
17 Network connected is used for connected event that is send when a thing connects to gateway device or to another thing (in mesh networks).
18 Network disconnected is used for disconnected event that is send when a thing disconnects from a gateway device or from an another thing (in mesh networks).
19 Assistance data requested is send from a thing to a cloud, when the thing requires additional assistance data from the cloud to perform an operation
20 Assistance data response is send as a reply to an event 19
21 Power ON requested A thing can receive this eventId as a request from cloud to power ON. This is possible to implement only on a devices that have standby functionality with network connections enabled.
22 Power OFF requested A thing can receive this eventId as a request from cloud to power OFF.
23 Reset requested A thing can receive this eventId as a request from cloud to perform power OFF -> power ON reset cycle.
24 Reserved Reserved
25 Firmware update requested A thing can receive this eventId as a request from cloud to perform firmware update. Firmware update parameters and data may be part of the request or the data may have been received earlier.
26 Software configuration update requested A thing can receive this eventId as a request from cloud to perform software configuration update. This request is only for low-level configuration update. For application level configurations event id 30 should be used.
27 Diagnostics requested A thing can receive this eventId as a request from cloud to enable a group of diagnostics events
28 Requested diagnostic event is used for diagnostic events that have been remotely enabled from cloud
29 Error diagnostic event is used to report critical error events to cloud
30 Application profile update requested The cloud can send this request to a device to indicate that the device must update its behaviour based on the data received or available in the cloud.
31 Application profile update response The response for profile update request
32 Firmware information request The cloud can send this request to ask for firmware information from the device, such as binary version or release version.
33 Firmware information response The response for firmware information request
34 Timed diagnostics event is used for periodic diagnostic events
35 Command request is used for commands sent to device.
36 Command response is used for command responses sent from device.

tsmTs

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

tsmTuid

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

Prefix Group  Description
XXXX00  R&D, pre-production  ThingseeGATEWAY 2G EU Wirepas
XXXX03  R&D, pre-production  ThingseeENVIRONMENT Wirepas
XXXX04  R&D, pre-production  ThingseeDISTANCE Wirepas
XXXX06  R&D, pre-production  ThingseePRESENCE Wirepas
XXXX10  R&D, pre-production  ThingseeANGLE Wirepas
XXXX13  R&D, pre-production  ThingseePRESENCE (rev2) Wirepas
XXXX16  R&D, pre-production  ThingseeGATEWAY LAN
XXXX18  R&D, pre-production  ThingseeENVIRONMENT RUGGED Wirepas
TSGW01  Haltian Oy  ThingseeGATEWAY 2G EU Wirepas
TSGW05  Haltian Oy  ThingseeGATEWAY LAN Wirepas
TSTF02  Haltian Oy  ThingseeDISTANCE Wirepas
TSPR02  Haltian Oy  ThingseePRESENCE Wirepas
TSPR04  Haltian Oy  ThingseePRESENCE (hw rev2) Wirepas
TSPD02  Haltian Oy  ThingseeENVIRONMENT Wirepas
TSPD04  Haltian Oy  ThingseeENVIRONMENT (hw rev2) Wirepas
TSPD05  Haltian Oy  ThingseeENVIRONMENT RUGGED Wirepas
TSAN01  Haltian Oy  ThingseeANGLE Wirepas

tsmDstTuid

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).

tsmGw

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 <color #ed1c24>do not use this information to identify installations, locations or customers especially if multiple logically different installations are installed nearby.

Additional message fields

tsmGwTs

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.

tsmCloudTs

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.