Welcome!

Welcome to HomeSpan - a robust and extremely easy-to-use Arduino library for creating your own ESP32-based HomeKit devices entirely within the Arduino IDE.

HomeSpan provides a microcontroller-focused implementation of Apple's HomeKit Accessory Protocol Specification Release R2 (HAP-R2) designed specifically for the Espressif ESP32 microcontroller running within the Arduino IDE. HomeSpan pairs directly to HomeKit via your home WiFi network without the need for any external bridges or components. With HomeSpan you can use the full power of the ESP32's I/O functionality to create custom control software and/or hardware to automatically operate external devices from the Home App on your iPhone, iPad, or Mac, or with Siri.

Requirements

[^8266]:HomeSpan cannot be run on an ESP-8266, though an ESP-8266 can be used as a remote sensor in conjunction with HomeSpan's SpanPoint functionality

[^fail]: The current production release of HomeSpan will fail to compile under any Arduino-ESP32 Core release earlier than the minimum version listed. However, prior versions of HomeSpan can be compiled and run under earlier versions of the Core. The README file under the HomeSpan branch for each release provides details on which version of the Core can be used for that release

[^tested]: Later releases may work fine, but have not (yet) been tested. Note HomeSpan does not support the use of alpha, beta, or pre-release candidates of the Arduino-ESP32 Core - testing is only done on production releases of the Core.

[^homehub]: Apple's HomeKit architecture requires the use of a Home Hub (either a HomePod or Apple TV) for full and proper operation of any HomeKit device, including those based on HomeSpan. Use of HomeSpan without a Home Hub is NOT supported.

[^partition]: This recommendation assumes an ESP device with 4MB of flash memory. For devices with 8MB or more of flash memory you may choose any partition scheme that provides at least 1.9MB APP space and 1.9MB of OTA space (if using OTA)

HomeSpan Highlights

• Provides a natural, intuitive, and very easy-to-use framework
• Utilizes a unique Service-Centric approach to creating HomeKit devices
• Takes full advantage of the widely-popular Arduino IDE
• 100% HAP-R2 compliance
• Dozens of integrated HomeKit Services
• Operates in either Accessory or Bridge mode
• Supports pairing with Setup Codes or QR Codes
• Supports both WiFi and Ethernet connectivity to your home network
• Supports dual-stack use of both IPv4 and IPv6 addresses

For the HomeSpan Developer

• Extensive use of the Arduino Serial Monitor
  • Real-time, easy-to-understand diagnostics
  • Complete transparency to every underlying HomeKit action, data request, and data response
  • Command-line interface with a variety of info, debugging, and configuration commands
• Built-in database validation to ensure your configuration meets all HAP requirements
• Dedicated classes that utilize the ESP32's 16-channel PWM peripheral for easy control of:
  • LED Brightness (including auto-fading)
  • Servo Motors
• Integrated Push Button and Toggle Switch functionality supporting single, double, and long presses of:
  • Physical pushbuttons that connect an ESP32 pin to either ground or VCC
  • Touch pads/sensors connected to an ESP32 pin (for ESP32 devices that support touch pads)
• Integrated access to the ESP32's on-chip Remote Control peripheral for easy generation of IR and RF signals
• Dedicated classes to control one- and two-wire addressable RGB LEDs and LED strips
• Dedicated classes to control stepper motors that can run smoothly in the background without interfering with HomeSpan
• Dedicated class that faciliates seamless point-to-point communication between ESP32 devices using ESP-NOW
• Integrated Web Log for user-defined log messages
• Extensively-commented Tutorial Sketches taking you from the very basics of HomeSpan through advanced HomeKit topics
• Additional examples and projects showcasing real-world implementations of HomeSpan
• A complete set of documentation explaining every aspect of the HomeSpan API

For the HomeSpan End-User

• Embedded WiFi Access Point and Web Interface to allow end-users (non-developers) to:
  • Set up Homespan with their own home WiFi Credentials
  • Create their own HomeKit Pairing Setup Code
• Status LED and Control Button to allow end-users to:
  • Force-unpair the device from HomeKit
  • Perform a Factory Reset
  • Launch the WiFi Access Point
• A standalone, detailed End-User Guide

❗Latest Update - HomeSpan 2.1.8 (26 APR 2026)

New Features

• Updated HomeSpan Status logic and functionality for improved diagnostics

  • Added new HS_STATUS enum type HS_CONNECTED
    • reflects fully operational state where HomeSpan is connected to a WiFi or Ethernet network, paired to HomeKit and is maintaining one or more secure connections to HomeKit
    • Status LED set to steady ON when in this state
  • Modified HS_STATUS enum type HS_PAIRED
    • reflects potential "No Response" state where HomeSpan is connected to a WiFi or Ethernet network, paired to HomeKit but does not (yet) have any open secure connections to HomeKit
    • Status LED set to inverted double-blink when in this state
  • Added new std::pair homeSpan.getStatus() method
    • returns std::pair containing:
      • current HomeSpan Status as HS_STATUS enum type
      • duration (in seconds) since HomeSpan first changed to that Status
    • this thread-safe method allows user to actively poll HomeSpan status and duration from the main loop() as alternative to using homeSpan.setStatusCallback() (which is only called when the HomeSpan Status changes)
  • Added new void homeSpan.resetStatusDuration() method
    • this thread-safe method allows user to reset current HomeSpan Status duration to zero
  • Complete re-write of HomeSpan Status documentation
    • demonstrates how to use the new methods above
    • provides example of using homeSpan.getStatus() to reboot HomeSpan if the device has lost secure HomeKit connections for an extended period of time
    • adds table providing graphic representation of all Status LED patterns for each HomeSpan Status state
    • adds direct link to this documentation on the main HomeSpan README.md page
  • See HomeSpan Status and the HomeSpan Status LED for details

• Improvements to Web Log output

  • Added new Client Connections Table (similar output to 's' CLI command)
    • used as diagnostic to check whether HomeSpan has any active secure connections to HomeKit
  • Added descriptive class names for use with custom style sheets
    • body - background and header text (can use bod1 for backwards compatibility)
    • infoTable - the top table that provides general information about the device (can use tab1 for backwards compatibility)
    • clientTable - the newly-added table listing all active client connections (can use tab2 for backwards compatibility)
    • logTable - the bottom table listed all the individual Web Log entries (can also use tab2 for backwards compatibility)
  • See Message Logging for details

• Created ability to programmatically retrieve base-64 encoded Pairing Data from within a sketch

  • Added the following two new methods:
    • const char* homeSpan.getPairingInfo(char **buf)
      • allocates memory to buf and fills with HomeSpan's Device Pairing Data
      • returns buf, which must be de-allocated with free(buf) when no longer needed
    • const char* Controller::getPairingInfo(char **buf)
      • allocates memory to buf and fills with a Controller's Pairing Data
      • returns buf, which must be de-allocated with free(buf) when no longer needed
  • Using these methods duplicates the exact Accessory and Controller Pairing Data provided by the 'P' CLI Command needed to clone devices
  • See the API Reference for details on these methods and the Cloning Pairing Data page for a full example

• Added new boolean homeSpan.usingEthernet() method

  • returns true if Ethernet interface is being used, else false if WiFi is being used

• **Ad