API

Popular Search:integration, mqtt

Thingsee Gateway Profile (11000-11999)

Written by Haltian
October 19, 2021

Remote commands (dataId 1402) for Thingsee Gateway Profile

Reboot command

Command name: "REBOOT"
Payload: empty
Description: Orders reboot of gateway device.

CellLocate command

Command name: "CELLLOCATE"
Payload: empty
Description: Request for cellular location of gateway device. Works only with
2G/3G gateways.

Clear scratchpad command

Command name: "CLEAR_SCRATCHPAD"
Payload: empty
Description: Wirepas sink gateway only. Clears OTAP scratchpad of sink on
gateway device.

Wirepas remote update command

Command name: "WP_REMOTE_UPDATE"
Payload: String, format: "nodeid=’target_nodeid’;scratchpad_num=’target_scratchpad_num’;delay=’update_delay’", where:
    target_nodeid: Wirepas node-id of target sensor
    target_scratchpad_num: Scratchpad number of target sensor
    update_delay: Command delay in seconds, sensor will wait this amount before starting update procedure.

Set Sink Cost command

Command name: "SET_SINK_COST"
Payload: String, format: "’sink_cost’"
    sink_cost: Sink cost value as number, 0 to 254.

Gateway Heartbeat Summary dataId 11200

{
  "tsmId"               : 11200,
  "tsmEv"               : 10,
  "slotInterval"        : Number,
  "slotBitCount"        : Number,
  "heartbeats": [
    {
      "tuid"            : String,
      "slotBits"        : Number
    },
    ...
  ]
}

**slotInterval**: Heartbeat slot interval in seconds.
**slotBitCount**: Count of meaningful bits in the slotBits field.
**heartbeats**: Array of heartbeat information for sensors connected to this gateway.
    **tuid**: Thing Unique Id for sensor.
    **slotBits**: Bit-field of heartbeat slots when heartbeat was recorded from sensor. Bit[x] = [0|1] "in slot x" heartbeat was received (1) or not (0). Most recent slot is stored in least significant bit.

Gateway Heartbeat Single Device State Change dataId 11201

{
  "tsmId"               : 11201,
  "tsmEv"               : 10,
  "tuid"                : String,
  "slotInterval"        : Number,
  "slotBitCount"        : Number,
  "slotBits"            : Number
}
  • tuid: Thing Unique Id for sensor.
  • slotInterval: Heartbeat slot interval in seconds.
  • slotBitCount: Count of meaningful bits in the slotBits field.
    • Value is typically ‘3’ when have not seen heartbeats from sensor.
    • Value is typically ‘1’ when connection to sensor is re-established.
  • slotBits: Bit-field of heartbeat slots when heartbeat was recorded from sensor. Bit[x] = [0|1] "in slot x" heartbeat was received (1) or not (0). Most recent slot is stored in least significant bit.
    • In instant mode, value of slotBits is ‘0’ when gateway has failed to receive heartbeats from sensor.
    • Value is typically ‘1’ when gateway has received from sensor (slotBits may also have other non-zero when sensor becomes available).

Gateway Heartbeat Configuration dataId 11210

This data is always sent from a cloud by using common event id tsmEv:30.

{
  "tsmId"               : 11210,
  "tsmEv"               : 30,
  "transactionId"       : Number,
  "heartbeatInterval"   : Number,
  "reportInterval"      : Number,
  "instantMode"         : Boolean,
  "updateSinkCost"      : Boolean,
  "sinkCostMin"         : Number,
  "sinkCostMax"         : Number,
  "sinkCostStep"        : Number
}
  • heartbeatInterval: Heartbeat interval configured in minutes. Setting this to value "0", or less, will disable heartbeat functionality. Note, slotInterval will be half of heartbeatInterval.
  • reportInterval: Heartbeat reporting interval in minutes.
  • **instantMode: Instant mode on/off. In instant mode, gateway reports heartbeat state changes for individual sensors with Gateway Heartbeat Single Device State Change dataId 11201 message.
  • updateSinkCost: Dynamic sink cost updating on/off. When enabled, sink cost is update based on number of active devices connected to gateway. Sink cost works as load balancing hint for mesh network.
  • sinkCostMin: Minimum sink cost value to be used for dynamic sink cost updating. Default: 0.
  • sinkCostMax: Maximum sink cost value to be used for dynamic sink cost updating. Default: 16.
  • sinkCostStep: Maximum step of sink cost value per hour. Default: 1.

This message can be used to remotely configure the heartbeat functionality on the gateway and on the sensor network under the gateway.

