API

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

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

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