search

ThingSet / thingset-device-library

ThingSet library for resource-constrained devices written in C/C++
https://thingset.io/thingset-device-library/
Apache License 2.0
14 stars 6 forks source link

Updates for ThingSet Protocol draft v0.5 #24

Closed martinjaeger closed 2 years ago

martinjaeger commented 2 years ago

Background

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 (draft). 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.

What does this PR change

  1. An option TS_NESTED_JSON (or CONFIG_THINGSET_NESTED_JSON for Zephyr) is introduced which activates nested JSON for statements (see also comments in the code for the option). For compatibility reasons, the option is disabled by default.
  2. If TS_NESTED_JSON is enabled, references in subsets use the path to an item (e.g. Bat/rMeas_A) instead of just the name (rMeas_A).
  3. As configuration cannot be stored to EEPROM or flash via a callback anymore (config items can be anywhere and not just in config group) a new updated bit is introduced for each data item.
  4. The struct ts_data_objects is updated to use bitsets for reduced memory footprint. By doing this, we save 4 bytes for each data object in flash and RAM even though we added above mentioned updated bit parameter to be stored.

In order to reduce noise in the PR, the new naming schema with prefixes is not fully adapted for the unit tests. I might update the test data in a dedicated PR without functional changes.

Additional information

@daniel-connectedenergy Commit 7ce2093e2686625d359c8ad03dc878e19dcf9797 will be most interesting for you as it reduces memory footprint with zero effort.

martinjaeger commented 2 years ago

As this PR provides backwards compatibility and does not break existing firmware I'll also merge it to benefit from smaller firmware size.