jsiegenthaler / homebridge-eosstb

A homebridge plugin for the EOS set-top box as used by Sunrise, Telenet, Ziggo, Virgin Media and maybe more in various countries on the Horizon Go (HGO) platform
https://github.com/jsiegenthaler/homebridge-eosstb
32 stars 4 forks source link
entertain-box eos-box homebridge-eosstb horizon mediabox-next sunrise telenet telenet-tv telenet-tv-boxes tv-accessory tv-box upc upc-box upc-tv virgin virgin-media virgin-media-360 ziggo ziggo-next

Sunrise TV Box (ARRIS DCX960)
RoomWithEosstb EosstbControls RemoteControl

homebridge-eosstb

IMPORTANT NOTICE


22 June 2024: Logon method for BE confirmed working again, available from v2.3.2.

The logon method to the backend systems changed in January / February 2024. I currently lack the skills and knowledge to figure out how to get the session to connect for CH, GB, IE, NL, and likely SK. However, as at 15 June 2024, BE users have reported a fix for BE which I have added in to v2.3.2.

If you know anything about session authentication and are able to help, please get in touch.


npm npm npm EOSSTB Discord verified-by-homebridge GitHub issues

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.

iOS/iPadOS 16+ Accessory Tiles Older iOS/iPadOS Accessory Tiles
EosstbAccessoryTile EosstbAccessoryTileiOS15

This plugin displays your set-top box as a Set-Top Box accessory with power, channel and remote-control capabilities on your iOS device (iPhone, iPad, iMac, etc.).

You need a subscription to the online TV service from your local TV provider. The username and password are the same as used in the TV provider's TV app on your iOS device (the app varies by country; in Switzerland it is Sunrise TV).

Supports multiple set-top boxes, should you have more than one.

If you like this plugin, consider buying me a coffee!

Update June 2024

Logon methods for BE should be working again from v2.3.2-beta.1. Use Authentication Method B.

Update February 2024

Logon methods for many providers changed from January 2024 to mid February 2024.

Help Wanted

For GB, IE, NL and CH the logon method is no longer working. Refer Issue #112. If are able to help, please get in touch.

Readme Applicability

Due to the adding of features and functions, this Readme applies from v2.3.0. For prior versions, please see the eosstb release history on npm.

Works in Your Country (If you are with Sunrise / Telenet / UPC SK / Virgin Media / Ziggo)

As Liberty Global (the operator of the Horizon TV platform) operates in multiple countries under multiple brands, this plugin will work in a number of countries that use the Horizon TV platform. The known countries that use the same TV platform with the ARRIS DCX960 / VIP5002W or HUMAX EOS1008R / 2008C set-top box are:

Country TV Provider Web App Box Name Notes
BE Telenet Telenet TV Telenet TV-Box As of 15 June 2024 should be working again. Use Authentication Method B.
CH Sunrise Sunrise TV Sunrise TV Box As of February 2024, connection to box is no longer working. Help Wanted!
GB Virgin Media Virgin TV Go Virgin TV 360 and Virgin TV 360 Mini As of January 2024, connection to box is no longer working. Help Wanted!
IE Virgin Media Virgin TV Anywhere 360 Box As of January 2024, connection to box is no longer working. Help Wanted!
NL Ziggo Ziggo GO Mediabox Next As of February 2024, connection to box is no longer working. Help Wanted!
SK UPC Broadband Slovakia UPC TV UPC TV Box Testers Wanted
------- ----------- ------- -------- -------------
PL UPC PL UPC TV GO UPC TV Box UPC TV in Poland appears to have been discontinued in August 2023

If you subscribe to a TV service from one of these countries, you are lucky, this plugin will work for you.

May also work with other Liberty Global countries, if you know of any, let me know.

Made in Switzerland

This plugin was written and tested on the author's set-top box (ARRIS mediabox model DCX960/KK0L/A816/0000) running on Sunrise TV in Switzerland. It has also been extensively tested on Telenet in Belgium (also on the 2nd generation HUMAX 2008C-STB-xx), Virgin Media in Great Britain and Ireland, and Ziggo in the Netherlands.

Why I chose the Name EOSSTB

I tried to find a good common name that works for this plugin for all countries. Each country uses a different marketing name for the box, so I could not use the local name. The EOS system, also known as the Horizon platform, originally used an ARRIS DCX960, but even this box comes in different types and with different firmware, so I decided not to use the model name. I stuck with the box identifier that appears in the mqtt messages: EOSSTB.

In March 2022, a newer version of the set-top box appeared in Telenet in Belgium: a HUMAX 2008C-STB-TN, which identifies itself as EOS2STB. This has since been seen in NL as a HUMAX 2008C-STB-ZG, and in CH as a HUMAX 2008C-STB-UPC/CH.

In January 2023, an ARRIS VIP5002W appeared, which identifies itself as an APLSTB. However, I will keep the plugin name unchanged at EOSSTB.

Disclaimer (The Legal Stuff)

This plugin is not provided by Telenet or Sunrise or Virgin Media or Ziggo any other affiliate of Liberty Global. It is neither endorsed nor supported nor developed by Liberty Global or UPC Broadband or any affiliates. Liberty Global can change their systems at any time and that might break this plugin. But I hope not.

Requirements

Features

EosstbControls

Installation

Homebridge UI: the easiest way to install is to search for eosstb in the Homebridge UI, and then click INSTALL.

Manual install:

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 \<HomeName>: 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 \<HomeName>: Tap Done to finish the setup.
EosstbAccessoryTile

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:

RemoteControl
Key Single Tap Double Tap
Mute (see note) (see note)
Power (see note) (see note)
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: The Mute and Power buttons appear in the Remote Control as of iOS 17.5, however they are disabled. Currently, I do not know how to enable these buttons. If you have any information about these buttons, please get in touch with me.

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

Channel Count

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.

Media State (Play/Pause) Limitations

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 17.5) apart from allow you to read it in Shortcuts or Automations. Hopefully this will improve in the future.

Recording State Limitations

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.

Closed Captions Limitations

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 17.5) 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:

    "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:

    "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"
                }
            ]
        }
    ]

Platform Config Items

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.

Optional

Device Config Items

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

Optional

Name and Icon
Accessory information
Channel Display
Remote Control Button Mapping
Remote Control Volume Commands

Channel Config Items

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.

Set-Top Box KeyEvent Commands

See the Wiki for a collection of known key event commands that control the set-top box.

Special Commands

The volume and mute commands do not control the set-top box directly, but can be used to control the TV or Receiver volume (network remote control of the TV is required).

Volume

Mute

View TV Settings

You can use View TV Settings to open the set-top box main menu at the PROFILES menu. Usage: in the Home app, tap-and-wait on the set-top box tile to open the channel changer, then tap on the cogwheel to open the settings for the accessory, and scroll down to View TV Settings.

Siri

See the Wiki for details on how to control the set-top box with Siri.

Shortcuts

See the Wiki for details on how to read and control the set-top box in the Shortcuts app.

Thanks to