Homebridge plugin for Bang & Olufsen/Beoplay devices

This plugin allows you to control Bang & Olufsen Beoplay speakers and TVs using a HomeKit enabled iOS app or Siri. Note that this plugin does NOT work with B&O devices that use the new Mozart platform such as the Beolab 28, Beosound Balance, Beosound Emerge, Beosound Level or Beosound Theatre.

Due to the limitations of support for speakers in HomeKit, B&O devices can be represented in HomeKit as a number of different devices - including as a TV, speaker, smart speaker, lightbulb, switch or fan. Which device you choose will determine which features can be controlled in which way (please see below).

Note that the plugin honours the B&O device's "maximum volume" setting, so trying to set the volume to higher than this will set the volume to the maximum.

Community

Note there is now a #beoplay group on the Homebridge community on Discord for any usage and setup queries and/or bug reports.

Installation

Option 1: Install via Homebridge Config UI X:

Search for "beoplay" in homebridge-config-ui-x and install homebridge-beoplay.

Option 2: Install via HOOBS:

Search for "homebridge-beoplay" in HOOBS and install.

Option 3: Manually Install:

sudo npm install -g homebridge-beoplay

Configuration

The plugin is configured as part of your Homebridge config.json file.

Option 1: Configure via Homebridge Config UI X:

homebridge-beoplay supports plugin configuration within Config-UI-X (Plugins -> Homebridge Beoplay -> Settings). Note that most of the options (as noted below) are optional. Where you have multiple B&O devices you want to configure, make sure to add additional devices using the Add B&O/Beoplay Device button at the bottom of the configuration interface.

Option 2: Configure Manually:

The following is an example addition to an existing config.json. See below for valid options and values you can provide. Please note, homebridge-beoplay does not have any platform level settings - all settings are at the device level.

  "platforms": [
    {
      "platform": "Beoplay",
      "devices": [
        {
          "name": "Bedroom Speakers",
          "ip": "192.168.x.x"
        },
        {
          "name": "Living Room TV",
          "ip": "192.168.x.x"
        }
      ]
    }
  ]

Option 3: Configure via HOOBS:

Within the HOOBS interface you will be presented with a "Devices" box within the interface when first installing the plugin. This should be configured as above ("Option 2: Configure Manually"), by supplying only the values for the devices section, as below:

      [
        {
          "name": "Bedroom Speakers",
          "ip": "192.168.x.x"
        },
        {
          "name": "Living Room TV",
          "ip": "192.168.x.x"
        }
      ]

Options

Only the name and ip options are required. The defaults should be sensible in most cases, however there are a number of optional parameters supported in order to modify the device behaviour:

Option | Default | Explanation --- | --- | --- type | fan for speakers, tv for TVs | What device type to represent the BeoPlay device as in HomeKit. Values can be speaker, smartspeaker, bulb, fan, switch or tv. All have advantages and disadvantages - please see additional detail below mode | mute if type is speaker or smartspeaker, otherwise power | What behaviour to perform when the device is muted (speaker, smartspeaker) or turned off (bulb, fan, switch and TV). Values can be mute or power - please see additional detail below on | input if type is tv, otherwise on | Define whether to power on the device from standby using the API (on - available for speakers), via setting an input (input - available for both speakers and TVs), or via joining a B&O multiroom experience (join) default | 1 | The input number selected to power on the device when coming out of standby. Used when using an on value of input inputs | undefined | The inputs that can be selected from within the TV interface when using the TV integration. Available inputs will be parsed automatically if these values are not supplied, however by supplying these in the config you can customise which inputs are presented and the ordering. See below for the format exclude | undefined | If you don't supply inputs manually (via inputs above) these will be parsed automatically from the device. The exclude option allows you to exclude specific inputs from being automatically setup - for example, on a speaker its unlikely you use all of the supported music services, and on a TV you may not use all of the available inputs. See below for the format. speakergroups | undefined | If you don't supply speaker groups these will be parsed automatically from the device. See below for the format.

Adding your TVs and Smart Speakers to the Home app

Note that devices using the TV and Smart Speaker integrations are exposed as external accessories and as such will not automatically be shown in the Home app or Control Centre remote - they need to be added as if they were a standalone HomeKit device.

To add a TV or Smart Speaker to HomeKit follow this steps:

• Open the Home app
• Select Add Accessory
• Tap on the "More options..." link

The TV or Smart Speaker should appear on the next page. Select it and when asked for a PIN, use the same PIN you used for Homebridge (in the bridge section of your config.json). If you have multiple devices using these integrations, follow the same process to add each.

