API

This profile may be used as is, or be used as a basis, by all profiles to implement some generic functions that are typically required by all applications regardless of their actual use cases.

Thing system info data (1100)

{
    "swVersion"    : String,
    "modelCode"    : String,
    "psn"          : String
}

swVersion is string identifier of currently installed firmware version. The syntax is defined based on the product as part of product development and manufacturing process.

modelCode is a manufacturer specific code that devices product family or other product group identifier information.

psn is a manufacturer allocated serial number that uniquely identifies the product within modelCode.

Example

[{
    "tsmId"     : 1100,
    "tsmEv"     : 11,
    "tsmTs"     : 1492603998,
    "tsmTuid"   : "TSPOD6789",
    "tsmGw"     : "TSGW1234",
    "swVersion" : "tspodfw-2017-04-19-1"
}]

Thing information request (1101)

This request is always sent from a cloud by using common event id tsmEv : 32 (Firmware information request).

{
    "requestTsmId" : Number // required
}

requestTsmId is a Thingsee Message Id of the information that the cloud requests a device to send. If device supports sending the Thing Message tsmId on request, this response message is must have common event id tsmEv:33 (Firmware information response).

If device does not support sending the Thing Message tsmId on request, it may send Thing information unavailable response (1102) message instead.

Thing information unavailable response (1102)

This response is always sent to a cloud by using common event id tsmEv:33 (Firmware information response).

{
    "requestTsmId" : Number // required
}

requestTsmId is a Thingsee Message Id of the information that the cloud requests a device to send.

Thing battery info data (1110)

{
    "batl" : Number,   // required
    "chrg" : Number    // optional
}

Example

[{
    "tsmId"     : 1110,
    "tsmEv"     : 101,
    "tsmTs"     : 1492603998,
    "tsmTuid"   : "TSPOD6789",
    "tsmGw"     : "TSGW1234",
    "batl"      : 34.6,
    "chrg"      : 2
}]

Thing orientation info (1111)

A device orientation can be reported as acceleration values.

{
  "accx" : Number,
  "accy" : Number,
  "accz" : Number
}

Thing uptime info (1112)

Information on how long time since device started.

{
  "uptime" : Number
}

uptime is seconds since device start-up.

Wirepas network neighbouring data (1200)

{
  "wpnode"             : String,    // Required
  "rssi"               : Number,    // Required
  "rssiDbm"            : Number,    // Optional
  "neighNodeInfo"      : Number,    // Optional
  "neighRadioPower"    : Number,    // Optional
  "neighRadioPowerDbm" : Number     // Optional
}

• wpnode is the Wirepas Node Id of neighbouring thing. This message doesn’t contain mapping to actual product serial number, instead the mapping needs to be done on the cloud based on the received neighboring Wirepas Node Id.
• rssi is received signal strength between tsmTuid and node. To convert this to actual dBm: rssi(dBm) = (128 * rssi / 255) – 128
• rssiDbm is received signal strength between tsmTuid and node as dBm.
• neighNodeInfo is wirepas neighbouring diagnostics node info. "neighNodeInfo" may have following values:
  • 1: Node with "tuid" is routing traffic to sender of this message (sending device id available in header "tsmTuid"). In other words, routing direction is from "tuid" to "tsmTuid".
  • 2: Node is part of same cluster.
  • 3: Node with "tuid" is routing destination for sender of this message (sending device id available in header "tsmTuid"). In other words, routing direction is from "tsmTuid" to "tuid".
• neighRadioPower is transmission power used to communicate with neighbor (wirepas). To convert this to actual dBm: radio_power(dBm) = (4 * radio_power) – 8
• neighRadioPowerDbm is transmission power used to communicate with neighbor as dBm.

Example message from "TSPOD6789" with neighbouring thing "432235".

[{
    "tsmId"     : 1200,
    "tsmEv"     : 100,
    "tsmTs"     : 1492603998,
    "tsmTuid"   : "TSPOD6789",
    "tsmGw"     : "TSGW1234",
    "wpnode"    : "432235",
    "neighNodeInfo"   : 3,
    "neighRadioPower" : 22
}]

Wirepas node identification data (1201)

Request format:

{
  "wpnode"         : Number,     //required
}

Response format:

{
  "wpnode"         : Number,          //required
  "tuid"           : String or null   //required
}

• wpnode is the Wirepas Node Id of connected Wirepas node in the context of Wirepas Network Id. In addition the cloud needs to have the network id information available in the thing inventory.

This message can be used by a gateway device when unidentified Wirepas node is connected. With this message the gateway can fetch the tuid information for the node, so that the gateway can update its internal node-to-tuid mapping table.

