Message Header

Thingsee Message header structure and common fields

Every Thingsee Message follows a consistent JSON/CBOR structure with required header fields and profile-specific data.

Message Structure

[{
    "tsmId"      : Number,   // Message ID (required)
    "tsmEv"      : Number,   // Event type (required)
    "tsmTs"      : Number,   // UTC timestamp (required)
    "tsmTuid"    : String,   // Device ID (required)
    "tsmDstTuid" : String,   // Destination (optional)
    "tsmGw"      : String,   // Gateway ID (optional)
    // ... profile-specific data
}]

Required Fields

tsmId (Message Identifier)

Identifies the message type within an application profile.

Format: [profileId][dataId] as an integer

Component	Range	Description
profileId	1-99	Product/profile identifier
dataId	100-999	Message type within profile

Examples:

12100 = Profile 12 (Environment), Data 100 (sensor readings)
13100 = Profile 13 (Presence), Data 100 (movement detection)
1110 = Profile 1 (Common), Data 110 (battery status)

tsmEv (Event Type)

Indicates why the message was sent.

Range	Purpose
0	No event / undefined
1-99	Common events (see table below)
100-999	Profile-specific events

Common Event Types:

ID	Name	Description
0	No event	Event data not applicable
7	State change	Triggered by state change
8	Key event	Reactive event (sensor trigger, button press)
9	Threshold	Configured threshold exceeded
10	Timed	Periodic interval message
11	Power ON	Device booted up
12	Power OFF	Device powering down
17	Network connected	Joined network
18	Network disconnected	Left network
30	Config update request	Configuration change request
31	Config update response	Configuration change response
35	Command request	Command sent to device
36	Command response	Response from device

tsmTs (Timestamp)

UTC timestamp when the event occurred.

Format: Unix timestamp in seconds
Precision: Milliseconds supported via decimal (may be affected by JSON float conversion)
Exception: May be absent in tsmEv: 18 (Network disconnected) messages; cloud adds timestamp

tsmTuid (Thing Unique Identifier)

Unique identifier for the device (sensor/gateway).

Format: 17-character alphanumeric string

Prefix Identification:

Prefix	Description
`TSGW01`	Thingsee GATEWAY 2G EU
`TSGW05`	Thingsee GATEWAY LAN
`TSPR02`	Thingsee PRESENCE
`TSPR04`	Thingsee PRESENCE (rev2)
`TSPD02`	Thingsee ENVIRONMENT
`TSPD04`	Thingsee ENVIRONMENT (rev2)
`TSPD05`	Thingsee ENVIRONMENT RUGGED
`TSTF02`	Thingsee DISTANCE
`TSAN01`	Thingsee ANGLE
`TSAR01`	Thingsee AIR
`XXXX00-XXXX18`	R&D/pre-production devices

Optional Fields

tsmDstTuid (Destination)

Target device for command messages. Used when sending configuration or commands to a specific device.

tsmGw (Gateway Identifier)

Identifier of the gateway that forwarded the message.

Warning

tsmGw is not stable. Sensors may switch between gateways as the mesh network optimizes. Do not use for location identification or business logic.

tsmGwTs (Gateway Timestamp)

UTC timestamp when the gateway received the message. Used for diagnostics and mesh network performance analysis.

tsmCloudTs (Cloud Timestamp)

UTC timestamp when Thingsee Operations Cloud received the message. Used for diagnostics and connectivity benchmarking.

Profile IDs

Profile	ID Range	Description
Common	1000-1999	System, network, firmware
Analytics	2000-2999	Computed analytics data
Edge	3000-3999	Edge processing results
Gateway	11000-11999	Gateway-specific messages
Environment	12000-12999	Temperature, humidity, pressure
Presence	13000-13999	Occupancy, movement
Machine Usage	16000-16999	Equipment monitoring
Distance	17000-17999	Range measurements
Angle	18000-18999	Tilt and orientation
Air Quality	24000-24999	CO₂, TVOC measurements

Example Messages

Environment Reading (tsmId: 12100)

[{
  "tsmId": 12100,
  "tsmEv": 10,
  "tsmTs": 1520416221,
  "tsmTuid": "TSPD04ESY93100802",
  "tsmGw": "TSGW01ABC123456",
  "temp": 21.3,
  "humd": 45.2,
  "airp": 101364.5,
  "lght": 450
}]

Battery Status (tsmId: 1110)

[{
  "tsmId": 1110,
  "tsmEv": 10,
  "tsmTs": 1520416221,
  "tsmTuid": "TSPR04E2O90201558",
  "tsmGw": "TSGW01ABC123456",
  "batl": 87
}]

Configuration Response (tsmEv: 31)

[{
  "tsmId": 1500,
  "tsmEv": 31,
  "tsmTs": 1503714007,
  "tsmTuid": "TSPR04E2O90201558",
  "transactionId": 1,
  "measurementInterval": 10,
  "reportInterval": 60
}]