Key Macros

NOTE: Key Macros are available as of EOSSTB plugin version v2.1.0.

Description

A Key macro is a sequence of remote control key presses that can be used to control any function of the set-top box in a similar way to controlling it with the set-top box physical remote control.

Key macros are loaded as a channel in the channel list, and occupy the positions at the end of the channel list. If more key macros exist than channels, no channels will be loaded. Ensure you have maxChannels set high enough to cover the quantity of desired channels and key macros.

Every known key code can be used in a key macros. Refer to the KeyEvents wiki page for all known key codes.

The default time between each key code is 200ms, but can be set to any delay period with a wait(milliseconds) command, example: wait(1000) waits for 1000ms (1 second). Always bear in mind that key codes sent by the plugin go via the backend MQTT server, and thus always take longer to execute than key presses on the physical remote control.

Key macros are particularly useful for selecting channels on the set-top box where no direct selection via a channel number is possible, such as radio channels.

Note that Key Macros are sent blindly, meaning that the plugin gets no feedback from the set-top box that a previous key press was processed, and receives no status from the set-top box regarding the display of any menus. Therefore, at the beginning of every Key Macro, it is useful to send a few Escape (Back) key presses to exit from any currently displayed menu, as well as waiting between each key command.

Note also that the set-top box only provides status of the current TV channel, but not the current radio channel. Any change of a radio channel by the set-top box physical remote control cannot be detected by the plugin.

Waiting between Key Commands

When using the physical remote control and watching the menu of the set-top box, a person automatically waits until the selection function is displayed or the cursor advances before pressing the next remote control key.

In a key macro, the wait between keys can be specifically instructed, and the wait() command is provided for this purpose. If no wait is provided, a default of 200ms is used between keys. Remember that key macros go via the backend MQTT server and you will need to experiment with wait times until you find a reliable time.

wait() Command

Waits for the specified time in milliseconds. Defaults to 200ms if no time is provided. The wait time can be specified as any value from 0 to 20000 (0ms to 20000ms, being 0s to 20s), allowing you to set the best wait for the position within the key macro sequence.

Syntax:

wait() waits for the default wait time of 200 milliseconds

wait(n) waits for n milliseconds, e.g. wait(50), wait(500), wait(1000), etc.

Key Codes

Every known key code (also known as key events) can be used. Refer to the KeyEvents wiki page for all known key codes.

Testing of Key Macros

Experience has shown you should test your key macros under the following situations, as the set-top box experiences different delays per mode.

1. TV Mode: test under normal conditions where the set-top box is up and running and playing a TV channel.
2. App Mode: test under conditions where the set-top box is up and running and playing an app. Time to exit an app can be longer than switching from a TV channel.
3. Standby Mode: test under conditions where the box is in standby, and must switch on and boot up before it can run the key macro. It is easiest to test this with a Scene, where the set-top box is saved in the scene with power on and the desired key macro channel selected.
4. 2nd Run: test if you can run your key macro multiple times in a row, but always be aware that the previous run must complete before the new run should be started. Observe the Homebridge logs.

Default Start Up Mode and Channel

The set-top box always starts up in TV mode, with the last used TV channel selected, every when the last used mode was radio. To start the set-top box on a radio channel, the user must turn on the box, wait for it to become ready, and then navigate the menu to select the radio station. For a key macro to turn on the box and navigate to a radio station, the key macro will automatically wait until the box is ready before sending the key macro commands.

Resetting the Set-Top Box to a known State

When executing a key macro blindly, you need to know what state the set-top box is in. The best way to do this is to always reset it to a known state. There are two ways of doing this:

1. Send the Escape key multiple times, the quantity will depend on how deep into a menu the set-top box current is.
2. Send the TV button, which resets the set-top box into TV state. As this is a single key, this is the preferred method.

Boot Up from a Key Macro

Wait for Ready

If the set-top box is turned on as the result of a key macro, the plugin will wait for the set-top box to boot up and be ready before sending the key commands. The set-top box ready state occurs when the current media state changes from STOP to PLAY, a few seconds after boot up.

Skipping Unnecessary Keys

After a boot up, the set-top box will always play the last used TV channel. Any Escape or TV or wait commands at the start of the key macro (which are used to escape out of any currently displayed menu or reset t TV mode) are thus not needed, and the plugin automatically skips these keys. This improves the performance of the key macro by avoiding sending of unnecessary keys.

Key Macro Examples

The examples shown below was prepared using set-top box firmware 4.45 on Sunrise TV in Switzerland. The exact keys required may be different for your firmware version in your country, please check on your set-top box.

Notes and tips for the following examples below:

• The TV key will reset the box to a known state: the last selected Tv channel. This ensures the macro starts from a known state
• The multiple Escape keys exit any current on-screen menu, to ensure the macro starts from a known state
• The wait() commands (e.g. wait(2000)) allow the screen to redraw before issuing the next command
• Experiment first with long wait commands of 3000 ms, and then reduce them until you find the shortest wait time for reliable operation
• if you wish to save a radio station as a scene, test selecting the scene when the box is turned off, as well as turned on

Example 1: Selecting the Last Played Radio Station via the Guide (Set-Top Box Firmware 4.45 or later)

The last played radio station is always the default selected radio station in the radio channel list. If you only listen to one radio station all the time, then using Last Played Radio will be enough to select it reliably.

Guide Home Right Right OK OK.

As a key macro:

TV Guide wait(2500) MediaTopMenu ArrowRight ArrowRight Enter wait(2500) Enter

Example 2: Selecting the Last Played Radio Station via the Menu (Radio must be available as an App)

You can access the radio channel list using the App menu:

Home Right Right OK Down OK OK.

As a key macro:

TV MediaTopMenu wait(2000) ArrowRight ArrowRight Enter wait(1000) ArrowDown wait(1500) Enter wait(2000) Enter

Example 3: Selecting a specific Radio Station

If you wish to select different radio stations reliably, then you need to select them from their position in the radio channel list. When navigating the radio channel list, you need to allow enough time for the channel list to be redrawn on the screen, especially when scrolling past the currently displayed on-screen channels.

Selecting the radio station in the first position on the 3rd row of the radio channel list, from the APPS menu:

Home Right Right OK Down OK Down Down Down OK

As a key macro:

TV MediaTopMenu wait(2000) ArrowRight ArrowRight Enter wait(3000) ArrowDown Enter wait(3000) ArrowDown wait(800) ArrowDown wait(1000) ArrowDown wait(1000) Enter