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

  • 000 = no event
  • 001 - 099 = system-wide 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
  • 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.

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

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.

Previous