Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update TVServices.md

This commit is contained in:
HomeSpan 2021-10-31 15:21:37 -05:00 committed by GitHub
parent 46aab531c8
commit 336ec18545
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/TVServices.md
View File

@ -40,8 +40,21 @@ More advanced control of a TV can enabled with two other optional Characteristic
### `Service::InputSource()` ### `Service::InputSource()`
Use `Service::InputSource()` to create a new input source selection for the TV, such as HDMI-1, HDMI-2, Netflix, etc. The use of `Service::InputSource()` is optional - it is perfectly okay to create a Television Service without the ability to select different Input Sources. However, if used, each Input Source Service added should be defined in the *same* Accessory as the Television Service to which it applies, and ***must*** be linked to that Television Service using `addLink()`. The Home App behaves unexpectedly if it finds any Input Source Services that are not linked to a Television Service. `Service::InputSource()` support the following Characteristics: Use `Service::InputSource()` to create a new input source selection for the TV, such as HDMI-1, HDMI-2, Netflix, etc. The use of `Service::InputSource()` is optional - it is perfectly okay to create a Television Service without the ability to select different Input Sources. However, if used, each Input Source Service added should be defined in the *same* Accessory as the Television Service to which it applies, and ***must*** be linked to that Television Service using `addLink()`. The Home App behaves unexpectedly if it finds any Input Source Services that are not linked to a Television Service.
Input Sources can appear in two places within the Home App. The first is in the Input Source "Selector" that appears below the On/Off power button when you open the controls for a TV (i.e. long-press the Accessory Tile). This is how you change the Input Source for thge TV. The second place Input Sources appear is on the Settings page for a TV Accessory. This list is used to (a) change the name of each source, and (b) toggle the source so that it either appears or does not appear in the Input Source Selector.
The idea is that your sketch should implement a TV Accessory containing a full list of all potential inputs, using names that match the labels on the TV, such as "HDMI 1", "Component 1", "HDMI 2", etc. If your TV Remote has dedicated buttons for Netflix, HBO Max, Amazon Prime, etc. you can add these to the list as well. Once this generic list is created, you can then rename and enable these source directly from within the Home App. For example you might rename "HDMI 1" to "Comcast Cable", and "HDMI 2" to "Sony Blue-Ray". If you have nothing connected to the "Component 1" input source your can exclude it from the Input Source Selector. This makes it easy to configure and re-configure your TV Input Sources without ever having to change or update your HomeSpan sketch.
All of this is accomplished by using a combination of some, or all, of the following Characteristics that are supported by `Service::InputSource()`:
* `Characteristic::ConfiguredName()` - similar to how its used when applied to `Service::Television`, this Characteristic allows you set the default name for an Input Source. Note that if you change the name of an Input Source in the Home App, an update will be sent to HomeSpan with the new name for you to use if needed. This is very different from the usual `Characteristic::Name()` used for many other Services, and for which name changes performed in the Home App are never communicated back to the Accessory.
* `Characteristic::Identifier()` - this numerical Characteristic sets an ID for each Input Source. Any unsigned 32-bit number can be used as an ID, provided it is *unique* and not used by other Input Sources in the same TV Service. When the use the Input Source Selector in the Home App, the ActiveIdentifier Characteristic from the Television Service (see above) will be updated to match the ID corresponding to the Input Source. Within HomeSpan you can use the `update()` method to determine when `Characteristic::ActiveIdentifer()` is updated, and which Input Source is being requested. Note that setting an Identifier for an Input Source is technically optional. However, if it not set, the Home App will not allow it to be displayed in the Input Source Selector, which defeats the purpose of creating an Input Source
* `Characteristic::IsConfigured()` - this Characteristic determines where an Input Source appears in the Home App. Allowed values are 0 and 1. IsConfigured() is optional - if not defined, the Input Source will appear in the Input Source Selector (provided it has an Identifier), but *not* in the list of Input Sources found on the Setting page. This means you will not be able to rename the Input Source from the Home App, nor turn off its visibility in the Input Selector. If IsConfigured() is defined and set to 1, the Input Source appears in both the Input Source Selector List as well as the list of Input Sources on the Setting page. If instead IsConfigured is defined but set to 0, the Input Source will appear in the Settings page, but it will be excluded from the Input Source Selector under all circumstances
* `Characteristic::CurrentVisibilityState()` and `Characteristic::TargetVisibilityState()` - these two Characteristics work in tandem much like any current-state/target-state pair. When these are defined for an Input Source, a checkbox toggle appears next to the name of the Input Source on the Setting page (proivided IsConfigured() has also been defined). Clicking the checkbox causes the Home App to toggle the TargetVisibilityState between 0 to 1, where 0 means the checkbox is *checked*, and 1 means it is *unchecked* (the reverse of what you might expect). If you read this update in HomeSpan you can then use `setVal()` to change the CurrentVisibiltyState() to match the TargetVisibilityState(). Setting CurrentVisibilityState() to 0 means the Input Source appears in the Input Source Selector. Setting CurrentVisibilityState() to 1 means it does not appear as a selection. Note these features only operate if an ID has been set for the Input Source with `Characteristic::Identifier()`, and IsConfigures is set to 1.