diff --git a/docs/TVServices.md b/docs/TVServices.md index 34710a9..289910c 100644 --- a/docs/TVServices.md +++ b/docs/TVServices.md @@ -21,7 +21,7 @@ new Service::Television(); new Characteristic::Active(0); // set power to OFF at start-up 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: +More advanced control of a TV can enabled with these *optional* Characteristics: * `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: @@ -38,6 +38,23 @@ More advanced control of a TV can enabled with two other optional Characteristic * `Characteristic::ActiveIdentifier()` - this numerical Characteristic is used to control the input source for the TV (e.g. HDMI-1, HDMI-2, Netflix, etc.). It is only used when input sources are defined and linked using `Service::InputSource()` (see below), in which case it is a *required* Characteristic +* `Characteristic::DisplayOrder()` - this TLV8 Characteristic is used to control the order in which linked Input Sources are displayed in the Home App + * absent specifying the order with this Characteristic, the Home App will display the Input Sources in a random order within the selection section (under the power button), and in numerical order on the settings page of the Accessory based on the numeric Identifier for each Input Source + * the format of the TLV8 object use by this Characteristic is a series of TLV records of TAG=1 and VALUE set to the Identifer of an Input Source, interleaved with an empty TLV record of TAG=0 used as a separator + * example, the following code snippet sets the display order for three input sources with Identifiers 10, 20, and 30 to be 20, 30, and then 10: + +```C++ +TLV8 orderTLV; // create an empty TLV8 object named "orderTLV" + +orderTLV.add(1,20); // TAG=1, VALUE=20 (the Identifier of the first Input Source to be displayed) +orderTLV.add(0); // TAG=0 (empty record used as a separator) +orderTLV.add(1,30); // TAG=1, VALUE=30 (the Identifier of the second Input Source to be displayed) +orderTLV.add(0); // TAG=0 (empty record used as a separator) +orderTLV.add(1,10); // TAG=1, VALUE=10 (the Identifier of the third Input Source to be displayed) + +new Characteristic::DisplayOrder(orderTLV); // instantiate the DisplayOrder Characteristic and set its value to the orderTLV object +``` + ### `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.