New Features

• Updated HomeSpan Status logic and functionality for improved diagnostics (#848)

  • Added new HS_STATUS enum type HS_CONNECTED
    • reflects fully operational state where HomeSpan is connected to a WiFi or Ethernet network, paired to HomeKit and is maintaining one or more secure connections to HomeKit
    • Status LED set to steady ON when in this state
  • Modified HS_STATUS enum type HS_PAIRED
    • reflects potential "No Response" state where HomeSpan is connected to a WiFi or Ethernet network, paired to HomeKit but does not (yet) have any open secure connections to HomeKit
    • Status LED set to inverted double-blink when in this state
  • Added new std::pair<HS_STATUS,uint32_t> homeSpan.getStatus() method
    • returns pair containing:
      • current HomeSpan Status as HS_STATUS enum type
      • duration (in seconds) since HomeSpan first changed to that Status
    • this thread-safe method allows user to actively poll HomeSpan status and duration from the main loop() as alternative to using homeSpan.setStatusCallback() (which is only called when the HomeSpan Status changes)
  • Added new void homeSpan.resetStatusDuration() method
    • this thread-safe method allows user to reset current HomeSpan Status duration to zero
  • Complete re-write of HomeSpan Status documentation
    • demonstrates how to use the new methods above
    • provides example of using homeSpan.getStatus() to reboot HomeSpan if the device has lost secure HomeKit connections for an extended period of time
    • adds table providing graphic representation of all Status LED patterns for each HomeSpan Status state
    • adds direct link to this documentation on the main HomeSpan README.md page
  • See HS_STATUS.md for details

• Improvements to Web Log output (#848)

  • Added new Client Connections Table (similar output to 's' CLI command)
    • used as diagnostic to check whether HomeSpan has any active secure connections to HomeKit
  • Added descriptive class names for use with custom style sheets
    • body - background and header text (can use bod1 for backwards compatibility)
    • infoTable - the top table that provides general information about the device (can use tab1 for backwards compatibility)
    • clientTable - the newly-added table listing all active client connections (can use tab2 for backwards compatibility)
    • logTable - the bottom table listed all the individual Web Log entries (can also use tab2 for backwards compatibility)
  • See Logging.md for details

• Created ability to programmatically retrieve base-64 encoded Pairing Data from within a sketch (#1150)

  • Added the following two new methods:
    • const char* homeSpan.getPairingInfo(char **buf)
      • allocates memory to buf and fills with the HomeSpan's Device Pairing Data
      • returns buf, which must be de-allocated with free(buf) when no longer needed
    • const char* Controller::getPairingInfo(char **buf)
      • allocates memory to buf and fills with a Controller's Pairing Data
      • returns buf, which must be de-allocated with free(buf) when no longer needed
  • Using these methods duplicates the exact Accessory and Controller Pairing Data provided by the 'P' CLI Command needed to clone devices
  • See Reference.md for details on these methods and Cloning.md for a full example

• Added new boolean homeSpan.usingEthernet() method

  • returns true if Ethernet interface is being used, else false if WiFi is being used

• Added new Span& homeSpan.setControlTimes(uint32_t comTime, uint32_t resTime) method (#1149)

  • allows users to override HomeSpan's default hold times for the Control Button to trigger entering/exiting the Device Command Mode (default=3000ms) and for triggering a Factory Reset (default=10000ms)

• Redirected setVal() out-of-range warnings to WEBLOG instead of LOG0 so these warnings will be displayed in both the Serial Monitor and the Web Log

• Updated CUSTOM_CHAR() logic so that the HAP range and HAP description are automatically set based on the range and name specified in the macro

Other Updates and Corrections

• Revised User Guide documentation (UserGuide.md) to better align with HomeSpan Status conventions
  • also deleted Pages and PDF versions of User Guide since no longer needed
• Added loopTask and pollTask core and priority information to start-up diagnostics
• Corrected HAP nonce logic to utilize the full 64 bits allowed (#1144)
• Started WiFi radio during initialization so it can be used as an entropy source for random number generation (#1144)
  • changed DEFAULT_LOW_MEM_THRESHOLD from 80K to 20K for warning message since WiFi is now started earlier
• Added an "invert" mode to the Blinker class that provides additional flashing patterns for the HomeSpan Status LED
  • also corrected minor timing-delay mismatch in pattern logic

New Features

• HomeSpan now supports two-wire WS2801-based addressable RGB LEDs
  • adds new WS2801_LED class
  • uses SPI bus for optimal performance
  • includes the following methods consistent with HomeSpan's existing Pixel and Dot classes:
    • WS2801_LED(uint8_t dataPin, uint8_t clockPin)
    • void set(const Color *c, size_t nPixels)
    • void set(Color c, size_t nPixels)
    • static Color RGB(uint8_t r, uint8_t g, uint8_t b)
    • static Color HSV(float h, float s, float v)
    • void setTiming(uint32_t freq)
    • static Color *getMem(size_t nColors)
  • added a fully worked example of implementing a 25-pixel WS2801 RGB LED strand to HomeSpan's Pixel.ino tutorial sketch
  • see Pixels.md for complete documentation

Updates and Corrections

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

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).