From 247093dce230ac0d56040f55335b0af84bb0c290 Mon Sep 17 00:00:00 2001 From: Markus Jacobsen Date: Mon, 23 Dec 2024 00:18:10 +0100 Subject: [PATCH] Add Bang & Olufsen custom action examples (#36404) --- source/_integrations/bang_olufsen.markdown | 155 +++++++++++++++++++-- 1 file changed, 144 insertions(+), 11 deletions(-) diff --git a/source/_integrations/bang_olufsen.markdown b/source/_integrations/bang_olufsen.markdown index c4246b84bd8..349bdb45072 100644 --- a/source/_integrations/bang_olufsen.markdown +++ b/source/_integrations/bang_olufsen.markdown @@ -287,7 +287,11 @@ 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. + +Attempting to execute an invalid Beolink action will result in either a Home Assistant error or an audible error indication from your device. #### `bang_olufsen.beolink_join` @@ -298,20 +302,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`: -Join the `radio` source on a Beolink Converter NL/ML: +```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: 1111.2222222.33333333@products.bang-olufsen.com +``` + +##### Join the "radio" source on a Beolink Converter NL/ML ```yaml action: bang_olufsen.beolink_join @@ -322,6 +343,15 @@ 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` | + #### `bang_olufsen.beolink_expand` Expand current Beolink experience. @@ -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: + - 1111.2222222.33333333@products.bang-olufsen.com +``` + +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: + - 1111.2222222.33333333@products.bang-olufsen.com + - 4444.5555555.66666666@products.bang-olufsen.com +``` + +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. @@ -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: + - 1111.2222222.33333333@products.bang-olufsen.com +``` + +##### Remove devices from an active Beolink experience + +```yaml +action: bang_olufsen.beolink_unexpand +target: + entity_id: media_player.beosound_balance_12345678 +data: + beolink_jids: + - 1111.2222222.33333333@products.bang-olufsen.com + - 4444.5555555.66666666@products.bang-olufsen.com +``` + #### `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.