Identifiers¶

Identifiers are used to identify and implicitly 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

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:

Multibyte 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 parentheses 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.

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.