A gateway must have internal mapping to tuid as the Wirepas node Id cannot be used as an unique identifier.

If "wpnode" is unknown to cloud, cloud should send response with "tuid" set to null.

This message should be send as a request / response pair.

Request from a gateway

[{
    "tsmId"        : 1201,
    "tsmEv"        : 19,      //assistance requested
    "tsmTs"        : 1492603998,
    "tsmTuid"      : "TSGW1234",
    "tsmGw"        : "TSGW1234",
    "wpnode"       : 432235
}]

Response from the cloud

[{
    "tsmId"        : 1201,
    "tsmEv"        : 20,      //assistance response
    "tsmTuid"      : "TSGW1234",
    "wpnode"       : 432235,
    "tuid"         : "TSPOD_XMR3245T32"
}]

Sensor network neighbouring data (1202)

{
  "tuid"               : String,      // Required
  "rssi"               : Number,      // Required
  "rssiDbm"            : Number,      // Optional
  "neighNodeInfo"      : Number,      // Optional
  "neighRadioPower"    : Number,      // Optional
  "neighRadioPowerDbm" : Number       // Optional
}

• tuid is the Thing Unique Id of neighbouring thing.

• rssi is received signal strength between tsmTuid and node.

  To convert this to actual dBm: rssi(dBm) = (128 * rssi / 255) – 128

• rssiDbm is received signal strength between tsmTuid and node as dBm.

• neighNodeInfo is wirepas neighbouring diagnostics node info. "neighNodeInfo" may have following values:

  • 1: Node with "tuid" is routing traffic to sender of this message (sending device id available in header "tsmTuid"). In other words, routing direction is from "tuid" to "tsmTuid".
  • 2: Node is part of same cluster.
  • 3: Node with "tuid" is routing destination for sender of this message (sending device id available in header "tsmTuid"). In other words, routing direction is from "tsmTuid" to "tuid".

• neighRadioPower is transmission power used to communicate with neighbor (wirepas).

  To convert this to actual dBm: radio_power(dBm) = (4 * radio_power) – 8

• neighRadioPowerDbm is transmission power used to communicate with neighbor as dBm.

Example message from "TSPOD6789" with neighbouring thing "TSP0DCH1LD123".

[{
    "tsmId"     : 1202,
    "tsmEv"     : 100,
    "tsmTs"     : 1492603998,
    "tsmTuid"   : "TSPOD6789", //parent sensor tuid
    "tsmGw"     : "TSGW1234",
    "tuid"      : "TSP0DCH1LD123", //child sensor tuid
    "rssi"      : 77,
    "neighNodeInfo"   : 3,
    "neighRadioPower" : 22
}]

Bluetooth node identification data (1203)

Request format:

{
  "btid"         : String     //required
}

Response format:

{
  "btid"         : String,          //required
  "tuid"         : String or null   //required
}

• btid is the name that the Bluetooth sensor uses as its advertisement name.

This message can be used by a gateway device when unidentified bluetooth node is connected. With this message the gateway can fetch the tuid information for the node, so that the gateway can update its internal node-to-tuid mapping table.

If “btid” is unknown to cloud, cloud should send response with "tuid" set to null.

This message should be send as a request / response pair.

Request from a gateway

[{
    "tsmId"        : 1203,
    "tsmEv"        : 19,      //assistance requested
    "tsmTs"        : 1492603998,
    "tsmTuid"      : "TSGW1234",
    "tsmGw"        : "TSGW1234",
    "btid"         : "TPOD_1234567"
}]

Response from the cloud

[{
    "tsmId"        : 1203,
    "tsmEv"        : 20,      //assistance response
    "tsmTuid"      : "TSGW1234",
    "btid"         : "TPOD_1234567",
    "tuid"         : "XXXX061234567890"
}]

Sensor network identification data (1205)

Request format

{
  "tuid"         : String     //required
}

Response format:

{
  "tuid"         : String,             //required
  "btid"         : String,             //optional
  "wpnode"       : String              //optional
}

• tuid is the Thing Unique Id of sensor network device.

This message can be used by a gateway device when it needs to find out sensor network node identification for sensor device using "tuid". With this message the gateway can fetch the sensor node information for the dvice, so that the gateway can update its internal node-to-tuid mapping table.

Response has sensor network node information for the device. This information can be combination of these:

• "wpnode" is the Wirepas Node Id of connected Wirepas node in the context of Wirepas Network Id.
• "btid" is the name that the Bluetooth sensor uses as its advertisement name.

This message should be send as a request / response pair.

