✓ Verified 💻 Development ✓ Enhanced Data

Homebridge

Control smart home devices via Homebridge Config UI X.

Rating: 4.8 (351 reviews)
Downloads: 47,771 downloads
Version: 1.0.0

Overview

Control smart home devices via Homebridge Config UI X.

Complete Documentation

View Source →

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:

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:

bash

# 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

bash

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

Response includes accessory uniqueId, serviceName, type, and current values.

Get Accessory Layout (Rooms)

bash

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

Control an Accessory

Use PUT to update accessory characteristics:

bash

# 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

bash

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

Control Devices

bash

# 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

bash

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

Installation

Terminal bash


openclaw install homebridge

Copied!

💻Code Examples

| jq -r '.access_token')

--jq--r-accesstoken.txt

## Common Operations

### List All Accessories

-H "Authorization: Bearer ${TOKEN}" | jq

--h-authorization-bearer-token--jq.txt

Response includes accessory `uniqueId`, `serviceName`, `type`, and current `values`.

### Get Accessory Layout (Rooms)

-H "Authorization: Bearer ${TOKEN}" | jq

--h-authorization-bearer-token--jq.txt

### Control an Accessory

Use PUT to update accessory characteristics:

-d '{"characteristicType": "TargetTemperature", "value": 22}'

--d-characteristictype-targettemperature-value-22.txt

### 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

example.json

{
     "url": "https://homebridge.local:8581",
     "username": "admin",
     "password": "your-password"
   }

example.sh

# 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')

example.sh

# 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}'

example.sh

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

example.sh

# 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