From a53d98070c64a96d12e5ffd93e4e2c559ccb26f3 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 30 Oct 2021 22:06:02 -0500 Subject: [PATCH 1/4] Update version numbers to 1.4.1 --- library.properties | 2 +- src/Settings.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/library.properties b/library.properties index 7380088..274ff4b 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=HomeSpan -version=1.4.0 +version=1.4.1 author=Gregg maintainer=Gregg sentence=A robust and extremely easy-to-use HomeKit implementation for the Espressif ESP32 running on the Arduino IDE. diff --git a/src/Settings.h b/src/Settings.h index 51ec0d8..037c60b 100644 --- a/src/Settings.h +++ b/src/Settings.h @@ -36,7 +36,7 @@ #define HS_MAJOR 1 #define HS_MINOR 4 -#define HS_PATCH 0 +#define HS_PATCH 1 #define STRINGIFY(x) _STR(x) #define _STR(x) #x From a55a6972166a1098e869c74c1897c61422a07d3e Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 30 Oct 2021 23:01:02 -0500 Subject: [PATCH 2/4] Update TVServices.md --- docs/TVServices.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/TVServices.md b/docs/TVServices.md index d2c0b90..7a61ef6 100644 --- a/docs/TVServices.md +++ b/docs/TVServices.md @@ -1,6 +1,32 @@ # Television Services and Characteristics -(under construction) +HomeSpan includes a number of undocumented Television Services and Characteristics that are not part of HAP-R2. Though the UUID and specifications for each Television Service and Characteristic have been identified by the broader HomeKit community, it is only by trial-and-error that proper usage can be determined. This page documents the results of experimenting with the different Television Services and Characteristics within HomeSpan using the Home App provided in iOS 15.1. This documentaiton should be considered reliable, but Apple can of course change the behavior of such Service and Characteristics within the Home App at any time and without notice. + +### `Category::Television` + +Use `Category::Television` as the category in `homeSpan.begin()` to specify a Television Accessory. This causes the Home App to display an TV icon in the Accessory Tile. However, this only seems to work for the first Accessory implemented. If you create a device with multiple Television Accessories, or place a Television Accessory behind a Bridge Accessory, the icon for the TV Tile converts to a generic HomeKit symbol. + +### `Service::Television()` + +Use `Service::Television()` as the Service to create a Television Accessory Tile. It support two primary Characteristics: + +* `Characteristic::Active()` - this is the standard HomeKit Active Characteristic used to turn the TV on or off. It is a required Characteristic +* `Characteristic::ConfiguredName()` - this is an optional, TV-specific version of `Characteristic::Name()` that seems to be the only way to set the default name of the TV. Unlike all other HomeKit Services, the Home App ignores any names specified with `Characeteristic::Name()` when used with `Service::Television()` + +Based on the above, the following code snippet defines a simple TV Accessory with a basic on/off switch: + +```C++ +new Service::Television(); + new Characteristic::Active(0); // set power to OFF at start-up + new Characteristic::ConfiguredName("My TV"); // optional Characteristic to set name of TV +``` + + + + + + + --- From fce9b85e2476e8ee8ab66b0502dd95ff2b9b3408 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 30 Oct 2021 23:23:24 -0500 Subject: [PATCH 3/4] Update TVServices.md --- docs/TVServices.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/TVServices.md b/docs/TVServices.md index 7a61ef6..614fd1b 100644 --- a/docs/TVServices.md +++ b/docs/TVServices.md @@ -11,6 +11,7 @@ Use `Category::Television` as the category in `homeSpan.begin()` to specify a Te Use `Service::Television()` as the Service to create a Television Accessory Tile. It support two primary Characteristics: * `Characteristic::Active()` - this is the standard HomeKit Active Characteristic used to turn the TV on or off. It is a required Characteristic + * `Characteristic::ConfiguredName()` - this is an optional, TV-specific version of `Characteristic::Name()` that seems to be the only way to set the default name of the TV. Unlike all other HomeKit Services, the Home App ignores any names specified with `Characeteristic::Name()` when used with `Service::Television()` Based on the above, the following code snippet defines a simple TV Accessory with a basic on/off switch: @@ -18,8 +19,15 @@ Based on the above, the following code snippet defines a simple TV Accessory wit ```C++ new Service::Television(); new Characteristic::Active(0); // set power to OFF at start-up - new Characteristic::ConfiguredName("My TV"); // optional Characteristic to set name of TV + new Characteristic::ConfiguredName("Sony TV"); // optional Characteristic to set name of TV ``` +More advanced control of a TV can enabled with two other optional Characteristics: + +* `Characteristic::RemoteKey()` - this write-only numerical Characteristic enables HomeSpan to read button presses from the Remote Control widget on an iPhone. This widget is normally used to control Apple TVs, but it seems any Television Accessory created per above can be selected from the widget. The layout of the widget (which cannot be modified) includes 4 arrows, a central select button, a play/pause button, a large "back" button, and an "info" button. When a key is pressed, the Home App will send an update to `Characteristic::Remote()` that can be read by HomeSpan using the usual `update()` method. Values are as follows: up=4, down=5, left=6, right=7, select=8, back=9, play/pause=11, and info=15 + +* `Characteristic::PowerModeSelection()` - this write-only Characteristic activates an option in the Home App under the Settings page for a TV Accessory named + + From 4644d254c92ba82f527cbeed6408abdb5b25e2a4 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sun, 31 Oct 2021 09:57:23 -0500 Subject: [PATCH 4/4] Update TVServices.md --- docs/TVServices.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/TVServices.md b/docs/TVServices.md index 614fd1b..f333a55 100644 --- a/docs/TVServices.md +++ b/docs/TVServices.md @@ -10,7 +10,7 @@ Use `Category::Television` as the category in `homeSpan.begin()` to specify a Te Use `Service::Television()` as the Service to create a Television Accessory Tile. It support two primary Characteristics: -* `Characteristic::Active()` - this is the standard HomeKit Active Characteristic used to turn the TV on or off. It is a required Characteristic +* `Characteristic::Active()` - this HAP-R2 standard Characteristic it used to turn the TV on or off. It is a required Characteristic * `Characteristic::ConfiguredName()` - this is an optional, TV-specific version of `Characteristic::Name()` that seems to be the only way to set the default name of the TV. Unlike all other HomeKit Services, the Home App ignores any names specified with `Characeteristic::Name()` when used with `Service::Television()` @@ -23,9 +23,18 @@ new Service::Television(); ``` More advanced control of a TV can enabled with two other optional Characteristics: -* `Characteristic::RemoteKey()` - this write-only numerical Characteristic enables HomeSpan to read button presses from the Remote Control widget on an iPhone. This widget is normally used to control Apple TVs, but it seems any Television Accessory created per above can be selected from the widget. The layout of the widget (which cannot be modified) includes 4 arrows, a central select button, a play/pause button, a large "back" button, and an "info" button. When a key is pressed, the Home App will send an update to `Characteristic::Remote()` that can be read by HomeSpan using the usual `update()` method. Values are as follows: up=4, down=5, left=6, right=7, select=8, back=9, play/pause=11, and info=15 - -* `Characteristic::PowerModeSelection()` - this write-only Characteristic activates an option in the Home App under the Settings page for a TV Accessory named +* `Characteristic::RemoteKey()` - this write-only numerical Characteristic enables HomeSpan to read button presses from the Remote Control widget on an iPhone that can be found under the Control Center. This widget is normally used to control Apple TVs, but it seems any Television Accessory created per above can also be operated from the Remote Control widget. The layout of the widget (which cannot be modified) includes 4 arrows, a central select button, a play/pause button, a large "back" button, and an "info" button. When a "key" is pressed, the Home App sends an update to `Characteristic::RemoteKey()` that can be read by HomeSpan using the usual `update()` method. Values are as follows: + + * 4 = up arrow + * 5 = down arrow + * 6 = left arrow + * 7 = right arrow + * 8 = center select button + * 9 = back button + * 11 = play/pause button + * 15 = info button + +* `Characteristic::PowerModeSelection()` - this write-only Characteristic causes the text "View TV Settings" to appear in the Home App under the Settings page for a TV Accessory. When this text is pressed, the Home App sends an update with value=0 to `Characteristic::PowerModeSelection()` that can be read by HomeSpan using the usual `update()` method