Free@Home local REST api

[mountainsandcode]

With the latest firmware version 2.6.0, there is now a local REST API. This also allows web socket connections.

While this will require considerable effort, this will make it possible to ditch XMPP and go for an officially supported API 🎉

Documentation at https://developer.eu.mybuildings.abb.com/fah_local/

[miezie]

@Tho85 how could we make this work? Woohooo :). Shall I learn Python?

Maybe start with a Pypi lib?

[mountainsandcode]

Yes, I think this would be the best first step. I think it makes sense to set up a GitHub org for that, or alternatively to see if it can be hosted in the organization home-assistant-libs

[Tho85]

Interesting, definitely! I think the greatest news about this is that ABB seems to be commited to provide local access to the SysAP in the future, instead of forcing everyone to use their cloud.

Some thoughts:

• Going for a vendor-supported API is of course better than relying on the unofficial XMPP version. I think it is not worth it to keep the old XMPP stuff in order to be backwards compatible. So a 👍 for implementing this from my side
• We'll have to see how the device configuration is exported through their API. If it is the reduced version that we used until some weeks ago, this might mean that implementation for e.g. binary sensors might not be straight forward. If there is a way to export the extended configuration as we do now, things might look better. If anyone is already on 2.6.0: Does the official Web UI still use XMPP, or did they also switch that to REST?
• From what I understand by reading the docs, the API's internals doesn't differ much from what we do with XMPP now. The concept of pairing IDs, datapoints etc. is the same. So chances are that we can reuse much of the code in this repository, and just change the underlying connection mechanism from REST to XMPP.
• Regarding splitting off a library and using that for an official component in HA, let's discuss that in Make this an official component #19

I'm still on 2.4.0 for various reasons, but I will try to update to 2.6.0 in the next days and start tinkering with it 😃

[miezie]

I just updated... after updating all the actors also it works still like a charm. So a smooth migration is possible :).

What I noticed a year ago already is that f@h was lacking the local API. KNX devices had it already... Which means to me that this is quite stable. From a very quick scan I concluded that it doesn't differ that much from public API.

[jheling]

One of the requirements is : A system access point 2.0 with at least version 2.6.0 must be available. Do you have this 2.0 version? My system is five years old.

[miezie]

Yes I have this newest version. I bought it when I noticed that my Hue lights were not performing. It actually is a nice investment the bump in performance is really good.

[Tho85]

I've upgraded to 2.6.0 as well, and the component seems to work as before.

I just had a glimpse at the local API, and it looks like it only exports a reduced configuration file instead of a complete one. Especially, the following information is missing:

• Device (not channel) specific information like device name (e.g. "Switching actuator 8-gang"), model name, software version, etc. - basically everything we display in the "Devices" list in Home Assistant
• Parameters, i.e. are switching units configured as a single sensor (up/down combined) or as a splitted sensor (up/down splitted). So we can't distinguish between combined and splitted sensors
• Information if devices are external (e.g. Hue) or not. Currently we exclude external devices, because they can be integrated directly with Home Assistant, and for users with emulated_hue enabled

[Tho85]

Another information that's missing:

• Information about whether a device is currently online or offline (commisioningState). So with the API, we would add all devices known to the SysAP, regardless of whether they are actually available or not.

And although you can open a WebSocket connection to receive state updates from the SysAP, it looks like it is not possible to use that connection to send commands back to the SysAP. So every command (switch on etc.) is a separate HTTP call, which produces additional request overhead. (When inspecting the firmware update a little closer, it looks like it is dispatched through an nginx on the device to a separate REST handler, so I guess this is not nearly as fast as the XMPP way.)

Honestly, I'm unsure if we should jump on the API right now. Maybe we could give ABB/Busch-Jaeger some kind of feedback about this, so that they can address this in a future release?

[miezie]

Yeah, will try to get in contact

[Tho85]

• Scenes can't be controlled by the local API. If you want to control a scene, you have to add a switch, connect it to the scene and control the switch through the local API.

The virtual devices part looks interesting, though. It allows you to create virtual lights, shutter actuators, thermostats etc. and have them controlled in free@home. This way we could expose Home Assistant entities to free@home similar to emulated_hue, but with support for more device types.

[alfonsomainardi]

hi can anyone help me I integrated freeathome it gives me this error when it syncs can anyone help me? thank you

Logger: homeassistant.config_entries
Source: custom_components/freeathome/fah/pfreeathome.py:712
Integration: Busch Jaeger/ABB Free@Home (documentation)
First occurred: 9 gennaio 2023 19:34:04 (2 occurrences)
Last logged: 09:22:35

Error setting up entry 192.168.1.102 for freeathome
Traceback (most recent call last):
File "/usr/src/homeassistant/homeassistant/config_entries.py", line 382, in async_setup
result = await component.async_setup_entry(hass, self)
File "/config/custom_components/freeathome/init.py", line 77, in async_setup_entry
await sysap.find_devices()
File "/config/custom_components/freeathome/fah/pfreeathome.py", line 897, in find_devices
await self.xmpp.find_devices(self._use_room_names)
File "/config/custom_components/freeathome/fah/pfreeathome.py", line 712, in find_devices
filter_mask = int(option.get('mask'), 16) # e.g. '00000001' -> 0x00000001
AttributeError: 'NoneType' object has no attribute 'get'

