ESP32 HomeKit for TOTAL Beginners (Docker + ESP-IDF 5.4 + Demo LED Accessory)

A slow, friendly, step-by-step guide from zero to a working HomeKit accessory.

This is for you if you feel stuck because other tutorials assume you already know:

1. what Docker is
2. how firmware gets onto a microcontroller
3. what “flashing” means
4. why Wi-Fi configuration happens before compiling
5. what an ESP32 really is

By the end you will:

1. have a working ESP32 dev environment (without installing ESP-IDF manually)
2. compile firmware inside Docker
3. flash it to an ESP32-WROOM-32D
4. add it to Apple Home
5. understand what you’re doing (not just copy/paste magic)

What we’re building (big picture)

1. Prepare your computer
2. Install Docker
3. Download ready-made ESP32 HomeKit demo code
4. Configure Wi-Fi
5. Compile firmware
6. Flash to ESP32
7. Add to Apple Home

You need one of these:

Option A (recommended / easiest)

1. ESP32-WROOM-32D development board (USB built in, buttons, beginner-friendly)

Option B (advanced but fine)

1. Bare ESP-WROOM-32 module
2. USB programmer / baseboard

Also needed:

1. USB data cable (not charge-only)
2. 2.4 GHz Wi-Fi network
3. iPhone or iPad with Apple Home

Software

We will install:

1. Docker Desktop
2. Git
3. Python 3
4. esptool.py

We will not manually install ESP-IDF. Docker handles that.

Docker is like a pre-built computer inside your computer.

Inside that mini-computer:

1. ESP32 tools are already installed
2. correct versions are already chosen
3. nothing breaks your real system

This avoids hours of beginner pain.

Download

Go to Docker Desktop and download for your OS (Windows/macOS/Linux).

Install

1. Run installer
2. Accept defaults
3. Finish
4. Restart your computer

After reboot:

1. open Docker Desktop
2. log in (free)
3. wait until it says “Docker is running”

Open a terminal:

1. Windows: PowerShell
2. macOS: Terminal
3. Linux: Terminal

Run:

Good output looks like:

Now run:

You’ll likely see an empty list. That’s perfect.

If it errors: Docker Desktop is not running.

We use the official Espressif Docker image so everyone builds with the same toolchain.

Download it:

Verify it exists:

You should see something like:

Nothing is running yet — that’s normal.

If you ever want to remove it later:

Install Git from the Git website using default options.

Check it works:

We build firmware in Docker, but flashing a real ESP32 is easiest from your normal computer.

Check Python:

Good:

Install esptool:

Verify:

Good:

Common problems

“pip not found”

Permission errors (macOS/Linux)

Windows issues

1. re-open terminal
2. ensure Python is in PATH
3. use:

In your terminal:

Enter the folder:

You should see folders like:

1. examples
2. components
3. CMakeLists.txt

Now we “enter the development box”.

macOS / Linux

Windows (example path)

What this means:

1. your folder is shared with Docker
2. Docker can read/write your files
3. ESP32 tools are now available

Inside the Docker terminal:

Set target (ESP32 family):

Run:

In the blue menu, go to:

1. StudioPieters
2. set Wi-Fi SSID
3. set Wi-Fi password
4. Save and Exit

Compile:Type idf.py build and press enter, and wait until it is done.

After building, you should have:

1. bootloader.bin
2. partition-table.bin
3. main.bin

We’ll connect one LED so you can see the accessory work.

You need

1. 1 × LED
2. 1 × resistor (220Ω – 1kΩ)
3. 2 × jumper wires
4. breadboard (optional but recommended)

Pin used by the example

The LED example uses GPIO2.

LED polarity

1. long leg = positive (+)
2. short leg = negative (–)

If it’s backwards, nothing breaks — it just won’t light.

Wiring

Connect:

1. GPIO2 → resistor → LED → GND

Open a new terminal outside Docker and go to the example folder:

Erase:

While erasing, esptool shows the port name. Write it down.

Examples:

1. macOS: /dev/cu.usbserial-XXXX or /dev/cu.SLAB_USBtoUART
2. Linux: /dev/ttyUSB0 or /dev/ttyACM0
3. Windows: COM3, COM4, etc.

If it does NOT connect (common)

1. Hold BOOT
2. Press and release RESET
3. Release BOOT
4. Run erase again

Replace the port name (if needed for your system) and run:

When it finishes: firmware is on the ESP32.

We use a serial monitor to see what the ESP32 is doing.

Start serial monitor (macOS example)

Use the same port you saw earlier:

If you see nothing, press RESET on the board.

What you should see:

1. ESP32 boot info
2. Wi-Fi connection messages
3. HomeKit startup logs

Example HomeKit logs:

Exit screen

1. CTRL + A

This is a DIY HomeKit accessory, so Apple will show warnings. That’s expected.

Before you start:

1. ESP32 powered on
2. connected to Wi-Fi (check serial logs)
3. iPhone/iPad on the same Wi-Fi network

Steps

1. Open the Home app
2. Tap +
3. Tap Add Accessory
4. Scan the QR code (or add anyway if prompted)
5. Select the accessory when it appears
6. Accept the “uncertified accessory” warning → tap Add Anyway (possibly twice)
7. Assign room/name (optional)
8. Test: Tap ON/OFF → LED should respond

If you reached this point:

1. ESP32 boots
2. Wi-Fi connects
3. HomeKit pairs
4. LED responds

You built a real HomeKit accessory!

Next ideas:

1. change the GPIO to another pin
2. add a relay instead of an LED
3. build a real accessory (switch, sensor, power plug, etc.)

More homekit projects can be found on studiopieters.nl