Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Bang & Olufsen custom action examples #36404

Merged
merged 7 commits into from
Dec 22, 2024
Merged

Add Bang & Olufsen custom action examples #36404

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
eee46ce
Improve Beolink documentation
mj23000 Dec 17, 2024
c5f0ae6
Replace Beolink link
mj23000 Dec 17, 2024
3a7e4c6
Fix Beolink link
mj23000 Dec 17, 2024
be3575a
Remove trailing : from headings
mj23000 Dec 17, 2024
9c01f0c
Fix issues caught by coderabbit
mj23000 Dec 17, 2024
6fd8598
Merge branch 'next' into bang_olufsen_add_action_examples
mj23000 Dec 18, 2024
4ed7b42
Document general Beolink error indications
mj23000 Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 144 additions & 11 deletions source/_integrations/bang_olufsen.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,9 @@ data:

### Custom actions

The Bang & Olufsen integration additionally supports different custom actions
The Bang & Olufsen integration additionally supports different custom actions for Beolink.

[Beolink](https://support.bang-olufsen.com/hc/en-us/articles/4411572883089-What-is-Beolink-Multiroom) is Bang & Olufsen's advanced multiroom audio solution. This integration supports Home Assistant's `media_player` grouping, but to fully benefit from Beolink, such as being able to join legacy devices not added in Home Assistant, custom actions have been defined.

#### `bang_olufsen.beolink_join`

Expand All @@ -298,20 +300,37 @@ Join a Beolink experience.
| `beolink_jid` | yes | Manually specify Beolink JID to join. |
| `source_id` | yes | Specify which source to join, behavior varies between hardware platforms. Source names prefaced by a platform name can only be used when connecting to that platform. For example "ASE Beoradio" can only be used when joining an ASE device, while ”ASE / Mozart Deezer” can be used with ASE or Mozart devices. A defined Beolink JID is required. |

A limited selection of `source_id`'s are available. The below table shows which `source_id` can be joined on which hardware platform:
##### Join a currently active beolink experience or device playing compatible source

| Hardware platform | Compatible source_ids |
| ----------------------- | ------------------------------------------ |
| ASE | `beoradio` |
| ASE and Mozart | `deezer`, `spotify` |
| Mozart | `tidal` |
| Beolink Converter NL/ML | `radio`, `tp1`, `tp2`, `cd`, `aux_a`, `ph` |
```yaml
action: bang_olufsen.beolink_join
target:
entity_id: media_player.beosound_balance_12345678
```

Trying to join an invalid source will result in either a Home Assistant error or an audible error indication from your device.
Repeatedly calling this will cycle through available devices.

##### Action usage example
Will also be triggered by calling the `media_player.join` action with an empty list of `group_members`:

```yaml
action: media_player.join
target:
entity_id: media_player.beosound_balance_12345678
data:
group_members:
```

##### Join a specific active beolink experience

```yaml
action: bang_olufsen.beolink_join
target:
entity_id: media_player.beosound_balance_12345678
data:
beolink_jid: [email protected]
```

Join the `radio` source on a Beolink Converter NL/ML:
##### Join the "radio" source on a Beolink Converter NL/ML

```yaml
action: bang_olufsen.beolink_join
Expand All @@ -322,6 +341,17 @@ data:
source_id: radio
```

A limited selection of `source_id`s are available. The below table shows which `source_id` can be joined on which hardware platform:

| Hardware platform | Compatible source_ids |
| ----------------------- | ------------------------------------------ |
| ASE | `beoradio` |
| ASE and Mozart | `deezer`, `spotify` |
| Mozart | `tidal` |
| Beolink Converter NL/ML | `radio`, `tp1`, `tp2`, `cd`, `aux_a`, `ph` |

Trying to join an invalid source will result in either a Home Assistant error or an audible error indication from your device.

#### `bang_olufsen.beolink_expand`

Expand current Beolink experience.
Expand All @@ -331,6 +361,62 @@ Expand current Beolink experience.
| `all_discovered` | yes | Expand Beolink experience to all discovered devices. |
| `beolink_jids` | yes | Specify which Beolink JIDs will join current Beolink experience. |

##### Expand an active Beolink experience to all other devices discovered by the defined device

```yaml
action: bang_olufsen.beolink_expand
target:
entity_id: media_player.beosound_balance_12345678
data:
all_discovered: true
```

##### Expand an active Beolink experience to a specific device

```yaml
action: bang_olufsen.beolink_expand
target:
entity_id: media_player.beosound_balance_12345678
data:
beolink_jids:
- [email protected]
```

Will also be triggered by calling the `media_player.join` action, with the entity_id of a `media_player` entity from this integration in `group_members`:

```yaml
action: media_player.join
target:
entity_id: media_player.beosound_balance_12345678
data:
group_members:
- media_player.beosound_balance_33333333
```

##### Expand an active Beolink experience to specific devices

```yaml
action: bang_olufsen.beolink_expand
target:
entity_id: media_player.beosound_balance_12345678
data:
beolink_jids:
- [email protected]
- [email protected]
```

Will also be triggered by calling the `media_player.join` action, with the entity_ids of `media_player` entities from this integration in `group_members`:

```yaml
action: media_player.join
target:
entity_id: media_player.beosound_balance_12345678
data:
group_members:
- media_player.beosound_balance_33333333
- media_player.beosound_balance_66666666
```

#### `bang_olufsen.beolink_unexpand`

Unexpand from current Beolink experience.
Expand All @@ -339,14 +425,61 @@ Unexpand from current Beolink experience.
| --------------------- | -------- | ---------------------------------------------------------------------- |
| `beolink_jids` | no | Specify which Beolink JIDs will leave from current Beolink experience. |

##### Remove a device from an active Beolink experience

```yaml
action: bang_olufsen.beolink_unexpand
target:
entity_id: media_player.beosound_balance_12345678
data:
beolink_jids:
- [email protected]
```

##### Remove devices from an active Beolink experience

```yaml
action: bang_olufsen.beolink_unexpand
target:
entity_id: media_player.beosound_balance_12345678
data:
beolink_jids:
- [email protected]
- [email protected]
```

#### `bang_olufsen.beolink_leave`

Leave a Beolink experience.

##### Action usage example

```yaml
action: bang_olufsen.beolink_leave
target:
entity_id: media_player.beosound_balance_12345678
```

Same behavior as calling the `media_player.unjoin` action:

```yaml
action: media_player.unjoin
target:
entity_id: media_player.beosound_balance_12345678
```

#### `bang_olufsen.beolink_allstandby`

Set all connected Beolink devices to standby.

##### Action usage example

```yaml
action: bang_olufsen.beolink_allstandby
target:
entity_id: media_player.beosound_balance_12345678
```

## Automations

WebSocket notifications received from the device are fired as events in Home Assistant. These can be received by listening to `bang_olufsen_websocket_event` event types, where `device_id` or `serial_number` can be used to differentiate devices.
Expand Down
Loading