ABB/Busch-Jäger free@home - official REST api

UhA · December 4, 2022, 1:37pm

Continuing the discussion from Busch-Jaeger Free@Home:

I started a new thread for the ABB/Busch-Jäger free@home with the official REST api.

This binding is based on the REST API for setting values and Event Socket communication is used for status updates. This current version is complete is fulfilling the openHAB design guidelines where the binding is keeping handing one free@home device as one openHAB Thing. No splitting the devices into multiple Things. This means a 4xChannel actuator will be kept as one multi-channel Thing. For this it is important to give a name to the channels on the free@home dashboard, because it is used for the openHAB representation.

The data model used channels and data points in the free@home system. However they are used in combination for setting and reading state. Therefore a middle layer was necessary in the design, where it is able to group datapoints into get/set group.

Introducing a new Input/Output (Sensor/Actuator) functionalities is very simple, it just needed to define on which channel, and which “idp/odp” the communication is happening and define for the function ID lookup a new data point group.
The introduction of a new device time is simple as well, it just make a new lookup entry in the code for the new device

The usage of the current version needs only configuration of the SysAP (gateway) as use interaction. the further devices and channels are detected automatically, no user action or any additional configuration is needed.

The automatic detection is based on the REST API available function ID and pairing ID information. Due to this the binding can adapt itself and able to detect and control new/unknown devices, where the known function ID is used.

I made my test based on my free@home system and based on some shared configuration file.

If somebody would like to have a binary to test, to try it, I am happily sharing my current binary build.
In case of any question, or request to implement a new feature please contact me, the best would be in private message.

The binding binary is here

and

The source Code can be found here

In any questions or ideas to improve the binding, implement new functions feel free to contact me.

Thank you

LuiSauberhorn · December 11, 2022, 5:23pm

Hey @UhA,

the approach looks interesting and I would be interested to play around with the binding over Christmas. Do you have a things and items file example? I am using text files, as my configuration is quite large…

Thanks, Lui

UhA · December 17, 2022, 12:00pm

Hi @LuiSauberhorn,

I could not answer you mail, I was pretty busy in my work. The things in my binding are generated dynamically, therefore I did not planned and used any items files till now.

However it is possible to predict how the things and channels will be called in case of a manual configuration. please give me some days I will try out something and come back to you before Christmas.

thank you for the interest.

Andras

UhA · December 23, 2022, 8:23am

Hii @LuiSauberhorn,

I tried to find a solution for your question, and I hope that will help you.

The binding is able to handle specific input and ouptut function/channles, but where these channels are located in the device, whether this is the channel 1 or channel 20 is not known is not defined in the binding. This happens every thing in runtime,

I could give you just the wireless switch, sensor and thermostat examples. But if you are having different devices or wired, the configuration could be different.

But I would propose you a method to be able to simplify the item creation And you can apply to all of your devices
The best way is to add one free@home device, which you want to have in the openhab. Create its channles to your openhab configuration by the modell manager or by the thing manager. If you have all channels which you need you could replicate the items to other things as well.

The channel name structure look like this:

freeathomesystem : free-at-home-device : <bridge-id> : <free@hgome device-id> :  <channel_for_communication>_<short_channel_info>

Where:
bridge-id - is your SysAP bridge-id
free@hgome device-id - is the free@home id printed on the deivice
channel_for_communication - is the channel ID for free@home communication, for same channel type in a device type is every time same
short_channel_info - is a text info for the channel, for same channel type in a same device type is every time same

Like this

freeathomesystem:free-at-home-device:16a4aa538a:ABB700CF1000:ch0000_measured_temperature

For the same channel type you have to change only the free@home device-id, and you will have the new item.

I hope I could help you

Fichte07 · January 5, 2023, 11:42am

I was running an older version of this binding with OH 3.0.1, everything worked so far.

Now i made a new installation (new SD card, new everything) with Raspbian Bullseye and OH 3.4 and restored my backup.

Freeathome Binding was not there…so far ok.

Downloaed the newest version from here: The binding binary is here

Now trying to install a new bridge and always get the error:
COMMUNICATION_ERROR

