Thingsee Distance Profile (17000-17999)

Distance info (17100)

{
  "dist"       : 145
}

Distance is send as a millimetre value.

[{
    "tsmId"        : 17100,
    "tsmEv"        : 10,
    "tsmTs"        : 1492603998,
    "tsmTuid"      : "T5T0FS3R1AL",
    "tsmGw"        : "TSGW1234",
    "tsmAp"        : "ThingseeDemoApp",
    "dist"         : 145
}]

Distance sensor profile configuration (17110)

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.

{
  "transactionId"      : Number,
  "profileId"          : Number
}

transactionId is an integer value in range 0 to 2147483647.

profileId is distance sensor configuration profile. Following profiles are supported:

  • 0: Default profile. Typical performance: max distance X.Xm, white target accuracy ±A% (indoors).
  • 1: High accuracy profile. Typical performance: max distance X.Xm, accuracy < ±B%.
  • 2: Long range profile. Typical performance: max distance Y.Ym, white target accuracy ±CC% (dark conditions).
  • 3: Short distance profile. Typical performance: max distance 0.5m, white target accuracy ±E% (indoors).

If profileId is omitted from configuration message, device reports back current profileId setting.

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

Example response

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

Distance 2 info (17200)

Distance 2 sensor measures distance at configured measurement interval rate. Measured distance value is reported to cloud if value differs from previously reported value more than configured absolute or relative reporting threshold. Measured distance is nevertheless reported at configured reporting interval if value changes less than reporting threshold. Measurement and reporting intervals are configured using Sensor Application Interval Configuration (1500) message. Absolute and relative reporting thresholds are configured using Distance 2 Sensor Configuration (17220) message.

{
  "dist"         : Number,
  "status"       : Number,
  "ambientRate"  : Number,
  "numberOfSPADs": Number,
  "signalPerSPAD": Number
}

Data fields:

  • dist: Distance as a millimeter value.
  • status: Status code for reading. Value 0 means successful measurement, non-zero values indicate error.

Optional fields:

  • ambientRate, numberOfSPADs and signalPerSPAD are optional fields that are enabled in debugging mode.
[{
    "tsmId"        : 17200,
    "tsmEv"        : 10,
    "tsmTs"        : 1892603998,
    "tsmTuid"      : "TSTF02SERIAL1",
    "tsmGw"        : "TSGW1234",
    "dist"         : 79,
    "status"       : 0,
    "ambientRate"  : 8,
    "numberOfSPADs": 5,
    "signalPerSPAD": 20856
}]

Distance 2 2D area info (17201)

{
  "dist": [ [ Number, Number, Number, Number ],
            [ Number, Number, Number, Number ],
            [ Number, Number, Number, Number ],
            [ Number, Number, Number, Number ] ]
}

Data fields:

  • dist: Array of array of distances as a millimeter values.

Distance 2 Temperature info (17210)

Distance 2 sensor measures temperature every 10 seconds and takes moving average of 90 measurements. If average differs more than 20°C degrees from previously reported value, new average temperature is reported to cloud. Temperature measurements can be enabled or disabled using Distance 2 Sensor Configuration (17220) message.

{
  "temp"         : Number
}

Data fields:

  • temp: Temperature as Celcius value.

Distance 2 Sensor Configuration (17220)

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.

{
  "transactionId"              : Number,
  "rangingMode"                : Number,
  "rangingTimingBudget"        : Number,
  "rangingROI"                 : [ Number, Number, Number, Number ],
  "reportingHysteresisAbsolute": Number,
  "reportingHysteresisRelative": Number,
  "reportingIgnoreErrors"      : Number,
  "reportingEnableDebug"       : Number,
  "accelerometerMode"          : Number,
  "temperatureMode"            : Number
}

Optional fields:

  • transactionId is an integer value in range 0 to 2147483647. Transaction ID is reported back as is.

Configuration fields:

  • rangingMode is ranging mode (default: 1):
    • 1: Short range mode. Typical performance: minimum distance Xcm, maximum distance X.Xm.
    • 2: Long range mode. Typical performance: minimum distance Ycm, maximum distance Y.Ym.
  • rangingTimingBudget is timing budget used for time-of-flight measurement. Larger values increase accuracy in expence of current consumption. Supported values are (default: 50 ms):
    • In short range mode: 15, 20, 33, 50, 100, 200 and 500 milliseconds.
    • In long range mode: 20, 33, 50, 100, 200 and 500 milliseconds.
  • rangingROI is used to configure region of interest are for time-of-flight sensor. ROI is given as array of four numbers which represents two 2D coordinate points. Numbers are given in order X1, Y1, X2, Y2 and region of interest is rectangle where (X1, Y1) and (X2, Y2) are points on opposite edges of the rectangle. Valid range for values is 0 to 15 inclusive. Default ROI is the full area of sensor, [0, 0, 15, 15].
  • reportingHysteresisAbsolute is absolute reporting threshold given as millimeter value (default: 50 mm).
  • reportingHysteresisRelative is relative reporitng threshold given as percentage value (default: 5 %).
  • reportingIgnoreErrors controls how failed measurements are reported. By default (setting: 1, ignore), failed measurement is only reported for first occurance after successful measurement. Repeated failed measurements are reported only at configured reporting interval. When set to zero, all failed measurements are reported at measurement interval. Distance measurement errors are reported with status data field of Distance 2 info (17200) message.
  • reportingEnableDebug controls if optional debugging data fields are enabled for Distance 2 info (17200) message (default: 0, disabled).
  • accelerometerMode controls sensor orientation reporting (default: 1, enabled). Value 0 means that orientation reporting is disabled and value 1 means disabled.
  • temperatureMode controls sensor temperature reporting (default: 1, enabled). Value 0 means that temperature reporting is disabled and value 1 means disabled.

If any configuration field is omitted from configuration message, device reports back current setting.

Sensor replies reply with the same message (currently applied configuration values) with an tsmEv : 31.

Example request to read current configuration

[{
  "tsmId"                      : 17220,           //ID of message content
  "tsmEv"                      : 30,              //config request
  "tsmDstTuid"                 : "TSTF02SERIAL1", //destination thing
  "transactionId"              : 2147483647
}]

Example request to change ranging mode and timing budget

[{
  "tsmId"                      : 17220,           //ID of message content
  "tsmEv"                      : 30,              //config request
  "tsmDstTuid"                 : "TSTF02SERIAL1", //destination thing
  "transactionId"              : 2147483647,
  "rangingMode"                : 2,
  "rangingTimingBudget"        : 100
}]

Example response

[{
  "tsmId"                      : 17220,           //ID of message content
  "tsmEv"                      : 31,              //config update response
  "tsmTs"                      : 1892604004,      //message timestamp
  "tsmTuid"                    : "TSTF02SERIAL1", //originating thing
  "transactionId"              : 2147483647,
  "rangingMode"                : 1,
  "rangingTimingBudget"        : 50,
  "rangingROI"                 : [ 0, 0, 15, 15 ],
  "reportingHysteresisAbsolute": 50,
  "reportingHysteresisRelative": 5,
  "reportingIgnoreErrors"      : 1,
  "reportingEnableDebug"       : 0,
  "accelerometerMode"          : 1,
  "temperatureMode"            : 1
}]
Previous
Next