[derjoerg]

Hi,

I just looked at some comments above and checked the current Rest-API (3.1.1). Just two points:

• Scenes: I don't see this as a big problem. As of today - e.g. to react on the doorbell (Welcome@Home) - you need to create a sensor in HA, expose it to F@H through emulatedHue (which is somehow broken), and connect this "light" to the doorbell entity in F@H
• If I saw it correctly the configuration now has an attribute if a device is external (e.g. sonos, hue).

[victorclaessen]

One of the requirements is : A system access point 2.0 with at least version 2.6.0 must be available. Do you have this 2.0 version? My system is five years old.

The local REST api is now also available in the latest firmware version for the 1.0 hardware version :-).

[derjoerg]

Please also see my comment in #19 #19 (comment)

[derjoerg]

Hi,

I started creating a python library as a first step to control F@H through the local REST API.
For now you can control switches (On, Off), triggers (press) and get information from a Weatherstation (temperature, brightness).

Before I go further this way I would really like to get some feedback on the structure of the library and so on as it is the first time I've done something with python
https://github.com/derjoerg/python_freeathome_local

[kingsleyadam]

I've been working on this in the background for a little while and I think it's ready to be opened up to others to test. Looking for contributors/collaborators. Ultimate goal is to get this added as a core integration to HA.

Sorry @derjoerg, hope this doesn't step on your work.

PyPi Package

I've created a new PyPi library (GitHub) to interact with the local api.

Some things to point out:

• It currently only supports the Switching/Actuator device. I don't have dimmers in my house so I'll need some help from others to provide their configurations to test with. OR, if anyone is well-versed in Python they can also contribute to the code. 🧑‍💻.
  • I do have Hue devices which I can most likely use for testing, but I think we want to leave Hue devices out on the final HA integration.
• Implements a websocket mechanism to listen for events and notify (callback) Home Assistant.
• Has complete UnitTests and 100% code coverage to (hopefully) ensure stability.
• The PyPi package implements wheel packages to be fully supported by Home Assistant.
• Has a number of GitHub actions to ensure the repo is well maintained and easy to contribute to:
  • Actions to enforce code/style guidelines mostly provided by Home Assistant using Ruff.
  • Actions to enforce UnitTests passing and an acceptable percentage of code coverage.
  • Actions to automatically cut a new release and push to PyPi when a new tag is merged into the main branch. Creates automatic release notes based on PR's and their labels.
• As noted by @Tho85 above, because we have to invoke a new http request for each device update the interaction is slightly slower vs XMPP. For me that's acceptable, especially vs some instabilities of using XMPP which we've seen in the past (mostly XML formatting issues).

Custom Home Assistant Integration

With the new PyPi package above, I've also created a custom Home Assistant Integration which can be easily added to HA via HACS.

If anyone is willing to help test or only has switching devices you can switch this integration. I've been running this on a test server for a couple of weeks and it seems quite stable. I haven't had to implement any major bug fixes.

Some things to point out on this:

• This introduces proper device discovery using the SerialNumber of your SysAP. It will track any IP changes to the SysAP and update accordingly. It will not prompt re-discovery even if the hostname or IP has changed as it uses the serial number as a unique id.
• Automatically adds the devices to an Area when adding the integration based on the room name given in the Free@Home configuration.
• I've tested a few different scenario's for the websocket. It's designed to reconnect to the SysAP if it loses connection and so far that's worked.
  • In general, I don't lose connections to the SysAP, but I've tested a physical reboot of the SysAP and Home Assistant recovered the webscket connection when it was available.
• I've submitted the ABB logo/branding to the HA brands to ensure the logo shows correctly for this custom integration. Add icon for custom integration ABB Free@Home home-assistant/brands#5937
• As with the PyPi package, the repo has a number of Github Actions.
  • Actions to enfore code/style guidelines and formatting using Ruff. Following Home Assistant guidelines which will make implementing this integration easier.
  • Actions to run HASSFEST action which will run nightly (and on PR's) to ensure the integration is setup correctly and ready to be integrated as a core component.
  • Actions to automatically cut a new release when a new tag is merged into the main branch. Creates automatic release notes based on PR's and their labels. The release notes will show up in HACS when a new version is available, which is nice to know what's changed before you decide to upgrade.

[derjoerg]

@kingsleyadam : I have absolutely no problem if someone else supersedes my work 🙂 Even that I think that my python-library was on a good way I have to say that I have no real glue on python-programming and I gave up to start with an HA-integration as I didn't understood how to connect HA to my F@H-websocket.

Nevertheless, I'm absolutely happy that you opened your work and as soon as I get it working on my HA-testinstallation I will try to contribute to get as much devices in as possible.