Updates and Corrections

• Added support for ESP32-C5

  • added WiFi band information to all log file output since the C5 supports both 5.0 GHz and 2.4 GHz WiFi bands
  • to force the C5 to use of the 5.0 GHz band, add the following to the setup() function in your sketch:
    • WiFi.STA.begin(); WiFi.setBandMode(WIFI_BAND_MODE_5G_ONLY);
    • See Networks.md for details

• Updated OTA password storage to use SHA256 instead of MD5 hashing to conform with latest ArduinoOTA library protocol

  • for backwards compatibility with prior Cores, HomeSpan uses SHA256 hashing only if compiled under Core 3.3.2 or greater, else it continues to use MD5

  • if you set your OTA password from within your sketch using homeSpan.enableOTA(char *pwd), the new hashing will be automatic

  • if instead you previously entered your password into the Serial Monitor using the "O" CLI command, you will need to re-enter it again so that HomeSpan can save it as SHA256

    • if not re-entered, uploading OTA sketches using Core 3.3.2 or greater will still work, but a diagnostic message will warn you to migrate from MD5 to SHA256 hashing

  • homeSpan.enableOTA(char *pwd) has been modified to allow you to directly specify the hash of your password instead of a plain-text password

    • if pwd starts with "0x" followed by exactly 64 hexidecimal characters, pwd will be interpreted as a SHA256 hash instead of plain-text and HomeSpan will store it directly instead of first hashing it
    • if pwd starts with "0x" followed by exactly 32 hexidecimal characters, pwd will be interpreted as an MD5 hash instead of plain-text and HomeSpan will store it directly instead of first hashing it
    • in any other cases, HomeSpan will continue to interpret pwd as a plain-text password and will hash it using either SHA256 or MD5 (depending on the Core version as per above) before storing it
    • note specifying the hash of your OTA password inside a sketch is more secure than specifying the plain-text password
      • useful for devices that cannot be readily connected to a Serial port, which prevents you from using the "O" CLI command to enter your OTA password

  • the "O" CLI command inherits the same logic above allowing you to specify your OTA password in either plain-text or as a hash

    • once specified, the "O" command will confirm by displaying on the Serial Monitor the hashed value it has stored

• Added new "c" CLI command that outputs to the Serial Monitor the same chip and sketch configuration information HomeSpan displays during initial start-up

• Fixed a compile-time warning related to the incorrect formatting of a diagnostic output messages when calibrating a touch sensor

Updates and Corrections

• Added new homeSpan method Span& setWebLogFavicon(const char *faviconURL)

  • adds a favicon to the HomeSpan Web Log, where faviconURL points to a hosted PNG image file containing the favicon
  • if left unspecified, faviconURL defaults to the standard HomeSpan logo:
    • https://raw.githubusercontent.com/HomeSpan/HomeSpan/refs/heads/master/docs/images/HomeSpanLogo.png
  • for a version of the logo re-centered on a white background, set faviconURL to:
    • https://raw.githubusercontent.com/HomeSpan/HomeSpan/refs/heads/master/docs/images/HomeSpanLogoW.png
  • for a version of the logo on a transparent background, set faviconURL to:
    • https://raw.githubusercontent.com/HomeSpan/HomeSpan/refs/heads/master/docs/images/HomeSpanLogoX.png

• Minor update to the touch-sensor logic in SpanButton to ensure compatibility with breaking changes introduced in Arduino-ESP32 core version 3.3.1

  • removed SpanButton::setTouchCycles() since the underlying Arduino-ESP32 touchSetCycles() function was removed as part of the changeover to new ESP-IDF touch-sensor logic
  • added an initial touchRead() call followed by short delay when calibrating trigger thresholds to provide sufficient time for the ESP32 hardware to stabilize after the new ESP-IDF touch-sensor logic initializes
  • users can still customize the touch-sensor peripheral by directly calling relevant Arduino-ESP32 or ESP-IDF functions

Updates and Corrections

