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  On true
scripts/homebridge_api.py set  On false
Adjust brightness
scripts/homebridge_api.py set  Brightness 75
Set color
scripts/homebridge_api.py set  Hue 120
scripts/homebridge_api.py set  Saturation 100

Get Accessory Status

scripts/homebridge_api.py get 

Tips

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"
   }