v0.5 - Update to ThingSet Spec v0.5

With this release the library was updated to comply with ThingSet Specification v0.5.

Related PR: #24

Background information regarding Spec updates

While developing a mobile phone app that translates ThingSet data objects read from a device into a user interface, I realized several shortcomings with the approach of structuring the data into categories like info, conf, meas, etc. Most importantly, it was not semantically clear which data items could be written, so an app would have to try writing a value, process the response and if it is allowed to write the value, display it in a text box so that it can be changed via the UI.

The v0.5 spec introduces prefixes for data items which define if an item is write-able, read-only, executable, stored in RAM or flash, etc. This makes the previous categories obsolete and data can be structured more logically based on features of the device.

An example using the new data structure can be seen in ThingSet Spec v0.5 Example Data. Also consider the section "User interface processing" at the end.

As data item names don't have to be globally unique anymore (e.g. there can be a measured current for the battery Bat/rMeas_A and the load Load/rMeas_A) the JSON in the statement messages needs to be nested.

v0.4 - Update to ThingSet Spec v0.4

With this release the library was updated to comply with ThingSet Specification v0.4.

Related PRs:

• Library: #11
• Specification: ThingSet/thingset.github.io#18

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.

v0.3 - Updates to new ThingSet spec

Major update to support new ThingSet v0.3 specification: https://libre.solar/thingset/

• Data objects are now structured in a tree and called nodes. This allows more flexible structuring of the data and is better aligned to other JSON-based APIs.
• The previous concept of categories is replaced with a more powerful concept of parent nodes. These can still be named like previous categories ("conf", "output", etc.) and will keep the commands the same as before.
• Function names aligned with CoAP and HTTP: GET, FETCH, PATCH instead of read, write, etc..
• Functions are not distinguished by their payload anymore (nothing / array / map), but by a text-based or binary identifier as the first byte. Text mode has now '?', '=', '!', '+', '-' instead of just '!'.
• Authentication handled via callback and normal "executable" node instead of dedicated functions in ThingSet library. This allows the user to implement any sort of authentication mechanism, not necessarily via the protocol. (e.g. if the user presses a button on the device)
• Executable nodes can have parameters and don't have to be "void". This is implemented via child nodes of the executable node.
• Coding style improvements and more Doxygen comments

See commit history for more details.