Bang & Olufsen MasterLink Gateway / BeoLink Gateway - Home Assistant component

This component integrates Bang & Olufsen Masterlink Gateway (2009) and BeoLink Gateway (2014) with Home Assistant. These devices support Masterlink, the first generation B&O API to control their equipment, used from 1995 through 2015, and include BeoLab speakers, BeoSound audio equipment, and BeoVision TVs.

It will turn all your Bang & Olufsen audio and video devices into "media_player" entities in Home Assistant. By using an undocumented back door of the B&O gateways, you can control any Home Assistant devices with your B&O remote, and integrate the B&O equipment in automations. You can buy a used ML Gateway on eBay for $200-400. While newer 'Network Link' devices are supported by the gateway, the BeoPlay Home Assistant plugin supports more advanced NL features. You can use both plugins at the same time. In that case, use MLGW for automations, and BeoPlay to control the device. This is an example of a B&O / Home Assistant integrated setup

Installation

• With HACS: go to your HACS download panel, search for "MasterLink Gateway" and download from there. You need to restart.
• Manually: Create a mlgw directory in /config/custom_components/ and copy all the files in the /custom_components/mlgw repository into it.

Configuration

MLGW should show up through auto discovery in your Configuration->Integrations panel on Home Assistant. If you don't see it, go to "Configuration->Integrations-> (+)" and look for MLGW.

The configuration flow will ask for the IP address of the MLGW, username and password and whether to use the "Direct MasterLink" backdoor (see below). This backdoor significantly increases the power of the plugin. For example, to start and control your Spotify or other streaming integrations directly from your Beo4 or BeoOne remote control.

The integration works also without this feature, but it's much better with it. To enable it, you must use the admin account to login. Explicitly select or unselect the feature before continuing.

Setting up devices

The plugin will automatically pick up the configuration from the the MLGW. The devices and their sources must be configured in the MLGW/BLGW setup page (Programming->Devices->Beolink and Programming->Sources) as seen in the pictures below.

Set up Favorites in the MLGW configuration settings, to configure radio stations. Similar to the offical BeoLink app, the icons and the names of these radio stations will show up in Home Assistant.

You will need to reference icon urls on the Internet, or if you prefer more privacy, store the icons somewhere on your local network, for example on Home Assistant's www/icons folder, similar to the example in the picture below. Replace the URL with your specific situation.

There is also a way to configure through configuration.yaml for testing and hacking, but it is deprecated.

Using the integration

Speakers and Bang & Olufsen Sources

Beolink speakers (e.g., a Beolab 3500 in your kitchen) will show up as normal "media_player" devices that you can control from Home Assistant, similar to what you'd get from the standard BeoLink app. I use mini media player because I like that it groups all items together. You can control volume and turn on the B&O sources from your Home Assistant dashboard.

