Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
HomeKit Library for the Arduino-ESP32
1,718 Commits 18 Branches 21 Tags 6.9 MiB
C++ 89.5%
C 9.7%
Awk 0.7%
Go to file
HomeSpan d10f73e3c7
Release 1.9.0 (#775) 
* Converted various homeSpan.set() methods from void to Span& to enable chaining

* Update Reference.md

* Update Reference.md

* Update src.ino

* Update Pixel.ino

changed nPixels from uint8_t to int to allow for longer pixel strands (library is coded for int, so there is no need to limit to uint8_t in the example).

* Converted static HTTP Buffer to dynamic TempBuffer

Saved about 8K in RAM!

* Upgraded TempBuffer logic to use .get() to return pointer

Next up: update Network.cpp to use client.available() and reduce fixed memory usage.

* Update Network.cpp

* Replaced appropriate snprintf() with asprintf() and used *m in sscanf

Optimized use of heap memory instead of stack memory for temporary variables, and makes code easier to read, provided all heap usage is free() at end of each function.

Also removed char *hostName as a member variable of homeSpan.  It's never actually used since MDNS constructs its own copy of hostName as needed.

* Removed duplicate if(POST /pairings)

* modified HAP::receivedEncrypted() to use TempBuffer instead of fixed stack array

* Added HAPClient::listControllers()

Will be used for pairings list request

* Completed adding LIST to HAPClient::postPairingsURL()

HomeSpan now correctly responds to pairing list requests

* Refactored TLV

* Added support for zero-length TLV
* Added SEPARATOR as a formal kTLVType (and updated listControllers() to use)
* Added `uint8_t *buf(tagType tag, uint8_t *src, int len);` to load buffer needing external memcpy (and updated listControllers() to use)

* Simplified `uint8_t *TLV<tagType, maxTags>::buf(tagType tag, int len)`

Also updated HAP.cpp to use new `uint8_t *TLV<tagType, maxTags>::buf(tagType tag, uint8_t *src, int len)`

* Refactored Controller Structure and Add/Remove/List/Save Functions

Changed fixed-size array `struct Controller[MAX_CONTROLLERS]` to a dynamic linked-list of Controllers.  Re-coded all related functions.  MAX_CONTROLLERS no sets the size of any buffers but is only used to limit the ultimate size of the linked-list.

Saved about 1K of RAM since most of the time there are only 2 Controllers defined (as opposed to the 16 allowed).

* Support Non-English WiFi name

* Preventing possibility of buffer overwrite.

* Update README.md

* Update README.md

* Bumped release to 1.8.1

* Added homeSpan.setWebLogCallback(String (*f)())

Allows extension of initial table produced in WebLog, where f is a function that returns a String.  The returned String is copied into the WebLog HTML just before the </table> tag is printed in the initial table.

* Change webLogCallback() to pass String as reference

* Verbose WiFi Reconnect
Add the ability to turn off WiFi reconnect messages.

* Update Reference.md

* Update Logging.md

* Update README.md

* Added homeSpan.setWifiCallbackAll(int n)

Adds a second type of WiFi Callback that is called every time WiFi is established OR re-established after a disconnect.  Passes the number of times WiFi has been connected as an argument.

* Update README.md

* Update Reference.md

* Update README.md

* Made conforming changes to setVerboseWiFiReconnect

* Update Reference.md

* Update README.md

* Update Reference.md

* Update Logging.md

* Changed Accessory Limit from 41 to 150 and added Memory Warning

Low Memory Watermark is compared to DEFAULT_LOW_MEM_THRESHOLD (currently set at 80,000 bytes) after HAP initialization but before WIFI connection.  If Low Memory Watermark is below DEFAULT_LOW_MEM_THRESHOLD, a WARNING is issued.

Note: memory is based on heap with MALLOC_CAP_DEFAULT capabilities

* Update Reference.md

* Made vTaskDelay(5) in pollTask conditional of using autoPoll()

vTaskDelay(5) is only needed if polling is in its own task.  If calling poll() directly, there is no need for any delay.

* Update Logging.md

* Add hint for UTF8 usage in names

* Moved vTaskDelay(5) from pollTask() to homeSpan.autoPoll()

Adding the vTaskDelay(5) to the code that spawns the separate task is more consistent with how Arduino-ESP32 spawns the main loop() task.

* Update HomeSpan.h

Forgot braces in for-loop of autoPoll()

* Update 07-AccessoryNames.ino

fix typo

* Update Reference.md

* Add MAC Address output to RemoteDevice.ino

Prompts user with reminder of which MAC Address to use in Main Device.

* Added new homeSpan.rebootCallback() function

An optional callback used to track the number of times the device reboots, where a reboot is defined as any restart where the uptime was less than a specified number of milliseconds (default=5000)

* Update src.ino

* Update Reference.md

* Update src.ino

* Update README.md

* Update Reference.md

* Update README.md

* Update 07-AccessoryNames.ino

* Update HAPClient::sendEncrypted() to send individual frames to save memory

Rather than use a large temporary buffer to store all encrypted frames to transmit all at once, each encrypted frame is transmitted as soon as created, which means the temporary buffer only needs to be large enough to store a single encrypted frame.

For a device with a large number of Accessories, this can save 15-20 KB of temporary storage, allowing for more Accessories.

Note this change does not reduce the size of the unencrypted message that is initially produced and can also be quite large.  Potential for future project.

* Changed storage of required and optional Characteristics from unordered_set to vector

Significantly reduces memory usage - unordered_sets take up much more memory and using std::find from <algorithm> is as efficient as using find() method of an unordered_set.

To do: Remove all uses of unordered_set across HomeSpan wherever possible

* Changed unordered_set to vector when checking for duplicate AID

This eliminated the use of unordered_set everywhere in HomeSpan

* Added error checking for NVS storage

Also added NVS storage diagnostic to 'm' command.

* Fixing HTML syntax error in weblogs.

* PSRAM: Adds custom allocator and HS_MALLOC/HS_CALLOC macros

Forces all heap requests to be drawn from PSRAM, unless the device does not contain PSRAM.

To do:  Provide easy-to-use NEW() macro; add custom allocator to unordered sets; auto-shrink vectors after updateDatabase()

* Added ps_new() macro

A more generic version of `new(*ptr)` that allocates from PSRAM if present, otherwise is that same a normal `new`

* Added HS_REALLOC macro for generalized realloc() when using PSRAM

When using PSRAM, changing the number of Accessories no longer creates any change to heap usage on internal RAM.  The entire Accessory will be stored in PSRAM.

* Address WebLog size issue that limited number of entries

Added logic to sequentially transmit chunks of the HTML response String whenever it grows beyond 1024 bytes.  This ensures the number of WebLog entries does not create a very large HTML String that eats up all the free heap space.  WebLog entries are now only limited by storage of the entries themselves.  Tested successfully with 500 entries.

* Change NVS storage for Characteristics to always use nvs_set_u64()

Reduces NVS consumption by from 3 to only 1 records when storing numerical values.

Also:  Fixed memory problem in getCharacteristics by replacing dynamically-sized stack buffers with TempBuffer (must do this everywhere), which was causing stack probllem when combination number of Accessories and number of Characteristics got very large.

* Override new operator for SpanAccessory, SpanService, and SpanCharacteristic

New Operator now uses PSRAM if available, else uses Internal RAM.  Obviates the need for the ps_new() macro, though will keep definition since it may be useful for any class that does not already override malloc() to use PSRAM.

* Streamlined NVS recall for String values

Avoids need for intermediate variable

* Create MaxAccessories.ino

Demonstrates use of custom partition and shows how PSRAM is used in background when available

* Create partitions.csv

* Changed various static and dynamic stack-based buffers to TempBuffer

Also added casting overload to TempBuffer so that get() method is no longer needed

* Eliminated .get() from TempBuffer objects where possible

Stylistic only.  Cannot remove .get() when a TempBuffer is being re-cast.  Also can't remove .get() when cast can't be determined, such as when used in Serial.printf() [potential to do: explore if this can be addressed, though this is stylistic only and has no impact on code]

* Added Characteristic Constants

Added constants to Characteristics that describe states.

Example: Characteristic::SecuritySystemTargetState::ARM_STAY

* Correction to time server URL doc

* Addressed issue with new Characteristic enum constants

* Update MaxAccessories.ino

* Added ability to turn off SpanPoint encryption

New class-level method SpanPoint::setEncryption(boolean encrypt).  Default is to use encryption unless method is called with encrypt=false.

With encryption, 7 connections max; without encryption, 20 connections max.
 Serial Monitor provides warnings if connections are exceeded.

* Update NOW.md

* Update README.md

* Update README.md

* Update README.md

* Added new TLV8 class

To do: Refactor HAP.cpp to use new TLV8 class

* Starting to integrate new TLV8 into postPairVerify

* Completed re-factoring of postPairVerify using new TLV8

Next: re-factor postPairSetup

* Preparing for re-factoring postPairSetup

* Starting re-factoring of postPairSetup

* added TLV length function

Checks that iterator exists (i.e. does not equal end()) and returns length, else returns -1.  Can be used for checking for both the presence, and length, of a TLV record

* Completed initial re-factoring of postPairSetup - must test!

* Completed postPairSetup and fully tested - also changes TLV8 from vector to forward_list

Changed TLV8 from vector to forward_list to ensure iterators are always retained after adding new elements.

Nest: refactor postPairings

* Completed and fully tested refactoring of TLV8

Next up: remove old TLV code and clean up

* Removed all old TLV code

* Cleaning up postverify

* Added new initializer to TempBuffer

Allows TempBuffer to be initialized by concatenation of multiple existing buffers.

Constructor contains pairs of (T *buf), nElements, where last argument MUST BE NULL to signify end of variable argument list.

Will work with any type T, and nElements is in units of elements of type T.

* Start re-working SRP6A's use in Pair-Setup to make it local instead of global

* Initial integration of local SRP6A into Pair Setup

* Moved definitions of N3072 and other constants into SRP6A structure

* In process of updated Pair-Setup M3...

Cleaning up code by replacing calls to mbedTLS within Pair-Setup with arguments passed to/from SRP6A.  Much better and better encapsulates SRP6A

* Completed Pair-Setup M3 update

* Completed refactoring of SRP6A and integration into all steps of Pair-Setup

* Remove include HAP.h from SRP

SRP now only requires Utils (for TempBuffer).

Also, moved HS_ALLOC definitions into Utils so it can be re-used by others files

* Initial test of StreamBuffer added to WebLog

* Moved Streamer from Utils.h into separate Streamer.cpp

But declared Streamer inside HomeSpan.h instead of separate Streamer.h since it  should only be used when HomeSpan.h is used.

Also, changed class structure so that it is "final" by removing virtual tags and making all protected variables private.

* Begin integration of hapStream into HAP.ccp

* Moved StreamBuf parameter calls into HapOut

* Moved StreamBuf into HapOut as private nested class

* Added getSize() to HapOut and changed default behavior to NEVER output anything

Note: getSize() must be called before flush(), which resets byte counter

* Converted sprintfAttributes to printfAttributes and added encryption to HapOut

Success!

* Added SHA-384 hash computation to HapOut

Hashing of entire database is now done piecemeal within HapOut, preventing the need to load the entire database into a large buffer just to obtain a unique hash.

Modified updateDatabase() to use HapOut.getHash()

* Deleted sprintfAttributes for Span, SpanAccessory, and SpanService

These now use the new printfAttributes with HapOut

* Converted sprintfNotify and eventNotify to use HapOut

Successfully tested with MultiTest script

* Added back weblogCallback() functionality that uses hapOut

* Converted all remaining sprintfAttributes to printfAttributes

This removes last of large-sized JSON buffers - everything has now been converted to using hapOut.

Next up: Must add prettyPrint to hapOut to support 'd' command

* Moved prettyPrint into HapOut

This completes re-work of all JSON buffer memory management to use HAPOut.

Next up: Stress test with Max Accessories to see how many Accessories we can now handle.

* Changed HapOut delay from 1ms to 50ms for WiFi transmits.  Seems to be much more stable.

* Update MaxAccessories.ino

* fix for PSRAM with new hapOut

Force hapOut to use internal memory only.

Tested on ESP32-S2 with/without PSRAM.  However, crashes on ESP32-S3 when using PSRAM (?!)

* Changed hapOut delay back to 1ms - works fine

Identified issue with ESP32-S3 crashing when using PSRAM.  Problem was not the code, but that the sketch was using pins that are needed to run the Octal PSRAM that comes with the Espressif S3 DevKit.

* Fixed CSS in weblog

Missing conversion from String to c_str() when using hapOut.

* Added homeSpan.getWebLog()

* Update src.ino

* Update src.ino

* started work on TLV streaming with << operator

Goal - eliminate sendEncrypted() completely by using hapOut in tlvRepond().
Next up: use function call instead of << operator so logic can be moved into TLV.h

* moved tlv streaming into tlv class

* refactored tlvRespond() to use hapOut instead of sendEncrypted()

To do:

1) update putPrepareURL() to use hapOut instead of sendEncrypted()
2) remove sendEncrypted() since it is no longer needed
3) try moving MAllocator template into separate file (memory.h?) so it can be called from any other module
4) remove #include "HomeSpan.h" from TLV8

