From 6967ac5d88c510f3911dc26b72407e641f40f77f Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 6 May 2023 14:24:18 -0500 Subject: [PATCH 1/9] Update README.md --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 345c0c1..1c5d140 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,8 @@ HomeSpan includes the following documentation: * [HomeSpan Projects](https://github.com/topics/homespan) - real-world applications of the HomeSpan Library * [HomeSpan FAQ](docs/FAQ.md) - answers to frequently-asked questions * [Solutions to Common Problems](docs/Solutions.md) - resolutions to some common problems when using/compiling HomeSpan -* [HomeSpan Reference Sketches](https://github.com/HomeSpan/HomeSpanReferenceSketches) - a collection of self-contained Reference Sketches showcasing some of the more complex HomeKit Services, such as Thermostats and Irrigation Systems +* [HomeSpan Reference Sketches](https://github.com/HomeSpan/HomeSpanReferenceSketches) - a collection of self-contained Reference Sketches showcasing some of the more complex HomeKit Services, such as Thermostats and Irrigation Systems + Note that all documentation is version-controlled and tied to each branch. The *master* branch generally points to the latest release. The *dev* branch, when available, will contain code under active development. # External Resources From 7ceee3fda066005aeb3dd90678dd25524d6d8244 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Mon, 29 May 2023 16:07:22 -0500 Subject: [PATCH 2/9] Update FAQ.md --- docs/FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 1bfb217..2678f8f 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -72,7 +72,7 @@ #### Why does the Home App indicate the Doorbell Service is unsupported? -* Though not documented in HAP-R2, it appears that the Doorbell Service is designed to be used in conjunction with another service, such as the Lock Mechanism. If you add in a second service, the Home App will show the appropriate Tile (such as a Lock) with the Doorbell being the second service. Howeveer, you can still use the Doorbell Service on a stanadlone basis --- even though the Home App says it is unsupported, a button press on the device will properly trigger a chime on your Home Pods as expected. +* Though not documented in HAP-R2, it appears that the Doorbell Service is designed to be used in conjunction with another service, such as the Lock Mechanism. If you add in a second service, the Home App will show the appropriate Tile (such as a Lock) with the Doorbell being the second service. However, you can still use the Doorbell Service on a stanadlone basis --- even though the Home App says it is unsupported, a button press on the device will properly trigger a chime on your Home Pods as expected. --- [↩️](../README.md) Back to the Welcome page From 03400653da8c396b2984a3b635e439d6d88498e7 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Tue, 11 Jul 2023 05:35:00 -0500 Subject: [PATCH 3/9] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c92f99d..a87d6fa 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ 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.0.0 or later of the [Arduino-ESP32 Board Manager](https://github.com/espressif/arduino-esp32), and has been tested up through version 2.0.7 (recommended). HomeSpan can be run on the original ESP32 as well as Espressif's ESP32-S2, ESP32-C3, and ESP32-S3 chips. +HomeSpan requires version 2.0.0 or later of the [Arduino-ESP32 Board Manager](https://github.com/espressif/arduino-esp32), and has been tested up through version 2.0.9 (recommended). HomeSpan can be run on the original ESP32 as well as Espressif's ESP32-S2, ESP32-C3, and ESP32-S3 chips. ### HomeSpan Highlights From bde6b6b5a8343bd70ef92a5a23043607d09f9564 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Tue, 11 Jul 2023 06:09:41 -0500 Subject: [PATCH 4/9] Update GettingStarted.md --- docs/GettingStarted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index bf53f36..c8e1788 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -20,7 +20,7 @@ HomeSpan is packaged as a standard Arduino library and can be installed either a #### Step 4: Acquire an ESP32 Board -ESP32 development boards are widely available in different configurations from most electronics hobby sites, such as [Adafruit](https://www.adafruit.com) and [Sparkfun](https://www.sparkfun.com). HomeSpan was developed using a dual-core ESP32-WROOM-32 (the [Huzzah32 from Adafruit](https://www.adafruit.com/product/3619)) but should work equally well on dual-core ESP32-WROVER chips. HomeSpan has *not* been tested on any single-core ESP32 chips, such as the ESP32-S2. +ESP32 development boards are widely available in different configurations from most electronics hobby sites, such as [Adafruit](https://www.adafruit.com) and [Sparkfun](https://www.sparkfun.com). HomeSpan works with any ESP32 supported by the [Arduino-ESP32 Core](https://github.com/espressif/arduino-esp32#arduino-core-for-esp32-wifi-chip), including the original ESP32, the ESP32-S2 and ESP32‑S3, and the ESP32-C3. #### Step 5: Install any required USB Drivers From 15149eb8d7460cbaf1b33f2946b4769deb7c0f18 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Tue, 11 Jul 2023 06:18:55 -0500 Subject: [PATCH 5/9] Update GettingStarted.md --- docs/GettingStarted.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index c8e1788..fd8fdda 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -8,7 +8,7 @@ Since HomeSpan is a library designed for Arduino's Integrated Development Enviro #### Step 2: Install the Arduino-ESP32 Core -The Arduino IDE comes with built-in compilers and support for a variety of Arduino boards, such as the Arduino Uno and Arduino Nano. However, the IDE does not natively support programming for the ESP32. Fortunately, the IDE allows you to download and install *cores* for other micro-controllers, including the ESP32, so they can be programming from within the Arduino environment. See the [Espressif Arduino-ESP32 GitHub page](https://github.com/espressif/arduino-esp32#arduino-core-for-esp32-wifi-chip) for complete instructions on how to install the Arduino-ESP32 core into the Arduino IDE using the [Arduino IDE Board Manager](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md). +The Arduino IDE comes with built-in compilers and support for a variety of Arduino boards, such as the Arduino Uno and Arduino Nano. However, the IDE does not natively support programming for the ESP32. Fortunately, the IDE allows you to download and install *cores* for other micro-controllers, including the ESP32, so they can be programming from within the Arduino environment. See the [Espressif Arduino-ESP32 GitHub page](https://github.com/espressif/arduino-esp32) for details on he Arduino-ESP32 Core, as well as for instructions on how to install easily this core (and keep it updated) from within the Arduino IDE using the [Arduino IDE Board Manager](https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide). #### Step 3: Install HomeSpan @@ -20,7 +20,7 @@ HomeSpan is packaged as a standard Arduino library and can be installed either a #### Step 4: Acquire an ESP32 Board -ESP32 development boards are widely available in different configurations from most electronics hobby sites, such as [Adafruit](https://www.adafruit.com) and [Sparkfun](https://www.sparkfun.com). HomeSpan works with any ESP32 supported by the [Arduino-ESP32 Core](https://github.com/espressif/arduino-esp32#arduino-core-for-esp32-wifi-chip), including the original ESP32, the ESP32-S2 and ESP32‑S3, and the ESP32-C3. +ESP32 development boards are widely available in different configurations from most electronics hobby sites, such as [Adafruit](https://www.adafruit.com) and [Sparkfun](https://www.sparkfun.com). HomeSpan works with any ESP32 supported by the [Arduino-ESP32 Core](https://docs.espressif.com/projects/arduino-esp32/en/latest/getting_started.html#supported-soc-s), including the original ESP32, the ESP32-S2 and ESP32‑S3, and the ESP32-C3. #### Step 5: Install any required USB Drivers From b0dbf0222774c7cada169d80c4fe917988426591 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Tue, 11 Jul 2023 06:20:13 -0500 Subject: [PATCH 6/9] Update GettingStarted.md --- docs/GettingStarted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index fd8fdda..1bd8b60 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -8,7 +8,7 @@ Since HomeSpan is a library designed for Arduino's Integrated Development Enviro #### Step 2: Install the Arduino-ESP32 Core -The Arduino IDE comes with built-in compilers and support for a variety of Arduino boards, such as the Arduino Uno and Arduino Nano. However, the IDE does not natively support programming for the ESP32. Fortunately, the IDE allows you to download and install *cores* for other micro-controllers, including the ESP32, so they can be programming from within the Arduino environment. See the [Espressif Arduino-ESP32 GitHub page](https://github.com/espressif/arduino-esp32) for details on he Arduino-ESP32 Core, as well as for instructions on how to install easily this core (and keep it updated) from within the Arduino IDE using the [Arduino IDE Board Manager](https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide). +The Arduino IDE comes with built-in compilers and support for a variety of Arduino boards, such as the Arduino Uno and Arduino Nano. However, the IDE does not natively support programming for the ESP32. Fortunately, the IDE allows you to download and install *cores* for other micro-controllers, including the ESP32, so they can be programming from within the Arduino environment. See the [Espressif Arduino-ESP32 GitHub page](https://github.com/espressif/arduino-esp32) for details on the Arduino-ESP32 Core, as well as for instructions on how to install easily this core (and keep it updated) from within the Arduino IDE using the [Arduino IDE Board Manager](https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide). #### Step 3: Install HomeSpan From 6ff9de03c9ba39c02197db8b363631b989dac00d Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Thu, 20 Jul 2023 22:48:06 -0500 Subject: [PATCH 7/9] Update FAQ.md --- docs/FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 2678f8f..f664427 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -32,7 +32,7 @@ #### Will HomeSpan work on an ESP8266 device? -* No, HomeSpan is coded specifically for the ESP32 and will not operate on an ESP8266 device. +* No, HomeSpan is coded specifically for the ESP32 and will not operate on an ESP8266 device, though an ESP8266 can be used as a remote [SpanPoint ESP-NOW](../docs/NOW.md) Device. #### How can I read HomeSpan's MDNS broadcast mentioned in the [OTA](OTA.md) documentation? From 3cb2e16418e277e88a56850724201f31eee39ee6 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Thu, 20 Jul 2023 22:52:14 -0500 Subject: [PATCH 8/9] Update NOW.md --- docs/NOW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/NOW.md b/docs/NOW.md index eb63b48..bd8f82e 100644 --- a/docs/NOW.md +++ b/docs/NOW.md @@ -1,6 +1,6 @@ # SpanPoint: Point-to-Point Communication between ESP32 Devices -SpanPoint is HomeSpan's easy-to-use implementation of the Espressif ESP-NOW protocol. SpanPoint provides bi-directional, point-to-point communication of small, fixed-size messages directly between ESP32 devices based on their MAC Addresses without the need for a central WiFi network. +SpanPoint is HomeSpan's easy-to-use implementation of the Espressif ESP-NOW protocol. SpanPoint provides bi-directional, point-to-point communication of small, fixed-size messages directly between ESP32 devices based on their MAC Addresses without the need for a central WiFi network. SpanPoint can also be used on an ESP-8266 when configured as a remote device. To establish connectivity between any two devices simply instantiate a SpanPoint object on each device that references the MAC Address of the other device, as well as specifies the (potentially different) sizes of the messages that each device is expected to send to, and receive from, the other. From a10f00c7213c155efbe2df5035cba193941de632 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Thu, 20 Jul 2023 23:03:33 -0500 Subject: [PATCH 9/9] Update FAQ.md --- docs/FAQ.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index f664427..8164dcd 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -22,6 +22,10 @@ * Yes, multiple ESP32's, each running a separate copy of HomeSpan, can be used on the same HomeKit network, provided that each device has a unique *Device ID*, a unique *Host Name*, and a unique *Display Name*. Normally, the *Device ID* is randomly-generated by HomeSpan at start-up and will therefore automatically be unique across multiple devices. Also, unless you override the suffix of the default *Host Name*, it will also be unique across multiple devices since HomeSpan uses the *Device ID* as the suffix of the *Host Name*. The only thing you need to ensure is that you assign a different *Display Name* to each of your devices. See the [HomeSpan API Reference](https://github.com/HomeSpan/HomeSpan/blob/master/docs/Reference.md) for details on how to do this. +#### Does HomeSpan require the use of a HomeKit Hub, such as a HomePod or Apple TV? + +* Yes, if you want HomeSpan to be able to send notifications, such as status updates if a contact sensor is opened, or updates from a temperature sensor. If your device can only be operated from the Home App (i.e. it has no local control buttons) and does not generate any status messages, than a HomeKit Hub would not be necessary. Note you will also need a HomeKit Hub if you wish to control your device via the Internet when away from your local WiFi network. These requirements and conditions are not specific to HomeSpan, but apply to all commercial HomeKit devices as a result of Apple updating its HomeKit Architecture (as of iOS 16.4). + #### Does HomeSpan support video and audio streams? * No, HomeSpan does not support streaming services, such as Audio Stream Management, Data Stream Transport Management, or Camera RTP Management. See [HomeSpan Services and Characteristics](ServiceList.md) for a complete list of all Services supported by HomeSpan.