Add your set-top box to Homekit (for Telenet BE, Sunrise CH, UPC SK, Virgin Media GB & IE, Ziggo NL)
npm install homebridge-eosstb

homebridge-eosstb is a Homebridge plugin allowing you to control your set-top box (typically an ARRIS DCX960 / VIP5002W or HUMAX EOS1008R / 2008C) running on the Telenet BE / Sunrise CH / UPC SK / Virgin Media GB & IE / Ziggo NL Horizon TV platform with Apple HomeKit using the Home app and the Apple TV Remote in the Control Center.
|
|
sh
sudo npm install -g homebridge-eosstb
`
After installing, make sure you restart Homebridge.
Adding the Set-Top Box to the Home App
The set-top box accessory is exposed as a separate external accessory and each set-top box needs to be manually paired as follows:
1. Open the Home app on your device.
2. Tap the Home tab, then tap + in the top right corner of the screen and then Add Accessory to start the process of adding a new accessory.
3. Add Accessory: tap More options... to add the accessory manually.
4. Select an Accessory to Add to \ : Select the accessory you want to add. You should see your set-top box here. If not, check your Homebridge config.
5. Accept the Uncertified Accessory warning by tapping Add Anyway.
6. Enter HomeKit Setup Code: Enter the HomeKit Setup Code (displayed in Homebridge under the QR code, format XXXX-XXXX), or use the device's camera to scan the QR code in Homebridge and tap Continue.
7. Set-Top Box Location: Select a room for your new accessory and tap Continue.
8. Set-Top Box Name: Give your set-top box a different name if you wish (synchronised to your real set-top box, you can change this in the Home app later) and tap Continue.
9. Name TV Input Sources: Re-name your TV input sources if you wish (you can change these in the Home app later) and tap Continue.
10. Set-Top Box Automations: Switch on any suggested automations if you wish (you can change these in the Home app later) and tap Continue.
11. Set-Top Box Added to \ : Tap Done to finish the setup.
Your new accessory will appear shortly in the room that you selected. It may show Updating... for a few minutes as it loads all the data.
You can force a Home app refresh by switching to another room and then back again.
Remote Control Supported Keys
To access the Apple TV Remote, open your Control Center by swiping down from the top (newer iPhones and iPads) or up from the bottom of the screen (older iPhones). If you do not see the remote-control icon, you will need to activate it in Settings > Control Centre and ensure that the Apple TV Remote is in the list of INCLUDED CONTROLS.
Make sure you select the correct device from the drop-down list at the top of the Apple TV Remote:
The following keys are supported by in the Apple TV Remote in the Control Center:
| Key | Single Tap | Double Tap |
| ----------- | -------------- | ---------------- |
| Mute | Mute | n/a |
| Power | Power | n/a |
| Up | ArrowUp | ChannelUp |
| Down | ArrowDown | ChannelDown |
| Left | ArrowLeft | MediaRewind |
| Right | ArrowRight | MediaFastForward |
| Select | Enter | Enter |
| PlayPause | MediaPlayPause | MediaPlayPause |
| Back | Escape | Escape |
| Info | MediaTopMenu | Guide |
| Volume Up | volUpCommand | - |
| Volume Down | volDownCommand | 3 clicks = mute |
NOTE: Prior to iOS 18.0, the Mute and Power buttons appeared in the Remote Control, however they were disabled. As of iOS 18.0, the buttons are enabled. Double tap is not applicable to the Mute and Power buttons.
The table shows the default key mappings. You can map any Apple TV Remote button to any set-top box remote control button, see the Wiki for all of the known KeyEvents.
The volume controls do not control the set-top box directly, as the set-top box has no volume capability. The set-top box physical remote actually sends IR commands to your TV. If you can control your TV volume via a network connection then the volume controls can be used to send volume commands to your TV via the raspberry pi. This is what the author uses.
Using Profiles to Better Manage your Channel List
Many TV providers provide hundreds of TV channels. The Home app is limited to 100 "services", which are TV channels or reserved for system control. This limits the maximum possible channels to 95, and thus the plugin will load the first 95 subscribed channels found, ignoring all non-subscribed channels.
If the channels you wish to have in the Home app are not within the first 95 subscribed channels in your TV providers channel list, then you can create a profile on the set-top box, and configure the profile with the channels you want, in the order you want. Enter the same profile name in the plugin config Profile Name, and the plugin will load the channels from that profile.
Any changes in the profile on the set-top box will automatically be reflected in the plugin. As the Home app does not expect channels to change in the channel list, you may need to force-close the Home app and reopen it to force a refresh of the displayed channels after a change is made on your set-top box.
The profile used by the plugin does not have to be the same as the set-top box's start-up profile. It is OK to configure a profile that is dedicated to the plugin, if you so wish.
Sorting the Channel list
The config item Channel Sort By allows the channels to be sorted by Channel Order (the standard channel order as shown on the TV) or by Most Watched. Most Watched is reported by the backend systems and is profile-based. It is not clear how often this list is updated, however for a TV subscription with many channels, this may be a preferable option to show your most watched channels at the top of the channel list.
Using Key Macros to Access Extra Capabilities
You can program key macros to access any function of your set-top box. This is particularly useful to select radio channels. Key macros are loaded at the end of the channel list. See the Wiki Key Macros page for full details.
Limitations
$3
Due to HomeKit design limitations, the maximum services for a single accessory are 100. Over this value the Home app will no longer respond.
Services used in this set-top box accessory are:
1. Information service (Name, model, serial number of the accessory)
2. Television service (for controlling the TV accessory)
3. Speaker service (for the controlling the TV accessory volume)
4. Input service. The input (TV channels) utilises one service per input. The maximum possible channels (inputs) are thus 100 - 3 = 97. I have limited the inputs to maximum 95, but you can override this in the config (helpful to reduce log entries when debugging). The inputs are hard limited to 95 inputs.
$3
The eosstb plugin can detect the target and current media state and shows STOP, PLAY, PAUSE or LOADING (loading is displayed only for current media state when fast-forwarding or rewinding) in the Homebridge logs. Unfortunately, the Apple Home app cannot do anything with the media state (as at iOS 18.6) apart from allow you to read it in Shortcuts or Automations. Hopefully this will improve in the future.
$3
The eosstb plugin can detect the current recording state of the set-top box, both for local HDD-based recording (for boxes that have a HDD fitted) and for network recording. The plugin shows IDLE, ONGOING_NDVR or ONGOING_LOCALDVR in the Homebridge logs. DVR means digital video recorder; N for network and LOCAL for local HDD based recording. The Apple Home app cannot natively do anything with the recording state but the eosstb plugin uses it to set the inUse charateristic if the set-top box is turned on or is recording to the local HDD. This is useful in Shortcuts or Automations.
$3
The eosstb plugin can detect the closed captions state (Subtitle options in the set-top box menu) and shows ENABLED or DISABLED in the Homebridge logs. Unfortunately, the Apple Home app cannot do anything with the closed captions state (as at iOS 18.6) apart from allow you to read it in Shortcuts or Automations. Hopefully this will improve in the future.
Configuration
Add a new platform to the platforms section of your homebridge config.json.
Example minimum (mandatory) configuration:
`js
"platforms": [
{
"country": "ch",
"username": "yourTvProviderUsername",
"password": "yourTvProviderPassword",
"platform": "eosstb"
}
]
`
Example extended configuration as used on the author with his EOSSTB set-top box. An extended configuration allows you to customise the behaviour of each set-top box device. You must identify the devices by their deviceId:
`js
"platforms": [
{
"platform": "eosstb",
"name": "EOS",
"country": "ch",
"username": "yourTvProviderUsername",
"password": "yourTvProviderPassword",
"doublePressTime": 250,
"triplePressTime": 800,
"masterChannelRefreshCheckInterval": 60,
"debugLevel": 0,
"devices": [
{
"deviceId": "3C36E4-EOSSTB-00365657xxxx",
"name": "Sunrise TV",
"syncName": true,
"profile": "Dad",
"channelOrder": "mostWatched",
"accessoryCategory": "settopbox",
"playPauseButton": "MediaPlayPause",
"backButton": "Escape",
"infoButton": "MediaTopMenu",
"volUpCommand": "samsungctl --host x.x.x.x --name HomeKit --timeout 0.2 KEY_VOLUP",
"volDownCommand": "samsungctl --host x.x.x.x --name HomeKit --timeout 0.2 KEY_VOLDOWN",
"muteCommand": "samsungctl --host x.x.x.x --name HomeKit --timeout 0.2 KEY_MUTE",
"manufacturer": "ARRIS",
"modelName": "DCX960",
"serialNumber": "123456",
"firmwareRevision": "4.40",
"showChannelNumbers": false,
"maxChannels": 50
},
],
"channels": [
{
"channelKeyMacro": "TV MediaTopMenu wait(2000) ArrowRight ArrowRight Enter wait(1000) ArrowDown wait(1500) Enter wait(2000) Enter",
"channelName": "Last Played Radio"
},
{
"channelId": "SV09690",
"channelName": "Netflix"
}
]
}
]
`
$3
Unless otherwise stated, all config items are case sensitive.
#### Mandatory
Mandatory config items must always exist. These are used to establish the session to the EOS / Horizon platform. If any mandatory config items are missing, a warning is shown and initialization is aborted.
- platform: the name of the platform. Mandatory, must be eosstb.
* country: Your country. Must be one of ch, nl, be-nl, be-fr, at or gb. Not case sensitive. This controls the country-specific logon sequence and the mqtt sessions. Mandatory.
- username: Your login username for your TV account, same as used in the TV app on your iOS device. Often an email address, but some providers use a mobile phone number. Mandatory.
- password: Your password associated with your TV account. Mandatory.
#### Optional
- name: The platform name that appears in the Homebridge logs. In many countries the platform is called Horizon, but you can name it to anything. Optional, defaults to "EOSSTB".
- doublePressTime: The amount of time in ms to detect double-tap of a button. Used for double-tap or triple-press features, such as double-tap of Info generates Guide. Optional, defaults to 250ms.
- triplePressTime: The amount of time in ms to detect triple-tap of a button. Used for triple-tap or triple-press features, such as triple-press of Volume Down generates Mute. Optional, defaults to 800ms.
- masterChannelListValidFor: Amount of time in seconds that the master channel list stays valid for. Default 60s.
- debugLevel: Controls the amount of debug data shown in the Homebridge logs, independent of the debug setting in Homebridge. Extra debug messages above level 0 are shown in the Homebridge log in the warning colour, normally yellow. Supported values are: 0=No debug logging, 1=Minimum, 2=Enhanced, 3=Verbose. Optional. Defaults to 0 if not found. Warning: a lot of log entries can occur at the higher debug levels.
$3
Most people will be happy with the default device config. If you do not need to change anything, you can omit the device config section.
If you want to configure your devices differently, do so here. Multiple devices are supported, each device can be configured separately. The devices are identified by their physical deviceId. You will see that there is no option to set the name in the config, as the name of the set-top box displayed in the Home app is always synchronised to the physical set-top box. You can change the set-top box name in the Home app.
#### Mandatory
- deviceId: The unique set-top box physical device id, in Switzerland, Belgium and the Netherlands this is in the format 3C36E4-EOSSTB-001234567890. Other countries are similar. Required to identify the set-top box in your network, as multiple boxes can exist. Review the Homebridge log to see your deviceId, it is displayed shortly after a Homebridge restart. Mandatory for a device configuration.
#### Optional
##### Name and Icon
- name: The device name. Set to anything you want. If syncName is true, the name will also be synced to the set-top box. Note that the set-top box name must be between 3 and 14 characters long; shorter names are expanded, longer names are truncated. Optional, defaults to the current set-top box name.
- syncName: You can choose to sync the HomeKit name with the physical set-top box name. If you set syncName to false, you can name the set-top box in HomeKit differently to the physical set-top box. Optional, defaults to true.
- accessoryCategory: The accessory category. This changes the image on the tile in the Home app. Allows you to use a TV or an Audio Receiver or a Set-Top Box (default). Available values are: Set-Top-Box = any of "settopbox", "stb". TV = any of "television", "tv". Audio Receiver = any of "receiver", "audio-receiver", "avr". Not case sensitive. Optional, defaults to Set-Top Box if the value is not recognised.
##### Accessory information
- manufacturer: You can add a manufacturer name if you wish. Defaults to the detected device and platform type, otherwise to the eosstb platform name. Optional.
- serialNumber: You can add a serial number if you wish. Defaults to the set-top box serial number id, otherwise to the physical deviceId. Optional.
- modelName: You can add a model name if you wish. Defaults to the detected device model and product type or device type, otherwise to the eosstb plugin name. Optional.
- firmwareRevision: You can add a firmware revision if you wish. Must be numeric (non-numeric values are not displayed in the Home app). Defaults to the eosstb plugin version. Optional.
##### Channel Display
- profile: The profile name to use to load the channel list for the device. Optional, defaults to the default profile on startup, as configured on the set-top box. The plugin loads the first 95 subscribed channels found, which is a limitation of HomeKit. To manage your favourite channels within the constraint of 95 channels, create a profile on your set-top box, and use the profile name in the plugin config. If your profile is changed to the set-top box, the changes will be pushed to HomeKit. Channels should stay in a consistent channel order as the channel number is used in HomeKit scenes, not the channel name.
- channelOrder: The method to sort the channels in the channel list in the Home app. Available values are: Channel order = "channelOrder", Most Watched = "mostWatched". Case sensitive. Optional, defaults to channelOrder.
- maxChannels: The maximum number of channels to load. Optional, defaults to 95. Note: you may need to do force-close and reopen the Home app to force it to recognise a change in the quantity of channels available.
- showChannelNumbers: Shows or hides the channel numbers in the channel selector in HomeKit. Values: true or false (default). If channel numbers are displayed, there is less room for the channel name. Optional, defaults to false.
##### Remote Control Button Mapping
- playPauseButton: The command issued to the set-top box when the Play/Pause button (> ||) in the Apple TV Remote is tapped. Normally MediaPause. Optional, defaults to MediaPause if not found.
- backButton: The command issued to the set-top box when the BACK button in the Apple TV Remote is tapped. Normally Escape. Optional, defaults to Escape if not found.
- infoButton: The command issued to the set-top box when the Info button (i) in the Apple TV Remote is tapped. As the Apple TV Remote has no Menu button, the Info button should be used to access the menu. This is why the Info button is set to MediaTopMenu. Optional, defaults to MediaTopMenu if not found.
##### Remote Control Volume Commands
- volUpCommand: The bash command to increase the volume of the TV. This command is sent when the Apple TV Remote is open and you press the Volume Up button on your device. Optional.
- volDownCommand: The bash command to decrease the volume of the TV. This command is sent when the Apple TV Remote is open and you press the Volume Down button on your device. Optional.
- muteCommand: The bash command to mute the TV. Whilst not supported natively in the Apple TV Remote, this plugin integrates it with a triple-press on the Volume Down button. Mute is also supported in Homebridge. Optional.
$3
Some channels such as Netflix are actually apps on the set-top box, and not normal linear TV channels. They appear in the channel list on the TV, and can be added to favourites from the TV menu (but not from the web app menu). However, they are not broadcast as a normal linear TV channel in the master channel list. Therefore, the name cannot be determined from the profile favourite channel list, and the name appears as "Channel xxxxxx" where xxxxxx is the channelId. To overcome this, add the channelId and the channelName to the channels section in the config as per the examples below.
- channelId: The channelId, as defined by the TV provider. Unknown channelIds will appear in the Homebridge log.
- channelKeyMacro: The channel key macro (key sequence) to send. If channelKeyMacro is present, channelId is ignored.
- channelNames: Allows you to add unknown channel names, names for key macros, or to rename any channel as you wish. Required as some channels (e.g., Netflix) are not published on the master channel list. If a channel displays in the Home app like this: "Channel SV09690", then check your TV to see the channel name, and add it to the config. An example is provided for Netflix. Optional, unknown channels are displayed as "Channel xxxxxxx" where xxxxxxx is the channelId.
- Telenet BE:
`js
"channels": [
{
"channelId": "netflix",
"channelName": "Netflix"
}
]
`
- Virgin Media GB:
`js
"channels": [
{
"channelId": "1755",
"channelName": "Netflix"
},
{
"channelId": "2054",
"channelName": "Prime Video"
}
]
`
- Sunrise CH:
`js
"channels": [
{
"channelId": "SVO9690",
"channelName": "Netflix"
}
]
`
- Ziggo NL:
`js
"channels": [
{
"channelId": "NL_000073_019506",
"channelName": "Netflix"
},
{
"channelId": "NL_000210_019505",
"channelName": "Viaplay"
}
]
``