名称： homebridge
描述： "通过 Homebridge Config UI X 的 REST API 控制智能家居设备。可用于列出、开关、调节亮度、颜色或色温等 HomeKit 兼容配件。支持灯、开关、温控器、风扇及其他由 Homebridge 管理的设备。"
主页： https://github.com/homebridge/homebridge-config-ui-x
元数据： { "clawdbot": { "emoji": "🏠" } }

Homebridge 控制

通过 Homebridge Config UI X 的 REST API 控制智能家居设备。

前提条件

1. 已安装并运行 Homebridge 及 Config UI X 插件
2. 凭证文件位于 ~/.clawdbot/credentials/homebridge.json：
   json { "url": "https://homebridge.local:8581", "username": "admin", "password": "your-password" }

API 概览

Homebridge Config UI X 提供 REST API。完整文档可在 {HOMEBRIDGE_URL}/swagger 查看。

认证

所有 API 调用都需要 Bearer 令牌。请先获取令牌：

# 获取认证令牌
TOKEN=$(curl -s -X POST "${HOMEBRIDGE_URL}/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${HOMEBRIDGE_USERNAME}\",\"password\":\"${HOMEBRIDGE_PASSWORD}\"}" \
  | jq -r '.access_token')

常用操作

列出所有配件

curl -s "${HOMEBRIDGE_URL}/api/accessories" \
  -H "Authorization: Bearer ${TOKEN}" | jq

响应包含配件的 uniqueId、serviceName、type 及当前 values。

获取配件布局（房间）

curl -s "${HOMEBRIDGE_URL}/api/accessories/layout" \
  -H "Authorization: Bearer ${TOKEN}" | jq

控制配件

使用 PUT 方法更新配件特性：

# 打开灯/开关
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "On", "value": true}'

# 关闭
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "On", "value": false}'

# 设置亮度 (0-100)
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "Brightness", "value": 50}'

# 设置颜色 (色相: 0-360, 饱和度: 0-100)
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "Hue", "value": 240}'

# 设置温控器目标温度
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"characteristicType": "TargetTemperature", "value": 22}'

常用特性类型

使用脚本

为方便起见，可使用提供的脚本：

列出配件

scripts/homebridge_api.py list
scripts/homebridge_api.py list --room "Living Room"
scripts/homebridge_api.py list --type Lightbulb

控制设备

# 开关
scripts/homebridge_api.py set <uniqueId> On true
scripts/homebridge_api.py set <uniqueId> On false

# 调节亮度
scripts/homebridge_api.py set <uniqueId> Brightness 75

# 设置颜色
scripts/homebridge_api.py set <uniqueId> Hue 120
scripts/homebridge_api.py set <uniqueId> Saturation 100

获取配件状态

scripts/homebridge_api.py get <uniqueId>

提示

• 首次使用前，请先列出所有配件以获取 uniqueId
• /swagger 处的 API 文档展示了所有可用端点
• 特性名称区分大小写（使用 On 而非 on）
• 部分配件可能包含多个服务；请检查响应中的服务类型
• 令牌会在一段时间后过期；若收到 401 错误，请重新认证