sieja/Arduino
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update libki

Browse Source
This commit is contained in:
sieja
2025-07-21 21:31:40 +02:00
parent d145590bd3
commit a9fba3267d
47 changed files with 2072 additions and 914 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
ESP32/HomeSpan-master/README.md
View File

@@ -4,12 +4,16 @@ Welcome to HomeSpan - a robust and extremely easy-to-use Arduino library for cre
HomeSpan provides a microcontroller-focused implementation of Apple's HomeKit Accessory Protocol Specification Release R2 (HAP-R2) designed specifically for the Espressif ESP32 microcontroller running within the Arduino IDE. HomeSpan pairs directly to HomeKit via your home WiFi network without the need for any external bridges or components. With HomeSpan you can use the full power of the ESP32's I/O functionality to create custom control software and/or hardware to automatically operate external devices from the Home App on your iPhone, iPad, or Mac, or with Siri.
HomeSpan requires version 2 of the [Arduino-ESP32 Board Manager](https://github.com/espressif/arduino-esp32). HomeSpan can be run on the original ESP32 as well as Espressif's ESP32-S2, ESP32-C3, and ESP32-S3 chips.
Requirements to run HomeSpan depend on which version you choose:
HomeSpan is currently NOT compatible with version 3.X of the Arduino-ESP32 Board Manager, since version 3 contains many breaking changes and is not backwards-compatible with version 2.X of the Arduino-ESP32 Board Manager. At present, HomeSpan can only be compiled under version 2.X of the Board Manager.
|HomeSpan Version | Arduino-ESP32 Board Manager | Partition Scheme | Supported Chips|
|:---:|:---:|:---:|---|
|1.9.1 or earlier | v2.0.0 - v2.0.17 | *Default* (1.3MB APP) | ESP32, S2, S3, C3 |
|2.0.0 or later | v3.0.2 - **v3.2.0**<sup>*</sup> | *Minimal SPIFFS* (1.9MB APP) | ESP32, S2, S3, C3, *and C6* |
> [!NOTE]
> Apple's new HomeKit architecture [requires the use of a Home Hub](https://support.apple.com/en-us/HT207057) (either a HomePod or Apple TV) for full and proper operation of any HomeKit device, including those based on HomeSpan. Without a Home Hub, HomeSpan cannot send notifications to the Home App - things like pushbuttons and temperature sensors will not be able to transmit updates to the Home App. Use of HomeSpan without a Home Hub is NOT recommended.
<sup>*</sup>HomeSpan has been tested through **version 3.2.0** of the Arduino-ESP32 Board Manager (built on IDF 5.4.1). Later releases may work fine, but have not (yet) been tested. Note HomeSpan does not support the use of alpha, beta, or pre-release candidates of the Arduino-ESP32 Board Manager - testing is only done on production releases of the Board Manager.
**ADDITIONAL REQUIREMENTS**: Apple's HomeKit architecture [requires the use of a Home Hub](https://support.apple.com/en-us/HT207057) (either a HomePod or Apple TV) for full and proper operation of any HomeKit device, including those based on HomeSpan. ***Use of HomeSpan without a Home Hub is NOT supported.***
### HomeSpan Highlights
@@ -20,6 +24,7 @@ HomeSpan is currently NOT compatible with version 3.X of the Arduino-ESP32 Board
* Dozens of integrated HomeKit Services
* Operates in either Accessory or Bridge mode
* Supports pairing with Setup Codes or QR Codes
* Supports both WiFi and Ethernet connectivity to your home network
### For the HomeSpan Developer
@@ -35,7 +40,7 @@ HomeSpan is currently NOT compatible with version 3.X of the Arduino-ESP32 Board
* Physical pushbuttons that connect an ESP32 pin to either ground or VCC
* Touch pads/sensors connected to an ESP32 pin (for ESP32 devices that support touch pads)
* Integrated access to the ESP32's on-chip Remote Control peripheral for easy generation of IR and RF signals
* Dedicated classes to control one- and two-wire addressable RGB and RGBW LEDs and LED strips
* Dedicated classes to control one- and two-wire addressable RGB LEDs and LED strips
* Dedicated classes to control stepper motors that can run smoothly in the background without interfering with HomeSpan
* Dedicated class that faciliates seamless point-to-point communication between ESP32 devices using ESP-NOW
* Integrated Web Log for user-defined log messages
@@ -54,97 +59,48 @@ HomeSpan is currently NOT compatible with version 3.X of the Arduino-ESP32 Board
* Launch the WiFi Access Point
* A standalone, detailed End-User Guide
## ❗Latest Update - HomeSpan 1.9.1 (07/03/2024)
## ❗Latest Update - HomeSpan 2.1.2 (05/08/2025)
* **HomeSpan now supports *Tag-Length-Value ("TLV8")* Characteristics!**
### Updates and Corrections
* adds new, fully-integrated `TLV8()` class library for the creation and management of TLV8 objects
* includes methods to handle standard byte-stream VALUES as well as strings, numerical values, zero-length tags, and sub-TLVs
* utilizes standard C++ iterators for easy access to reading and writing TLV8 records
* adds new `Characteristic` methods `getTLV()`, `getNewTLV()`, and `setTLV()`
* adds new `CUSTOM_CHAR_TLV8()` that allows for easy creation of custom TLV8 Characteristics
* includes new [Tutorial Example 22 - TLV8 Characteristics](examples/22-TLV8_Characteristics) demonstrating use of the `TLV8()` class and TLV8 Characteristics
* see the new [TLV8 Characteristics](docs/TLV8.md) page for complete details and documentation
* **New *DisplayOrder* TLV8 Characteristic**
* utlizes HomeSpan's new `TLV8()` library
* allows you to specify the exact order in which the Input Sources for a Television Service are displayed in the Home App
* see [Tutorial Example 22 - TLV8 Characteristics](examples/22-TLV8_Characteristics) for details
* **Added UUID validation for Custom Services**
* 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***
* 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***
* 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
* **New *AccessoryIdentifier* Tutorial**
* 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)
* demonstrates how to trigger an Accessory's Identifier Characteristic, optionally used to help identify a device during initial pairing
* see [Tutorial Example 21 - AccessoryIdentifier](examples/21-AccessoryIdentifier)
* **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 support for customizing Pixel chips**
* **Added new *homeSpan* method `assumeTimeAcquired()`**
* 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
* 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)
* added new [PixelTester](examples/Other%20Examples/PixelTester) sketch (found under *Other Examples*) to aid in determining the *pixelType* for any LED Strip
* see the [Adressable RGB LEDs](docs/Pixels.md) page for details
* **New ability to read and set the IIDs of Services and Characteristics**
* **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
* 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](docs/Reference.md) for details
* **New ability to read Controller pairing data (for advanced use-cases only)**
* **Explicitly added added `#include <mutex>` to *HomeSpan.cpp* to address compatibility issue with Arduino-ESP32 v3.2.0**
* adds new `homeSpan` methods `controllerListBegin()` and `controllerListEnd()` that returns iterators to HomeSpan's internal linked-list of Controller data records
* adds new methods to read each Controller's pairing data:
* `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
* adds new `homeSpan` method `setControllerCallback()` to set optional callback function that HomeSpan calls whenever a controller is added, removed, or updated
* see the [API Reference](docs/Reference.md) for details
* **HomeSpan now supports the *write-response ("WR")* protocol**
* added automated handling of the HomeKits's *write-response ("WR")* protocol*
* not needed for any Characteristics that are currently supported by HomeSpan, but useful for experimentation and work with Custom Characteristics
* 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
* **Converted the `getLinks()` SpanService method to a template function**
* allows user to automatically cast the elements of the returned vector into any specific Service type
* also adds an optional parameter to restrict the elements of the returned vector to match a specified HomeSpan Service
* see the [API Reference](docs/Reference.md) for details
* **New ability to halt the pulse generation for a ServoPin**
* 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
* **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()` since it is no longer needed
* **Fixed bug in `Pixel::getPin()` that would report channel number instead of pin number**
* **Fixed bug introduced in 1.9.0 that prevented `homeSpan.setPairingCode()` from saving (and subsequently using) the request Setup Pairing Code**
* 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**
* 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 `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()`
See [Releases](https://github.com/HomeSpan/HomeSpan/releases) for details on all changes and bug fixes included in this update.
# HomeSpan Resources
@@ -157,10 +113,12 @@ HomeSpan includes the following documentation:
* [HomeSpan Services and Characteristics](docs/ServiceList.md) - a list of all HAP Services and Characterstics supported by HomeSpan
* [HomeSpan Accessory Categories](docs/Categories.md) - a list of all HAP Accessory Categories defined by HomeSpan
* [HomeSpan Command-Line Interface (CLI)](docs/CLI.md) - configure a HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, monitor and update its status, and access detailed, real-time device diagnostics from the Arduino IDE Serial Monitor
* [HomeSpan WiFi and Ethernet Connectivity](docs/Networks.md) - a high-level discussion of HomeSpan's WiFi and Ethernet connectivity options
* [HomeSpan User Guide](docs/UserGuide.md) - turnkey instructions on how to configure an already-programmed HomeSpan device's WiFi Credentials, modify its HomeKit Setup Code, and pair the device to HomeKit. No computer needed!
* [HomeSpan API Reference](docs/Reference.md) - a complete guide to the HomeSpan Library API
* [HomeSpan QR Codes](docs/QRCodes.md) - create and use QR Codes for pairing HomeSpan devices
* [HomeSpan OTA](docs/OTA.md) - update your sketches Over-the-Air directly from the Arduino IDE without a serial connection
* [HomeSpan Watchdog Timer](docs/WDT.md) - optional protection that can trigger an automatic reboot if your sketch hangs or freezes for an extended period of time
* [HomeSpan PWM](docs/PWM.md) - integrated control of standard LEDs and Servo Motors using the ESP32's on-chip PWM peripheral
* [HomeSpan RFControl](docs/RMT.md) - easy generation of RF and IR Remote Control signals using the ESP32's on-chip RMT peripheral
* [HomeSpan Pixels](docs/Pixels.md) - integrated control of addressable one- and two-wire RGB and RGBW LEDs and LED strips
@@ -182,6 +140,11 @@ Note that all documentation is version-controlled and tied to each branch. The
In addition to HomeSpan resources, developers who are new to HomeKit programming may find useful Chapters 8 and 9 of Apple's HomeKit Accessory Protocol Specification, Non-Commercial Version, Release R2 (HAP-R2). This document is unfortunately no longer available from Apple (perhaps because it was last updated July, 2019, and is now somewhat out-of-date). However, you may be able find copies of this document elsewhere on the web. Note Apple has not replaced the HAP-R2 document with any other versions for non-commercial use, and Apple's open-source [HomeKit ADK](https://github.com/apple/HomeKitADK) only reflects the original HAP-R2 specs (rather than all the latest Services and Characteristics available in HomeKit for commercial devices).
---
### Matter and Thread
There are no plans to make HomeSpan compatible with Matter since HomeSpan was structured entirely around HAP R2. In addition, both Apple and Espressif have released Matter SDKs for public use, reducing the need for yet another Matter SDK.
Connecting HomeSpan directly to HomeKit via Thread is not planned (and might not even be possible). However, Thread may be useful for inter-device communication similar to how HomeSpan uses ESP-NOW to implement remote, battery-operated devices. This may be added at some point in a future release.
### Feedback or Questions?