ThingSet specification v0.4

[martinjaeger]

This PR suggests some breaking changes for the ThingSet protocol which try to solve issues that occured during the development of gateways to map ThingSet with MQTT and HTTP.

Preview: libre.solar/thingset/branch/v0.4/

Non-breaking changes

Nomenclature update

These updates try to enhance consistency and understanding of the protocol concepts.

• Data nodes are now called data objects (as it was already the case in a very early version of the protocol) in order to avoid confusion with IoT devices, which are also often called "nodes"
• Leaf nodes containing actual data (like Bat_V) are called data items.
• Publication messages are called statements. Statements are mainly used in a broadcasting fashion, but can also sent to a specific device in which case the device applies the stated data item values if possible. In contrast to request/response, no confirmation or error message is sent back after a statement has been received and processed.
• A data object referencing multiple other data items (array of their names) e.g. to specify the content of a statement is called data set.
• Executable data objects are prefixed with x- in order to distinguish them from paths or data sets.
• Internal data objects (prefixed with .) are introduced, which are used to configure e.g. the publication frequency of groups or data sets.

Other updates/improvements

• The example data structure was changed, e.g. output group was split into meas and state. However, adapting this structure is not mandatory.
• Draft specification for LoRaWAN mapping added
• Draft specification for MQTT topic layout added

Breaking changes

Statements now contain the path

Previously, a binary publication message only contained the hash sign followed by the payload data. Published messages (now called statements) have been extended to contain the path, e.g. meas:

#meas {"Bat_V":14.4,"Ambient_degC":20}

This is necessary for better integration with MQTT. It allows to have separate topics for static data, dynamic measurement data and event-driven data, which can be sent in very different periods.

GET requests in binary mode do not contain payload anymore

Previously, the payload behind the endpoint/path was used for device discovery (e.g. to get all data objects below a specific path or return name:value maps instead of id:value maps).

However, CoAP and HTTP requests do not allow any payload.

In order to make ThingSet more compatible, the FETCH request is used for device discovery instead.

The nameid command in binary mode has been removed

Instead, ID / name mapping is done via normal data items stored under the fixed path .names. This allows for better compatibility with other protocols aswell.

Some IDs are reserved

For LoRaWAN and CAN some IDs need to be known in advance in order to retrieve further device information. The IDs from 0x10 to 0x20 are now reserved for these purposes. In addition to that, IDs > 0x8000 are reserved for control purposes.

[martinjaeger]

Ping @b0661, @luizvilla, @light411

[b0661]

Endpoint -> Data item?

[martinjaeger]

An endpoint is a specific type of data object / path which is used for a request (like in RESTful APIs). It's slightly different from a generic data object name, so I'd like to keep this here.

[martinjaeger]

Going to merge this spec update now, as the library has been updated in parallel already.