henryspanka/freeathome-api

free@home-api 镜像文档

镜像概述和主要用途

free@home-api镜像是Busch-Jaeger free@home系统的API实现，用于控制各类执行器设备。该镜像暴露WebSocket和HTTP API接口，可接收并设置free@home执行器的状态变化，同时支持作为库集成到其他应用中。使用前需确保System Access Point固件版本为2.3.1或更高。

核心功能和特性

• 多协议支持：通过HTTP或WebSocket请求控制设备
• 设备控制：支持Busch-Jaeger灯光、插座、百叶窗等执行器
• 库集成：可作为Node.js库嵌入其他应用程序
• 加密通信：与System Access Point的通信采用加密和认证机制

支持的设备

• Busch-Jaeger System Access Point
• Busch-Jaeger System Access Point 2.0

系统要求

• Docker环境
• System Access Point固件版本 ≥ 2.3.1

使用方法和配置说明

Docker部署示例

使用以下命令启动容器：

sh
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

注意：将$IMAGE_ID替换为Docker Hub上的最新版本标签（不建议使用latest标签，因其可能包含未测试代码）。

环境变量配置

通过环境变量配置API，支持的变量如下：

查看容器日志

启动后可通过以下命令查看日志，确认认证是否成功：

sh
docker logs $CONTAINER_ID

其中$CONTAINER_ID为容器启动后返回的ID，可通过docker ps -a查询。

API端点

设置数据点

通过HTTP API设置设备数据点，请求路径格式：

raw/{serialNo}/{channel}/{datapoint}/{value}

获取所有执行器状态

发送请求获取所有设备状态：

info

获取特定执行器状态

获取指定设备状态，请求路径格式：

info/{serialNo}

实时更新

WebSocket客户端会自动接收实时更新，更新消息格式包含{type: 'update'}字段。

安全说明

与System Access Point的通信采用非对称加密和认证机制，与浏览器访问System Access Point使用相同的加密方式。

注意事项

• 该API处于早期开发阶段，可能存在功能限制
• 已知问题：System Access Point重启后，有时需重新登录其管理界面以启用WebSocket通知功能

免责声明

本API为第三方独立开发，与ABB或Busch-Jaeger无关联。可能与未来free@home固件更新不兼容，使用时需自行承担风险。软件按"原样"提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权性。作者不对任何因使用本软件导致的索赔、损害或其他责任负责。