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.

HomeSpan requires version 2.0.0 or later of the Arduino-ESP32 Board Manager, and has been tested up through version 2.0.4 (recommended). HomeSpan can be run on the original ESP32 as well as Espressif's ESP32-S2, ESP32-C3, and ESP32-S3 chips.

• 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
• 38 integrated HomeKit Services
• Operates in either Accessory or Bridge mode
• Supports pairing with Setup Codes or QR Codes

• 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
  • Servo Motors
• Integrated Push Button 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 and RGBW LEDs and LED strips
• 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

• 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

• Support for ESP32-S3 devices

  • Requires Arduino-ESP32 Board Manager version 2.0.4 or later

• New functionality to dynamically add/delete Accessories on the fly without rebooting the device

  • Adds homeSpan.deleteAccessory() and homeSpan.updateDatabase() methods
  • Includes new Example 20 - AdvancedTechniques to demonstrate how these methods can be used to create a dynamic bridge
  • See HomeSpan API Reference for details

• New support for Touch Pads

  • SpanButton() now supports three pin trigger methods: TRIGGER_ON_LOW, TRIGGER_ON_HIGH, and TRIGGER_ON_TOUCH
  • Also allows users to add their own trigger methods so SpanButton() can monitor pushbuttons attached to pin extenders, pin multiplexers, or any other device that requires calling third-party library functions
  • See HomeSpan API Reference for details

• Improved WiFi disconnect/reconnect handling

  • Fixes code that may, under certain circumstances, have prevented HomeSpan from reconnecting to WiFi after signal is lost
  • Adds WiFi diagnostics to Web Logs to monitor for disconnects and WiFi signal strength

• New option to run HomeSpan as a separate task in its own thread

  • Adds homeSpan.autoPoll() method
  • Works with both single- and dual-core processors
  • For dual-core processors, polling task will be created on the "free" core not being used for other Arduino functions
  • Allows user to add time-sensitive code the the main Arduino loop() function without delaying, or being dalyed by, HomeSpan polling
  • See HomeSpan API Reference for details

• New Programmable Hub Example

  • Demonstrates how to implement a Web Interface that allows users to dynamically add, delete, and configure up to 12 separate Light Accessories on a bridge device
  • Expands upon many of the methods used in Example 20

• Additional updates include:

  • New 'm' CLI command that prints free bytes remaining in heap memory - useful for monitoring memory usage when dynamically adding Accessories
  • New homeSpan.getLogLevel() method that returns the current log level

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

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 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 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 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 Projects - real-world applications of the HomeSpan Library
• HomeSpan FAQ - answers to frequently-asked questions

Note that all documentation is version-controlled and tied to each branch. The master branch generally points to the latest release. The dev branch, when available, will contain code under active development.

In addition to HomeSpan resources, developers who are new to HomeKit programming should download Apple's HomeKit Accessory Protocol Specification, Release R2 (HAP-R2). The download is free, but Apple requires you to register your Apple ID for access to the document.

You do not need to read the entire document. The whole point of HomeSpan is that it implements all the required HAP operations under the hood so you can focus on just programming whatever logic is needed to control your real-world appliances (lights, fans, RF remote controls, etc.) with the device. However, you will find Chapters 8 and 9 of the HAP guide to be an invaluable reference as it lists and describes all of the Services and Characteristics implemented in HomeSpan, many of which you will routinely utilize in your own HomeSpan sketches.

Please consider adding to the HomeSpan Discussion Board, or email me directly at [email protected].