ESP32 HomeKit Projects: The 2026 HomeSpan Smart Relay Build & Debug Guide

Building native Apple HomeKit accessories on the ESP32 platform has evolved significantly. While early projects relied on fragmented forks of Apple's deprecated ADK, the 2026 standard for ESP32 HomeKit projects is the HomeSpan library. It handles the complex HomeKit Accessory Protocol (HAP) cryptography, mDNS broadcasting, and state management natively within the Arduino framework.

This guide walks through building a robust, opto-isolated smart relay with physical push-button override, targeting the ESP32-S3 architecture. We will cover the hardware decision matrix, exact pin mapping, production-ready code with error handling, and a debugging playbook for the most common HAP pairing failures.

1. The 2026 Decision Matrix: Which ESP32 for HomeKit?

HomeKit requires significant SRAM for HAP cryptography and mDNS service records. Choosing the wrong silicon variant results in silent memory allocation failures during pairing. Use this decision tree to select your board:

2. Parts List & Pin Mapping for the Smart Relay Build

This build controls a 120V/240V AC load via a 5V mechanical relay, while providing a local tactile button for manual override. The relay module must be opto-isolated to prevent AC back-EMF from resetting the ESP32-S3's sensitive 3.3V logic.

Bill of Materials

• MCU: ESP32-S3-DevKitC-1 (N8R2 variant with 8MB Flash / 2MB PSRAM)
• Relay Module: 5V 1-Channel Opto-Isolated Relay (Omron G5LE-14 or Songle SRD-05VDC-SL-C)
• Switch: 12x12mm Tactile Pushbutton (Momentary NO)
• Resistor: 10kΩ (for hardware pull-up redundancy, though internal pull-ups are used)
• Power: 5V 2A USB-C Power Supply (Do not use unregulated wall-warts; HAP crypto spikes draw >300mA transient current)

Pin Mapping Table

3. Complete HomeSpan Code with Error Handling

The following code targets the ESP32-S3-DevKitC-1 (N8R2). It uses the HomeSpan library to expose the relay as a Lightbulb service, allowing Siri to control it via "Turn on the Smart Relay". It includes a non-blocking debounce routine for the physical button and a hard halt if the WiFi connection fails during setup.

Prerequisite: Install the HomeSpan library via the Arduino Library Manager and select "ESP32S3 Dev Module" in the Boards menu. Ensure "OPI PSRAM" is enabled in the Tools menu.

#include "HomeSpan.h"

// --- PIN DEFINITIONS ---
const int RELAY_PIN = 4;
const int BUTTON_PIN = 5;

// --- CUSTOM HAP SERVICE ---
struct DEV_Relay : Service::LightBulb {
  SpanCharacteristic *power;
  int relayPin;
  int buttonPin;
  int lastButtonState;
  unsigned long lastDebounceTime;
  const unsigned long debounceDelay = 50;

  DEV_Relay(int rPin, int bPin) : Service::LightBulb("Smart Relay") {
    power = new Characteristic::On();
    relayPin = rPin;
    buttonPin = bPin;
    
    pinMode(relayPin, OUTPUT);
    pinMode(buttonPin, INPUT_PULLUP);
    
    // Active LOW relay initialization (HIGH = OFF)
    digitalWrite(relayPin, HIGH); 
    lastButtonState = HIGH;
    lastDebounceTime = 0;
  }

  // Called when iOS/Home app sends a state change
  boolean update() {
    int newState = power->getNewVal();
    digitalWrite(relayPin, newState ? LOW : HIGH);
    Serial.printf("HomeKit update: Relay %s\n", newState ? "ON" : "OFF");
    return true;
  }

  // Polled continuously to check physical button state
  void loop() {
    int reading = digitalRead(buttonPin);
    
    if (reading != lastButtonState) {
      lastDebounceTime = millis();
    }
    
    if ((millis() - lastDebounceTime) > debounceDelay) {
      // Detect falling edge (button pressed)
      if (reading == LOW && lastButtonState == HIGH) {
        int newState = !power->getVal();
        power->setVal(newState); // Sync state back to HomeKit
        digitalWrite(relayPin, newState ? LOW : HIGH);
        Serial.printf("Physical Button: Relay %s\n", newState ? "ON" : "OFF");
      }
    }
    lastButtonState = reading;
  }
};