Cannot open http connection, wrong password or IP address

Tried different usernames etc, also tried bundle:restart several times, no change.

Any ideas?

Thx

Sleugner · January 6, 2023, 10:31pm

Hi @UhA,
I just wanted to thank you for the Binding. I installed it and everything workes fine.
I even set up new devices and the Binding was able to find them with the scan.

@Fichte07 Are you using the Alpha Numerical name of you user wich is shown in the “your IP/swagger/users” overview? Or maybe “installer” as user?

I am currently working on creating virtual devices with the Rest API. It worked fine with the weather station, I followed the instructions from this link here and intgrated the OpenWeather Informations and Channels from my Sonoff Devices via Node Red and Zigbee2mqtt.

But I have problems to find the right API Channels from the ABB documentation.
Does anybody have a good mapping from the virtual devices to the channels? The ABB Documentation is kind of lacking information here.

Thanks

Fichte07 · January 7, 2023, 8:37am

I am using the names like i use them to login into my SysAP (e.g. Installer and one other user i tried).

What do you mean with

“your IP/swagger/users” overview

where can I find this overview?

Sleugner · January 7, 2023, 9:08am

Morning @Fichte07
@UhA described it in his guide that you posted under “Prerequisites”. You have to use the user name for your basic authentication of the local API.
Safest way is just to go Into your next app to free@home settings → local API. There you see the user name in a form like xxxxxx-xxxx-xxxx-xxxx-xxxxx.
Other way is to go into your browser and enter “IP of your SysAP/swagger” there you can create virtual devices and have a documentation from the API. Under Users you also have the alphanumerical codes for you users.
You can use that to map the code to the user so you will pic the right password, if you are not sure which user is behind the code.

Good luck.

UhA · January 7, 2023, 12:50pm

Hi @Sleugner,

Thank you… and I am very happy with your experience. If you have any issues please inform me, that I am able to fix it.

regarding your question to the API documentation for the virtual devices. the local API is defining the function IDs and pairing IDs to identify what you are able to do with the free@home device.

You shall query and parse these information from the free@home device by the swagger to know, what you are able to do with the device/channels.

My free@home binding is doing the same.

I will check how I can integrate the WeatherStation as a new supported device to the binding

UhA · January 7, 2023, 12:59pm

Hello All,

I noticed with the SysAP 2.6.3 some instabilities with the status updates via websocket. The instability was: the websocket communication was closed after 2 Days of runtime and the reset/reconnect was not completely smooth. Just the status update were affected, not the REST API set datapoint.

Why the SysAP closed the communication is strange, because this was a normal closure and no error.

But I could localize the instability and fixed for openHAB 3.4.x and I am using this version since 1st of January without any instabilities.

Here is the source code:

The binaries are here:

I will replicate this fix for the openHAB4.x.x and for the pull request.

Fichte07 · January 8, 2023, 8:52am

Thank for that hint…found out the UUID now in the format you mentioned. But still i am getting the same error. I am not really sure which user and which pw to use…confused…

UhA · January 8, 2023, 11:41am

Hi @Fichte07,

maybe you are using an older version of the binding. Therefore please update to the above binary, switch on the debug mode in open hab

Restart your raspberry or other device with openhab and please make sure that the local api is activated (needs at least 2.6.3 SysAP version)

For the binding please use your installer
User: installer, pass:

If you still have problem we can check together your log

Fichte07 · January 8, 2023, 12:45pm

I added the latest binary…after restarting and setting log level to DEBUG i get the following message when Disabling/Enabling the bridge thing:

Cannot open http connection

Using “Installer” as a user, same behaviour with SysAP UUID username.

Additonal: using SysAP version 2.6.4 and local API is activated under “settings/myBusch-Jaeger/connections/free@home API support”

UhA · January 8, 2023, 3:17pm

This is very strange, but it looks like that your password is not matching to the user.

But generally the built-in installer with the password you are using for the standard free@home web interface log-in shall work in the openHAB binding also.

One hint… The username for the SysAP is completely lower-case. If you are using the buil-in “Installer”, it shall work but you shall write it completely lower-case. It is different as you are log-in on the SysAP web interface. For the SysAP web-interface, the browser is showing to you the buil-in installer with “I” capital letter.

