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

|Component | Requirement | See Note | |---|:---:|:---:| |Current HomeSpan Production Release | 2.1.7 | - | | Supported Chips | ESP32, S2, S3, C3, C5, and C6 | [^8266] | | Minimum Required Arduino-ESP32 Core | 3.3.0 | [^fail] | | Latest Core fully tested with HomeSpan | 3.3.6 | [^tested] | | Minimum Flash Partition Size | 1.9MB | - | | Recommended Partition Scheme | Minimal SPIFFS (1.9MB APP with OTA) | [^partition] | | HomeKit Hub | HomePod or Apple TV | [^homehub] |

[^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.7 (1 Jan 2026 - Happy New Year)

New Features

• HomeSpan now supports two-wire WS2801-based addressable RGB LEDs

  • adds new WS2801_LED class
  • uses SPI bus for optimal performance
  • includes the same set() and Color() methods used by HomeSpan's existing Pixel and Dot classes:
  • adds a fully worked example of implementing a 25-pixel WS2801 RGB LED strand to HomeSpan's Pixel tutorial sketch
  • see the Pixels page for complete documentation

Updates and Corrections

• Corrected begin/end block logic in Dot class for improved performance of DotStar RGB LEDs
• Bumped minimum required version of Arduino-ESP32 Core from 3.1.0 to 3.3.0
  • reflects breaking changes that were previously introduced in HomeSpan 2.1.6

See Releases for details on all changes and bug fixes included in this update.

HomeSpan Resources

HomeSpan includes the following documentation:

• Getting Started with HomeSpan - setting up the software and the hardware needed to develop HomeSpan devices
• HomeSpan API Overview - an overview of the HomeSpan API, including a step-by-step guide to developing your first HomeSpan Sketch
• HomeSpan Tutorials - a guide to HomeSpan's tutorial-sketches
• HomeSpan Services and Characteristics - a list of all HAP Services and Characterstics supported by HomeSpan
• HomeSpan Accessory Categories - a list of all HAP Accessory Categories defined by HomeSpan
• HomeSpan Command-Line Interface (CLI) - configure a HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, monitor and update its status, and access detailed, real-time device diagnostics from the Arduino IDE Serial Monitor
• HomeSpan WiFi and Ethernet Connectivity - a high-level discussion of HomeSpan's WiFi and Ethernet connectivity options
• HomeSpan User Guide - turnkey instructions on how to configure an already-programmed HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, and pair the device to HomeKit. No computer needed!
• HomeSpan API Reference - a complete guide to the HomeSpan Library API
• HomeSpan QR Codes - create and use QR Codes for pairing HomeSpan devices
• HomeSpan OTA - update your sketches Over-the-Air directly from the Arduino IDE without a serial connection
• HomeSpan Watchdog Timer - optional protection that can trigger an automatic reboot if your sketch hangs or freezes for an extended period of time
• HomeSpan PWM - integrated control of standard LEDs and Servo Motors using the ESP32's on-chip PWM peripheral
• HomeSpan RFControl - easy generation of RF and IR Remote Control signals using the ESP32's on-chip RMT peripheral
• HomeSpan Pixels - integrated control of addressable one- and two-wire RGB and RGBW LEDs and LED strips
• HomeSpan Stepper Motor Control - integrated control of stepper motors, including PWM microstepping
• HomeSpan SpanPoint - facilitates point-to-point, bi-directional communication between ESP32 Devices using ESP-NOW
• HomeSpan Television Services - how to use HomeKit's undocumented Television Services and Characteristics
• HomeSpan Message Logging - how to generate log messages for display on the Arduino Serial Monitor as well as optionally posted to an integrated Web Log page
• HomeSpan TLV8 Characteristics - classes and methods for creating TLV8 objects to use with TLV8-based Characteristics
• HomeSpan Device Cloning - seamlessly swap a broken device for a new one without needing to re-pair and lose HomeKit automations
• HomeSpan Projects - real-world applications of the HomeSpan Library
• HomeSpan FAQ - answers to frequently-asked questions
• Solutions to Common Problems - resolutions to some common problems when using/compiling HomeSpan
• HomeSpan Reference Sketches - a collection of self-contained Reference Sketches showcasing some of the more complex HomeKit Services, such as Thermostats and Irrigation Systems

Note that all documentation is version-controlled and tied to each branch. The master branch generally points to the latest release. The dev branch,