• Refactored Pixel Library for Improved Performance (#1102 )
  • the RMT routines in HomeSpan 1.X relied on directly accessing the RMT Peripheral. This worked very well under Arduino-ESP32 2.X and IDF 4.X
  • Espressif discontinued direct RMT access in IDF 5.X and thus the Pixel and RFControl libraries needed to be re-written when upgrading to Arduino-ESP32 3.X
  • the new IDF 5.X framework uses the concepts of "encoders"
  • the RFControl code was refactored to use the rmt_copy_encoder, which works fine
  • the Pixel code was refactored to use the rmt_byte_encoder, which appeared to work fine, but created an unforeseen latency that prevented some pixel strands from lighting (and would have also caused pixel strands to take more than 2X longer than needed to update
  • the solution (#1102) is to use rmt_simple_encoder instead of rmt_byte_encoder
  • this solves the latency issue and provides an optimized and more robust framework
  • unfortunately, Espressif did not add the rmt_simple_encoder until IDF 5.3, which was not incorporated into the Arduino-ESP32 library until version 3.1.0
  • as a result of this necessary fix to the Pixel library, HomeSpan 2.1.4 will only compile under Arduino-ESP32 3.1.0 or later
  • in addition, the following deprecated Pixel constructors and method that have not been used in HomeSpan 2.X have now been removed from the code:
    • Pixel(uint8_t pin, boolean isRGBW)
    • Pixel(int pin, pixelType_t pixelType)
    • boolean isRGBW()

Other Changes

• Removed FeatherPins.h file from the main HomeSpan Library
  • this file was used only by the HomeSpan developer to aid in testing HomeSpan builds across multiple boards
    • using macros for pin names allows the same test sketch to be used for different types of boards without needing to update any board-specific pin numbers
  • instead, HomeSpan now uses a custom boards.local.txt file which adds menu options, defaults, and pin mapping macros directly via the Arduino IDE

Updates and Corrections

• Added support for IPv6 addresses (#1081)

  • IPv6 can be enabled by adding the Arduino-ESP32 functions WiFi.enableIPv6() or ETH.enableIPv6() to a sketch
  • when IPv6 is enabled, HomeSpan reports the IPv6 Unique Link Address (ULA) alongside the IPv4 address in the Serial Monitor and Web Log (if IPv6 is not enabled, the IPv6 address is reported as "::")
  • each IP address acquired (whether IPv6 or IPv4) is logged to the Serial Monitor and Web Log at the time it is received from the router
  • note that if homeSpan.setConnectionCallback() is used to set a callback function upon initial WiFi or ETH connection, the callback function is called only ONCE upon acquisition of the very first IP address received from the router (regardless of whether it is an IPv4 or IPv6 address)
  • see WiFi and Ethernet Connectivity for details

• Updated the HomeSpan Access Point code to (hopefully) address issues that previously prevented the HomeSpan Setup pages from being displayed on non-Apple devices (#1090)

• Fixed bug in PID interpretation that was introduced when the JSON-parser was refactored in HomeSpan 2.1.2 (#1089)

• Added new homeSpan method forceNewConfigNumber()

  • when included in a sketch, this forces HomeSpan to update the database configuration number upon start-up, as well as anytime homeSpan.updateDatabase() is called, regardless of whether there has been any change to the database configuration
  • purpose of this function is an attempt to encourage the HomeKit backend architecture to more quickly re-establish a connection to a HomeSpan device that has been rebooted without the user opening the Home App (in which case HomeKit would immediately connect to the device)
  • prompting HomeKit in this fashion has had limited success (hopefully Apple will address this shortcoming more generally in iOS26)

Compatibility Issues

• Addressed compatibility issues with HomeSpan's LedPin, RFControl and Pixel modules when run under Arduino-ESP32 version 3.2 as a result of new fields added by Espressif to various LEDC and RMT configuration structures in IDF 5.4 (#1092)

  • the initialization routines in these modules has been modified to always pre-clear all relevant IDF config structures so that such issues will (hopefully) not re-surface in the future if/when Espressif adds any additional config fields in subsequent IDF updates

• Addressed compatibility issue with change in function signature for ESP-NOW callback under IDF 5.5 / Arduino-ESP32 3.3.0 (#1097)

  • adjusted signature of callback as per ESP-NOW IDF 5.5 breaking change

Updates and Corrections

• Added UUID validation for Custom Services (#1020)

  • reports an error in CLI at startup if invalid Service UUID is found
  • similar to existing UUID validation for Custom Characteristics

• Renamed example sketch RemoteDevice8286.ino to RemoteDevice8266.ino (#1028)

  • corrects a long-standing typo in the filename

• Modified OTA updating so that the HomeSpan check for its Magic Cookie is only made if uploading a new sketch (#1023)

  • avoids OTA aborting when OTA is used to upload SPIFFS data

• Refactored the JSON parsing logic that handles PUT Characteristic requests from HomeKit

  • now properly supports any JSON-allowed Unicode character used in a JSON string value, from U+0020 to U+10FFFF
    • allows string-based Characteristics to include escaped quotes, escaped solidus and reverse solidus, and any of the JSON token characters ,:[]{} that would have previously caused a parsing error
  • also now allows for empty string-based Characteristics (previously would have led to a parsing error)

• Added new setMaxStringLength(uint8_t n) method to Characteristics

  • allows user to change maximum length of string-based Characteristics from HAP default of 64 to n (less than 256)
  • though specified by HAP, this value does not seem to be used by HomeKit, and this method does not appear necessary

• Added new homeSpan method void assumeTimeAcquired() (#1033)

  • calling this method tells HomeSpan to assume that you have acquired the time using your own code
  • useful if you don't want to specify a timeServerURL when enabling the Web Log, but would rather acquire it manually

• Added new homeSpan method setGetCharacteristicsCallback(void (*func)(const char *getCharList))

  • sets an optional user-defined callback function, func, to be called by HomeSpan whenever it receives a GET /characteristics request from HomeKit
  • HomeKit generally sends this request to every paired device each time the Home App is opened on an iPhone or Mac
  • this callback is useful in circumstances where the current state of a sensor-style Characteristic must be read by HomeSpan using a separate "expensive" process that should be called only when needed as opposed to being continuously updated in a Services loop() method
  • the function func must be of type void and accept one argument of type const char * into which HomeSpan passes the list of Characteristic AID/IID pairs that HomeKit provided in its HTTP GET request
  • getCharList can be used to determine if the HTTP GET request includes the AID/IID pair for any specific Characteristic
    • this allows the user to act on the callback based on which specific Characteristics were requested by HomeKit
    • see new helper SpanCharacteristic method foundIn(const char *getCharList) that returns true or false depending on whether the AID/IID for a specific Characteristic is found in getCharList
    • for completeness, also added uint32_t getAID() methods to each of the SpanAccessory, SpanService, and SpanCharacteristic classes

• Explicitly added added #include <mutex> to HomeSpan.cpp to address compatibility issue with Arduino-ESP32 v3.2.0 (#1048)

• Fixed bug in Pixel::getPin() that would report channel number instead of pin number

Integrated Support for OTA Partition Rollbacks

• Users can now configure HomeSpan to automatically rollback new sketches uploaded via OTA to a previous version if the new sketch crashes the device before being validated

  • adds new header file SpanRollback.h
    • when included at the top of a user's sketch this disables the auto-validation of any newly-updated OTA partition that the ESP32-Arduino library otherwise would perform at startup
    • users can instead manually validate their sketch in software, which allows the device to automatically rollback to a prior sketch if the new sketch is not marked as valid
  • adds new homeSpan method markSketchOK() allowing users to mark the currently running partition as valid after uploading a new sketch via OTA
  • adds new homeSpan method setPollingCallback(void (*f)()) allowing users to add a callback function, f, that HomeSpan calls one time after the very first call to poll() has completed
    • provides a good check-point for users to mark new sketches uploaded via OTA as valid
  • adds new CLI 'p' command that prints partition full table to the Serial Monitor
    • includes details on whether OTA partitions are marked valid, invalid, undefined, etc.
  • adds new homeSpan method setCompileTime(char *compTime) allowing users to set the compile date/time of the sketch to any arbitrary string, compTime
    • the compile date/time string provided is indicated in Serial Monitor during start-up as well as in the top table of the Web Log output
    • if this method is called without a parameter HomeSpan uses the macros __DATE__ and __TIME__ as provided by the compiler during compilation to create a date/time string
    • setting the compile date/time with this method allows users to easily determine which version of their sketch is running after an OTA update by simply looking at the Web Log output, which is very helpful when OTA Rollbacks are enabled
  • see OTA.md for details on how to use OTA Rollbacks

HomeSpan Watchdog Timer

• Users can now configure HomeSpan to add a watchdog task that reboots the device if it has frozen or gone into an infinite loop preventing normal HomeSpan operations

  • works especially well when used in conjunction with the OTA rollback functionality above by allowing the operating system itself to automatically rollback a newly-uploaded sketch via OTA that freezes or hangs the device completely before the sketch is validated
  • adds new homeSpan method enableWatchdog(uint16_t nSeconds)
    • creates a separate HomeSpan task watchdog timer designed to trigger a reboot of the device if not periodically reset at least every nSeconds
    • calling this method after the HomeSpan watchdog timer has already been enabled changes the timeout to a new value of nSeconds
  • adds new homeSpan method resetWatchdog() used to periodically reset the HomeSpan watchdog timer
    • this method is already embedded in all HomeSpan library functions as needed
    • users DO NOT need to call resetWatchdog() themselves in their own sketch unless they have created a process that delays the normal operation of homeSpan.poll()
  • adds new homeSpan method disableWatchdog() to disable the HomeSpan watchdog timer after it has been enabled
    • has no effect if the HomeSpan watchdog timer is not currently enabled
  • see WDT.md for a complete discussion of the HomeSpan and other system watchdog timer

Other Updates

• Added homeSpan method Span& useEthernet() to force HomeSpan to use Ethernet instead of WiFi, even if ETH has not yet been called or an Ethernet card has not been found prior to homeSpan.begin() being called (#997)

Bug Fixes

• Fixes a bug introduced in HomeSpan 2.1.0 that improperly initialized the WiFi and Ethernet stacks depending on how code was compiled (#977 and #981)

Integrated Support for Ethernet Connectivity!

• Users can now readily connect HomeSpan to their home networks via Ethernet as an alternative to WiFi (#738)

  • no new homeSpan methods are required - during start-up HomeSpan checks if you've instructed the ESP32 to establish an Ethernet connection, and if so it will switch into "Ethernet mode" and not attempt to connect to your network via WiFi
  • once in Ethernet mode, HomeSpan customizes some of the output to the Serial Monitor and Web Log so it is clear Ethernet and not WiFi connectivity is being used
  • HomeSpan handles all reporting of connects/disconnects/reconnects just as it normally does for WiFi connections
  • to establish Ethernet connectivity, simply use the Arduino-ESP32's ETH library by calling ETH.begin() in your sketch with the appropriate parameters for your Ethernet board
    • you must call ETH.begin() before calling homeSpan.begin()
    • you do not need to include ETH.h in your sketch
    • note that the Arduino-ESP32 ETH library supports both direct-connect PHY as well as standalone SPI-based Ethernet boards
  • adds new homeSpan method setConnectionCallback(), which is a renamed version of the (now deprecated) setWifiCallbackAll to reflect the fact that this method can be used with both Ethernet and WiFi connections

WiFi Enhancements

• When connecting to a WiFi mesh network with multiple access points, HomeSpan now automatically connects to the access point with the strongest WiFi signal (i.e. the greatest RSSI)

  • previously HomeSpan would simply connect to the first access point it found that matched the SSID specified by the user, even if other access points with the same SSID had stronger signals
  • the BSSID (6-byte MAC address) of the access point to which HomeSpan is currently connected is provided in the Web Log as well as in the Serial Monitor in response to the 's' CLI command

• New WiFi-management methods

  • adds new homeSpan method setConnectionTimes(uint32_t minTime, uint32_t maxTime, uint8_t nSteps) that allows fine-tuning of how long HomeSpan wait for each connection attempt when trying to connect to a WiFi network (#896)
  • adds new homeSpan method enableWiFiRescan(uint32_t iTime=1, uint32_t pTime=0, int thresh=3) that causes HomeSpan to periodically re-scan for all access points matching the configured SSID and automatically switches to the access point with the strongest signal (#955)
    • useful after a mesh network is rebooted and HomeSpan initially reconnects to a more distance access point because a closer one with a stronger signal has not yet fully rebooted
  • adds new homeSpan method addBssidName(String bssid, string name) that allows users to create optional display names for each access point in a WiFi mesh network according to their 6-byte BSSID addresses
    • when defined, HomeSpan will display both this name and the BSSID of an access point whenever presenting info on the Serial Monitor or writing to the Web Log
  • adds new homeSpan method setWifiBegin(void (*f)(const char *, const char *)) that allows users to create an alternative function that HomeSpan uses instead of simply calling WiFi.begin() when attempting to connect to a WiFi network (#780)
    • provides ability to create customizations, such as using a different type of call to establish WiFi connectivity (e.g. connectivity to an enterprise network), or adding extra set-up functionality to be called while connectivity is being established (e.g. changing the WiFi power)
  • adds new 'D' CLI command that forces HomeSpan to disconnect and then automatically re-connect to the configured WiFi network
  • adds new 'Z' CLI command that scans a user's WiFi network environment and displays information about each SSID (including each BSSID for mesh networks with multiple access points broadcasting the same SSID) on the Serial Monitor
    • if defined, the HomeSpan Status LED will turn on and double-blink whenever a WiFi scan is being performed

• DEPRECATIONS

  • setWifiCallbackAll has been renamed to setConnectionCallback() to reflect the fact this callback can be used for both WiFi and Ethernet connections
  • setWifiCallback has been deprecated --- the more generic setConnectionCallback() should be used instead
    • requires any existing callbacks to be upgraded to add a single integer argument representing the number of connection attempts, similar to how setWifiCallbackAll(), and now setConnectionCallback(), works

Multi-Threading

• Made Web Log writing/reading thread-safe (#899)

  • adds shared_mutex locks to web log writing and reading functions
    • while web log is being displayed, writing new log records is temporarily suspended
    • while a new log record is being written, displaying or accessing the web log is temporarily suspended
  • this fixes a latent bug related to a race condition between displaying the web log and writing a log record when the separate thread HomeSpan creates at start-up to handle initial contact with an NTP server records the time found

• Made HomeSpan autopolling thread-safe

  • add shared_mutex lock to polling task
  • adds new macro homeSpanPAUSE that temporarily suspends the polling task once it completes its current run
    • allows users to make modifications to HomeSpan Characteristics and perform any other HomeSpan functions from a separate thread without worrying about inconsistencies if HomeSpan polling was being run at the same time
    • pauses only for the duration of the scope under which it was called --- polling resumes automatically after end of scope is reached
  • adds new macro homeSpanRESUME that resumes running of the polling task
    • use is optional --- only needed if user wants to resume polling that was paused using homeSpanPAUSE prior to the end of scope is reached
  • adds new homeSpan method std::shared_mutex& getMutex() that returns the shared_mutex used to lock the polling task
    • only needed if you want to create your own thread-locking lock management instead of using the above macros
  • adds new MultiThreading Tutorial Example

Web Log

• Web Log can now auto-refresh from browser

  • if a Web Log request from a browser includes the query string, refresh=N, HomeSpan will add an HTTP Refresh response header to the HTML it serves back to the browser to cause it to auto-refresh the Web Log request every N seconds
  • N must be greater or equal to 1
  • example: http://homespan-4e8eb8504e59.local/status?refresh=10

• Web Log requests are now case-insensitive

  • example: http://homespan-4e8eb8504e59.local/STATUS?REFRESH=10 is equivalent to above

Bug Fixes

• Fixes a latent bug that prevented compilation when the homeSpan methods controllerListBegin() and controllerListEnd() were used in a sketch (#950)

Compatibility with Arduino-ESP32 v3.1.0 (IDF v5.3.2)

• Set new LEDC "deconfigure" parameter to false in LedPin
• Added logic to handle name change in macros SOC_TOUCH_VERSION_1 /2 to macro SOC_TOUCH_SENSOR_VERSION

Other

• Updated the documentation in the CustomNVSPartition Example to note that even with the addition of a custom partitions.csv file, you still need to set the Partition Scheme in the IDE to a scheme that provides APP partitions that are large enough to hold your sketch. This is because the Arduino IDE uses the scheme selected to determine the size of the APP partitions, and checks the size of the sketch against the size of these App partitions even though the IDE ultimately uses the partitions.csv file for the scheme once loading the sketch to the device

Re-factored for compatibility with Arduino-ESP32 Board Manager version 3

• requires Arduino-ESP32 Board Manager 3.0.2 or later
  • Espressif did not include the Sodium cryptography library in versions 3.0.0 and 3.0.1, which is required by HomeSpan
• all user-sketches written under HomeSpan 1.9.1 should work without modification under HomeSpan 2.0.0, with the exception of sketches in which the user directly accessed IDF-4 functionality, which may or may not be compatible with IDF-5
• supports use of the ESP32-C6 chip
  • though the Arduino-ESP32 Board Manager also supports the ESP-H2, HomeSpan does not since the H2 does not have WiFi capabilities, as currently required

New API Functions

• Complete re-write of the HomeSpan Pixel and RFControl libraries

  • you can now instantiate both Pixel and RFControl objects in the same sketch (previously these classes were incompatible with each other and could not be used in the same sketch)

• Expanded Pixel class functionality

  • adds support for 5-color RGBWC (red, green, blue, warm-white, and cool-white) LEDs
  • adds new method Pixel::Color::WC() to support setting warm-white / cool-white color values
  • adds new methods Pixel::Color::CCT() and Pixel::setTemperatures() to automatically set the warm-white / cool-white colors of a Pixel device based on whatever correlated color temperature (CCT) the user specifies (e.g. 3000K)
  • adds new constructor Pixel(int pin, const char *pixelType) that provides the ability to both select the colors and specify their transmission order (pixelType) to match a very wide variety of Pixel devices (ranging from pure-white LEDs to 5-color RGBWC LEDs)
    • deprecates constructor Pixel(int pin, pixelType_t pixelType) that limited pixelType to a pre-defined set of values. This constructor will be removed in future versions of HomeSpan
  • adds new method boolean Pixel::hasColor(char c) to determine whether an existing Pixel object supports any particular color
    • deprecates boolean Pixel::isRGBW() which only distinguished RGB from RGBW devices. This method will be removed in future versions of HomeSpan
  • upgraded the PixelTester sketch to interactively step users through selecting and testing the correct pixelType for their device
  • added new Pixel-RGBWC example demonstrating how to implement an RGBWC Pixel light-strip with separate Home App controls for the RGB and WC LED
  • see the Pixels.md page for full details

❗ IMPORTANT SIZE CONSIDERATIONS ❗

• version 3 of the Arduino-ESP32 Board Manager has a much larger footprint than version 2
• the same HomeSpan sketch compiled under 1.9.1 will be approximately 200K larger when compiled under HomeSpan 2.0.0-rc.1
• as a result, HomeSpan sketches will no longer fit into the Default partition scheme which only allocates 1.3MB to an App partition
• HomeSpan sketches must instead be compiled under a larger partition scheme (such as Minimal SPIFFS, which provides for 1.9MB partitions)
• HOWEVER - Espressif does not support changing partition tables via OTA!
  • changes to the partition table are ignored if a sketch is updated via OTA
  • you can only update the partition table on a device if you load the sketch via the Serial port when connected to a computer
  • this means that if you have remote device running a HomeSpan sketch using the Default partition scheme, you will not be able to migrate to HomeSpan 2.0.0 using OTA
    • you must first connect the device directly to your computer, change the partition scheme to Minimal SPIFFS, and then update the sketch via the Serial port
  • once HomeSpan has been successfully updated via the Serial Port using the new partition scheme, OTA can be used for any further updates (provided you don't need to subsequently change the partition scheme again for some other reason).

Re-factored for compatibility with Arduino-ESP32 Board Manager version 3

• requires Arduino-ESP32 Board Manager 3.0.2 or later
  • Espressif did not include the Sodium cryptography library in versions 3.0.0 and 3.0.1, which is required by HomeSpan
• all user-sketches written under HomeSpan 1.9.1 should work without modification under HomeSpan 2.0.0, with the exception of sketches in which the user directly accessed IDF-4 functionality, which may or may not be compatible with IDF-5
• supports use of the ESP32-C6 chip
  • though the Arduino-ESP32 Board Manager also supports the ESP-H2, HomeSpan does not since the H2 does not have WiFi capabilities, as currently required

New API Functions

• Complete re-write of the HomeSpan Pixel and RFControl libraries

  • you can now instantiate both Pixel and RFControl objects in the same sketch (previously these classes were incompatible with eachother and could not be used in the same sketch)

• Expanded Pixel class functionality

  • adds support for 5-color RGBWC (red, green, blue, warm-white, and cool-white) LEDs
  • adds new method Pixel::Color::WC() to support setting warm-white / cool-white color values
  • adds new methods Pixel::Color::CCT() and Pixel::setTemperatures() to automatically set the warm-white / cool-white colors of a Pixel device based on whatever correlated color temperature (CCT) the user specifies (e.g. 3000K)
  • adds new constructor Pixel(int pin, const char *pixelType) that provides the ability to both select the colors and specify their transmission order (pixelType) to match a very wide variety of Pixel devices (ranging from pure-white LEDs to 5-color RGBWC LEDs)
    • deprecates constructor Pixel(int pin, pixelType_t pixelType) that limited pixelType to a pre-defined set of values. This constructor will be removed in future versions of HomeSpan
  • adds new method boolean Pixel::hasColor(char c) to determine whether an existing Pixel object supports any particular color
    • deprecates boolean Pixel::isRGBW() which only distinguished RGB from RGBW devices. This method will be removed in future versions of HomeSpan
  • upgraded the PixelTester sketch to interactively step users through selecting and testing the correct pixelType for their device
  • added new Pixel-RGBWC example demonstrating how to implement an RGBWC Pixel light-strip with separate Home App controls for the RGB and WC LED
  • see the Pixels.md page for full details

❗ IMPORTANT SIZE CONSIDERATIONS ❗

• version 3 of the Arduino-ESP32 Board Manager has a much larger footprint than version 2
• the same HomeSpan sketch compiled under 1.9.1 will be approximately 200K larger when compiled under HomeSpan 2.0.0-rc.1
• as a result, HomeSpan sketches will no longer fit into the Default partition scheme which only allocates 1.3MB to an App partition
• HomeSpan sketches must instead be compiled under a larger partition scheme (such as Minimal SPIFFS, which provides for 1.9MB partitions)
• HOWEVER - Espressif does not support changing partition tables via OTA!
  • changes to the partition table are ignored if a sketch is updated via OTA
  • you can only update the partition table on a device if you load the sketch via the Serial port when connected to a computer
  • this means that if you have remote device running a HomeSpan sketch using the Default partition scheme, you will not be able to migrate to HomeSpan 2.0.0 using OTA
    • you must first connect the device directly to your computer, change the partition scheme to Minimal SPIFFS, and then update the sketch via the Serial port
  • once HomeSpan has been successfully updated via the Serial Port using the new partition scheme, OTA can be used for any further updates (provided you don't need to subsequently change the partition scheme again for some other reason).

New API Functions

• New integrated support for TLV8 Characteristics

  • new TLV8() class library for the creation and management of TLV8 objects. Methods include:

    • add() - adds a TLV8 record containing a byte stream, string, numerical value, zero-length tag, or even another complete TLV8 object
    • find() - finds the TLV8 record matching a specified tag over an optionally-specified range
    • len() - returns the length of the specified TLV8 record
    • print() - prints each TLV8 record (or a range of records) to the Serial Monitor
    • printAll() - recursively prints all sub-TLV8 objects to the Serial Monitor
    • wipe() - erases all records from a TLV8 object

  • new TLV8_it() iterators used to extract and read data from TLV8 records. Methods include:

    • getTag() - returns the numeric TAG for a TLV8 record
    • getLen() - returns the LENGTH of a TLV8 record
    • get() - returns a pointer to the VALUE byte-stream of a TLV8 record
    • get()[] - returns a particular byte in the VALUE byte-stream of a TLV8 record
    • getVal() - a template function to convert the VALUE byte-stream of a TLV8 record to a numeric value

  • new homeSpan methods to read and write TLV8 objects to and from a TLV Characteristic

    • getTLV() and getNewTLV() reads from a TLV8-based Characteristic into a TLV8 object
    • setTLV() writes TLV8 object into a TLV8-based Characteristic

  • added new CUSTOM_CHAR_TLV8() that allows for easy creation of custom TLV8 Characteristics

  • added integrated support for new TLV8 Characteristic DisplayOrder

    • sets the order in which the Input Sources for a Television Service are displayed for selection in the Home App
    • credit to @zwaldowski (homebridge/HAP-NodeJS#644 (comment)) for reverse-engineering this undocumented Apple Characteristic, and to HomeBridge for documenting its UUID

  • added new Tutorial Example 22 - TLV8 Characteristics demonstrating use of the TLV8() class and TLV8 Characteristics

  • see the new TLV8.md page for complete details and documentation

• New methods to read Controller data (for advanced use-cases only) (#801)

  • adds new homeSpan method setControllerCallback() to set optional callback function that HomeSpan calls whenever a controller is added, removed, or updated
  • adds new homeSpan methods controllerListBegin() and controllerListEnd()
    • returns constant iterators to the beginning and end of the linked-list HomeSpan uses to store all controller data
    • methods to read the controller data pointed to by such iterators include:
      • getID() - returns a pointer to the 36-byte Device ID of the controller
      • getLTPK() - a pointer to the 32-byte Long-Term Public Key of the controller
      • isAdmin() - returns true if the controller has admin permission, else returns false
  • see the API Reference for details

• New methods to read and set the IIDs of Services and Characteristics

  • adds new SpanService method getIID() that returns the IID of a Service
  • adds new SpanCharacteristic method getIID() that returns the IID of a Characteristic
  • adds new homeSpan method resetIID(int newIID) that resets the IID count for the current Accessory
  • see the API Reference for details

• Added support for more Pixel chips (#781 / #784)

  • new constructor Pixel(uint8_t pin, [pixelType_t pixelType]) allows your to set the order in which colors are transmitted to the pixel chip, where pixelType is one of the following:
    • PixelType::RGB, PixelType::RBG, PixelType::BRG, PixelType::BGR, PixelType::GBR, PixelType::GRB
    • PixelType::RGBW, PixelType::RBGW, PixelType::BRGW, PixelType::BGRW, PixelType::GBRW, PixelType::GRBW*
  • deprecated previous constructor Pixel(uint8_t pin, boolean isRGBW)
    • this constructor will continue to work, but you will receive a warning during compilation that it has been deprecated
    • users should switch to the new constructor to avoid potential compatibility issues with future versions of HomeSpan
  • added new method boolean isRGBW()
    • returns true if Pixel was constructed as RGBW, else false if constructed as RGB only (i.e. no white LED)
  • created new PixelTester sketch (found under Other-> Examples) to aid in determining the pixelType for any LED Strip

• New Tutorial Example 21 - AccessoryIdentifier

  • demonstrates how to trigger an Accessory's Identifier Characteristic, optionally used to help identify a device during initial pairing to the Home App

• Converted the getLinks() SpanService method to a template function

  • new form is now: vector<T> getLinks<T=SpanService *>(const char *serviceName=NULL)
  • if template parameter, T, is specified, the elements of the returned vector will be cast into type T
  • if serviceName is specified, only those services matching serviceName will be included in the return vector
  • fully backwards-compatible with original getLinks() method

• New ability to halt the pulse generation for a ServoPin (#874)

  • calling set(NAN) for a ServoPin halts the pulse generation, which (for most analog servos) allows the motor to be freely rotated
  • calling set(position), where position equal the desired number of degrees, restarts the pulse generation and sets the servo position accordingly

Internal Updates

• Added support for Characteristics that require the write-response protocol to process write requests (#801)

  • not needed for any Characteristics that are currently supported by HomeSpan
  • but available for use with any Custom Characteristics that may require the write-response protocol
  • this feature is automatically enabled as needed - no user coding, setup, or configuration required
  • write-response requests will be processed regardless of whether the Characteristic has the WR permission set

• Added extra checks when using setVal()

  • a warning message is output on the Serial Monitor if setVal() is called to change the value of a Characteristic from within the update() method at the same time the Home App is sending an update request for that value
  • does not apply if setVal() is called from within update() to change the value of a Characteristic in response to a write-response request from the Home App

• Refactored client/slot management to save memory and prepare for future integration of Ethernet support

  • fixed-array of Client/Socket connections replaced by dynamic linked-list
  • serial interface now only shows active client connections (rather than a fixed list of client slots)
  • deprecated homeSpan.reserveSocketConnections()
    • no longer needed since new HomeKit Architecture requires only one or two connections from a central Home Hub
    • function throws compiler deprecation warning, but otherwise function does nothing

• Allow dynamic variables to be used for the string arguments in homeSpan.begin() and homeSpan.setHostNameSuffix() (#837)

  • string variables are now fully copied into their own memory rather than simply copying the pointers
  • allows local dynamic variables that go out of scope to be used as parameters

Bug Fixes

• Fixed bug introduced in 1.9.0 that prevented homeSpan.setPairingCode() from saving (and subsequently using) the request Setup Pairing Code (#786)

  • this method now operates silently, unless an invalid pairing code is provided, in which case an error is reported to the Serial Monitor and the sketch is halted
  • the process for setting the Pairing Code using the CLI 'S' command or via the Access Point are unchanged - confirmation messages are still output to the Serial Monitor and errors do not cause the sketch to halt

• Fixed memory leak introduced in 1.9.0 that would fail to free a small temporary memory block created when verifying a new connection (#844)

  • had no practical impact when using a Home Hub since Home Kit only creates a few permanent connections
  • had significant impact when not using a Home Hub in cases where the Home App repeatedly drops and re-establishes connections, resulting in slow erosion of heap memory and then out-of-memory failure of the device after a few days (note use of HomeSpan without a Home Hub is not formally supported)

• Fixed latent bug in SpanPoint

  • HomeSpan would crash when printing SpanPoint configuration information to the Serial Monitor (the 'i' CLI command) if any of the instances of SpanPoint had receiveSize=0
  • this bug never surfaced before since all the SpanPoint examples were based on receiving data and therefore had a non-zero receiveSize

Deleted Functions

• Deleted homeSpan.setMaxConnections(), which had been deprecated many versions ago

• Deleted stand-alone SpanRange structure, which had been deprecated many versions ago

  • this has no impact on standard use of the Characteristic method setRange()