If any parameter have been omitted from 11210 but is supported by device, that parameter is not changed and device reports back current setting.

A gateway application replies with the same message (applied configuration values) with an tsmEv:31.

Gateway Heartbeat Request Summary dataId 11211

This data is always sent from a cloud by using common event id tsmEv:32.

{
  "tsmId"       : 11211,
  "tsmEv"       : 32
}

Gateway responds with "Gateway Heartbeat Summary dataId 11200" with event id set to tsmEv:33.

Send Wirepas Raw Packet dataId 11310

This data is always sent from a cloud by using common event id tsmEv:35 (Command request).

{
  "tsmId"               : 11310,
  "tsmEv"               : 35,
  "wpnode"              : Number,
  "payload"             : Buffer (CBOR byte-string),
  "srcEndpoint"         : Number,
  "dstEndpoint"         : Number,
  "transactionId"       : Number
}
  • wpnode: Destination address of Wirepas node for packet.
  • payload: Data buffer containing Wirepas Mesh packet (1 to 102 bytes).
  • srcEndpoint: Source endpoint to be used when sending packet (0 – 255).
  • dstEndpoint: Destination endpoint for packet (0 – 255).
  • transactionId is identifier field for this request and will be used for command response.

Gateway responds with "Send Wirepas Raw Packet dataId 11310" with event id set to tsmEv:36 (Command response).

Response format:

{
  "tsmId"               : 11310,
  "tsmEv"               : 36,
  "result"              : Number,
  "transactionId"       : Number
}

result is the result code command. Common result codes are:

  • 0: OK.
  • -3: Invalid parameters.
  • -2: Too long payload.
  • -1: Other error.

Receive Wirepas Raw Packet dataId 11311

This data is always sent from a gateway by using common event id tsmEv:0 (event data is not applicable or is unknown).

{
  "tsmId"       : 11311,
  "tsmEv"       : 0,
  "wpnode"      : Number,
  "payload"     : Buffer (CBOR byte-string),
  "srcEndpoint" : Number,
  "dstEndpoint" : Number
}
  • wpnode: Source address of Wirepas node for packet.
  • payload: Data buffer containing Wirepas Mesh packet (1 to 102 bytes).
  • srcEndpoint: Source endpoint from where packet orginated from.
  • dstEndpoint: Destination endpoint where packet was received to.

Wirepas Raw Packet Reception Configuration dataId 11312

This data is always sent from a cloud by using common event id tsmEv : 30 (Application profile update requested).

{
  "tsmId"               : 11312,
  "tsmEv"               : 30,
  "receiveEndpoints"    : [ Number, Number, Number, ... ],
  "diagSrcEndpoints"    : [ Number, Number, Number, ... ],
  "transactionId"       : Number
}
  • **receiveEndpointsÄÄ: List of destination endpoints to listen for and forward raw packets to the cloud using "Receive Wirepas Raw Packet dataId 11311" message. Valid values for endpoints are 0 to 255.
  • **diagSrcEndpointsÄÄ: List of source endpoints to listen for destination endpoint 255 (diagnostics/Wirepas Mesh Remote API endpoint). Valid values for endpoints are 0 to 255.
  • **transactionIdÄÄ is identifier field for this request and will be used for command response.

If any parameter have been omitted from 11312 but is supported by device, that parameter is not changed and device reports back current setting.

A gateway application replies with the same message type containing applied configuration values with an tsmEv : 31. Wirepas Application Config Data Configuration dataId 11320

This data is always sent from a cloud by using common event id tsmEv:30 (Application profile update requested).

{
  "tsmId"               : 11320,
  "tsmEv"               : 30,
  "appConfigData"       : Buffer (CBOR byte-string),
  "transactionId"       : Number
}
  • appConfigData: Data buffer containing Wirepas Mesh Application Config packet. This packet is pushed to Wirepas Mesh network and is shared between all nodes under this gateway.
  • transactionId is identifier field for this request and will be used for command response.

If any parameter have been omitted from 11320 but is supported by device, that parameter is not changed and device reports back current setting.

A gateway application replies with the same message type containing applied configuration values with an tsmEv:31.

Secondary MQTT connection configuration dataId 11500

{
  "host"                : "mqtt.broker.hostname.org",
  "port"                : 8888,
  "tls"                 : false,
  "anonymous"           : false,
  "username"            : "user",
  "password"            : "pass",
  "publishTopic"        : "topic/to/publish"
}
  • host: hostname of MQTT broker
  • port: TCP port of MQTT broker
  • tls: use TLS for connection
  • anonymous: anonymous MQTT connection (no username/password)
  • username: username for MQTT connection
  • password: password for MQTT connection
  • publishTopic: target topic for publishing things messages