it means… the same installer in my SysAP

Shall look like for the REST API

Unfortunately the REST-API*Swagger is showing that you are successfully log in to the SysAP, even if you are writing the Installer with capital “I”, but the get/set methods will not work with the incorrect installer.

Therefore an easy test of your local API login is to check with the REST-API-Swagger to log-in and get/read-out the “Configuration” - The binding is doing the same as well, therefore says “not able to open the HTTP connection”. However some lines above this message in the LOG, you shall see “Wrong credentials for SysAP” also.

I hope that It could bring you nearer to solution

Fichte07 · January 10, 2023, 9:57am

Thanks for that hint with the capital “I”.

i changed to lower-case “i” in the binding/thing config and re-checked the PW, but still same result.

Need to setup swagger UI to test…will let you know.

I tried connection via a chrome API Tool (YARC), but not sure how to read the output. At least I am getting a 200-OK message while connecting.

Fichte07 · January 10, 2023, 3:17pm

Meanwhile also tried it with postman in chrome…
I am getting quite a long output like…

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html 
    xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0" />
        <meta name="apple-mobile-web-app-title" content="free@home"/>
        <meta name="mobile-web-app-capable" content="yes"/>
        <meta name="apple-mobile-web-app-capable" content="yes"/>
        <meta name="apple-mobile-web-app-status-bar-style" content="default"/>
        <meta name="apple-itunes-app" content="app-id=892486683"/>
        <meta name="google" value="notranslate"/>

…and a “200 - OK” message. Even without entering any credentials.

Any further ideas?

UhA · January 12, 2023, 6:53pm

Hi,

I checked with the postman and with the Swagger-API. Both are working. Basic Auth must be set-up

however you shall get a JASON output.
see:

UhA · January 15, 2023, 4:38pm

Hello all,

I added the virtual device handling in the binding. The virtual wether station and virtual switches are tested.

The wether station is working fine in my test. for the virtual switch an additional feedback needed for the use-case, if the virtual switch is switched on the f@h dashboard. The switch is working from the openHAB point of view, just the status update on the f@h dashboard is not done.

This is just a small work for the next days.

with virtual device handling you are able to communicate directly with the f@h system, no special messages and configuration for opeHAB is necessary.

The release can be found here, source code and binary

@Sleugner You could have a try with this virtual devices, maybe you could implement the connection easier

I would be very appreciate you could also test the new virtual devices

have a nice day

Sleugner · January 15, 2023, 6:15pm

Hey @UhA,
I will absolutely try the new binding.
I was about to wright you anyway. After implementing my hue color lights directly into free@home with the hue bridge I was hoping to also control it with OpenHAB. It does work with the additional “hue binding” but then it shows the wrong stats in free@home. Like your virtual switch.
Your old binding does find the hue dimActuator but no channels attached. Same thing with the WeatherStation. I will let you know how it is with the new version.
If you want to add another virtual device. The Dim Actuator would be nice. Then I can at least make the dimable lights work.

Quick question before I can test the binding. I never did update an external binding. Do I just have to switch the .jar file in my addons folder?
Or do I need to remove all the things first?

Thanks

kklausl · January 15, 2023, 6:46pm

Hello @UhA !
I really love to see you cover F@H and OH - since the possibilities (also thanks to @kjoglums ) are the reason, why I chose OH …

Since you are an expert on the API: May I kindly ask you to check the following:

I connected F@H, OH, Nodered and Netatmo to show all values form Netatmo or Amazon Sensors (e.g. CO2, Humidity, Temp, PM25, VOC, CO, etc.) also in F@H-App using the API and Virtual Devices, please see [here](AirQuality (eg. humidity + CO2 + temp) in free@home via 3rd-party-sensors - Busch-Jaeger Community - (see also the comments)).

I was able to integrate CO2, Humidity, Temp - but I failed with PM25, VOC, CO. Do you know how to integrate those other values in the same way? I was able to create PM25, VOC or CO-sensor and pass all values for F@H - but the values are not shown in the app.

I reached somehow a dead end - can you help?