This is an old revision of the document!


Thingsee Common Profile (1)

{
    "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",
    "tsmAp"     : "ThingseeDemoApp",
    "swVersion" : "tspodfw-2017-04-19-1"
}]

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 (102) message instead.

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.

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

Example

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

A device orientation can be reported as acceleration values.

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

The value is gravity/acceleration as mG. For example, when the device is standing still on a table the values are : accx = 0, accy = 0 and accz = 1000(mG)

Information on how long time since device started.

{
  "uptime" : Number
}

uptime is seconds since device start-up.

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",
    "tsmAp"        : "ThingseeDemoApp"
    "btid"         : "TPOD_1234567"
}]

Response from the cloud

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

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
}
  • beaconFrame is 1 = URL, 2 = UID, 3 = TLM, 4 = EID
  • 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

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

{
  "lat"  : Number,
  "lon"  : Number,
  "lacr" : Number
}
{
  "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.

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

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.

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

This is informational message sent by a device.

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

This is informational message sent by a device.

{
  "hwid"    : String
}

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.

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.

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.

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”

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

{
  "tsmId"      : 1404,
  "tsmEv"      : 23
}
[{
  "tsmId"      : 1500, //ID of message content
  "tsmEv"      : 30,   //config update request
  "tsmTs"      : 1492603998, //message timestamp
  "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.

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
}]
[{
  "tsmId"         : 1502, //ID of message content
  "tsmEv"         : 30,   //config update request
  "tsmTs"         : 1492603998, //message timestamp
  "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
}]
This website uses cookies for visitor traffic analysis. By using the website, you agree with storing the cookies on your computer.More information