void setup() {
  Serial.begin(115200);
  delay(1000); // Wait for serial monitor
  
  // Initialize HomeSpan
  homeSpan.begin();
  
  // Error Handling: Verify WiFi credentials are set and connected
  // Note: HomeSpan handles WiFi via its CLI, but we verify connection here.
  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("ERROR: WiFi disconnected. Use HomeSpan CLI (type 'W') to set 2.4GHz SSID.");
    // Blink onboard LED to indicate fatal WiFi error
    pinMode(48, OUTPUT); // RGB LED pin on standard S3 DevKit
    while(1) {
      digitalWrite(48, !digitalRead(48));
      delay(250);
    }
  }

  // Define HAP Accessory
  new SpanAccessory();
    new Service::AccessoryInformation();
      new Characteristic::Identify();
      new Characteristic::Manufacturer("ElectricalFlux");
      new Characteristic::Model("S3-Relay-v1");
    
    // Instantiate our custom relay service
    new DEV_Relay(RELAY_PIN, BUTTON_PIN);
}

void loop() {
  homeSpan.poll();
}

4. Debugging HomeKit Pairing & Runtime Failures

HomeKit pairing relies on mDNS (Bonjour) and the Secure Remote Password (SRP) protocol. When it fails, the Arduino serial monitor provides specific HAP error strings. Here is the ranked cause list for the most common failures.

Exact Error Strings & Fixes

1. mDNS init failed: ESP_ERR_NO_MEM

• Cause: The ESP32 has run out of internal SRAM while allocating memory for HAP service records and mDNS TXT records.
• Fix: If using an older WROOM board, reduce the number of accessories. If using the S3, ensure "OPI PSRAM" is enabled in the Arduino IDE Tools menu so HomeSpan can offload buffers to external RAM.

2. HomeSpan: WiFi disconnected (Flashing continuously)

• Cause: The ESP32 is dropping off the network due to 2.4GHz/5GHz band steering on modern mesh routers, or RSSI is below -70dBm.
• Fix: Create a dedicated 2.4GHz-only IoT SSID on your router. Move the ESP32 closer to the AP to ensure RSSI is > -65dBm.

3. HAP Pairing Failed: M2/M4 Crypto Error

• Cause: The SRP handshake failed. This usually happens if the ESP32's internal pairing database is corrupted, or if you are trying to re-pair an accessory that iOS still thinks is paired.
• Fix: Call homeSpan.clearPairings() once in setup(), flash, then remove it. Alternatively, type 'H' in the HomeSpan Serial CLI to clear HAP data, and remove the "Ghost" accessory from the Apple Home app.

5. Extending and Simplifying the Build

Depending on your deployment environment, you may need to strip this project down to its bare essentials or expand it into a multi-function sensor node.

How to Simplify (The "Headless" Relay)

If this relay is mounted inside a ceiling junction box or behind a wall plate where physical access is impossible, remove the physical button logic to save flash and reduce loop overhead:

• Delete BUTTON_PIN and the loop() method inside the DEV_Relay struct.
• Change the service type from LightBulb to Switch (Service::Switch) if you want it to appear as a generic plug rather than a light in the Apple Home UI.
• Remove the 10kΩ pull-up resistor and tactile switch from your BOM.

How to Extend (Adding Environmental Automation)

To make the relay respond to ambient conditions without relying on HomeKit automations (which require an Apple TV or HomePod hub), add an I2C sensor directly to the ESP32-S3:

• Add a BH1750 Light Sensor: Wire SDA to GPIO 8 and SCL to GPIO 9. Use the claws/BH1750 library.
• Implement Local Hysteresis: In the loop() function, read the lux value. If lux < 50 and the time is past 6:00 PM (using NTP time sync), trigger power->setVal(1) and pull the relay pin LOW.
• Add a LightSensor HAP Service: Expose the BH1750 readings to the Home app by adding new Service::LightSensor(); and a Characteristic::CurrentAmbientLightLevel() inside your SpanAccessory definition. This allows you to view real-time lux data directly in the Apple Home interface alongside your relay control.

By standardizing on the ESP32-S3 and the HomeSpan framework, you bypass the fragility of older MQTT-to-Homebridge bridges, achieving local, low-latency control that survives internet outages and integrates natively with Apple's secure HomeKit ecosystem.