homekit-proxy

HomeKit Proxy

HomeKit Proxy is a lightweight, self-hosted bridge that exposes your shell commands as HomeKit accessories. It allows you to control your custom devices and scripts through Apple's Home app and Siri.

Features

• HomeKit Bridge: Exposes shell commands as HomeKit accessories.
• Device Configuration: Configure devices and their characteristics using a simple YAML file (device.yaml).
• Automations: Schedule shell commands to run at specific times using cron expressions (automation.yaml).
• Web UI: A simple web interface to view the status of your accessories and automations, and to manually trigger automations.
• Action Log: Logs all actions to a SQLite database for auditing and debugging.
• Configuration Hot-Reload: Automatically reloads the server when configuration files are changed.
• Customizable: Customize network interface, address, and PIN code.

How it Works

HomeKit Proxy works by creating a virtual HomeKit bridge. You define your accessories and their characteristics in a device.yaml file. For each characteristic, you specify shell commands to get or set its value. The proxy then exposes these accessories to your HomeKit network.

When you interact with an accessory in the Home app (e.g., turn on a light), HomeKit Proxy executes the corresponding shell command. It can also periodically poll the get command to keep the state of the accessory up-to-date.

Getting Started

Prerequisites

• Go 1.18 or later

Installation

1. Clone the repository:

   git clone https://github.com/waynezhang/homekit-proxy.git
   cd homekit-proxy
   

2. Build the binary:

   make build
   

   The binary will be located in the bin directory.

Configuration

1. Create a config directory:

   mkdir config
   

2. Create a device.yaml file in the config directory. See the device.sample.yaml for an example.

3. Create an automation.yaml file in the config directory. See the automation.sample.yaml for an example.

Running the Proxy

./bin/homekit-proxy serve --config ./config --db ./db

This will start the HomeKit Proxy server. You can then add the bridge to your Home app by scanning the QR code displayed in the console or by entering the PIN code.

Configuration

See config/device.sample.yaml and config/automation.sample.yaml.

Environment Variables

Web UI

HomeKit Proxy provides a simple web UI to view the status of your accessories and automations. You can access it at http://bindaddr.

The web UI also allows you to manually trigger automations.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the MIT License. See the LICENSE file for details.