* Moved all PSRAM definitions into separate PSRAM.h file

Now allows #include "HomeSpan.h" to be removed from TLV dependencies

* updated putPrepareURL and deleted receiveEncrypted()

Must test with Door example, which uses putPrepare

* Modified range checks so that "NAN" gets picked up as error for FLOAT Characteristics

* Truncate all STRING-based Characteristics to 64 characters when adding to JSON

HAP default max length of STRING Characteristics is 64 characters

* Added homeSpan.getAutoPollTask() to return task handler of autoPoll

Returns NULL if autoPoll has not been used.

Also added low stack size for both main Arduino loop task and HomeSpan autoPoll task to 'm' command

* Added optional triggerType to homeSpan.setControlPin()

Default is SpanButton::TRIGGER_ON_LOW.  Follows same options as SpanButton, including the ability to provide your own triggerType function of form:

boolean f(int pin)

* Cleaned up some public/private permissioning inside PushButton and SpanButton

Ensure users can access constants like TRIGGER_ON_HIGH, TRIGGER_ON_LOW, etc. using any of these equivalent fully-qualified names:

* PushButton::TRIGGER_ON_HIGH
* SpanButton::TRIGGER_ON_HIGH
* SpanToggle::TRIGGER_ON_HIGH

* Update Reference.md