Option details

Type parameter

Note that any of the types can be used if your B&O device is a speaker - TVs will only use the tv type. Functionality and how the device can be controlled will differ as shown below. Note that how you have set the "mode" setting (see below) will determine whether on/off control will standby/wakeup the device or mute/unmute the device.

Type | Apple Home app | Siri | Third party HomeKit app (ie Eve, Home+ etc) --- | --- | --- | --- tv | on/off and change input. Volume up/down via hardware buttons and media control in Control Centre remote | on/off | Not supported speaker | Not supported | Not supported | May be supported (works in Eve, Home+) for mute/unmute and volume smartspeaker | play/pause. Volume setting supported via creating a Scene or Automation | Not supported | Not supported bulb | on/off and volume | on/off and volume | on/off and volume fan | on/off and volume | on/off and volume | on/off and volume switch | on/off | on/off | on/off and volume

Note that for the bulb option, Siri will include the device within commands that effect all lighting, so Siri will turn the speaker off if you say "Turn off the lights" and will change the volume if you say "Dim the lights to 20%".

Note for the smartspeaker option that you can only adjust the volume, pause audio and resume audio within a HomeKit Scene/Automation. You cannot use the Play Audio option with this plugin as that uses Airplay 2, not HomeKit, to play the audio.

Mode parameter

The plugin will mute/unmute if using the speaker/smartspeaker integration type when the HomeKit mute button is selected/unselected, and turn on/off if using the TV, bulb switch, or fan integrations when the HomeKit power button is on/off. By setting "mode" to "power" the plugin will instead power on/standby your speaker/smartspeaker integration when you unmute/mute. By setting "mode" to "mute" the plugin will instead mute/unmute a fan, bulb, switch or TV integration when the power button is turned off/on. This may be preferable, depending on what behaviour you are looking for.

TV Media Control in the Control Center Remote

For TV integrations, volume can be incremented/decremented via the hardware buttons on your iOS device in the Control Center Remote application.

Additionally, the following functionality has been mapped to each of the following buttons in the Control Centre Remote:

Button | Functionality
--- | --- Arrow Up | Next Speaker Group Arrow Down | Previous Speaker Group Arrow Left | Media Back Arrow Right | Media Forward Select (Button in Middle of Arrows) | Toggle Mute Play/Pause | Play/Pause Back | Leave Multiroom Experience Information | Join Multiroom Experience

Inputs parameter

Inputs for the TV integration type are defined as follows:

"inputs": [{
        "name": "Tune In",
        "type": "APPLICATION",
        "apiID": "radio:[email protected]"
    },
    {
        "name": "Bluetooth",
        "type": "OTHER",
        "apiID": "bluetooth:[email protected]"
    }
]

The values are as follows:

• name: Name for the input in the interface
• type: Can be one of TV, HDMI, APPLICATION, AIRPLAY, or OTHER
• apiID: This is the id value for the input in the Beoplay API. This can be found by browsing to the following URL path on your device: http://x.x.x.x:8080/BeoZone/Zone/ActiveSources/

Exclude parameter

Note that you can either supply an inputs value or an exclude value - if you supply both the exclude option will be ignored.

Exclude options for the TV integration type are defined as follows:

"exclude": [
  "radio:[email protected]",
  "bluetooth:[email protected]"
]

The values to supply are the id value for the input in the Beoplay API. As per for the inputs values, the inputs supported by your device can be found by browsing to the following URL path on your device: http://x.x.x.x:8080/BeoZone/Zone/ActiveSources/

Speakergroups parameter

You can supply speaker groups manually in the following format. This is optional as they will be parsed from the device if this parameter is not supplied:

"speakergroups": [{
        "id": 1,
        "name": "Speaker Group 1"
    },
    {
        "id": 2,
        "name": "Speaker Group 2"
    }
]

The values to supply for the id value for each speaker group can be found by browsing to the following URL path on your device: http://x.x.x.x:8080/BeoZone/Zone/Sound/SpeakerGroup/

Credits

This plugin started life as a fork of the homebridge-http-speaker plugin by Supereg

Inspiration for the Lightbulb implementation is derived from a fork of homebridge-sonos by Dominic Stelljes

Television implementation inspiration largely derived from the homebridge-panasonic plugin by George Nick Gorzynski

Inspiration for patterns on handling cached accessories taken from the homebridge-dyson-pure-cool plugin by Lukas Rögner