Secondary MQTT connection control dataId 11501

{
  "enabled"   : true,
  "tsopsMode" : 0…2
}
  • enabled: secondary MQTT connection enabled/disabled.
  • tsopsMode:
    • 0 = send all data to TSOPS (tmsId = *)
    • 1 = send full diagnostics data to TSOPS (tsmId < 9999)
    • 2 = send only minimum system data (tsmId : reset info, etc)

USB communication protocol specification

USB ACM serial port is used when communication is through USB.

###Data format

Both USB connection and cloud connections will use CBOR for Things Messages. CBOR has the exactly same content as JSON, but it is compressed to optimise data-size. Things Message specification contains JSON-CBOR mapping table and reference conversion functions between these two formats.

CBOR messages send from device to cloud are compressed using zlib library compiled with parameters suited for embedded SW use. CBOR message send to device from cloud are not compressed (as ready built zlib libraries are compiled with parameters that are not suited for embedded use, that is too large memory usage).

USB serial message protocol

USB Events (HUB->PC) format

Event line format:

(E,<timestamp>,<event-type>,<event-payload>,<crc-checksum>)
  • <timestamp>: Unix timestamp of event (device time, UTC timezone), for example: 1504614160.510
  • <event-type>: type of event, for example: TSM
  • <event-payload>: base64 encoded event payload, for example: OWuV0+z7Cpc=
  • <crc-checksum>: See section ‘CRC Checksum’.

USB Event types

  • "TSM": payload is CBOR message as described in Things Message specification.

Example:

(E,1506000431.608914,TSM,qQEZJ5ICChgoGQQYGCkYGBgqJwMaWcO+HwRxWFhYWDAzWFdONzAxNjEyMzgFcVhYWFgwMDAwMEpVU1NJR1dZBmJSRA==,fXMe)

USB Commands (PC->HUB) and responses (HUB->PC) format

Command line format:

(C,<command-id>,<command>,<command-payload>,<crc-checksum>)

Command response line format:

(R,<command-id>,<return-code>,<response-payload>,<crc-checksum>)
  • <command-id>: unique identifier for command/request pair.
  • <command>: type of command, for example: CONFIG_GET
  • <command-payload>: base64 encoded command payload
  • <return-code>: 0 or above if successful, negative number if command failed.
    • Common error codes: -1000=unknown command
  • <response-payload>: base64 encoded response payload
  • <crc-checksum>: See section ‘CRC Checksum’.

USB Commands

  • GET_VERSION: Ask SW version from gateway. Response payload is a string containing SW version number.
  • GET_TUID: Ask TUID from gateway. Response payload is a string containing Thing Unique ID for gateway.
  • CONFIG_GET: Get configuration parameter. Command payload is a string "<key>", and response payload is "<key>=<value>", where
    • `: key for configuration item,
    • <value>: value for configuration item.
    • Return code ‘-1’ returned if given <key> does not exist.
  • CONFIG_SET: Set configuration parameter. Command payload is a string "<key>=<value>", where
    • <key>: key for configuration item,
    • <value>: new value for configuration item.
  • SEND_TSM: Send Things Message CBOR to gateway. Command payload is a Things Message CBOR message.
  • GET_TIME: Ask SW version from gateway. Response payload is a string containing current Unix time in UTC timezone, for example, "1504615898.570687".
  • SET_TIME: Set system time for gateway device. Command payload is a string containing current Unix time in UTC timezone, for example, "1504615898.570687".
  • REBOOT: Reboot gateway device.
  • DFU_MODE: Reset gateway device to DFU mode.

CRC Checksum

Message checksum algorithm is CRC-24 with initializer 0xB704CE and generator 0x864CFB. For reference implementation, see RFC 2440 section ‘6.1. An Implementation of the CRC-24 in "C"’. The checksum is calculated starting from initial ‘(‘ character to last ‘,’ character of the message. The calculated CRC-24 checksum is base64 encoded and included after last ‘,’ character of the message.

  • Example message with correct CRC-24:
(E,1504614160.510,TEST,OWuV0+z7Cpc=,T40+)
  • CRC-24 calculated for "(E,1504614160.510,TEST,OWuV0+z7Cpc=," is 0x4F8D3E and this CRC-24 value encoded as base64 is "T40+".

Was this helpful?

 
Related Articles

Didn't find your answer? Contact Us

  

  

Popular Search:integration, mqtt