Start Here: Your First ESP32 HomeKit Accessory

ESP32 HomeKit projects look easy until the first hour, when Docker, ESP-IDF, flashing and pairing all arrive at once. This page puts the guides and projects on this site in the order that works for a first build, so each step prepares you for the next.

The path ends with a working HomeKit accessory that you can update over the air, and points to what to build after that.

1. Decide: HomeKit or Matter

Both keep control on your local network, but they work in different places and are certified differently. A few minutes here saves you from starting on the wrong path. If you only use Apple Home, HomeKit is the route the rest of this page follows.

HomeKit or Matter for your ESP32? How to choose › 5 min read

2. Know your board

The beginner guides use the ESP32-WROOM-32D. Its pinout guide lists every GPIO with its boot behaviour, so you know which pins are safe before you wire anything. Keep it open while you build.

ESP32-WROOM-32D pinout ›

3. Set up your tools, the easy way

You do not install ESP-IDF on your computer. The guide has you run it in Docker, using Espressif’s official image, and explains each tool in plain words: Docker, ESP-IDF, Git, Python and esptool. It goes on to configuring Wi-Fi, compiling, flashing and adding the accessory to Apple Home, so this is the longest step and the most important one.

ESP32 HomeKit for total beginners › 17 min read

4. Build your first accessory

A single LED you can switch from the Home app or with Siri, with no extra hub. It is small enough to finish in one sitting and proves that your toolchain, flashing and pairing all work.

HomeKit LED › 4 min read

5. Stop hard-coding Wi-Fi

Typing your Wi-Fi name and password into the firmware works for one device on your own desk. WiFi Bootstrap adds a captive portal for onboarding, stores the credentials in flash and has a SoftAP fallback. It is demonstrated with the same HomeKit LED you just built.

ESP32 WiFi Bootstrap › 5 min read

6. Update over the air

Once a device is installed somewhere awkward, you do not want to reach for a USB cable. Lifecycle Manager handles network setup and updates before your own application starts. This is a slow, friendly walk-through for OTA updates, written for people who get stuck early.

ESP32 Lifecycle Manager V2 › 21 min read

7. Label it like a real product

A small tool generates a HomeKit pairing label with a scannable QR code, the setup code, the MAC address and barcoded serials. Optional, but it makes sharing or giving away a device much easier than a code on a scrap of paper.

HomeKit QR code guide › 8 min read

Where to go next

• A colourful next build: HomeKit NeoPixel controller, an LED strip you control from the Home app, on a small ESP32-C3 board.
• Matter: esp32-matter is a toolkit for Matter devices on the ESP32, and it is under active development.
• Everything on one board or sensor: browse the guides for pinouts and component references.

Stuck?

Check the FAQ first. If your question is not there, use the contact form and say which step you are on, which board you have and what you already tried.