Free@Home local REST api

mountainsandcode commented 3 years ago

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 commented 3 years ago

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

Maybe start with a Pypi lib?

mountainsandcode commented 3 years ago

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 commented 3 years ago

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 :+1: 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 #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 :smiley:

miezie commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Yeah, will try to get in contact

Tho85 commented 3 years ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 9 months ago

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 commented 9 months ago

Please also see my comment in #19 https://github.com/jheling/freeathome/issues/19#issuecomment-1727812158

derjoerg commented 6 months ago

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

jheling / freeathome

Free@Home local REST api #80