Homekit

---
name: homekit
description: Control Apple HomeKit smart home devices. Supports listing, discovering, pairing devices, and controlling lights, switches, outlets, thermostats. Use when the user needs to manage HomeKit accessories programmatically. Requires homekit library and paired devices.
---

# HomeKit Smart Home Controller

Control Apple HomeKit smart home devices using Python scripts.

## Features

- 🔍 Discover unpaired devices
- 🔗 Pair/Unpair devices
- 📱 List all paired devices
- 💡 Control light switches and brightness
- 🔌 Control outlets and switches
- 🌡️ View device status

## Prerequisites

### 1. Install Dependencies

```bash
pip3 install HAP-python homekit --user
```

### 2. Pair Devices

Pair your devices before first use:

```bash
# Discover devices
python3 scripts/homekit.py discover

# Pair a device
python3 scripts/homekit.py pair "Device Name" "XXX-XX-XXX" "alias"
```

The pairing code is usually found in the device manual or on the device itself (format: XXX-XX-XXX).

## Usage

### List All Devices

```bash
python3 scripts/homekit.py list
```

Example output:
```
📱 Found 3 devices:

Alias           Name                      Type            Status
----------------------------------------------------------------------
💡 living-light  Living Room Light         Lightbulb       on (80%)
🔌 desk-outlet   Desk Outlet               Outlet          off
💡 bedroom-lamp  Bedside Lamp              Lightbulb       off
```

### Control Devices

**Turn on:**
```bash
python3 scripts/homekit.py on living-light
```

**Turn off:**
```bash
python3 scripts/homekit.py off living-light
```

**Set brightness (0-100):**
```bash
python3 scripts/homekit.py brightness living-light 50
```

### View Device Status

```bash
python3 scripts/homekit.py status living-light
```

### Device Management

**Discover new devices:**
```bash
python3 scripts/homekit.py discover --timeout 10
```

**Unpair a device:**
```bash
python3 scripts/homekit.py unpair living-light
```

## Supported Device Types

| Type | Supported Operations |
|------|---------|
| 💡 Lightbulb | On/Off, Brightness |
| 🔌 Outlet | On/Off |
| 🔲 Switch | On/Off |
| 🌡️ Thermostat | View temp, Set target temp |
| 🌀 Fan | On/Off, Speed |

## Troubleshooting

**Error: homekit library not installed**
→ Run: `pip3 install HAP-python homekit --user`

**Error: Device not found**
→ Ensure the device and computer are on the same WiFi network.

**Error: Pairing failed**
→ Check if the pairing code is correct and the device is in pairing mode.

**Device shows offline**
→ Try re-pairing or check device power.

## Advanced Usage

### Batch Control

```bash
# Turn off all lights
for device in living-light bedroom-lamp kitchen-light; do
    python3 scripts/homekit.py off $device
done
```

### Scene Script Example

Create `~/scripts/goodnight.sh`:
```bash
#!/bin/bash
# Goodnight Scene: Turn off all lights except a dim bedside lamp

python3 ~/.openclaw/workspace/homekit/scripts/homekit.py off living-light
python3 ~/.openclaw/workspace/homekit/scripts/homekit.py off kitchen-light
python3 ~/.openclaw/workspace/homekit/scripts/homekit.py brightness bedroom-lamp 10

echo "Goodnight 😴"
```

## References

- HomeKit Official Docs: https://developer.apple.com/homekit/
- Library Docs: https://github.com/jlusiardi/homekit_python