Message Commands

Sending commands and configuration to Thingsee devices

Thingsee Commands are special messages for sending configurations or commands to gateways and sensors. They enable remote device management and behavior customization.

Overview

Commands use the same structure as regular Thingsee Messages but carry data that devices can process and act upon.

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#73F9C1','primaryTextColor':'#143633','primaryBorderColor':'#143633','lineColor':'#143633','secondaryColor':'#C7FDE6','tertiaryColor':'#F6FAFA','actorBkg':'#73F9C1','actorBorder':'#143633','noteBorderColor':'#FF8862','noteBkgColor':'#FFCFC0','signalColor':'#143633'}}}%%
sequenceDiagram
    participant Cloud as Your Cloud
    participant API as Thingsee API
    participant GW as Gateway
    participant Sensor as Sensor

    Cloud->>API: POST Command Message
    API->>API: Locate device
    API->>GW: Forward command
    GW->>Sensor: Deliver via mesh
    Sensor->>Sensor: Process command
    Sensor-->>GW: Echo response
    GW-->>API: Forward response
    API-->>Cloud: Deliver to endpoint

Command Structure

[{
  "tsmId"      : 1500,              // Command message ID
  "tsmEv"      : 30,                // Config update request
  "tsmTs"      : 1492603998,        // Timestamp
  "tsmDstTuid" : "TSPR04E2O90201558", // Target device
  "transactionId"       : 1,        // Your tracking ID
  "measurementInterval" : 10,       // Config parameter
  "reportInterval"      : 60        // Config parameter
}]

Key Differences from Regular Messages

FieldRegular MessageCommand Message
tsmTuidSource deviceNot used
tsmDstTuidNot usedTarget device (required)
tsmEvEvent typeCommand type (30, 35, etc.)

Sending Commands

Via Open Services API

curl -X POST \
  'https://api.thingsee.com/v1/messages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[{
    "tsmId": 1500,
    "tsmEv": 30,
    "tsmTs": 1492603998,
    "tsmDstTuid": "TSPR04E2O90201558",
    "transactionId": 1,
    "measurementInterval": 10,
    "reportInterval": 60
  }]'

Transaction ID

The transactionId field:

  • Allocated by your application
  • Returned in device response
  • Maps requests to responses
  • Enables tracking multiple concurrent commands

Device Response

The device echoes the command back with updated event type:

[{
  "tsmId": 1500,
  "tsmEv": 31,                       // Config update RESPONSE
  "tsmTs": 1503714007,
  "tsmTuid": "TSPR04E2O90201558",    // Now source (responding device)
  "transactionId": 1,                // Same as request
  "measurementInterval": 10,
  "reportInterval": 60
}]

The response confirms:

  • Command was received
  • Parameters were applied
  • Current configuration state

Command Event Types

tsmEvDirectionPurpose
30→ DeviceConfiguration update request
31← DeviceConfiguration update response
35→ DeviceCommand request
36← DeviceCommand response
25→ DeviceFirmware update request
32← DeviceFirmware info request
33← DeviceFirmware info response

Common Commands

Change Measurement Interval

[{
  "tsmId": 1500,
  "tsmEv": 30,
  "tsmTs": 1492603998,
  "tsmDstTuid": "TSPD04ESY93100802",
  "transactionId": 42,
  "measurementInterval": 300,  // 5 minutes
  "reportInterval": 3600       // 1 hour
}]

Request Diagnostics

[{
  "tsmId": 1000,
  "tsmEv": 27,
  "tsmTs": 1492603998,
  "tsmDstTuid": "TSPR04E2O90201558",
  "transactionId": 43
}]

Request Firmware Info

[{
  "tsmId": 1000,
  "tsmEv": 32,
  "tsmTs": 1492603998,
  "tsmDstTuid": "TSGW01ABC123456",
  "transactionId": 44
}]

Profile-Specific Commands

Each profile may define additional command messages. Check the profile documentation for available commands:

Best Practices

Track Commands

Maintain a command log for troubleshooting:

const pendingCommands = new Map();

function sendCommand(device, params) {
  const transactionId = generateTransactionId();
  
  pendingCommands.set(transactionId, {
    device,
    params,
    sentAt: Date.now(),
    status: 'pending'
  });
  
  // Send via API
  return api.sendCommand({ ...params, transactionId });
}

function handleResponse(message) {
  const cmd = pendingCommands.get(message.transactionId);
  if (cmd) {
    cmd.status = 'confirmed';
    cmd.confirmedAt = Date.now();
    cmd.response = message;
  }
}

Handle Timeouts

Commands may not receive responses if:

  • Device is offline
  • Network issues
  • Device processing error
const COMMAND_TIMEOUT = 300000; // 5 minutes

function checkPendingCommands() {
  const now = Date.now();
  
  for (const [id, cmd] of pendingCommands) {
    if (cmd.status === 'pending' && now - cmd.sentAt > COMMAND_TIMEOUT) {
      cmd.status = 'timeout';
      // Alert or retry logic
    }
  }
}

Batch Configuration Changes

When changing multiple parameters, send them in a single command:

// Good: Single command with all parameters
[{
  "tsmId": 1500,
  "tsmEv": 30,
  "tsmDstTuid": "TSPR04E2O90201558",
  "transactionId": 1,
  "measurementInterval": 10,
  "reportInterval": 60,
  "threshold": 25
}]

Avoid sending multiple separate commands for related changes.

Error Handling

If a command fails, the device may:

  1. Not respond (timeout)
  2. Echo with error status
  3. Echo with unchanged values

Always compare response values with requested values to confirm success.