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

pip3 install HAP-python homekit --user

2. Pair Devices

Pair your devices before first use:

# 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

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:

python3 scripts/homekit.py on living-light

Turn off:

python3 scripts/homekit.py off living-light

Set brightness (0-100):

python3 scripts/homekit.py brightness living-light 50

View Device Status

python3 scripts/homekit.py status living-light

Device Management

Discover new devices:

python3 scripts/homekit.py discover --timeout 10

Unpair a device:

python3 scripts/homekit.py unpair living-light

Supported Device Types

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

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

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