Request from a gateway for Wirepas sensor "TSPOD_XMR3245T32":

[{
    "tsmId"        : 1205,
    "tsmEv"        : 19,      //assistance requested
    "tsmTs"        : 1492603998,
    "tsmTuid"      : "TSGW1234",
    "tsmGw"        : "TSGW1234",
    "tuid"         : "TSPOD_XMR3245T32",
}]

Response from the cloud for Wirepas sensor "TSPOD_XMR3245T32":

[{
    "tsmId"        : 1205,
    "tsmEv"        : 20,      //assistance response
    "tsmTs"        : 1492604091,
    "tsmTuid"      : "TSGW1234",
    "tuid"         : "TSPOD_XMR3245T32",
    "wpnode"       : 432235,
}]

BLE iBeacon configuration data (1206)

Request format sent by using tsmEv : 30

{
  "tsmId"           : 1206,
  "tsmEv"           : 30,
  "transactionId"   : Number,
  "beaconData"      : JSON/CBOR buffer,
  "beaconMajor"     : Number,
  "beaconMinor"     : Number,
  "beaconChannels"  : Number,
  "reportInterval"  : Number,
  "txPower"         : Number
}

• beaconData is a binary string (JSON/CBOR buffer) that is used as url in advertisement data,

• beaconMajor iBeacon Major information field, length 1 byte

• beaconMinor iBeacon Minor information field, length 1 byte

• beaconChannels Mask of beacon advertising channels used. 0 = 37, 1 = 38, 2 = 39, 3 = 37 & 38, 4 = 37 & 39, 5 = 38 & 39, 6 = 37 & 38 & 39 (All)

  Note, mask 255 turns off the beacon.

• reportInterval is Beacon advertising interval (ms). Range is 100 ms to 60000ms

• txPower in dBm. Acceptable values: -8, -4, 0, 4

Response is the same payload content echoed back by using tsmEv:31

Note that txPower and reportInterval are common to all beacons so changing them for iBeacon(1206), Eddystone (1207) or generic (1208) beacons will change them for all of those.

This will modify beacon configuration in index 1 of generic beacons (1208)

BLE EddyStone Beacon configuration data (1207)

Request format sent by using tsmEv : 30

{
  "tsmId"           : 1207,
  "tsmEv"           : 30,
  "transactionId"   : Number,
  "beaconFrame"     : Number,
  "beaconData"      : JSON/CBOR buffer,
  "beaconChannels"  : Number,
  "reportInterval"  : Number,
  "txPower"         : Number
}

• beaconFrame is 0 = UID, 16 = URL, 32 = TLM, 48 = EID

• beaconData is a binary string (JSON/CBOR buffer) that is used in advertisement data,

  In case of beaconFrame = URL this contains compressed URL format, max len 17 bytes. 037468696e6773656507, for example, equals https://thingsee.com

  In case of beaconFrame = UUID this contains Namespace (first 10 bytes) and Instance (6 bytes)

• beaconChannels Mask of beacon advertising channels used. 0 = 37, 1 = 38, 2 = 39, 3 = 37 & 38, 4 = 37 & 39, 5 = 38 & 39, 6 = 37 & 38 & 39 (All)

  Note, mask 255 turns off the beacon.

• reportInterval is Beacon advertising interval (ms). Range is 100ms to 60000ms

• txPower in dBm. Acceptable values: -8, -4, 0, 4

Response is the same payload content echoed back by using tsmEv:31

Note that txPower and reportInterval are common to all beacons so changing them for iBeacon(1206), Eddystone (1207) or generic (1208) beacons will change them for all of those.

This will modify beacon configuration in index 0 of generic beacons (1208)

BLE Generic Beacon configuration data (1208)

Request format sent by using tsmEv : 30

{
  "tsmId"           : 1208,
  "tsmEv"           : 30,
  "transactionId"   : Number,
  "txPower"         : Number,
  "reportInterval"  : Number,
  "index"           : 0,
  "beaconChannels"  : 6,
  "beaconData"      : JSON/CBOR buffer,
}

• txPower in dBm. Acceptable values: -8, -4, 0, 4

• reportInterval is Beacon advertising interval (ms). Range is 10ms to 60000ms

• index Beacon index to configure. Range is 0 to 2.

• beaconChannels Mask of beacon advertising channels used. 0 = 37, 1 = 38, 2 = 39, 3 = 37 & 38, 4 = 37 & 39, 5 = 38 & 39, 6 = 37 & 38 & 39 (All)

  Note, mask 255 turns off the beacon.

