Skip to content

Introduction

Identifiers are used to identify and describe device properties, events and measurements.

Some measurements are reported. Some properties are not reported, they must be read explicitly. Reported means that the device sends all property's details every 20 minutes (this time period can vary for each device).

Example

If 98.10 - Whitelist Key property's reported value is "No" it means that the device will not report 98.10 - Whitelist Key property every 20 minutes. For example, MT Wristband 211 property 98.10 - Whitelist Key's reported value is Yes, so MT Wristband 211 will send the property's details every 20 minutes.

The ID can be decoded by reading bytes one by one:

  • If byte is in the range 128-255 (dec) or 80-FF(hex), append this byte and go to the next byte
  • If byte is in the range 0-127 (dec) or 00-7F (hex), append this byte and stop
Examples (hex bytes, separated by .)
  • 05 - One byte ID
  • 7E - One byte ID
  • 80.00 - Two byte ID
  • EF.10 - Two byte ID
  • EE.80.01 - Three byte ID

Note

ID is always written using hex encoding.

The ID implies the value type. This type can be a simple value type or a composite/structure type.

Common Types

Common types and their representation:

Type Representation JSON Data Type
void No bytes null
bool 1 byte of value 0 or 1 boolean
s8 1 byte (signed) number
u8 1 byte (unsigned) number
s16 2 bytes (signed) number
u16 2 bytes (unsigned) number
s32 4 bytes (signed) number
u32 4 bytes (unsigned) number
u48 6 bytes (unsigned) number
UTF-8 string encoded using UTF-8 string
float 4 bytes (float) number

Multi-byte types are always encoded as big-endian.

Please, follow this link to convert bytes.

In short, the identifier describes:

  • What it is
  • Format of the data (if there is any data associated)

Dictionary Value Type

Sometimes an identifier value only makes sense as a collection of values, some of which may be optional. In these cases the value can be represented using a dictionary type. The format of the dictionary type is as follows:

KEY|LENGTH|VALUE...KEY|LENGTH|VALUE...
  • KEY is a byte used to identify the dictionary entry
  • LENGTH is a byte indicating the length of VALUE that follows (in bytes)

Key-value pairs shall be ordered by KEY.

Value Extensions

The value for an identifier can be extended in the future. To ensure backwards compatibility it is important to allow for extra bytes at the end of the value byte-array when parsing/validating. Value extensions are typically used to extend common types.

Identifier Translation and JSON encoding

A gateway can support translation of raw hex identifiers and byte-array value to a human readable name and a corresponding JSON encoded value.

The dictionary used for translation has a version number, starting at 1. In the identifier description, the translation dictionary version number where it was added is in parenthesis behind the human-readable name.

A specific firmware version of a gateway implements a version of the dictionary.

Value extensions will always be encoded as a JSON object.

Note

When the translation to JSON is obvious from the value type, there will be no JSON description.