HomeSpan v1.9.1

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

HomeSpan v1.9.0

New API Functions

• New ability to "chain" homeSpan methods

  • converted the following homeSpan methods that previously returned void to now return Span &:
    • setControlPin, setStatusPin, setStatusPixel, setStatusDevice, setStatusAutoOff
    • setApSSID, setApPassword, setApTimeout, setCommandTimeout, setLogLevel
    • reserveSocketConnections, setPortNum, setHostNameSuffix, setQRID
    • enableAutoStartAP, setApFunction, setWifiCredentials, setWifiCallback, setPairCallback, setStatusCallback
    • setPairingCode, setSketchVersion, enableWebLog, setTimeServerTimeout, setWebLogCSS, setSerialInputDisable
  • allows for chaining multiple homeSpan methods
  • example: homeSpan.setControlPin(21).setStatusPin(13);

• New ability to add custom content to the Web Log through a user-defined callback function (#657)

  • adds new homeSpan method Span& setWebLogCallback(void (*func)(String &))
  • provides a hook into the HTML that HomeSpan uses to generate the Web Log output
  • a reference to a String is passed as the first argument to func after the HTML for the initial table is produced, but before the table is ended and the second table is started
  • creating a function func to extend this String allows the user to add arbitrary data to additional rows of the initial table, as well as to optionally end the table and add a completely new block of custom HTML
  • see Logging.md for details

• New ability to suppress WiFi "Trying to connect to..." messages (#670)

  • adds new homeSpan method Span& setVerboseWifiReconnect(bool verbose=true)
  • set verbose to false to suppress WiFi "Trying to connect to..." messages from being logged to the Serial Monitor and Web Log
  • see Reference.md for details

• Updated WiFi Callback functionality (#655)

  • adds new homeSpan method Span& setWifiCallbackAll(void (*func)(int count))
  • similar to existing homeSpan method setWiFiCallback(void (*func)()) except that func is called every time a WiFi connection is established or re-established after a disconnect
  • func must be of type void and accept a single int argument, count, that HomeSpan uses to pass the number of times a WiFi connection has been established or re-established
  • see Reference.md for details

• New ability to trigger HomeSpan actions by power-cycling (or resetting) the device one or more times (#629)

  • adds new homeSpan method Span& setRebootCallback(void (*func)(uint8_t count), uint32_t upTime=5000)
  • func must be of type void and accept one argument of type uint8_t
  • func is called by HomeSpan after booting once upTime milliseconds have elapsed (default upTime=5000 ms if not specified)
  • 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
  • see Reference.md for details

• New ability to disable SpanPoint encryption (#712)

  • adds new class-level method SpanPoint::setEncryption(boolean encrypt)
  • if encrypt set to true, encryption is enabled; if encrypt set to false, encryption is disabled
  • by default, SpanPoint encryption is enabled unless this method is called to disable it
  • if SpanPoint encryption is disabled on the main device, it must be disabled on all remote SpanPoint devices as well
  • enabling/disabling SpanPoint encryption changes the maximum number of connections that can be supported by a single device:
    • with encryption, max=7 remote devices
    • without encryption, max=20 remote devices
  • these limitations are a result of the underlying ESP-NOW protocol
  • if exceeded, HomeSpan will provide warning messages on the Serial Monitor during start-up
  • see NOW.md for details

• New ability to get handle of HomeSpan Auto Poll task (#725)

  • adds homeSpan method TaskHandle_t getAutoPollTask()
  • returns the Task Handle for the HomeSpan Auto Poll Task (when invoked by homeSpan.autoPoll()), or NULL if Auto Polling is not used
  • see Reference.md for details

• New ability to use Inverted or Touch Buttons as a Control Button (#701)

  • adds triggerType as a second, optional argument to Span& setControlPin(uint8_t pin, PushButton::triggerType_t triggerType=PushButton::TRIGGER_ON_LOW), where triggerType has the same meaning as in SpanButton:
    • PushButton::TRIGGER_ON_LOW
      • triggers when pin is driven LOW
      • suitable for buttons that connect pin to GROUND (this is the default when triggerType is not specified)
    • PushButton::TRIGGER_ON_HIGH
      • triggers when pin is driven HIGH
      • suitable for buttons that connect pin to VCC (typically 3.3V)
    • PushButton::TRIGGER_ON_TOUCH
      • uses the device's touch-sensor peripheral to trigger when a sensor attached to pin has been touched
      • not available on ESP32-C3
    • as an alternative, you can set triggerType to any user-defined function of the form boolean(int arg) to utilize any device as a Control Button
  • see Reference.md for details

• New HomeSpan constants to reflect allowable states for each Characteristic (#679)

  • can use named constants instead of integers when reading and writing values of applicable Characteristics
  • 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) {...}
  • see ServiceList.md for an update list of Services, Characteristics, and their constants

• New ability to name individual Services (#485)

  • deprecated Characteristic::Name() and replaced with Characteristic::ConfiguredName() for all Services except the AccessoryInformation Service, which till requires Characteristic::Name()
  • completely re-wrote Example 11 (ServiceNames) to reflect the new use of the ConfiguredName Characteristic

• Updated the Services and Characteristics web page to provide functional descriptions and detailed specifications for every Service and Characteristic supported by HomeSpan

  • page is autogenerated as needed from the structure and comments presented in certain HomeSpan library files
  • includes a complete list of all allowed constants for each Characteristic (and their default values)

• New Stepper Motor Drivers

  • Stepper_UNIPOLAR: a generic driver for any 4-wire center-tapped unipolar motor
  • Stepper_UNL2003: support for the UNL2003 driver board
  • see Stepper.md for details

• Removed dependencies on various "extra" #include files

  • the following #include files are now embedded in HomeSpan.h and do not need to be specified in any sketch:
    • extras/Pixel.h
    • extras/RFControl.h
    • extras/PwmPin.h
    • extras/StepperControl.h
  • automatic inclusion of these files does not yield a larger binary since the classes within each module are not linked into the final binary unless a class is explicitly used in your sketch (or by HomeSpan itself)
  • including these files in sketch has no impact but is allowed (providing backwards compatibility for sketches that previously included these files)

• Additional Web Log functionality (#770)

  • adds new homeSpan method getWebLog(void (*f)(const char *, void *), void *args)
    • when called, HomeSpan streams the current Web Log HTML text, and any optionally-specified user-data, args, directly to the user-defined function, f(), for user-defined processing
  • setting the optional fourth argument of homeSpan.enableWebLog() to NULL sets the URL for the Web Log to NULL
    • this causes HomeSpan to ignore any HTTP requests for the Web Log page
    • allows use of enableWebLog() to set the time from an NTP server without also serving Web Log pages
  • see Logging.md for details

Significant Refactoring to Optimize Memory Use

• HomeSpan can now support 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
• Changed 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 (#619)
• HomeSpan will print a warning to the Serial Monitor at boot-up if free internal RAM seems to be getting too low based on memory use before WiFi is started
• Refactoring included:
  • converted all large fixed-size stack-based buffers to dynamically-sized heap-based buffers
  • ensure applicable heap-based buffers use PSRAM when available
  • added custom allocators to containers, and custom constructors to objects, to ensure they use PSRAM when available
  • converted the static array that stored all pairing info for 16 Controllers to a linked-list only storing data for Controllers as needed
    • HomeKit typically only assigns a few Controllers, so no need always reserve space for 16
    • also frees up a lot of NVS space (since Controller pairing info is stored there)
  • converted the containers holding the lists of required and optional Characteristics for each Service to a much more efficient storage class
    ...

HomeSpan v1.8.0

Updates

• New Stepper Motor Control

  • adds new StepperControl class that allows for smooth, uninterrupted operation of one or more stepper motors running in the background while HomeSpan continues to run simultaneously in the foreground
  • includes drivers for the Toshiba TB6612 and Allegro A3967 stepper motor chips
  • supports creation of user-defined drivers
  • provides the following methods:
    • StepperControl *setStepType(int mode) - sets the stepping mode (including microstepping)
    • StepperControl *setAccel(float accelSize, float accelSteps) - automatic acceleration and deceleration for smooth starts and stops
    • void move(int nSteps, uint32_t msDelay, endAction_t endAction) - turns the motor a specified number of steps, with a specified delay between steps
    • void moveTo(int nPosition, uint32_t msDelay, endAction_t endAction) - turns the motor to an absolute position, with a specified delay between steps
    • StepperControl *enable() - enables the motor driver
    • StepperControl *disable() - disables the motor driver
    • StepperControl *brake() - puts the motor into a short brake state
    • int position() - returns the absolute position of the motor
    • void setPosition(int pos) - resets the absolute position of the motor
    • int stepsRemaining() - returns the number steps remaining to turn the motor
  • includes a fully worked example of a motorized window shade
  • see Stepper.md for details

• Upgrades to HomeSpan Web Log output (#563 and #566 - thanks @frankonski)

  • adds new method void homeSpan.setWebLogCSS(const char *css) that allows you to define custom style sheets (CSS) for the Web Log text, tables, and background
  • adds charset=utf-8 to HTML responses to ensure proper handling of UTF-8 characters
  • adds version numbers for the Sodium and MbedTLS libraries
  • adds HomeKit pairing status
  • adds text description of Reset Reason code
  • see Logging.md for details

• Upgrades to Web Log Time Server initialization (#553)

  • the process for retrieving the time and date from an NTP server upon booting now runs in the background as a separate task
  • HomeSpan is no longer blocked from running during the NTP query
  • the default time-out for the NTP server query has been extended from 10 seconds to 120 seconds

• Added methods to disable HomeSpan's use of the USB Serial port (#576)

  • new Log Level, -1, causes HomeSpan to suppress all OUTPUT messages
  • new homeSpan method setSerialInputDisable(boolean val) disables/re-enables HomeSpan's reading of CLI commands INPUT into the Arduino Serial Monitor
  • useful when the USB Serial port is needed to communicate with a separate Serial device instead of with the Serial Monitor
  • new homeSpan method boolean getSerialInputDisable() returns true if HomeSpan's reading of CLI commands from the Serial Monitor is disabled, else returns false

• Added ability to use a non-standard LED as the HomeSpan Status LED (#590)

  • new homeSpan method setStatusDevice(Blinkable *sDev) sets the Status LED to the Blinkable object sDev
  • allows an LED connected to a pin expander, or any other non-standard LED controller (such as an inverted LED that lights when a pin is LOW instead of HIGH) to be used as the HomeSpan Status LED
  • see Blinkable.md for details (including an example) on how to create Blinkable objects

Bug Fix

• Addressed a compilation error caused by a conflict between the name of an internal enum, "BUTTON", which is used by SpanButton, but also happens to be a macro definition used in the pins_arduino.h configuration files for the adafruit_feather_esp32_v2, adafruit_qtpy_esp32c3, and cytron_maker_feather_aiot_s3 boards (#564)

  • Solution was to change the name of the enum from "BUTTON" to "HS_BUTTON" in SpanButton. This is a private enum and has no end-user impact

HomeSpan v1.7.2

Updates

• New ability to set OTA password from within sketch (#503)

  • adds homeSpan.enableOTA(const char *pwd, boolean safeLoad=true) method
  • see OTA.md for details

• Added logic to allow duplicates of the same Custom Characteristic to be "defined" in more than one file in a sketch (#499)

  • include #define CUSTOM_CHAR_HEADER before #include "HomeSpan.h" in any file using a Custom Characteristic macro to create a duplicate of a Custom Characteristic that was already defined in another file
  • the allows the use of the same Custom Characteristic across multiple files in the same sketch without the compiler throwing a "redefinition error"
  • see Reference.md for details

• Extended functionality of setValidValues() to work with more than just UINT8 Characteristics (#487)

  • now works with INT, UINT16, and UINT32 Characteristics, as well as UINT8 Characteristics
  • will be ignored and throw a Warning message on the Serial Monitor if used with any other Characteristic format

• Added two more parameters to homeSpan.autoPoll() that allow the user to set priority and CPU (#536)

  • new signature is autoPoll(uint32_t stackSize=8192, uint32_t priority=1, uint32_t cpu=0)
  • cpu parameter is ignored on single-processor boards
  • see Reference.md for details

• Added new methods to LedPin class that enable use of ESP32's built-in fade controls (#529)

  • int fade(float level, uint32_t fadeTime, int fadeType=ABSOLUTE) automatically fades an LedPin to the level specified over the fadeTime (in milliseconds) specified
  • int fadeStatus() returns the current fading status (e.g. fading, not fading) of an LedPin
  • see PWM.md for details

• Added ability to Clone the Pairing Data from one device to another (#543)

  • adds new 'P' and 'C' commands to the CLI
  • enables a broken device to be swapped for a new device (running the same sketch) without the need to unpair the old device or pair the new device
  • avoids loss of automations, scenes, and any other Home App customizations associated with device
  • new and old device can be different chips (e.g. ESP32-S2 versus ESP32-C3)
  • see Cloning.MD for details

Bug Fix

• Deleted initialization of WiFiClient (was being set to zero), which caused "Bad file number" errors when HomeSpan first boots (#508)

  • this error message was only output to the Serial Monitor if the sketch was compiled with "Core Debug Level" set to "error" or above

HomeSpan 1.7.1

Updates

• Improved SpanPoint scanning

  • the last channel used for transmission is now automatically retained in NVS so that upon reboot this channel, rather than the lowest channel allowed by your channel mask, will become the first channel tried when transmissions resume
  • helps improve battery life by likely reducing the number of channels SpanPoint may need to try upon reboot (because it starts scanning with a channel that was previously known to work)
  • exception: the channel stored will not be used upon reboot if it is not allowed by your channel mask
  • this feature requires no user configuration and is automatically implemented on any "remote" HomeSpan device
  • this feature is not used for "main" HomeSpan devices connecting to HomeKit (the channel is set according to your WiFi network)

• Connect an ESP8266 to HomeSpan using ESP-NOW

  • added an option to the SpanPoint constructor indicating that SpanPoint should use the ESP32 device's AP MAC Address instead of its STA MAC Address when transmitting and receiving data via ESP-NOW
    • this enables SpanPoint to receive ESP-NOW data from ESP8266 devices
    • without this option, data transmission from a "Remote" ESP8266 device to the "Main" ESP32 device running HomeSpan fail as soon as HomeSpan connects to a central WiFi network (this is not an issue when the Remote device is also an ESP32)
  • added a list of all SpanPoint objects instantiated in a sketch showing their parameters and associated MAC Addresses, along with current WiFi channel being used by the device, to the HomeSpan Info displayed in the Serial Monitor when typing 'i' into the CLI
  • added a detailed example, RemoteDevice8266, illustrating how to configure ESP-NOW on an ESP8266 so it can transmit data to an ESP32 running HomeSpan
  • see the SpanPoint page for full details

• New SpanToggle class

  • similar to SpanButton, but provides functionality to read the state of a toggle-switch
  • calls the button() method within a Service whenever the switch is toggled from one position to another
  • automatically debounces the switch to prevent false triggers
  • include a posiiton() method that returns the state of the toggle switch (CLOSED or OPEN)
  • useful for implementing Contact Sensors
  • see the API Reference for full details

• Added TelevisionSpeaker Service

  • allows user to control the volume of a Television from Apple's Remote App (found in the Control Panel on an iPhone)
  • updated Television example to include this new Service

• Added HAP-R2 DATA format to store and transmit byte-array Characteristics

  • includes new methods setData(), getData(), and getNewData(), which are analogous to setVal(), getVal(), and getNewVal()
  • includes new macro CUSTOM_CHAR_DATA() for creating custom byte-array Characteristics
  • note that HAP-R2 does not currently include any Characteristics that use the DATA format, but other applications, such as Eve for HomeKit, do make use of this format
  • see the API Reference for full details

• Added optional flag to LedPin that inverts the PWM output signal

  • useful for generating two, separate out-of-phase PWM signals (one inverted, one not) to drive certain two-pin devices in a push/pull manner, such as a piezo-electric buzzer

• Relocated the Other Examples folder so that it is now a subfolder of "examples"

  • required for proper displaying and access to the examples when using version 2 of the Arduino IDE

• Added logic to prevent the extraneous broadcasting of an Access Point SSID when SpanPoint is being used

  • since SpanPoint starts WiFi in AP+STA mode when data is to be received, this caused the device to broadcast its AP SSID, even though the device was not running an access point server

HomeSpan 1.7.0

Updates

• Created the SpanPoint class, an easy-to-use, device-to-device communication method based on ESP-NOW

  • supported methods include:
    • send() and get() to transmit and receive fixed-size messages,
    • time() to track elapsed time since last message received, and
    • class-level setPassword() and setChannelMask() to customize SpanPoint settings
  • includes detailed example sketches demonstrating how SpanPoint can be used to implement a battery-powered Remote Sensor
  • see the dedicated SpanPoint tutorial page for full details

• Created homeSpan.setStatusPixel() method

  • allows an RGB NeoPixel to be used as the HomeSpan Status LED instead of a regular LED
  • works well with ESP32 boards that have a built-in NeoPixel LED, though adding an external NeoPixel is fine
  • allows user to optionally specify the operating color (default is red)
  • see the API Reference for details

• Created homeSpan.setStatusCallback() method

  • provides users with a callback method whenever the internal state of HomeSpan changes, such as from WiFi Needed to WiFi Connecting...
  • tracks changes to the run-time state of HomeSpan that would normally trigger a change in the blinking pattern of the (optional) Status LED
  • includes a helper function, homeSpan.statusString(), that returns short pre-defined character string message associated with each status update
  • facilitates the creation of custom user code to output status messages to an LCD or other display attached to a HomeSpan device
  • see API Reference for details

Bug Fixes

• Fixed bug in touch sensor logic that would cause compile failure when using Arduino-ESP32 versions 2.0.0-2.0.2

  • verified that code compiles and works under all versions (2.0.0 through 2.0.5) of Arduino-ESP32

• Fixed bug in controller-update logic that caused an admin controller to downgrade to a non-admin controller

  • was result of a particular HAP message that was previously unused by Apple HomeKit but not handled correctly in HomeSpan

HomeSpan 1.6.0

Updates

• Created homeSpan.autoPoll() method

  • can be used as an alternative to placing homeSpan.poll() in main Arduino loop()
  • if used, should be placed at very end of main Arduino setup() function
  • creates a background task that automatically calls homeSpan.poll()
  • useful if user-defined code needs to be added to loop() that would either block, or be blocked by, calling homeSpan.poll()
  • works with single-core and dual-core processors
  • for dual-core processors, task is created on "free" core not being used by other Arduino functions
  • created default weakly-defined Arduino loop() function so that it does not need to be defined in a sketch (unless needed for other purposes) if homeSpan.autoPoll() is called at the end of setup()
  • do not use homeSpan.autoPoll() and homeSpan.poll() in the same sketch - use one method or the other!
  • see API Reference for details

• Refactored HomeSpan Info 'i' CLI command

  • database validation is now dynamically generated based on the current state of all Characteristics (previously 'i' only reflected a static view of the initial values of the database at start-up)
  • all error checking logic from a variety of constructors and initializers has been simplified and moved to the 'i' command
  • allows for re-validation of the database after any real-time structural changes (e.g. adding/deleting an Accessory)

• Created homeSpan.deleteAccessory(aid) method

  • deletes an Accessory with the specified aid and automatically deletes all Services, Characteristics, and any other resources associated with the Accessory
  • returns true if an Accessory with matching aid is found, or false if not
  • allows database to be dynamically altered without needing to reboot device
  • typing 'i' in the CLI (see above) immediately reflects changes
  • note: the Home App will not reflect changes made in this fashion until it receives an updated configuration number via MDSN (see below)

• Created homeSpan.updateDatabase() method

  • checks for changes in database made dynamically during runtime (as a result of new or deleted Accessories)
  • if changes found, configuration number is updated, saved in NVS, and broadcast over MDNS
  • this triggers the Home App to immediately request a refresh of the full database so that changes can be reflected in the Home App without the need to reboot the device
  • returns true if config number is updated, or false if not (i.e. database had not been changed)

• Created Example 20-AdvancedTechniques

  • Demonstrates how the homeSpan.deleteAccessory() and homeSpan.updateDatabase() methods can be used to create a bridge device that can be dynamically updated without the need to reboot HomeSpan
  • Also included the homeSpan.autoPoll() method to show how it can be used in place calling homeSpan.poll() from the main Arduino loop() method

• Created ProgrammableHub Example

  • Located in Other Examples
  • Demonstrates how to implement a web interface to dynamically add/delete Light Accessories to a bridge accessory
  • Expands upon many of the methods used in Example 20

• Added 'm' CLI command

  • prints free bytes remaining in heap memory that can be used for any arbitrary allocations made by alloc or new

• Added homeSpan.getLogLevel() method

  • returns current Log Level
  • needed for LOG, LOG1, and LOG2 macros after converting Span from struct to class (see below)

• Added homeSpan.addWebLog() method

  • needed by WEBLOG() macro after converting Span from struct to class (see below)
  • NOT exposed in API (users should use WEBLOG instead)

• Added support for ESP32-S3

  • changed clock-select logic in RFControl to use clock-divider by checking to see if it is available (ESP32-C3 and S3); if not, use REF_TICK as RMT clock (ESP32 and ESP32-S2)
  • reported bug to Espressif re the S3 version of the header file rmt_regs.h that contains misnamed macros for RMT channels 4-7, which causes a compiler warning ("duplicate definitions"). However, this has no impact of the operation of HomeSpan and the warning can be safely ignored. Espressif fixed the bug and it is incorporated into board manager version 2.0.4.

• Improved WiFi disconnect/reconnect handling

  • initialization of MDNS, Web Logs, time-sync, etc. now occurs ONLY after initial WiFi connection is made, NOT after each reconnect caused by a disconnect (this was creating a resource drain, and also caused Web Log to incorrectly show boot time to be last reconnect time)
  • WiFi diagnostics added to Web Log, including messages for connect/disconnects, a tally for total number of disconnects since boot time, and WiFi signal strength

• Expanded SpanButton() functionality

  • users can choose between a pin connected to ground via a pushbutton, a pin connected to VCC via a pushbutton, or a pin connected to a touch sensor or touch pad
  • touch pad pins are automatically calibrated upon instantiation of SpanButton()
  • users can override calibration if needed using new methods SpanButton::setTouchThreshold() and SpanButton::setTouchCycles()
  • users can extend the functionality of SpanButton to use pin expanders, multiplexers, or other "pushbutton" devices by defining custom triggering functionality

Refactoring

• Converted all API objects (Span, SpanAccessory, SpanService, SpanButton...) from struct to class

  • allows for the proper separation of public, protected, and private members of each class

• moved underlying code for HAPClient::callServiceLoops() and HAPClient::checkPushButtons() into homeSpan.pollTask()

  • cleans up some previously convoluted code

HomeSpan v1.5.1

Updates

• Added an additional (optional) argument to the SpanUserCommand() constructor that allows the user to provide a pointer to an object that HomeSpan will pass to the function specified

  • The new (optional) constructor is of the form:
    • SpanUserCommand(char c, const char *desc, void (*f)(const char *buf, void *obj), void *userObject)
    • where the specified userObject will be passed by HomeSpan to the function f in the second argument, obj when called
  • Useful for passing the pointer to an Accessory, Service, or Characteristic, that will be the subject of a custom User Command
  • See the API Reference for details

• Add new CUSTOM_SERV() macro

  • Allows users to add their own Custom Services for use with third-party apps, such as Eve for HomeKit
  • Works well with the existing CUSTOM_CHAR() and CUSTOM_CHAR_STRING() macros
  • Includes a fully worked example of a custom Pressure Sensor Accessory that is recognized by Eve for HomeKit
  • See the API Reference for details

• New Web Logging Functionality

  • Added homeSpan.enableWebLog(uint16_t maxEntries=0, const char *serv=NULL, const char *tz="UTC", const char *url=DEFAULT_WEBLOG_URL)
  • Added setTimeServerTimeout(uint32_t tSec){webLog.waitTime=tSec*1000;}
  • Added WEBLOG() Macro
  • Added new Example 19 showing how web logging works
  • See Message Logging for details

• Added variadic form of LOG1() and LOG2() macros; added LOG0() macro

  • Allows the use of printf-style formatting when provided with 2 or more arguments
  • Example: LOG2("The pin is: %d\n",pinNumber);
  • See Message Logging for details

• Added "Safe-Load" mode to OTA (enabled by default)

  • HomeSpan checks to make sure the new sketch being uploaded via OTA is another HomeSpan sketch. If not, the upload fails
  • Upon rebooting after an OTA update, HomeSpan checks to ensure that OTA is enabled in the updated sketch. If not, HomeSpan rolls back to the previous version of the sketch

• Added new SPAN_ACCESSORY() and SPAN_ACCESSORY(NAME) macros

  • Convenience macros that expand to very common code snippets used frequently when creating new Accessories
  • See the API Reference for details

• Refreshed all Tutorials and Examples

  • Ensured each sketch works under iOS 15.4 given the number of significant changes Apple has made to the Home App
  • Simplified sketches by eliminating the separate DEV_Identify.h file, previously introduced in Example 7, and used in most subsequent examples as a result of experimentation that shows:
    • the HAP Protocol Information Service and associated Version Characteristic are no longer needed/used by HomeKit. Deleted from all examples
    • the Firmware Revision, Manufacturer, Model, and Serial Number Characteristics for the Accessory Information Service are now optional as opposed to being required. With the exception of Example 1, these have been deleted for all other sketches to promote clarify and ease of use
    • the Name Characteristic for the Accessory Information Service is also longer required, but can still be used to effect a change to the default name for an Accessory Tile, except for the very first Accessory in a device, which always matches the device name
    • Replaced Example 7 - IdentifyRoutines with Example 7 - AccessoryNames to demonstrate how to change the default names of Accessory Tiles
  • Replaced Example 11 - ServiceOptions with Example 11 - Accessory Names
    • HomeKit and the Home App seem to now ignore the Primary Service property of a Service (as set in HomeSpan with the setPrimary() method)
    • the example has been re-worked to demonstrate how the Name Characteristic, as well as the order in which Service are implemented in an Accessory, can change how Services are named and presented (including Tile icons) in the Home App
  • Note that Example 17 - LinkedServices, which implements a multi-head shower, does not seem to function properly under iOS 15.4 (maybe earlier versions of iOS 15 as well). Will retain example as is in hope that Apple addresses the issues in the future, or a work-around can be found

Internal/Developer Use

• Added FeatherPins.h that provides a mapping of various boards to a standard set of pins that map the Adafruit ESP32 FeatherBoard. Useful for creating generic sketches that can run on any board defined in FeatherPins.h without remapping pins

HomeSpan v1.5.0

Updates

• Added new Pixel() and Dot() classes

  • allows for easy control of one- and two-wire addressable RGB and RGBW LEDs and LED strips, such as this NeoPixel RGBW LED or this DotStar RGB Strip
  • three modes of operation:
    • set a single LED pixel to a specific color
    • set a multi-pixel strip of LEDs to the same color
    • set each LED pixel in a multi-pixel strip to a different color
  • colors can be specified in RGB or HSV space
  • the Pixel() class supports a 4th white LED (applicable for RGBW devices)
  • the Dot() class supports control of LED brightness by specifying the maximum LED current for any pixel
  • includes a detailed tutorial sketch demonstrating different ways of using the Pixel() and Dot classes, as well an advanced HomeSpan "HolidayLights" Project that shows how to develop custom special effects
  • see HomeSpan Pixels for full details

• Re-worked the logic by which HomeSpan determines the number of HomeKit Controller Connections to instantiate

  • The default number of connections is now set to CONFIG_LWIP_MAX_SOCKETS-2
    • prior to Arduino-ESP32 version 2.01, this yielded 8 Controller Connections
    • as of Arduino-ESP32 version 2.01 and later, this yields 14 Controller Connections
  • Added new method reserveSocketConnection(uint8_t nSockets) to homeSpan object
    • provides a way for users to reserve network resources for custom functions, such as a web server or MQTT server
    • the total number of Controller Connections actually instantiated by HomeSpan at start-up will be the default above minus the total number of sockets reserved
  • Deprecated setMaxConnections(uint8_t nCon) method, which was less flexible and required the uses to specify the net number of connections HomeSpan should instantiate, rather than let HomeSpan compute this based on the number of sockets the user needs for any additional network functions

• Added new method setDescription(const char *desc) to SpanCharacteristic

  • allows you to set an optional description field, desc, for any Characteristic
  • this field does not appear to be used in any way by the Home App, but may be useful for describing custom Characteristics

• Added new method setUnit(const char *unit) to SpanCharacteristic

  • allows you to set or override the unit for any Characteristic
  • useful for requiring numeric Characteristics to be displayed as percentages in the Home App

• Added new method setStatusAutoOff(uint16_t duration) to homeSpan object

  • causes Status LED (if used) to automatically turn off after duration seconds
  • Status LED will turn back on whenever HomeSpan changes the blinking pattern, after which the duration timer restarts
  • useful for devices located in darkened rooms (such as a bedroom) where the Status LED might be very noticeable

• Added new method setPairCallback(func) to homeSpan object

  • func is a user-definable function that HomeSpan calls upon completion of pairing or unpairing the device to a controller
  • func should be of the form void func(boolean status) where status will be set to true when device is first paired, or false when it is unpaired

• Added new method deleteStoredValues() to homeSpan object

  • deletes value setting of all Characteristics stored in the NVS
  • performs the same function as typing 'V' into the CLI

• Added getPin() method to RFControl class

  • returns pin number for any instantiated RFControl
  • used by new Pixel class

• Updated MDNS broadcast with addition fields:

  • ARDUINO_VARIANT (type of board)
  • Arduino-ESP32 Version Number

Bug Fixes

• The CUSTOM_CHAR() macro could not be used to create a custom String-based Characteristic (would throw compiler error). A new macro CUSTOM_CHAR_STRING() has been implemented specifically to create custom String-based Characteristics. See API for details

• Extended the HomeSpan HAP parser to accept the words "true" and "false" when sent by the Home App to update an integer-based Characteristic, such as Characteristic:Active. This is not specified by HAP-R2 and HomeSpan would only accept Home App updates with words "true" or "false" if the Characteristic was of type boolean. Under normal circumstances the Home App never sends the word "true" or "false" to update an integer-based Characteristic, but it does do so when being triggered by a Home App automation. Extending the HomeSpan HAP parser to also accept the words "true" and "false" (and convert them to 1 and 0, accordingly) for all integer-based Characteristics, instead of just boolean-based Characteristics, fixes the problem of unresponsive automations for certain Services.

HomeSpan v1.4.2

Updates to Library

• Added optional second argument to setVal(value [,boolean notify=true]) that allows the value of a Characteristic to be updated without sending notification messages to HomeKit

  • If notify is unspecified, it defaults to true, which is the normal behavior
  • Not sending notifications is an exceptional case used in limited circumstances - see API for details

• Added getLinks() as a new method to SpanService

  • Returns a vector of pointers to SpanServices that have been linked to another Service with the addLink() method
  • Typically will be recast into a specific Service - see API for details

• Added setPerms(uint8_t perms), addPerms(uint8_t perms), and removePerms(uint8_t perms) as new methods to SpanCharacteristic

  • Allows the user to modify (set/add/remove) the default permissions for any Characteristic
  • perms is additive list of permissions as described in HAP-R2 Table 6-4. Valid values are PR, PW, EV, AA, TW, HD, and WR

• Added setPairingCode(const char *s) method to the global homeSpan object that allows for programmatically configuring the Pairing Setup Code inside your sketch. See API for important security considerations when using this function!

Bug Fixes

• Fixed bug in TimedWrite logic that would crash an ESP32-C3 if Characteristics subject to a Timed Write process were updated (not sure why this problem only surfaced on the ESP32-C2 - it should have created a similar memory issue on the ESP32 as well)

• Updated logic in Blinker::isrTimer() to address compilation errors when using Arduino-ESP32 version 2.0.1 with ESP32-S2 and C3 chips (there were no problems when using original ESP32). Logic is now fully compatible with Arduino-ESP32 versions 2.0.1, 2.0.0, and original 1.0.6, and will hopefully be future-proof to any further changes in the IDF for timers