Introduction
Identifiers are used to identify and implicity describe device properties, events and measurements.
The ID can be decoded by reading bytes one by one, up to 4 bytes maximum:
- If byte value is in the range 0x00 - 0x7F, append this byte and stop
- If byte value is in the range 0x80 - 0xFF, append this byte and go to the next byte
Examples
- 0x05 - One byte ID
- 0x7E - One byte ID
- 0x8000 - Two byte ID
- 0xEF10 - Two byte ID
- 0xEE8001 - Three byte ID
The ID implies the value type. This type can be a simple value type or a composite/structure type. In short, the identifier describes:
- What it is
- Format of the data (if there is any data associated)
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 | UTF-8 encoded string | string |
| float | 4 bytes (float) | number |
| mac-address | 6 bytes (unsigned) | 12-digit hex-string |
Multi-byte types are always encoded as big-endian.
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.
Property Reporting
Most device properties are reported automatically at a predefined interval. For most devices this interval be 20 minutes. Some properties are not reported and they must be read explicitly.
Example
If 0x9810 - Whitelist Key property's reported value is No it means that the device will not report 0x9810 - Whitelist Key property every 20 minutes. For example, MT Wristband 211 property 0x9810 - Whitelist Key's reported value is Yes, so MT Wristband 211 will send the property's details every 20 minutes.