API changes (announcements only)

[fredlcore]

In this GitHub discussion thread we will announce changes to the (JSON) API that is used by external modules to connect to BSB-LAN. To comment or discuss on these features, please use this discussion thread, so that this one here remains "clean": #258

Here is a list of known authors of external modules for use with BSB-LAN. If yours is not listed here, if you have a direct link to the module or if there are any errors, please let me know:

IOBroker:
@hacki11 - https://github.com/hacki11/ioBroker.bsblan

OpenHAB:
@sihui62

OpenHAB2:
@hypetsch

Home Assistant:
@liudger - https://github.com/liudger/BSB-LAN-Component-for-Home-Assistant
@florianrenner - https://github.com/florianrenner/BSB-LAN-Component-for-Home-Assistant

smarthomeNG:
@thengsty

nodeRED:
@konne

FHEM:
@justme-1968

MQTT, InfluxDB, Telegraf & Grafana:
@futschikato - https://github.com/futschikato/bsb_lan-mqtt-workspace

[fredlcore]

Due to further insights into the telegrams used for date and time used both in the heater's date and time settings as well as for the daylight-savings and vacation settings, there have been a few (most likely non-breaking) changes in the data and value types used:
New data types VT_YEAR, VT_DAYMONTH and VT_TIME have been added to reflect parameters 1 to 3. VT_SUMMERPERIOD has been removed and parameters 5 and 6 have been changed to VT_DAYMONTH. VT_VACATIONPROG has so far been retained although it is in the end also just VT_DAYMONTH albeit with a different status flag in the last position of the data payload. Regarding processing VT_DAYMONTH and VT_VACATIONPROG via the API, both can be treated exactly the same, and if possible in such a way that removing VT_VACATIONPROG won't break the code on your side.
In this context, DT_THMS is a new value type for time expressed as hour:minute:second.

[fredlcore]

The protected pin functionality has been removed due to the fact that there are too many different boards around now which can run BSB-LAN. Keeping track of these boards different protected pins is no longer feasible, and rather than having a half-working functionality, it's better to give the responsibility back to the users who will have to check the datasheet of their microcontroller.
Therefore, the variable "protected_pins" has also been removed from the JSON output. This was a read-only variable, so it shouldn't bring any harm if your module's API deals with undefined return values.

[fredlcore]

In conjunction with the upcoming release of BSB-LAN 2.0, here comes a list of changes over the last months:

• New command /JB: Export a list of all writeable parameters of the heating system as JSON structure. Takes no parameters. Can be used in conjunction with /JS to (selectively) write back values as JSON structure is the same. Use at your own risk!
• Schema Parameter now has new attributes dataType_name (such as VT_TEMP), dataType_family (such as DT_VALS), precision(characters after decimal dot) and readwrite: 0 - read/write, 1 - read only, 2 - write only. Attribute readonly is still kept for now but is going to be deprecated.
• Schema PossibleValue now has new attributeisswitch: 0 - Any type, 1 - ONOFF or YESNO type
• Schema Error now has additional new parameter values; complete list is now: 0 - ok, 7 - parameter not supported, 1-255 - LPB/BSB bus errors, 256 - decoding error, 257 - unknown command, 258 - not found, 259 - no enum str, 260 - unknown type, 261 - query failed, 262 - Too few/many arguments in SET command

[fredlcore]

I'm sorry for having neglected the API documentation for such a long time, but version 2.3 contained in the openapi.yaml should now reflect all changes that have been made over the last years. Some changes might be relevant for external integrations because BSB-LAN now supports category lists for more than one device in an LPB setting. The necessary information is now included in the parameter and category results, as well as in /JI which contains a list of devices discovered on the bus.
Note that not all these devices also provide parameters, so it's necessary to check against /JK=ALL whether they are relevant or not.