* Update Reference.md

* Added CustomNVSPartition Example

To do:  Add to list of Other Examples in documentation.

* Update CustomNVSPartition.ino

* Update Tutorials.md

* Create ExternalReference.ino

* Update Tutorials.md

* Update Logging.md

* Update Reference.md

* New Services and Characteristics List (#751)

* auto-generation of service list

* Update makeServiceList

* Update makeServiceList

* Update test.md

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* Update Span.h

* Update test.md

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* update

* Create ServiceListHead.md

* Update ServiceListHead.md

* Update ServiceListHead.md

* Update test.md

* update

* update

* Update ServiceList.md

* update

* Update ServiceList.md

* update

* removed bold font for Characteristic Constants in ServiceList.md

* fix heavy_check_mark

* add <span> to ServiceList to prevent linebreaks before checkmark

* fixed typo in ServiceLabelNameSpace description

* Create ServistList_Expanded.md

* Update ServistList_Expanded.md

* Update ServiceList.md

* added ServiceList_Expanded

* added code to create pre-expanded Services and Characteristics List

* Update Tutorials.md

* Update Tutorials.md

* Added ConfiguredName to Switch and Lightbulb

* Moved error/warning output to end of 'i' output

* Add configuredName() to all applicable Services and deprecated Name()

* reformat ServiceList to remove expandable details

Expandable details are not as practical to navigate for a page this size.  Easier to see everything laid out all at once.

* Re-organized Services List into Service Groups

* Update ServiceList.md

* converted Service Group names to upper case

* Added linebreak after each Service

* updated some descriptions

* Delete ServiceList_Expanded.md

* Revised Example 11 (Service Names) to use ConfiguredName Characteristic

Complete re-work of Example 11 - fully tested for iOS 17.2.1

* Documentation update (#765)

* Update Stepper.md

* Update README.md

* Update FAQ.md

* Update TVServices.md

* Get Arduino-ESP32 Version from <esp_arduino_version.h> instead of <core_version.h>

This works fine for all versions after 2.0.3, but returns 2.0.0 for versions 2.0.2 and 2.0.1, as well as 2.0.0.  Not an issue since current version is 2.0.14.

* Update Solutions.md

* Added Stepper_UNIPOLAR and Stepper_UNL2003

ALSO:  Re-arranged include files so that StepperControl.h is now part of HomeSpan.h.   No need to include anything except for HomeSpan.h to use any of the Stepper Motor classes.  Must update documentation accordingly.

NOTE: Always including StepperControl.h DOES NOT increase size of compile if no stepper motors are instantiated.

To do:  Consider doing the same for Pixel, PWM, and RMT as well.

* Removed #include "extras/PwmPin.h" from all Tutorial Examples

Since PwmPin.h is already included in HomeSpan.h, there is no reason to separately include it in user sketches.

* Removed all #include "extras/*.h" from "Other Examples"

Including any extras/*.h files in a HomeSpan sketch is no longer necessary since these are already included in HomeSpan.h.

* Update PWM.md

* Update RMT.md

* Update Pixels.md

* Update RMT.md

* Update Stepper.md

* Update 17-LinkedServices.ino

* Update Stepper.md

* Update Stepper_TB6612.md

* Update Stepper_A3967.md

* Update Stepper.md

* Update Stepper.md

* Update Stepper.md

* Update StepperControl.h

* Update Stepper_A3967.md

* Create Stepper_ULN2003A.md

* Update Stepper_ULN2003A.md

* Update Stepper_ULN2003A.md

* Update Stepper_TB6612.md

* Update Stepper_A3967.md

* Create Stepper_UNIPOLAR

* Create Stepper_UNIPOLAR.md

* Update Stepper_UNIPOLAR.md

* Delete Stepper_UNIPOLAR

* Update Stepper_UNIPOLAR.md

* Update Stepper_UNIPOLAR.md

* Update Stepper_UNIPOLAR.md

* Update Stepper_UNIPOLAR.md

* Added option to specify NULL for 4th parameter of homeSpan.enableWebLog()

If 4th parameter (the statusURL) is NULL, web logging will NOT be enabled BUT time server will still acquire time if server address and time zone were specified as 2nd and 3rd parameters.

Note that not having web logging enabled only impacts ability to acquire weblog from HTTP request.  It has no effect on the actual logging of WEBLOG() messages and thus homeSpan.getWebLog() works as expected.

* Allow user-defined data when receiving weblogs from callback (#770)

* Adding userData to getweblogs callback.
Allows user-specific data to be available in the callback that returns weblog HTML data.

* Adding userData to getweblogs callback.
Allows user-specific data to be available in the callback that returns weblog HTML data.

Return HTTP response code and content type only when no weblog callback defined

* Small clean-up and formatting of comments

* Bump version to 1.9.0

* Updated copyright dates to 2024

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update Reference.md

* Update Logging.md

* Update README.md

* Update Logging.md

* Update README.md

* Update HomeSpan.h

* Update README.md

* Update FeatherPins.h

Changed F21 from pin 35 to pin 38 for ESP32-S3 to avoid conflicting with Octal PSRAM.

* Update README.md

* Update README.md

* Update Logging.md

* Update library.properties

---------

Co-authored-by: Yitao Jiang <jytscientist@hotmail.com>
Co-authored-by: Francois <franklamoureux@hotmail.com>
Co-authored-by: Michael Geramb <mail@michael-geramb.at>
Co-authored-by: frankonski <frankonski@users.noreply.github.com>
 		2024-02-17 17:11:17 -06:00
docs Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00
documents Update HomeSpanDiagrams.key 2023-06-27 22:19:41 -05:00
examples Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00
src Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00
tools Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00
.gitattributes Update .gitattributes 2020-11-15 20:59:16 -06:00
.gitignore Update .gitignore 2021-09-19 14:01:30 -05:00
LICENSE Update LICENSE 2023-01-02 06:28:40 -06:00
README.md Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00
library.properties Release 1.9.0 (#775) 2024-02-17 17:11:17 -06:00

README.md

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.

HomeSpan requires version 2.0.0 or later of the Arduino-ESP32 Board Manager, 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.

[!NOTE] Apple's new HomeKit architecture requires the use of a Home Hub (either a HomePod or Apple TV) for full and proper operation of any HomeKit device, include those based on HomeSpan. Without a Home Hub, HomeSpan cannot send notifications to the Home App - things like pushbuttons and temperature sensors will not be able to transmit updates to the Home App.

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
  • 38 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

❗Latest Update - HomeSpan 1.9.0 (2/17/2024)

  • HomeSpan has been optimized to use significantly less RAM!

    • supports approximately TWICE the number of Accessories using the same amount of memory
    • minimized memory use also means much more room for users to add non-HomeSpan features to their sketch without running out of memory, especially if the non-HomeSpan code consumes a lot of stack space
    • HomeSpan now automatically detects the presence of PSRAM (SPIRAM) and will utilize that extra memory to the largest extent possible to keep internal RAM free for certain HomeSpan functions and ESP32 functions (e.g. WiFi) that require internal RAM. Also keeps internal RAM free for use by any non-HomeSpan code that does not (or cannot) use PSRAM
    • increased HomeSpan's 41-Accessory limit to a 150-Accessory Limit (as specified by HAP) since it is now possible to create a device with many more than 41 Accessories without running out of memory, especially if PSRAM is used

  • HomeSpan has been optimized to use significantly less Non-Volatile Storage (NVS)

    • allows you to use NVS to save the values of a many more Characteristics
    • see the newly-added CustomNVSPartition example that demonstrates how to create your own Partition Scheme to further expand the size of the NVS partition beyond the ESP32 default to support sketches with a large number of Accessories each configured to use NVS to save the values of many Characteristics

  • New features and documentation for Services and Characteristics

    • created "enumerated constants" (e.g. SWING_ENABLED, HUMIDIFYING, etc.) for every applicable Characteristic that can be used instead of integers when reading and writing values
      • very helpful since Apple is no longer publishing its non-commercial HAP document that provided a list and description of the states for each Characteristic
      • example: if(target.getNewVal()==target.ARM_STAY) {...}
    • added ability to properly name individual Services within a single Accessory using new Characteristic::ConfiguredName()
    • new Services and Characteristics page now provides functional descriptions and detailed specifications for every Service and Characteristic supported by HomeSpan, including a list of the enumerated constants available for every Characteristic

  • New ability to use Inverted Buttons and Touch Sensors as a Control Button

    • adds triggerType as a second, optional argument to Span& setControlPin(uint8_t pin, triggerType_t triggerType)
    • supports TRIGGER_ON_LOW, TRIGGER_ON_HIGH, TRIGGER_ON_TOUCH, or any user-defined function
    • see API Reference for details

  • New ability to "remotely" trigger user-defined actions by repeatedly power-cycling the device

    • adds new homeSpan method Span& setRebootCallback(void (*func)(uint8_t count), uint32_t upTime=5000)
    • the parameter count, which is passed by HomeSpan to func, indicates the number of "short" reboots that have occurred prior to the current reboot, where a "short" reboot is any that occurs before upTime milliseconds have elapsed
    • can be use to remotely restore a device that is not easily accessible to a pre-defined state
    • see API Reference for details

  • Added two new Stepper Motor Drivers

    • Stepper_UNIPOLAR: a generic driver for any 4-wire center-tapped unipolar motor
    • Stepper_ULN2003A: support for the ULN2003A driver board
    • see Stepper Motor Control Stepper for details

  • Additional Web Log functionality

    • adds new homeSpan method Span& setWebLogCallback(void (*func)(String &))
      • allows users to include additional data and custom HTML in the Web Log
    • adds new homeSpan method getWebLog(void (*f)(const char *, void *), void *args)
      • allows users to retrieve the underlying Web Log HTML from within sketch
    • modified enableWebLog() so that it can be used to set the time from an NTP server without actually serving Web Log pages
    • see Message Logging for details

  • Added ability to "chain" homeSpan methods

    • converted various homeSpan methods that previously returned void to now return Span &
    • example: homeSpan.setControlPin(21).setStatusPin(13);
    • see API Reference for details

  • Added ability to disable SpanPoint encryption

    • without encryption increases the maximum number of allowed SpanPoint devices from 7 to 20
    • see SpanPoint for details

  • Other new homeSpan methods included in this release:

    • Span& setVerboseWifiReconnect() - optionally suppresses "Trying to connect to..." messages
    • Span& setWifiCallbackAll() - provides an optional callback every time WiFi is connected or re-connected
    • TaskHandle_t getAutoPollTask() - returns the Task Handle for the HomeSpan Auto Poll Task

  • Removed dependencies on various "extra" #include files

    • the following #include files are now embedded in HomeSpan.h and should not be specified in any sketch:
      • extras/Pixel.h
      • extras/RFControl.h
      • extras/PwmPin.h
      • extras/StepperControl.h

[!IMPORTANT] At present it is okay to include the above #include files in your sketch (they have no effect on the compiled code), but they will be deleted at some point in the future so please remove them from your sketches now to ensure forward compatibility with subsequent releases.

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 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 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 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, when available, will contain code under active development.

External Resources

In addition to HomeSpan resources, developers who are new to HomeKit programming may find useful Chapters 8 and 9 of 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 only reflects the original HAP-R2 specs (rather than all the latest Services and Characteristics available in HomeKit for commercial devices).

Feedback or Questions?

Please post bug reports or other problems with HomeSpan to the Issues Board. 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. For more general questions or feedback not related to a specific HomeSpan issue or function, you can email me directly at 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.