{"id":15747376,"url":"https://github.com/henry-spanka/freeathome-api","last_synced_at":"2025-04-09T12:05:44.567Z","repository":{"id":35138035,"uuid":"211529007","full_name":"henry-spanka/freeathome-api","owner":"henry-spanka","description":"Busch-Jaeger free@home API to control actuators","archived":false,"fork":false,"pushed_at":"2025-01-15T15:37:47.000Z","size":260,"stargazers_count":45,"open_issues_count":9,"forks_count":4,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-02T11:09:08.261Z","etag":null,"topics":["abb","api","busch-jaeger","buschjaeger","freeathome","nodejs","smarthome"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/henry-spanka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.me/Hspanka"]}},"created_at":"2019-09-28T16:25:25.000Z","updated_at":"2024-08-31T12:19:58.000Z","dependencies_parsed_at":"2024-06-19T06:18:07.692Z","dependency_job_id":"666279cc-b1e5-4ff9-90e8-31804981b5b0","html_url":"https://github.com/henry-spanka/freeathome-api","commit_stats":{"total_commits":74,"total_committers":4,"mean_commits":18.5,"dds":"0.18918918918918914","last_synced_commit":"bda6de3432a5d5b2d64c08d4cd5eeafbb2b9fa9e"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henry-spanka%2Ffreeathome-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henry-spanka%2Ffreeathome-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henry-spanka%2Ffreeathome-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henry-spanka%2Ffreeathome-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/henry-spanka","download_url":"https://codeload.github.com/henry-spanka/freeathome-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036063,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abb","api","busch-jaeger","buschjaeger","freeathome","nodejs","smarthome"],"created_at":"2024-10-04T05:05:12.329Z","updated_at":"2025-04-09T12:05:44.542Z","avatar_url":"https://github.com/henry-spanka.png","language":"TypeScript","funding_links":["https://www.paypal.me/Hspanka"],"categories":[],"sub_categories":[],"readme":"[Install Homebridge]: https://github.com/nfarina/homebridge#installation\n[Install Busch-Jaeger API]: https://github.com/sstadlberger/home\n[Configuration]: #api-configuration\n\n[sstadlberger]: https://github.com/sstadlberger\n[Home Hub]: https://support.apple.com/en-us/HT207057\n\n\n# free@home-api\n\nBusch-Jaeger free@home API to control actuators.\n\n[![NPM](https://nodei.co/npm/freeathome-api.png?compact=true)](https://npmjs.org/package/freeathome-api)\n\n# Description\nThis API exposes a websocket and HTTP API which can be used to receive and set state changes of free@home actuators. It\ncan be used as a library as well in other applications. \nIt requires a System Access Point with version 2.3.1 or higher.\n\n# Features\n* Control your Busch-Jaeger Lights, Outlets, Blinds, etc. via HTTP or Websocket requests\n\n# Supported devices\n- Busch-Jaeger System Access Point\n- Busch-Jaeger System Access Point 2.0\n\n# Tested Versions\n|Version|Supported|Notes|\n|---|---|---|\n|3.0.1|:heavy_check_mark:|no known issues|\n|2.5.0|:heavy_check_mark:|no known issues|\n|2.4.0|:heavy_check_mark:|no known issues|\n|2.3.1|:heavy_check_mark:|no known issues|\n\n# Requirements\n* Node.JS \u003e= 10\n* Linux or macOS (may run on Windows but not tested)\n\n# Setup / Installation\nYou 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.\n\nAlternatively you can also use docker if Node \u003e= 10 is not available or you want to isolate the API from the rest of your system using containers.\n\n## Locally\n1. Create a new directory for the project and enter it\n2. Run `npm install freeathome-api --save`\n3. See [Configuration](#api-configuration) section.\n4. Start the API with `node node_modules/freeathome-api/bin/freeathome-api`\n5. Star the repository ;)\n\n## Globally\n1. Run `npm install freeathome-api -g`\n2. See [Configuration](#api-configuration) section.\n3. Start the API with `freeathome-api`\n4. Star the repository ;)\n\n## Docker\nRun the docker container with:\n```sh\ndocker run -d -p 8080:8080 -p 8081:8081 \\\n-e FREEATHOME_HOSTNAME=bj.example.com \\\n-e FREEATHOME_USERNAME=freeathome \\\n-e FREEATHOME_PASSWORD=mypassword \\\nhenryspanka/freeathome-api:$IMAGE_ID\n```\n\nReplace *$IMAGE_ID* with the latest version on [Docker Hub](https://hub.docker.com/r/henryspanka/freeathome-api/tags).\nDo not use the *latest* tag unless necessary as it is built from the master branch and may contain untested code/features.\n\nFor more configuration options see [Configuration](#api-configuration).\n\nTo view the logs and see if any errors during authentication occurred run:\n```sh\ndocker logs $CONTAINER_ID\n```\n\nReplace *$CONTAINER_ID* with the id that is shown after starting the docker container. Alternatively check with `docker ps -a`\n\n## Use `freeathome-api` as a library\n1. Use `npm install freeathome-api` in your application for which you want control over busch jaeger devices\n1. Include package in code:\n\nJavascript:\n```ecmascript 6\n\"use strict\";\nconst {SystemAccessPoint} = require(\"freeathome-api\");\n\nmodule.exports = class FreeAtHomeApi {\n    constructor() {\n        this._connected = false\n        const config = {\n            hostname: \"192.168.2.164\",\n            username: \"API\",\n            password: \"12345\",\n        };\n\n        this.systemAccessPoint = new SystemAccessPoint(\n            config,\n            this,      // instance to report broadcastMessages\n        );\n    }\n\n    async start() {\n        console.log(\"Starting free@home API\");\n\n        try {\n            await this.systemAccessPoint.connect();\n            this._connected = true\n        } catch (e) {\n            console.error(\"Could not connect to SysAp: \", e);\n            this._connected = false\n        }\n    }\n\n    async stop() {\n        if (this._connected) {\n            console.log(\"Stopping free@home API\")\n            await this.systemAccessPoint.disconnect()\n            this._connected = false\n        }\n    }\n\n    /**\n     * @param message\n     */\n    broadcastMessage(message) {\n        // Do nothing when receiving a message from SysAccessPoint\n\n    }\n\n    async getAllDevices() {\n        if (this._connected) {\n            console.log(\"Getting device info\");\n            try {\n                const response = await this.systemAccessPoint.getDeviceData();\n                console.log(response);\n                return response;\n            } catch (e) {\n                console.error(\"Error getting device data\", e);\n                return {};\n            }\n        }\n    }\n\n    /**\n     *\n     * @param deviceId\n     * @param channel\n     * @param dataPoint\n     * @param value\n     * @returns {Promise\u003cvoid\u003e}\n     */\n    async set(deviceId, channel, dataPoint, value) {\n        console.log(\n            `Setting (device, channel, datapoint, value): ${deviceId}, ${channel}, ${dataPoint}, ${value}`\n        );\n\n        if (this._connected) {\n            return await this.systemAccessPoint.setDatapoint(\n                deviceId.toString(),\n                channel.toString(),\n                dataPoint.toString(),\n                value.toString()\n            );\n        }\n    }\n};\n\n```\n\n\n# Automatically Start on Boot\nYou 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.\nCopy the contents of the following code section to `/etc/systemd/system/freeathome-api.service` and run `systemctl daemon-reload`.\n\nYou 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`\n\n```\n[Unit]\nDescription=freeathome API Service\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=/usr/bin/node node_modules/freeathome-api/bin/freeathome-api\nRestart=on-failure\nUser=freeathome\nGroup=freeathome\nWorkingDirectory=/opt/freeathome-api\n\n[Install]\nWantedBy=multi-user.target\n```\n\nI 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`\n\n# API Configuration\nThe API can be configured using a `config.json` or using environment variables. For unexperienced users I recommend using the `config.json`.\n\n## Using `config.json`\nThe API will look for the configuration file in the directory from which the API is executed. Make sure to set your working directory accordingly.\n\nCopy the [config.example.json](config.example.json) to `config.json` and edit it accordingly.\nIf installed locally, you can copy the example file with: `cp node_modules/freeathome-api/config.example.json ./config.json`\n\n## Using environment variables\nThe following environment variables can be set to configure the API:\n\n| Name                      | Required  | Type | Default Value | Description\n|---------------------------|-----------|---|---|---|\n| FREEATHOME_HOSTNAME       | yes       | string | | Hostname where we will connect to\n| FREEATHOME_USERNAME       | yes       | string | | System Access Point Username\n| FREEATHOME_PASSWORD       | yes       | string | | System Access Point Password\n| FREEATHOME_HTTP_ENABLED   | no        | 0 \\| 1 | 1 | Enable/Disable the HTTP API\n| FREEATHOME_WS_ENABLED     | no        | 0 \\| 1 | 1 | Enable/Disable the Websocket API\n| FREEATHOME_DEBUG          | no        | 0 \\| 1 | 0 | Enable/Disable Debug Logging\n\nThe environment variables can be passed to node with (When using local installation):\n\n```sh\nFREEATHOME_HOSTNAME=bj.example.com FREEATHOME_USERNAME=freeathome FREEATHOME_PASSWORD=mypassword node_modules/freeathome-api/bin/freeathome-api\n```\n\n\n# Security\nThe 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.\n\n# Note\nThis API is still in an early state. After Busch-Jaeger released an updated firmware (\u003e= 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](https://github.com/henry-spanka/homebridge-freeathome)). I have tried to keep the API endpoints of [sstadlberger/home](https://github.com/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.\n\n# Known Issues\n\n* If you do not receive any updates from the System Access Point or are unable to set any datapoints log into the System Access Point interface and log out again. This must be done sometimes after a reboot of the System Access Point to enable websocket notifications.\n\n# API Endpoints\n\n## Set a datapoint\nA datapoint can be set by sending the following payload to the API (for the HTTP based API send the payload as path):\n`raw/{serialNo}/{channel}/{datapoint}/{value}`\n\n## Get the state of all actuators\nTo get the state of all actuators send the following payload: `info`\n\n## Get the state of a specific actuator\nTo get the state of a specific actuator send the following payload: `info/{serialNo}`\n\n## Receive real-time updates\nReal-Time updates are automatically sent to all connected websocket clients. Messages which have `{type: 'update'}` set are updates.\n\n# Technical description\nThis API reflects the internal XML structure of the ABB free@home API. Therefore, the cloud API is similar to this API.\n\n## functionId\nThe attribute `functionID` describes what function a device or a channel has. [Full list of functionIds](https://developer.eu.mybuildings.abb.com/fah_cloud/reference/functionids/)\n\nExamples for `functionIds`:\n* 0x0000 \tFID_SWITCH_SENSOR \tControl element\n* 0x0001 \tFID_DIMMING_SENSOR \tDimming sensor\n* 0x0003 \tFID_BLIND_SENSOR \tBlind sensor\n* 0x0004 \tFID_STAIRCASE_LIGHT_SENSOR \tStairwell light sensor\n* 0x0005 \tFID_FORCE_ON_OFF_SENSOR \tForce On/Off sensor\n* 0x0006 \tFID_SCENE_SENSOR \tScene sensor\n* 0x0007 \tFID_SWITCH_ACTUATOR \tSwitch actuator\n* 0x0009 \tFID_SHUTTER_ACTUATOR \tBlind actuator\n* 0x000A \tFID_ROOM_TEMPERATURE_CONTROLLER_MASTER_WITH_FAN \tRoom temperature controller with fan speed level\n* 0x000B \tFID_ROOM_TEMPERATURE_CONTROLLER_SLAVE \tRoom temperature controller extension unit\n* 0x000C \tFID_WIND_ALARM_SENSOR \tWind Alarm\n* 0x000D \tFID_FROST_ALARM_SENSOR \tFrost Alarm\n* 0x000E \tFID_RAIN_ALARM_SENSOR \tRain Alarm\n* 0x000F \tFID_WINDOW_DOOR_SENSOR \tWindow sensor\n* 0x0011 \tFID_MOVEMENT_DETECTOR \tMovement Detector\n* 0x0012 \tFID_DIMMING_ACTUATOR \tDim actuator\n\n# Changelog\nThe changelog can be viewed [here](CHANGELOG.md).\n\n# Upgrade Notes\nUpgrade Notes can be found in the [CHANGELOG](CHANGELOG.md).\n\n# Help\nIf you have any questions or help please open an issue on the GitHub project page.\n\n# Contributing\nPull requests are always welcome.\n\n# Donation\nIf you find my work useful you can support the ongoing development of this project by buying me a [cup of coffee](https://www.paypal.me/Hspanka)\n\n# License\nThe project is subject to the MIT license unless otherwise noted. A copy can be found in the root directory of the project [LICENSE](LICENSE).\n\n# Disclaimer\nThis 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!\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenry-spanka%2Ffreeathome-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenry-spanka%2Ffreeathome-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenry-spanka%2Ffreeathome-api/lists"}