145 lines
12 KiB
Markdown
145 lines
12 KiB
Markdown
|
# Welcome!
|
||
|
|
|
||
|
|
Welcome to HomeSpan - a robust and extremely easy-to-use Arduino library for creating your own [ESP32-based](https://www.espressif.com/en/products/modules/esp32) HomeKit devices entirely within the [Arduino IDE](http://www.arduino.cc).
|
||
|
|
|
||
|
|
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](https://github.com/espressif/arduino-esp32), and has been tested up through version 2.0.14 (recommended). HomeSpan can be run on the original ESP32 as well as Espressif's ESP32-S2, ESP32-C3, and ESP32-S3 chips.
|
||
|
|
|
||
|
|
### 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
|
||
|
|
* 41 integrated HomeKit Services
|
||
|
|
* Operates in either Accessory or Bridge mode
|
||
|
|
* Supports pairing with Setup Codes or QR Codes
|
||
|
|
|
||
|
|
### 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 and RGBW 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
|
||
|
|
|
||
|
|
## ❗Current DEVELOPMENT Branch - HomeSpan 1.8.1
|
||
|
|
|
||
|
|
* **Memory-Usage Improvements**
|
||
|
|
|
||
|
|
* reduced RAM usage by 30-50K (as well as reduced reliance on large stack-based buffers)
|
||
|
|
|
||
|
|
* **New ability to "chain" *homeSpan* methods**
|
||
|
|
|
||
|
|
* converted various *homeSpan* methods that previously returned *void* to now return *Span &*
|
||
|
|
* allows for chaining multiple *homeSpan* methods
|
||
|
|
* example: `homeSpan.setControlPin(21).setStatusPin(13);`
|
||
|
|
* see [HomeSpan API Reference](docs/Reference.md) for details
|
||
|
|
|
||
|
|
* **New Message Logging Customizations**
|
||
|
|
|
||
|
|
* adds new *homeSpan* method `Span& setVerboseWifiReconnect(bool verbose)`
|
||
|
|
* set *verbose* to *false* to suppress WiFi "Trying to connect to..." messages from being logged to the Serial Monitor and Web Log
|
||
|
|
* adds new *homeSpan* method `setWebLogCallback(void (*func)(String &))`
|
||
|
|
* provides a callback allowing you to extend the initial Web Log table with additional data of your own
|
||
|
|
* also allows you to add custom HTML to be shown after the initial table
|
||
|
|
* see [Message Logging](docs/Logging.md) for details and examples
|
||
|
|
|
||
|
|
* **New WiFi Callback Mechanism**
|
||
|
|
|
||
|
|
* adds new *homeSpan* method `setWifiCallbackAll(void (*func)(int))` that provides a callback every time WiFi is established, *or re-established after a disconnect*
|
||
|
|
* passes the number of times WiFi has been connected/re-connected as an argument
|
||
|
|
* see [API Reference](docs/Reference.md) for details
|
||
|
|
|
||
|
|
* **New Mechanism to trigger/reset HomeSpan by power-cycling or resetting the device a specified number of times**
|
||
|
|
|
||
|
|
* add new *homeSpan* method `Span& setRebootCallback(void (*func)(uint8_t), uint32_t upTime)` that provides a callback *upTime* milliseconds after rebooting
|
||
|
|
* passes the number of "short" reboots that have occured prior to the current reboot, where a "short" reboot is any that occurs **before** *upTime* milliseconds have elapsed
|
||
|
|
* can be used to reset WiFi Credentials, start the HomeSpan Access Point, perform a Factory Reset, or run any user-defined code, on a hard-to-access HomeSpan device by simply power-cycling the device a specified number of times
|
||
|
|
* see [API Reference](docs/Reference.md) for details
|
||
|
|
|
||
|
|
|
||
|
|
* **New ability to disable SpanPoint encryption**
|
||
|
|
|
||
|
|
* adds optional class-level method `SpanPoint::setEncryption(boolean encrypt)`
|
||
|
|
* enabling/disabling SpanPoint encryption changes the maximum number of connections that can be supported by a single device:
|
||
|
|
* with encryption, HomeSpan can support up to 7 SpanPoint connections to remote devices
|
||
|
|
* without encryption, HomeSpan can support up to 20 SpanPoint connections to remote devices
|
||
|
|
* if these limits are exceeded, HomeSpan will provide warning messages on the Serial Monitor during start-up
|
||
|
|
* see [SpanPoint](docs/NOW.md) for details
|
||
|
|
|
||
|
|
See [Releases](https://github.com/HomeSpan/HomeSpan/releases) for details on all changes and bug fixes included in this update.
|
||
|
|
|
||
|
|
# HomeSpan Resources
|
||
|
|
|
||
|
|
HomeSpan includes the following documentation:
|
||
|
|
|
||
|
|
* [Getting Started with HomeSpan](docs/GettingStarted.md) - setting up the software and the hardware needed to develop HomeSpan devices
|
||
|
|
* [HomeSpan API Overview](docs/Overview.md) - an overview of the HomeSpan API, including a step-by-step guide to developing your first HomeSpan Sketch
|
||
|
|
* [HomeSpan Tutorials](docs/Tutorials.md) - a guide to HomeSpan's tutorial-sketches
|
||
|
|
* [HomeSpan Services and Characteristics](docs/ServiceList.md) - a list of all HAP Services and Characterstics supported by HomeSpan
|
||
|
|
* [HomeSpan Accessory Categories](docs/Categories.md) - a list of all HAP Accessory Categories defined by HomeSpan
|
||
|
|
* [HomeSpan Command-Line Interface (CLI)](docs/CLI.md) - 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](docs/UserGuide.md) - 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](docs/Reference.md) - a complete guide to the HomeSpan Library API
|
||
|
|
* [HomeSpan QR Codes](docs/QRCodes.md) - create and use QR Codes for pairing HomeSpan devices
|
||
|
|
* [HomeSpan OTA](docs/OTA.md) - update your sketches Over-the-Air directly from the Arduino IDE without a serial connection
|
||
|
|
* [HomeSpan PWM](docs/PWM.md) - integrated control of standard LEDs and Servo Motors using the ESP32's on-chip PWM peripheral
|
||
|
|
* [HomeSpan RFControl](docs/RMT.md) - easy generation of RF and IR Remote Control signals using the ESP32's on-chip RMT peripheral
|
||
|
|
* [HomeSpan Pixels](docs/Pixels.md) - integrated control of addressable one- and two-wire RGB and RGBW LEDs and LED strips
|
||
|
|
* [HomeSpan Stepper Motor Control](docs/Stepper.md) - integrated control of stepper motors, including PWM microstepping
|
||
|
|
* [HomeSpan SpanPoint](docs/NOW.md) - facilitates point-to-point, bi-directional communication between ESP32 Devices using ESP-NOW
|
||
|
|
* [HomeSpan Television Services](docs/TVServices.md) - how to use HomeKit's undocumented Television Services and Characteristics
|
||
|
|
* [HomeSpan Message Logging](docs/Logging.md) - how to generate log messages for display on the Arduino Serial Monitor as well as optionally posted to an integrated Web Log page
|
||
|
|
* [HomeSpan Device Cloning](docs/Cloning.md) - seamlessly swap a broken device for a new one without needing to re-pair and lose HomeKit automations
|
||
|
|
* [HomeSpan Projects](https://github.com/topics/homespan) - real-world applications of the HomeSpan Library
|
||
|
|
* [HomeSpan FAQ](docs/FAQ.md) - answers to frequently-asked questions
|
||
|
|
* [Solutions to Common Problems](docs/Solutions.md) - resolutions to some common problems when using/compiling HomeSpan
|
||
|
|
* [HomeSpan Reference Sketches](https://github.com/HomeSpan/HomeSpanReferenceSketches) - 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, when available, will contain code under active development.
|
||
|
|
|
||
|
|
# External Resources
|
||
|
|
|
||
|
|
In addition to HomeSpan resources, developers who are new to HomeKit programming should download Apple's HomeKit Accessory Protocol Specification, Non-Commercial Version, Release R2 (HAP-R2). This document is unfortunately no longer available from Apple (perhaps because it was last updated July, 2019, and is now somewhat out-of-date). However, you may be able find copies of this document elsewhere on the web. Note Apple has not replaced the HAP-R2 document with any other versions for non-commercial use, and Apple's open-source [HomeKit ADK](https://github.com/apple/HomeKitADK) only reflects the original HAP-R2 specs (rather than all the latest Services and Characteristics available in HomeKit for commercial devices).
|
||
|
|
|
||
|
|
You ***do not*** need to read the entire HAP-R2 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.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Feedback or Questions?
|
||
|
|
|
||
|
|
Please post bug reports or other problems with HomeSpan to the [Issues Board](https://github.com/HomeSpan/HomeSpan/issues). Please post all other questions about HomeSpan (use, functionality, specs, examples, etc.) or any ideas or recommendations you may have for new functionality, or any general feedback about HomeSpan or HomeKit, to the [Discussion Board](https://github.com/HomeSpan/HomeSpan/discussions). For more general questions or feedback not related to a specific HomeSpan issue or function, you can email me directly at [homespan@icloud.com](mailto:homespan@icloud.com).
|
||
|
|
|
||
|
|
### About the Author
|
||
|
|
|
||
|
|
HomeSpan was developed and continues to be maintained and supported by Gregg Berman. It was originally conceived to solve the pesky problem of not being able to operate an RF-controlled kitchen vent hood with Siri. I hope you find it useful as well as fun to use.
|
||
|
|
|
||
|
|
This is my second large-scale open-source project --- my first was the design of an open-source sytem for operating model railroads using nothing more than an Arduino Uno and Arduino Motor Shield to generate digital command and control (DCC) signals. Though I have not been involved with the model railroading hobby for many years, videos showcasing my original system (dubbed DCC++), along with detailed tutorials of how it works, are still available on the [DCC++ YouTube Channel](https://www.youtube.com/@dcc2840/videos).
|