Remember that only one source is shared on all the Masterlink speakers (it's a single zone system) so you can't play different sources on different speakers at the same time.

The implemented media_player commands include:

turn_on, turn_off, select_source, volume_up, volume_down, volume_mute, media_previous_track, media_next_track, media_play, media_stop, media_pause, shuffle_set, repeat_set

Home Assistant Events

The more powerful use of this integration is to listen to events on the B&O system to power your automations.

Lights and Virtual Buttons

The mlgw component forwards Virtual Buttons, Light / Control commands from the remove control, "All Standby" and other commands to Home Assistant. Automations on HA can use them to power automations. You can see what events fire with the Home Assistant "Events" UI. (Developer tools->Events->Listen to Events and type: mlgw.MLGW_telegram in the field on the bottom of the page).

Light / Control and "All Standby" commands are also available as predefined Triggers.

For example, if the user selects LIGHT 1 on their Beo4 or BeoRemoteOne remote control, an Event in Home assistant will allow you to control your lights or a scene. Note that Light and Control events are only supported by the devices listed here.

The following Event Automation catches "All Standby" (which means the entire B&O system is turned off). You can use it to turn off Spotify streaming:

There are 5 events fired by the official integration:

Trigger Device Automations

You can use a subset of LIGHT + \<key> commands to generate automation triggers in a simple way for the MLGW gateway. Just create a new automation from the device screen for your MLGW. You will find the Triggers listed under the MLGW device name. In the example below, the device name is "SanCarlos". This is the same name configured in the MLGW configuration panel.

"Direct MasterLink"

A special undocumented feature of the Master Link Gateway allows captures ALL traffic on the Masterlink bus, including events that aren't included in B&O's standard API, like a speaker turning off, or specific key presses on the remote control.

You can use them to drive much more interesting behavior. For example, you can:

• start Spotify by pressing the "green" button on your Beo4 remote after selecting A.MEM (the source associated with the Aux input on B&O equipment where you can connect a streaming devices like a Chromecast Audio).
• use the "Blue" button to turn off a speaker and turn on another one when moving within the house
• use the number buttons to select different 'streaming radios' through the 'netradio' plugin.
• use the up, down, wind, rewind buttons to switch Spotify playlists or move to the next song in the playlist.

The possibilities are endless. You can see a few examples here: https://github.com/giachello/mlgw/blob/main/example_automations.yaml. An easy way to see what goes on the ML bus is using the "Events" UI. (Developer tools->Events->Listen to Events and type: mlgw.ML_telegram in the field on the bottom of the page.

For example the following setup catches the Green key event on the Beo4 remote.

Another example is to stop playback when the "Stop" button is pressed on the remote (in this case, "media_player.bang_olfusen" is the Chromecast connected to the input of the B&O audio system):

There are a lot of ML telegram types; a few useful telegrams you can use in automations are listed in the table below. The most useful are likely going to be the BEO4_KEY (a key press on the B&O remote control). A full list of BEO4 Keys is available in this file: const.py

Sending Virtual Button Commands

You can send virtual button commands to the MLGW/BLGW by using the mlgw.virtual_button service. This is useful if you want to activate macros on the MLGW. You can send PRESS, HOLD and RELEASE commands, but typically you will just need to send one PRESS. This documentation file describes how to use the HOLD and RELEASE commands.

Alternatively, you can use the "Action" setting in an automation to send Virtual Button and 'All Standby' commands, as shown below.

Debugging

You can see the details of the plugin operation, including what is being fired by the MasterLink bus by enabling "DEBUG" logging in Configuration.yaml. Then just look at your home-assistant.log file.

logger:
  default: warning
  logs:
    custom_components.mlgw: debug

Not implemented / TODO

• Timer and Clock packets unpacking
• Remote Integration into Home Assistant

Known Issues

• When a Audio Master or a Video Master starts playing a source that it owns (e.g., a BeoSound 3000 turning on A.MEM), it doesn't tell the ML bus that is happening, so we cannot detect it in the plugin. Unfortunately, there is no known solution.
• When a Video Master has several sources active at the same time (e.g., a Decoder on 'TV' being played locally and a tuner on 'DTV' being distributed on the system) it reports both sources at the same time and that confuses the plugin.
• Reports that certain NL products (e.g., Beosound 35) will forward LIGHT commands sent through a IR remote (e.g., Beo4) but not the Bluetooth remote (e.e., BeoRemote One). The workaround is to listen to the LIGHT events using my BeoPlay plugin.

High level description of the code

• gateway.py deals with the communication with the mlgw and is likely code that should go into a separate library / python module (PyPI). It has some code to fire events on home assistant when things happen on the MLGW.
• config_flow.py is the configuration flow and is Home Assistant specific. It stores the MLGW host and password configuration parameters inside HA which are then used by __init__.py. There is one piece of MLGW-specific code (to get the serial number through XMPP).
• __init__.py is called by Home Assistant to start the module. It calls gateway.py to create a gateway instance. It also pulls the json configuration from the gateway that lists all the devices configured on the gateway.
• media_player.py creates "MediaPlayer" entities in Home assistant for each MLGW device. The BeoSpeaker class manages the communication to and from the MLGW on an ongoing basis. There is one instance of the class for each device (speaker, audio, TV) in the MLGW configuration. It monitors the traffic on both the MLGW api and on the special masterlink backdoor.

Because the ml/mlgw is a single zone system and not all features are documented, there is a lot of random code to handle corner cases (e.g., if one speaker changes source, all other should too, because it's a single zone system, handling multiple video sources...).