Shortcuts
The set-top box state can be read and controlled in the iOS Shortcuts app and in the Home app. I have added as many characteristics as possible to
provide for maximum flexibility. Please note that the descriptions below are written for iOS 16.x, and should be the same for iOS 17.x. Older iOS version may have slightly different displayed text.
The shortcut actions supported for a TV accessory are:
- Get the state of HomeName
- Control HomeName
Shortcut actions are part of the iOS operating system and are thus under the control of Apple. Only Apple can add more actions.
To see the available actions, search for Home in the Shortcuts app or the Home app. Select the desired action from the displayed list to use it.
Displays initially as Get Accessory State. Tap on Accessory State to select the desired accessory, then select on the displayed characteristic to select the desired characteristic. Supported accessory characteristics for the set-top box are:
The set-top box current power state, On or Off. One of 0 (INACTIVE) or 1 (ACTIVE). Note that shortcuts displays Off for INACTIVE (instead of 0), and On for ACTIVE (instead of 1). See https://developers.homebridge.io/#/characteristic/Active
The set-top box current selected channel, 0 is the first in the list, 1 the next, and so on. Input 99 is used when the input is unknown. See https://developers.homebridge.io/#/characteristic/ActiveIdentifier
The set-top box current closed captions state, one of 0 (DISABLED) or 1 (ENABLED). See https://developers.homebridge.io/#/characteristic/ClosedCaptions
The set-top box name. See https://developers.homebridge.io/#/characteristic/ConfiguredName
The set-top box current selected channel id, normally a text such as SV01234. This is a custom characteristic, available from v2.1.0. The id is always populated even if the channel is not in the HomeKit accessory channel list. Useful to find the id of any current channel such as Netflix. In Shortcuts, it appears with the name Custom.
The set-top box current selected channel name. This is a custom characteristic, available from v2.1.0. The name is always populated even if the channel is not in the HomeKit accessory channel list. In Shortcuts, it appears with the name Custom.
IN DEVELOPMENT FOR V2.1.x The set-top box currently playing program name, either from linear TV or from a recording. This is a custom characteristic, available from v2.1.1. In Shortcuts, it appears with the name Custom.
IN DEVELOPMENT FOR V2.1.x
The set-top box currently playing program scheduled end time. Currently shows only the linear TV original scheduled end time, which means any playing recording with have end time in the past. Returns a string containing a UTC date value formatted as an ISO string, example: 2023-01-05T11:30:00.000Z which means 11:30 UTC on 05 January 2023, which translates to 12:30 CET local time when the CET time zone is UTC+1. Use the Format Date shortcut action to change the UTC datetime to local datetime or any format of your choosing. If no end time is known, the value defaults to 1970-01-01T00:00:00.000Z to ensure that a valid date is always returned. This is a custom characteristic, available from v2.1.1. In Shortcuts, it appears with the name Custom.
The set-top box current media state, one of 0 (PLAY), 1 (PAUSE), 2 (STOP), 4 (LOADING) or 5 (INTERRUPTED). STOP is set when the set-top box power is off; PAUSE is set when the set-top box has paused a program; PLAY is when the set-top box is playing a program; LOADING is set when current program is playing at negative speeds (rewind) or positive speeds (fast-forward). See. https://developers.homebridge.io/#/characteristic/CurrentMediaState
Due to Apple HomeKit restrictions, all custom characteristics appear with the name Custom in the Shortcuts app. The Shortcuts app allows you to read the custom characteristics. To identify a custom characteristic in the Shortcuts app, select each in turn and observe the value to determine which custom characteristic it is.
This plugin contains the following custom characteristics:
- Current Channel Id, which contains the current channel id. From v2.1.0
- Current Channel Name, which contains the current channel name, as shown on the TV. From v2.1.0
- Current Program Name, which contains the current program name, as shown on the TV. From v2.1.x
- Current Program End Time, which contains the current program scheduled end time. From v2.1.x
The set-top box current usage state, one of 0 (NOT_IN_USE) or 1 (IN_USE). A set-top box is in use when it is turned on, or when it is turned off and is still recording to the local hard drive (if fitted). Intended as an indicator to show when the set-top box can be disconnected from power without interrupting hard drive recording. Added in v1.3.0. See https://developers.homebridge.io/#/characteristic/InUse
The set-top box current input device type, to indicate if playing live TV a recording. One of 0 (1 (TV) for linear TV and the review buffer, 2 (TUNER) for radio stations, and 4 (PLAYBACK) for replay TV or local or network recordings. Other values are not used. Added in v1.3.0. See https://developers.homebridge.io/#/characteristic/InputDeviceType
The set-top box current source type, one of 0 (OTHER) for replay TV and radio, 3 (TUNER) for linear TV, and 10 (APPLICATION) for apps such as Netflix, YouTube. Other values are not used. See https://developers.homebridge.io/#/characteristic/InputSourceType
The set-top box name as at last restart of Homebridge. See https://developers.homebridge.io/#/characteristic/Name
The set-top box picture mode, always 1 (STANDARD). See https://developers.homebridge.io/#/characteristic/PictureMode
NOTE: A customPicturemode was previously used together with this characteristic. As of v1.3.0, customPictureMode is replaced by In Use, and as of v2.0.0 customPictureMode has been removed (deprecated).
Menu command sent by the accessory. For control only. If Shortcuts tries to get the state of this characteristic then the error Operation is not supported is displayed. See https://developers.homebridge.io/#/characteristic/PowerModeSelection
The set-top box scheduled recording mode, one of 0 (NO_PROGRAM_SCHEDULED), 1 (PROGRAM_SCHEDULED), or 2 (PROGRAM_SCHEDULED_MANUAL_MODE_). 0 when no recording is scheduled, otherwise 1 when some recording is scheduled (at any time in the future). Useful to indicate if a recording is planned. Added in v1.3.0. See https://developers.homebridge.io/#/characteristic/ProgramMode
Remaining Duration returns the amount of time left in seconds for the current TV program, as an integer. Apple has limited this value to maximum 3600 seconds (60 minutes). Any duration greater than 3600 seconds will be shown as 3600 seconds. Added in v2.1.1. See https://developers.homebridge.io/#/characteristic/RemainingDuration
Remote control keys sent by the Apple TV Remote. For control only. If Shortcuts tries to get the state of this characteristic then the error Operation is not supported is displayed. See https://developers.homebridge.io/#/characteristic/RemoteKey
The set-top box sleep discovery mode, indicates whether the box can be found when sleeping (powered off). One of 0 (NOT_DISCOVERABLE) or 1 (ALWAYS_DISCOVERABLE). Set by default to 1. See https://developers.homebridge.io/#/characteristic/SleepDiscoveryMode
The set-top box current working status. ACTIVE when the set-top box is working without errors, meaning it is connected to the network and is reachable by mqtt, or NOT_ACTIVE if the box is not reachable by mqtt and cannot be controlled. Useful to indicate if the box is physically powered on and can be controlled by the Home app. Note that the box can only be turned on by the Home app if the Standby power consumption is set to Fast start, meaning the box stays active always. Status Active is visible in the accessory Settings. One of 0 (NOT_ACTIVE) or 1 (ACTIVE). Note that shortcuts display this characteristic in IF actions as two values: Is Active and Is Not Active. Added in v1.3.0. See https://developers.homebridge.io/#/characteristic/StatusActive
The set-top box general fault status. NO_FAULT when box is connected to the mqtt service, or GENERAL_FAULT if the backend servers are not reachable or the mqtt service has become disconnected for any reason, meaning that the box cannot be controlled. One of 0 (NO_FAULT) or 1 (GENERAL_FAULT). Note that shortcuts displays No for NO_FAULT (instead of 0), and Yes for GENERAL_FAULT (instead of 1). Added in v1.3.0. See https://developers.homebridge.io/#/characteristic/StatusFault
The set-top box target media state, one of 0 (PLAY), 1 (PAUSE) or 2 (STOP). STOP is set when the set-top box power is off; PAUSE is set when the set-top box has paused a program; PLAY is when the set-top box is playing a program. If the set-top box is fast-forwarding or rewinding, then the target media state does not change. See https://developers.homebridge.io/#/characteristic/TargetMediaState
Displays initially as Set Scenes and Accessories. Tap on Scenes and Accessories to select the desired accessory.
You can only control the items accessible through the Home app accessory tile. Unfortunately, this is an Apple limitation. Hopefully Apple will improve Shortcut’s control in the future. Press and hold to adjust the accessory. Supported accessory control capabilities for the set-top box are:
The power button. Power state, On or Off. See https://developers.homebridge.io/#/characteristic/Active
The channel list (also known as the input list). In the channel list, the Active Identifier 0 is the first channel in the list, 1 the next, and so on. See https://developers.homebridge.io/#/characteristic/ActiveIdentifier
The set-top box can also be controlled by the Apple TV Remote. In the Shortcuts app, search for the Remote action category, then select Show Remote Control.
Running the action Show remote control for (Apple TV) will open the Apple TV Remote. Apple TV is shown to indicate you should select an Apple TV, but you do not have to. Leave the Apple TV input empty, or pass an empty Magic Variable to open the remote control with the last used device selected.
NOTE: Show Remote Control with no Apple TV selected works in iOS 14 and iOS 18. It does not work in iOS 15/16/17: when running Show remote control for (Apple TV) with no Apple TV selected, an error is displayed: Could Not Run Show Remote Control - An unknown error occurred