ESP32 HomeKit Development with IDF

Overview

This repository provides a step-by-step guide to developing HomeKit accessories using ESP32 and the ESP-IDF framework.

Prerequisites

Ensure you have the necessary software installed before proceeding:

1. Setup Development Environment

Docker

Install Docker Desktop for Mac.
Sign in to your Docker account.
Pull the latest ESP-IDF version:
```
docker pull espressif/idf:v5.3
```

Python Installation

Check if Python 3 is installed:

python3 --version

If not installed:

xcode-select --install  # Install Xcode
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"  # Install Homebrew
brew install python3  # Install Python 3

PIP Installation

python3 -m ensurepip

ESP Tool Installation

Ensure Python 3.10.1 or newer is installed, then run:

pip3 install esptool

Getting Started with ESP32 HomeKit - LED

1. Clone the Repository

git clone --recursive https://github.com/AchimPieters/esp32-homekit-demo.git

2. Set Up Docker Environment

docker run -it -v ~/esp32-homekit-demo:/project -w /project espressif/idf:v5.3

3. Configuration

cd examples/led
idf.py set-target esp32
idf.py menuconfig

Configure Wi-Fi credentials under StudioPieters:

Wi-Fi SSID: (mysid)
Wi-Fi Password: (mypassword)

Save and exit.

4. Build and Flash ESP32

idf.py build
esptool.py erase_flash
python -m esptool --chip esp32 -b 460800 --before default_reset --after hard_reset write_flash \
--flash_mode dio --flash_size 4MB --flash_freq 40m \
0x1000 build/bootloader/bootloader.bin \
0x8000 build/partition_table/partition-table.bin \
0x10000 build/main.bin

5. View Serial Output

screen /dev/tty.usbserial-01FD1166 115200

Replace /dev/tty.usbserial-01FD1166 with your USB port.

Connecting ESP32 to HomeKit

1. Open HomeKit App

Launch your HomeKit app on your smartphone.

2. Scan QR Code

Scan the generated QR code to add your ESP32 device.

3. Add Device

Accept the uncertified accessory prompt and add the device.

4. Control the LED

Toggle the LED on/off directly from the HomeKit app.

5. Customize Automations (Optional)

Set up HomeKit automations for advanced functionality.

Generating a QR Code for ESP32 HomeKit

Setup Code

The HomeKit setup code must be an 8-digit number, formatted as XXX-XX-XXX (e.g., 101-48-005).

Setup ID

Each accessory needs a unique 4-character setup ID (e.g., 1QJ8).

homekit_server_config_t config = {
     .accessories = accessories,
     .password = "123-45-678",
     .setupId = "1QJ8",
};

Generate the QR Code

Ensure Python and required libraries are installed:

python3 -m pip install --upgrade pip Pillow qrcode

Generate the QR code:

tools/gen_qrcode 5 123-45-678 1QJ8 qrcode.png

5: HomeKit accessory category (Lighting)
123-45-678: Setup code
1QJ8: Setup ID
qrcode.png: Output file

HomeKit Accessory Categories

Category	Number
Other	1
Bridges	2
Fans	3
Garage Door Openers	4
Lighting	5
Locks	6
Outlets	7
Switches	8
Thermostats	9
Sensors	10
Security systems	11
Doors	12
Windows	13
Window coverings	14
Programmable switches	15
Range extenders	16
IP cameras	17
Video doorbells	18
Air purifiers	19
Heaters	20
Air conditioners	21
Humidifiers	22
Dehumidifiers	23
Apple TV	24
Speakers	26
Airport	27
Sprinklers	28
Faucets	29
Shower heads	30
Televisions	31
Target remotes	32

For the full list, refer to the official HomeKit documentation.

Conclusion

By following this guide, you've successfully set up an ESP32-based HomeKit accessory using ESP-IDF. Happy coding!

_{__________________________________________________________________________________________}

MIT License

_{Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:}

_{The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.}

_{THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.}

_{__________________________________________________________________________________________}

WORKS WITH APPLE HOME BADGE

_{The Works with Apple Home badge can be used to visually communicate that your accessory is compatible with the Apple Home and Siri on Apple devices. If you plan to develop or manufacture a HomeKit accessory that will be distributed or sold, your company needs to be enrolled in the MFi Program.}

_{__________________________________________________________________________________________}

APPLE HOME

_{HomeKit Accessory Protocol (HAP) is Apple’s proprietary protocol that enables third-party accessories in the home (e.g., lights, thermostats and door locks) and Apple products to communicate with each other. HAP supports two transports, IP and Bluetooth LE. The information provided in the HomeKit Accessory Protocol Specification (Non-Commercial Version) describes how to implement HAP in an accessory that you create for non-commercial use and that will not be distributed or sold.}

_{The HomeKit Accessory Protocol Specification (Non-Commercial Version) can be downloaded from the HomeKit Apple Developer page.}