Homebridge Control
Control smart home devices through Homebridge Config UI X's REST API.
Prerequisites
- Homebridge with Config UI X installed and running
- Credentials file at
~/.clawdbot/credentials/homebridge.json
:
{
"url": "https://homebridge.local:8581",
"username": "admin",
"password": "your-password"
}
API Overview
Homebridge Config UI X exposes a REST API. View full documentation at
{HOMEBRIDGE_URL}/swagger
.
Authentication
All API calls require a Bearer token. Obtain it first:
# Get auth token
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')
Common Operations
List All Accessories
curl -s "${HOMEBRIDGE_URL}/api/accessories" \
-H "Authorization: Bearer ${TOKEN}" | jq
Response includes accessory
uniqueId
,
serviceName
,
type
, and current
values
.
Get Accessory Layout (Rooms)
curl -s "${HOMEBRIDGE_URL}/api/accessories/layout" \
-H "Authorization: Bearer ${TOKEN}" | jq
Control an Accessory
Use PUT to update accessory characteristics:
# Turn on a light/switch
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"characteristicType": "On", "value": true}'
Turn off
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d '{"characteristicType": "On", "value": false}'
Set brightness (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}'
Set color (Hue: 0-360, Saturation: 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}'
Set thermostat target temperature
curl -s -X PUT "${HOMEBRIDGE_URL}/api/accessories/{uniqueId}"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d '{"characteristicType": "TargetTemperature", "value": 22}'
Common Characteristic Types
| Type | Values | Description |
|---|
On
| true
/false
| Power state |
Brightness
| 0-100
| Light brightness % |
Hue
| 0-360
| Color hue in degrees |
Saturation
| 0-100
| Color saturation % |
ColorTemperature
| 140-500
| Color temp in Mired |
TargetTemperature
| 10-38
| Thermostat target °C |
TargetHeatingCoolingState
| 0-3
| 0=Off, 1=Heat, 2=Cool, 3=Auto |
RotationSpeed
| 0-100
| Fan speed % |
Active
| 0
/1
| Active state (fans, etc.) |
Using the Scripts
For convenience, use the provided scripts:
List Accessories
scripts/homebridge_api.py list
scripts/homebridge_api.py list --room "Living Room"
scripts/homebridge_api.py list --type Lightbulb
Control Devices
# Turn on/off
scripts/homebridge_api.py set <uniqueId> On true
scripts/homebridge_api.py set <uniqueId> On false
Adjust brightness
scripts/homebridge_api.py set <uniqueId> Brightness 75
Set color
scripts/homebridge_api.py set <uniqueId> Hue 120
scripts/homebridge_api.py set <uniqueId> Saturation 100
Get Accessory Status
scripts/homebridge_api.py get <uniqueId>
Tips
- Find your accessory's
uniqueId
by listing all accessories first
- The API documentation at
/swagger
shows all available endpoints
- Characteristic names are case-sensitive (use
On
not on
)
- Some accessories may have multiple services; check the response for service types
- Token expires after some time; re-authenticate if you get 401 errors