• beaconData is a binary string (JSON/CBOR buffer) that is used as the advertisement data. PDU header will be set to 0x42 (non-connectable, random tx address) and address is generated from wirepas network id and sensor’s node id.

  Sample beaconData for EddyStone-URL:

  2,1,4,3,3,170,254,14,22,170,254,16,4,1,104,97,108,116,105,97,110,7
  where:
  2,1,4                         = GAP/Flags only BLE
  3,3,170,254                   = GAP/Service list: Eddystone
  14                            = length (header(5) + URL data
  22,170,254                    = GAP/Service: Eddystone
  16                            = Frame type Eddystone-URL
  4                             = Tx power 4
  1,104,97,108,116,105,97,110,7 = "https://support.haltian.com"
  

Response is the same payload content echoed back by using tsmEv:31

Note that txPower and reportInterval are common to all beacons so changing them for iBeacon(1206), Eddystone (1207) or generic (1208) beacons will change them for all of those.

Index 0 overwrites Eddystone (1207) and index 1 iBeacon (1206) configurations.

Cellular location data (1210)

{
  "lat"  : Number,
  "lon"  : Number,
  "lacr" : Number
}

Cellular RF data (1211)

{
  "cellRsrp"  : Number,  //optional, dBm
  "cellRsrq"  : Number,  //optional, dB
  "cellSinr"  : Number,  //optional, dB
  "cellRssi"  : Number,  //optional, dBm
  "cellRscp"  : Number,  //optional, dBm
  "cellEcn0"  : Number,  //optional, dB
  "cellLac"   : Number,  //optional
  "cellId"    : Number,  //optional
  "cellTac"   : Number,  //optional
  "cellRat"   : String   //optional
}

cellLac, cellTac and cellId are typically shown as hex.

This message is used to send signal quality information.

Cellular Identification data (1212)

{
  "imei"        : String, //optional
  "imsi"        : String, //optional
  "mcc_mnc"     : String, //optional
  "operatorName": String  //optional
}

Wirepas node diagnostics data (1220)

{
  "nodeAccessCycle"                       : Number,
  "nodeRole"                              : Number,
  "nodeVoltage"                           : Number,
  "nodeMaxBufferUsage"                    : Number,
  "nodeAverageBufferUsage"                : Number,
  "nodeMemAllocFails"                     : Number,
  "nodeNormalPrioBufDelay"                : Number,
  "nodeHighPrioBufDelay"                  : Number,
  "nodeScans"                             : Number,
  "nodeDelayFromSink_NormalPrio_Avg"      : Number,
  "nodeDelayFromSink_NormalPrio_Min"      : Number,
  "nodeDelayFromSink_NormalPrio_Max"      : Number,
  "nodeDelayFromSink_NormalPrio_Num"      : Number,
  "nodeDelayFromSink_HighPrio_Avg"        : Number,
  "nodeDelayFromSink_HighPrio_Min"        : Number,
  "nodeDelayFromSink_HighPrio_Max"        : Number,
  "nodeDelayFromSink_HighPrio_Num"        : Number,
  "nodeDroppedPackets"                    : Number,
  "nodeCostInfo_SinkNodeId"               : String,
  "nodeCostInfo_NormalPrio_NextHopNodeId" : String,
  "nodeCostInfo_NormalPrio_Cost"          : Number,
  "nodeCostInfo_NormalPrio_LinkQual"      : Number,
  "nodeCostInfo_HighPrio_NextHopNodeId"   : String,
  "nodeCostInfo_HighPrio_Cost"            : Number,
  "nodeCostInfo_HighPrio_LinkQual"         : Number,
  "nodeEvents"                            : { "type" : "Buffer", "data" : Array },
  "nodeDutyCycle"                         : Number,
  "nodeCurrentAntenna"                    : Number
}

• nodeAccessCycle is value of the access cycle in milliseconds.
• nodeRole is bitfield of following values:
  • 0x01: subnode
  • 0x02: headnode
  • 0x04: sink
  • 0x10: low-latency node
  • 0x20: node in relay mode
  • 0x80: node in autorole mode
• nodeVoltage is battery voltage in volts.
• nodeMaxBufferUsage is maximum amount of used buffers in percentage.
• nodeAverageBufferUsage is average amount of used buffers in percentage.
• nodeMemAllocFails is amount of memory allocation failures.
• nodeNormalPrioBufDelay is average buffering default of normal priority packets in seconds.
• nodeHighPrioBufDelay is average buffering default of high priority packets in seconds.
• nodeScans is amount of network scans.
• nodeDelayFromSink_NormalPrio_Avg is average delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_NormalPrio_Min is minimum delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_NormalPrio_Max is maximum delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_NormalPrio_Num is number of normal priority packets received from sink by the device.
• nodeDelayFromSink_HighPrio_Avg is minimum delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_HighPrio_Min is maximum delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_HighPrio_Max is average delay for normal priority packets from sink to the device in seconds.
• nodeDelayFromSink_HighPrio_Num is number of high priority packets received from sink by the device.
• nodeDroppedNormalPrioPackets is amount of dropped normal priority packets.
• nodeDroppedHighPrioPackets is amount of dropped high priority packets.
• nodeCostInfo_SinkNodeId is target sink address.
• **nodeCostInfo_NormalPrio_NextHopNodeIdv is next hop address for normal priority packets.
• nodeCostInfo_NormalPrio_Cost is price of the route for normal priority packets (1-254).
• nodeCostInfo_NormalPrio_LinkQual is the quality of the normal priority link in percentage.
• nodeCostInfo_HighPrio_NextHopNodeId is next hop address for high priority packets.
• nodeCostInfo_HighPrio_Cost is price of the route for high priority packets (1-254).
• nodeCostInfo_HighPrio_LinkQual is the quality of the high priority link in percentage.
• nodeEvents is variable sized and may contain any binary data. This data is internally handled as a CBOR buffer and converted to JSON buffer representation for clients.
• nodeDutyCycle is radio Tx activity in percentage.
• nodeCurrentAntenna is currently active antenna.

Wirepas scratchpad sequence number info (1221)

This is informational message sent by a device.

{
  "scratchpadSeqNumber" : Number,
}

"scratchpadSeqNumber" is the current scratchpad sequence number for Wirepas network. Scratchpad is over-the-air area used to delivering firmware updates over Wirepas network.

Wirepas traffic diagnostics data (1222)

{
  "nodeAccessCycle"               : Number,
  "nodeClusterChannel"            : Number,
  "nodeChannelReliability"        : Number,
  "nodeRxAmount"                  : Number,
  "nodeTxAmount"                  : Number,
  "nodeAlohaRxRatio"              : Number,
  "nodeReservedRxSuccessRatio"    : Number,
  "nodeDataRxRatio"               : Number,
  "nodeRxDuplicateRatio"          : Number,
  "nodeCCASuccessRatio"           : Number,
  "nodeBroadcastRatio"            : Number,
  "nodeFailedUnicastRatio"        : Number,
  "nodeMaxReservedSlotUsage"      : Number,
  "nodeAverageReservedSlotUsage"  : Number,
  "nodeMaxAlohaSlotUsage"         : Number
}

• nodeAccessCycle is value of the access cycle in milliseconds.
• nodeClusterChannel is current cluster channel used.
• nodeChannelReliability is the reliability of the cluster channel in percentage.
• nodeRxAmount is the cumulative sum of the received packets from cluster members in percentage.
• nodeTxAmount is the cumulative sum of the transmitted packets to cluster members in percentage.
• nodeAlohaRxRatio is ratio of the receptions done in unallocated slots since last traffic diagnostics in percentage.
• nodeReservedRxSuccessRatio is ratio of the receptions that have succeeded in percentage.
• nodeDataRxRatio is ratio of receptions that are data payload (remaining is network control payload) in percentage
• nodeRxDuplicateRatio is ratio of receptions that are duplicates in percentage
• nodeCCASuccessRatio is ratio relative to other detected transmissions on the used channel in percentage (100%=channel free, 0%=blocked).
• nodeBroadcastRatio is ratio of transmissions that are broadcasts in percentage.
• nodeFailedUnicastRatio ratio of transmissions that have failed in percentage.
• nodeMaxReservedSlotUsage is maximum ratio of the reserved transmission slots used in percentage.
• nodeAverageReservedSlotUsage is average ratio of the reserved transmission slots used in percentage.
• nodeMaxAlohaSlotUsage is maximum ratio of the unallocated transmission slots used in percentage.

Firmware update for Gateway (1300)

This data is always sent from a cloud by using common event id tsmEv : 25 (Firmware update requested)

{
  "binaries" : [
    {
      "binaryVersion"  : String,
      "binaryUrl"      : String,
      "binaryType"     : String,
      "binarySHA"      : String
    },
    {
      "binaryVersion"  : String,
      "binaryUrl"      : String,
      "binaryType"     : String,
      "binarySHA"      : String
    }
  ]
}

This data defines the content for a firmware update.

• **binariesÄÄ is list of binaries that are part of the release. Release may have one or more binaries.
• **binary versionÄÄ is a string that defines the binary
• **binary url/pathÄÄ is download location to the binary
• **binary typeÄÄ is the type of the binary
  • ‘stm32_mcu’
  • ‘nRF52_sink’
• **binary shaÄÄ is SHA256 checksum of the binary

Authentication is part of binaryUrl. Firmware update status from Gateway (1301)

This message is sent by a gateway after FOTA update with the same tsmEv as received request.

{
  "result"       : String,
  "resultReason" : String
}

Where result is

• ‘ok’ succesful FOTA update,
• ‘fail’ failed FOTA update,
• ‘cancel’ cancelled FOTA update.

result reason is a string with additional information for given result, for example: "Failed to download binary type ‘foo’", "Unsupported binary type ‘bar’".

Wirepas OTAP update for Network (1302)

This data is always sent from a cloud by using common event id tsmEv : 25 (Firmware update requested)

{
  "binaryUrl"           : String,
  "binaryVersion"       : String,
  "binarySHA"           : String,
  "binaryFlags"         : Number,
  "scratchpadSeqNumber" : Number,
  "targetNodeIds"       : [ Number, Number, ...  ]
}

This data defines the content for a firmware update.

• binaryVersion is a string that defines the binary
• binaryUrl is download location to the binary
• binarySHA is SHA256 checksum of the binary
• scratchpadSeqNumber is scratchpad sequence number to use when loading binary to sink. Valid sequence numbers are 1 to 254. Sequence number needs to be larger than current scratchpad sequence number that gateway has reported to cloud. Sequence number after 254 is 1. Following rule is utilized to compare two sequence numbers:
  • A is larger than B if (A - B) AND 128 is zero, unless A equals B.
• binaryFlags is set to 1 if binary OTAP contains Wirepas stack update. Otherwise binaryFlags is set to 0.
• targetNodeIds is array of Node Ids that are target for this OTAP update. Gateway will track update progress for these nodes. If list is empty, Gateway loads binary to sink, but does not track update progress.

Request from the cloud to a gateway:

[{
    "tsmId"               : 1302,
    "tsmEv"               : 25,
    "tsmTs"               : 1492603998,
    "tsmDstTuid"          : "TSGW1234",
    "binaryUrl"           : "https://foo.bar/file.otap",
    "binaryVersion"       : "SensorSoftware1",
    "binarySHA"           : "00112233445566778899aabbccddeeffffeeddccbbaa99887766554433221100",
    "binaryFlags"         : 0,
    "scratchpadSeqNumber" : 199,
    "targetNodeIds"       : [ 100010, 100011, 100029, 9009 ]
}]

Wirepas OTAP status for Network (1303)

This message is sent by a gateway after Wirepas OTAP update with the same tsmEv as received request.

{
  "result"       : String,
  "resultReason" : String
}

Where result is

• ‘ok’ succesful OTAP update,
• ‘fail’ failed OTAP update,
• ‘cancel’ cancelled OTAP update.

result reason is a string with additional information for given result, for example: "Failed to download binary", "Could not load binary to sink".

Firmware binary version info (1312)

This is informational message sent by a device.

{
  "binaryType"    : String,
  "binaryVersion" : String
}

Hardware identification info (1313)

This is informational message sent by a device.

{
  "hwid"    : String
}

Diagnostics info (1400)

This is diagnostic message sent by a device.

{
  "diagGroup" : Number,
  "diagType" : String,
  "diagData" : String
}

• diagGroup is group identifier for diagnostic event. Diagnostics groups are:
  • 0: System diagnostics
  • 1: Mobile network diagnostics
  • 2: Sensor network diagnostics
  • 3: Gateway diagnostics
  • 4: Sensor diagnostics
  • 5: FOTA diagnostics
• diagType is a short string describing diagnostic type.
• diagData contains diagnostics data for event as a string. This entry may also contain binary data encoded to base64 string depending on diagnostics type.

Enable diagnostics info (1401)

This event is always sent from a cloud by using common event id tsmEv:27 (Diagnostics requested). Event enables send data for given diagnostics group from a device to a cloud.

{
  "diagGroup" : Number,
  "diagExpiry" : Number,
  "diagInterval" : Number, //optional
  "diagLevel" : Number     //optional
}

• diagExpiry is a UTC timestamp up to diagnostics events will be sent by a device.
• diagInterval is an interval in seconds at which rate diagnostics events are generated.
• diagLevel is a level of diagnostic events that are generated. Higher levels yield most verbose diagnostics output from the device.

Remote command (1402)

This event is always sent from a cloud by using common event id tsmEv : 35 (Command request). Commands are profile specific, and are listed in each profile’s documents.

Request format:

{
  "command" : String,
  "payload" : String,
  "transactionId" : Number
}

• command is the name of remote command. Each product has its own set of commands that are supported. Supported commands are listed in the documentation of each product.
• payload is the payload or/and parameters for the remote command.
• transactionId is identifier field for this request and will be used for command response.

This response is always sent from a cloud by using common event id tsmEv:36 (Command response).

Response format:

{
"result" : Number,
"payload" : String,
"transactionId" : Number
}

• result is the result code command. Common result codes are:
  • 0: OK; command specific result data is payload.
  • -1: Generic error; command specific details in payload.
  • -2: Unsupported command
• payload is the payload or/and output for the remote command.

Error info (1403)

This is Error information message sent by a device using common event id tsmEv:29 (Error Diagnostics)

{
  "tsmId"      : 1403,
  "tsmEv"      : 29,
  "errorType"  : String,
  "errorCause" : String
}

• errorType String containing the error. For example, "FlashWriteFailed"
• errorCause String containing the cause for error. For example, "LowBattery"

Remote reset request (1404)

This event is always sent from a cloud by using common event id tsmEv:23 (Reset request).

{
  "tsmId"      : 1404,
  "tsmEv"      : 23
}

Sensor Application Interval Configuration (1500)

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

[{
  "tsmId"      : 1500, //ID of message content
  "tsmEv"      : 30,   //config update request
  "tsmDstTuid" : "TSPOD6789", //destination thing
  "transactionId"       : 1,
  "measurementInterval" : 10,
  "reportInterval"      : 60
}]

This message can be used to remotely configure how a specific Thingsee device measures and reports its sensor values. This configuration is generic within a device, and will change the behaviour of all the included sensors within a product.

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

A sensor application must reply with the same message (applied configuration values) with an tsmEv : 31.

Example response

[{
  "tsmId"      : 1500, //ID of message content
  "tsmEv"      : 31,   //config update response
  "tsmTs"      : 1492604004, //message timestamp
  "tsmTuid"    : "TSPOD6789", //originating thing
  "transactionId"       : 1,
  "measurementInterval" : 10,
  "reportInterval"      : 60
}]

Sensor Wirepas Node Role Configuration (1501)

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

[{
  "tsmId"         : 1501, //ID of message content
  "tsmEv"         : 30,   //config update request
  "tsmDstTuid"    : "TSPOD6789", //destination thing
  "transactionId" : 1,
  "nodeRole"      : 1,
  "autoRole"      : 0,
  "lowLatency"    : 0
}]

This message can be used to remotely configure how a specific Thingsee device configures its role in Wirepas network.

• nodeRole configures role of sensor. Value of nodeRole may be one of following:
  • 0: Headnode (sensor can route other sensors’ traffic)
  • 1: Subnode (sensor does not route other sensors’ traffic)
• autoRole configures automatic switching between headnode and subnode roles. Value of autoRole may be one of following:
  • 0: Automatic switching disabled
  • 1: Automatic switching enabled
• lowLatency configures low-latency operation. Low-latency mode should only be enabled for mains powered sensors as this setting increases power consumption significantly. Value of lowLatency may be one of following:
  • 0: Low-latency mode disabled
  • 1: Low-latency mode enabled

If nodeRole, autoRole, and/or lowLatency are omitted from request, sensors responds back currently used values.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:31.

Example response

[{
  "tsmId"         : 1501, //ID of message content
  "tsmEv"         : 31,   //config update response
  "tsmTs"         : 1492604004, //message timestamp
  "tsmTuid"       : "TSPOD6789", //originating thing
  "transactionId" : 1,
  "nodeRole"      : 1,
  "autoRole"      : 0,
  "lowLatency"    : 0
}]

Sensor Wirepas Access Cycle Configuration (1502)

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

[{
  "tsmId"           : 1502, //ID of message content
  "tsmEv"           : 30,   //config update request
  "tsmDstTuid"      : "TSPOD6789", //destination thing
  "transactionId"   : 1,
  "nodeAccessCycle" : 3
}]

This message can be used to remotely configure how a specific Thingsee device configures its access cycle range in Wirepas network.

Access cycle defines how responsive sensor is in mesh network. Lower access cycle reduces latency at the expence of greater battery consumption. Higher access cycle increases battery life but increases latency.

• nodeAccessCycle configures access cycle range of sensor. Value of nodeAccessCycle may be one of following:
  • 0: Default access cycle range, automatic selection between 2000 milliseconds and 8000 milliseconds.
  • 1: Force access cycle of 2000 milliseconds.
  • 2: Force access cycle of 4000 milliseconds.
  • 3: Force access cycle of 8000 milliseconds.

If nodeAccessCycle is omitted from request, sensors responds back currently used value.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:31.

Example response

[{
  "tsmId"           : 1502, //ID of message content
  "tsmEv"           : 31,   //config update response
  "tsmTs"           : 1492604004, //message timestamp
  "tsmTuid"         : "TSPOD6789", //originating thing
  "transactionId"   : 1,
  "nodeAccessCycle" : 3
}]

Sensor Battery Profile Configuration (1503)

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

[{
  "tsmId"         : 1502, //ID of message content
  "tsmEv"         : 30,   //config update request
  "tsmDstTuid"    : "TSPOD6789", //destination thing
  "transactionId" : 1509,
  "profileId"     : 2
}]

This message can be used to remotely configure battery profile used by sensor device.

• profileId configures battery profile of sensor. Value of profileId may be one of following:
  • 0: Default battery profile for device type.
  • 1: Battery profile for two alkaline AA or AAA batteries in series.
  • 2: Battery profile for two lithium AA or AAA batteries in series.
  • 3: Battery profile for single lithium CR2032 battery.

If profileId is omitted from request, sensors responds back currently used value.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:31.

Example response

[{
  "tsmId"         : 1502, //ID of message content
  "tsmEv"         : 31,   //config update response
  "tsmTs"         : 1492604004, //message timestamp
  "tsmTuid"       : "TSPOD6789", //originating thing
  "transactionId" : 1509,
  "profileId"     : 2
}]

Set Sensor in Low-power Storage Mode (1504)

[{
  "tsmId"      : 1504, //ID of message content
  "tsmEv"      : 30,   //config update request
  "tsmDstTuid" : "SENSOR0001", //destination thing
  "transactionId" : 199882244,
  "enabled"    : 1
}]

This message can be used to remotely set a sensor device in to a low-power storage mode. In low-power mode, device stops communicating to preserve battery.

Each sensor variant implement wake-up from low-power mode differently, see each reference manual of corresponding sensor device for proper wake-up method.

• enabled enables low-power mode. If this value is omitted from the 1504 message, low-power mode is not enabled and device reports back current setting of ‘0’.
  • ‘0’: Low-power mode is not enabled and device stays in normal mode.
  • ‘1’: Low-power mode is enabled and device enters low-power mode.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:31.

Sensor LED control request (1505)

A client will send this message with tsmEv:30 to update new configuration parameter to the sensor. The sensor will reply with the same updated data content with tsmEv:31. The sensor may send this same data in boot-up or other event to inform the client about currently applied configuration content.

{
  "tsmId"        : 1505, //ID of message content
  "tsmEv"        : 30,   //config update request
  "tsmDstTuid"   : "SENSOR0001", //destination thing
  "transactionId": 123499,
  "profileId"    : 1,
  "duration"     : 1800,
}

• transactionId is an integer value in range 0 to 2147483647.
• profileId is LED control profile. Following profiles are supported:
  • 0: Turn off LED.
  • 1: Blink LED every 2 seconds.
• duration is duration of how long profile is to be active in seconds. After deactication, LED is powered off. Duration is only used if profileId is set.

If profileId is omitted from configuration message, device reports back current profileId and duration settings.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:31.

Example response

[{
  "tsmId"         : 1505, //ID of message content
  "tsmEv"         : 31,   //config update response
  "tsmTs"         : 1492604004, //message timestamp
  "tsmTuid"       : "SENSOR0001", //originating thing
  "transactionId" : 123499,
  "profileId"     : 1,
  "duration"      : 1800
}]

Ping Request (1600)

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

[{
  "tsmId"      : 1600, //ID of message content
  "tsmEv"      : 35,   //config update request
  "tsmDstTuid" : "TSPOD6789", //destination thing
  "transactionId": 1009900,
  "wpnode"     : 6789
}]

This message can be used to test if sensor is connected to network and is receiving and transmitting messages.

Value of wpnode is compared to sensor’s own node-id and if they match, sensor sends response that contains same transactionId and wpnode fields as request. If they do not match, sensor ignores the message and does not send response. If request does not contain wpnode field, then sensor sends response without wpnode field. transactionId is optional.

A sensor application must reply with the same message (applied configuration values) with an tsmEv:36.

Example response

[{
  "tsmId"      : 1600, //ID of message content
  "tsmEv"      : 36,   //config update response
  "tsmTs"      : 1492604004, //message timestamp
  "tsmTuid"    : "TSPOD6789", //originating thing
  "transactionId" : 1009900,
  "wpnode"     : 6789
}]