homebridge

Homebridge Control

Control smart home devices through Homebridge Config UI X's REST API.

Prerequisites

1. Homebridge with Config UI X installed and running
2. 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