Busch-Jaeger free@home API to control actuators.
This API exposes a websocket and HTTP API which can be used to receive and set state changes of free@home actuators. It can be used as a library as well in other applications. It requires a System Access Point with version 2.3.1 or higher.
Version | Supported | Notes |
---|---|---|
3.0.1 | :heavy_check_mark: | no known issues |
2.5.0 | :heavy_check_mark: | no known issues |
2.4.0 | :heavy_check_mark: | no known issues |
2.3.1 | :heavy_check_mark: | no known issues |
You can install free@home-api both locally or globally. Choose whatever works best for you. I recommend local installation to keep all related project files in the same directory.
Alternatively you can also use docker if Node >= 10 is not available or you want to isolate the API from the rest of your system using containers.
npm install freeathome-api --save
node node_modules/freeathome-api/bin/freeathome-api
npm install freeathome-api -g
freeathome-api
Run the docker container with:
docker run -d -p 8080:8080 -p 8081:8081 \
-e FREEATHOME_HOSTNAME=bj.example.com \
-e FREEATHOME_USERNAME=freeathome \
-e FREEATHOME_PASSWORD=mypassword \
henryspanka/freeathome-api:$IMAGE_ID
Replace $IMAGE_ID with the latest version on Docker Hub. Do not use the latest tag unless necessary as it is built from the master branch and may contain untested code/features.
For more configuration options see Configuration.
To view the logs and see if any errors during authentication occurred run:
docker logs $CONTAINER_ID
Replace $CONTAINER_ID with the id that is shown after starting the docker container. Alternatively check with docker ps -a
freeathome-api
as a librarynpm install freeathome-api
in your application for which you want control over busch jaeger devicesJavascript:
"use strict";
const {SystemAccessPoint} = require("freeathome-api");
module.exports = class FreeAtHomeApi {
constructor() {
this._connected = false
const config = {
hostname: "192.168.2.164",
username: "API",
password: "12345",
};
this.systemAccessPoint = new SystemAccessPoint(
config,
this, // instance to report broadcastMessages
);
}
async start() {
console.log("Starting free@home API");
try {
await this.systemAccessPoint.connect();
this._connected = true
} catch (e) {
console.error("Could not connect to SysAp: ", e);
this._connected = false
}
}
async stop() {
if (this._connected) {
console.log("Stopping free@home API")
await this.systemAccessPoint.disconnect()
this._connected = false
}
}
/**
* @param message
*/
broadcastMessage(message) {
// Do nothing when receiving a message from SysAccessPoint
}
async getAllDevices() {
if (this._connected) {
console.log("Getting device info");
try {
const response = await this.systemAccessPoint.getDeviceData();
console.log(response);
return response;
} catch (e) {
console.error("Error getting device data", e);
return {};
}
}
}
/**
*
* @param deviceId
* @param channel
* @param dataPoint
* @param value
* @returns {Promise<void>}
*/
async set(deviceId, channel, dataPoint, value) {
console.log(
`Setting (device, channel, datapoint, value): ${deviceId}, ${channel}, ${dataPoint}, ${value}`
);
if (this._connected) {
return await this.systemAccessPoint.setDatapoint(
deviceId.toString(),
channel.toString(),
dataPoint.toString(),
value.toString()
);
}
}
};
You can automatically start the API on boot. The following example is for Linux when using the local install (installed in /opt/freeathome-api). You may need to adjust the script if the API is installed globally.
Copy the contents of the following code section to /etc/systemd/system/freeathome-api.service
and run systemctl daemon-reload
.
You can then enable the service to auto-start on boot with systemctl enable freeathome-api.service
and start it with systemctl start freeathome-api.service
[Unit]
Description=freeathome API Service
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/node node_modules/freeathome-api/bin/freeathome-api
Restart=on-failure
User=freeathome
Group=freeathome
WorkingDirectory=/opt/freeathome-api
[Install]
WantedBy=multi-user.target
I recommend running the API as a separate user. For this example I have first created a new user with adduser --system --group --home /opt/freeathome-api freeathome
The API can be configured using a config.json
or using environment variables. For unexperienced users I recommend using the config.json
.
config.json
The API will look for the configuration file in the directory from which the API is executed. Make sure to set your working directory accordingly.
Copy the config.example.json to config.json
and edit it accordingly.
If installed locally, you can copy the example file with: cp node_modules/freeathome-api/config.example.json ./config.json
The following environment variables can be set to configure the API:
Name | Required | Type | Default Value | Description |
---|---|---|---|---|
FREEATHOME_HOSTNAME | yes | string | Hostname where we will connect to | |
FREEATHOME_USERNAME | yes | string | System Access Point Username | |
FREEATHOME_PASSWORD | yes | string | System Access Point Password | |
FREEATHOME_HTTP_ENABLED | no | 0 | 1 | 1 | Enable/Disable the HTTP API |
FREEATHOME_WS_ENABLED | no | 0 | 1 | 1 | Enable/Disable the Websocket API |
FREEATHOME_DEBUG | no | 0 | 1 | 0 | Enable/Disable Debug Logging |
The environment variables can be passed to node with (When using local installation):
FREEATHOME_HOSTNAME=bj.example.com FREEATHOME_USERNAME=freeathome FREEATHOME_PASSWORD=mypassword node_modules/freeathome-api/bin/freeathome-api
The communication with the System Access Point is encrypted and authenticated with asymmetric encryption. This API uses the same encryption as used by the Browser when communicating with the System Access Point.
This API is still in an early state. After Busch-Jaeger released an updated firmware (>= 2.3.0), which is not compatible with other APIs anymore, I have written a new API from scratch to bring my home back to life and make Apple HomeKit work again (homebridge-freeathome). I have tried to keep the API endpoints of sstadlberger/home's API so I don't need to rewrite all my plugins to integrate with a new API. Therefore this project should be backwards-compatible.
A datapoint can be set by sending the following payload to the API (for the HTTP based API send the payload as path):
raw/{serialNo}/{channel}/{datapoint}/{value}
To get the state of all actuators send the following payload: info
To get the state of a specific actuator send the following payload: info/{serialNo}
Real-Time updates are automatically sent to all connected websocket clients. Messages which have {type: 'update'}
set are updates.
This API reflects the internal XML structure of the ABB free@home API. Therefore, the cloud API is similar to this API.
The attribute functionID
describes what function a device or a channel has. Full list of functionIds
Examples for functionIds
:
The changelog can be viewed here.
Upgrade Notes can be found in the CHANGELOG.
If you have any questions or help please open an issue on the GitHub project page.
Pull requests are always welcome.
If you find my work useful you can support the ongoing development of this project by buying me a cup of coffee
The project is subject to the MIT license unless otherwise noted. A copy can be found in the root directory of the project LICENSE.
This API is a private contribution and not related to ABB or Busch-Jaeger. It may not work with future updates of the free@home firmware and can also cause unintended behavior. Use at your own risk!
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.