From db10f56c63a985cb3a44526bdc0b7ea02f9a2479 Mon Sep 17 00:00:00 2001 From: Markus Jacobsen Date: Sun, 28 Jan 2024 19:11:35 +0100 Subject: [PATCH] Add documentation for the bang_olufsen integration (#30432) Co-authored-by: Franck Nijhof --- source/_integrations/bang_olufsen.markdown | 161 +++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 source/_integrations/bang_olufsen.markdown diff --git a/source/_integrations/bang_olufsen.markdown b/source/_integrations/bang_olufsen.markdown new file mode 100644 index 00000000000..76052263814 --- /dev/null +++ b/source/_integrations/bang_olufsen.markdown @@ -0,0 +1,161 @@ +--- +title: Bang & Olufsen +description: Instructions on how to integrate Bang & Olufsen devices into Home Assistant. +ha_category: + - Media Player + - Multimedia +ha_release: 2024.2 +ha_iot_class: Local Push +ha_domain: bang_olufsen +ha_platforms: + - media_player +ha_codeowners: + - "@mj23000" +ha_config_flow: true +ha_zeroconf: true +ha_integration_type: integration +--- + +The Bang & Olufsen integration enables control of some of the features of certain [Bang & Olufsen](https://www.bang-olufsen.com/) devices through Home Assistant. + +## Compatible devices + +Devices that have been tested and _should_ work without any trouble are: + +- [Beolab 8](https://www.bang-olufsen.com/en/dk/speakers/beolab-8) +- [Beolab 28](https://www.bang-olufsen.com/en/dk/speakers/beolab-28) +- [Beosound 2 3rd gen](https://www.bang-olufsen.com/en/dk/speakers/beosound-2) +- [Beosound A5](https://www.bang-olufsen.com/en/dk/speakers/beosound-a5) +- [Beosound A9 5th gen](https://www.bang-olufsen.com/en/dk/speakers/beosound-a9) +- [Beosound Balance](https://www.bang-olufsen.com/en/dk/speakers/beosound-balance) +- [Beosound Emerge](https://www.bang-olufsen.com/en/dk/speakers/beosound-emerge) +- [Beosound Level](https://www.bang-olufsen.com/en/dk/speakers/beosound-level) +- [Beosound Theatre](https://www.bang-olufsen.com/en/dk/soundbars/beosound-theatre) + +and any other Mozart based products. + +{% include integrations/config_flow.md %} + +{% configuration_basic %} +IP Address: + description: The IP address of your device. Can be found by navigating to the device on the [Bang & Olufsen app](https://www.bang-olufsen.com/en/dk/story/apps) and selecting `Settings` → `About` → `IP address`. + required: true + type: string +Device model: + description: The model name of your Bang & Olufsen device. This is used to determine some capabilities of the device. If the device is not in the list yet, choose a product similar to yours. + required: true + type: string +{% endconfiguration_basic %} + + +## Services + +### play_media services + +The Bang & Olufsen integration supports different playback types in the `media_player.play_media` service: playback from URL, activating a favourite, playback from a local file, playing a radio station, activating a Deezer flow and Deezer playlists, albums, and tracks. + +#### play_media examples + +Playing [DR P1](https://www.dr.dk/lyd/p1) from a URL: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: url + media_content_id: http://live-icy.dr.dk/A/A03H.mp3 +``` + +Activating the first favourite: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: favourite + media_content_id: 1 +``` + +Playing a local file: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_id: media-source://media_source/local/example.mp3 + media_content_type: music +``` + +Playing a radio station: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_id: 1234567890123456 + media_content_type: radio +``` + +Playing a Deezer flow. Optionally define a Deezer user ID: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: deezer + media_content_id: flow + extra: + id: 1234567890 +``` + +Playing a Deezer playlist. Optionally define starting position for the playlist: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: deezer + media_content_id: playlist:1234567890 + extra: + start_from: 123 +``` + +Playing a Deezer album. Optionally define starting position for the album: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: deezer + media_content_id: album:1234567890 + extra: + start_from: 123 +``` + +Playing a Deezer track: + +```yaml +service: media_player.play_media +target: + entity_id: media_player.beosound_balance_12345678 +data: + media_content_type: deezer + media_content_id: 1234567890 +``` + +## 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. + +### Getting Deezer URIs + +To find Deezer playlist, album URIs, and user IDs for Deezer flows, the Deezer website has to be accessed. When navigating to an album, the URL will look something like: , and this needs to be converted to: `album:ALBUM_ID` and the same applies to playlists, which have the format: `playlist:PLAYLIST_ID`. + +Additionally a Deezer user ID can be found at by selecting the active user in a web browser.