BeoGateway/ReadMe.MD

#BeoGateway: *Indigo Server Plugin for Bang and Olufsen AV Systems*

<svg id="svg" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="400" height="269.1011235955056" viewBox="0, 0, 400,269.1011235955056"><g id="svgg"><path id="path0" d="M231.023 14.559 C 219.617 18.530,216.258 32.569,224.578 41.502 L 226.344 43.399 222.502 47.331 C 213.301 56.750,212.699 67.283,220.896 75.423 C 229.142 83.611,239.361 82.962,248.974 73.638 L 252.864 69.865 257.436 74.431 L 262.008 78.996 265.344 75.567 C 267.179 73.681,268.712 72.052,268.752 71.949 C 268.791 71.845,266.790 69.740,264.305 67.270 L 259.786 62.781 263.109 59.637 L 266.433 56.492 262.926 52.965 L 259.419 49.438 256.181 52.667 L 252.944 55.896 241.791 44.732 C 229.938 32.867,229.770 32.661,229.781 29.995 C 229.804 24.562,236.206 21.601,240.547 25.016 L 241.346 25.645 244.760 22.216 L 248.174 18.786 246.879 17.599 C 242.906 13.958,236.357 12.703,231.023 14.559 M125.562 99.011 L 125.562 182.066 137.149 181.942 C 150.694 181.797,152.648 181.486,158.909 178.487 C 182.990 166.951,186.259 133.259,164.837 117.378 C 162.534 115.671,162.498 116.062,165.098 114.516 C 199.184 94.243,198.942 43.575,164.663 23.398 C 155.253 17.860,148.847 16.278,135.042 16.087 L 125.562 15.956 125.562 99.011 M145.839 28.947 C 160.163 31.849,172.335 42.893,176.659 56.914 C 184.437 82.131,166.793 108.048,140.520 110.000 L 137.921 110.193 137.921 69.101 L 137.921 28.009 140.520 28.202 C 141.949 28.308,144.343 28.643,145.839 28.947 M239.746 56.740 L 245.920 62.919 242.693 66.163 C 238.696 70.181,237.058 71.117,234.026 71.117 C 227.906 71.117,223.729 65.176,225.698 59.270 C 226.159 57.886,232.643 50.562,233.407 50.562 C 233.498 50.562,236.350 53.342,239.746 56.740 M232.444 89.625 C 193.928 92.927,176.267 139.733,202.986 167.699 C 231.162 197.190,281.296 178.060,282.501 137.356 C 283.333 109.257,260.244 87.241,232.444 89.625 M242.307 102.120 C 267.238 106.468,278.898 135.783,263.776 156.096 C 247.552 177.888,213.280 172.723,204.255 147.125 C 195.605 122.594,216.694 97.654,242.307 102.120 M145.482 122.483 C 165.599 124.547,174.318 148.671,160.090 162.899 C 155.283 167.706,150.495 169.617,142.626 169.870 L 137.921 170.022 137.921 146.106 L 137.921 122.191 140.279 122.191 C 141.576 122.191,143.917 122.322,145.482 122.483 M126.826 225.177 C 111.897 227.496,110.472 248.730,124.998 252.414 C 127.164 252.963,133.496 252.827,135.815 252.181 L 137.219 251.789 137.294 244.715 L 137.369 237.640 132.449 237.640 L 127.528 237.640 127.528 239.326 L 127.528 241.011 130.337 241.011 L 133.146 241.011 133.146 244.931 L 133.146 248.851 132.150 249.038 C 124.346 250.502,118.200 244.833,119.415 237.291 C 120.569 230.121,128.531 226.439,135.378 229.908 L 136.725 230.591 136.902 229.301 C 137.287 226.491,137.287 226.492,135.205 225.848 C 133.352 225.276,128.625 224.897,126.826 225.177 M162.558 225.453 C 157.933 226.874,156.578 232.713,159.943 236.712 L 160.644 237.545 159.101 238.997 C 153.486 244.282,156.361 252.809,163.758 252.809 C 166.245 252.809,167.717 252.157,169.996 250.047 L 171.662 248.504 173.409 250.235 C 175.485 252.293,175.367 252.274,176.885 250.784 C 178.409 249.289,178.420 249.365,176.344 247.270 L 174.597 245.508 175.922 244.163 L 177.247 242.818 175.766 241.355 L 174.285 239.893 172.952 241.224 L 171.619 242.556 166.849 237.764 C 162.368 233.263,162.079 232.909,162.079 231.914 C 162.079 229.841,164.538 228.466,166.184 229.619 C 166.724 229.997,166.865 229.922,168.238 228.532 L 169.712 227.039 168.824 226.407 C 166.961 225.081,164.827 224.756,162.558 225.453 M201.124 225.307 C 188.483 227.757,187.364 248.454,199.667 252.254 C 208.156 254.876,215.740 250.040,216.835 241.308 C 218.151 230.815,210.884 223.414,201.124 225.307 M301.685 225.451 C 298.005 226.437,296.067 228.892,296.067 232.571 C 296.067 235.897,297.759 237.857,302.645 240.189 C 311.005 244.181,307.673 251.335,298.738 248.576 C 296.507 247.887,296.730 247.742,296.488 250.033 L 296.291 251.892 298.311 252.387 C 305.897 254.246,311.635 251.044,311.651 244.944 C 311.662 240.869,310.438 239.307,305.045 236.511 C 300.663 234.239,299.780 233.137,300.606 230.968 C 301.532 228.536,304

*Please note this plugin is not endorsed or affiliated with Bang & Olufsen in any way*

##Introduction
Plugin for the [Indigo Domotics](https://www.indigodomo.com) Home Automation software allowing integration and control of Bang and Olufsen AV systems. 
The plugin provides the following functionality:

- Defines an Indigo AV Renderer device type with state monitoring of 
  - Current Source ID and Source Name, 
  - PlayState, 
  - Current Channel/Track number and Name, and 
  - Volume
- Light and appliance control via Beo4/BeoRemote One LIGHT and CONTOL commands
- Native control of Apple Music via user defined audio source (*N.MUSIC by default*), using Beo4/BeoRemote One to control transport 
- One touch activation of audio experiences via Indigo UI, any Indigo trigger, or Apple Home app. [^1]  
  - If all sources are in standby, a single press starts a pre-defined default audio experience (*RADIO by default*)
  - If sources are already playing, a single press joins the current audio experience
- Send Home Integration Protocol commands to the gateway (BLGW only)
- State change reporting in the Apple Notification Center
- Basic monitoring and reporting of traffic on the Bang and Olufsen MasterLink network, including:
  - MasterLink packet information, 
  - MLGW protocol data, and 
  - Home Automation Protocol data
  
[1]: Via the [HomeKit Bridge](https://www.indigodomo.com/pluginstore/172/) Plugin 

##Requirements
Compatible with legacy DataLink (via 1611 converter), MasterLink, and modern NetworkLink products, including the BeoLink Converter ML/NL.
The code requires a MasterLink or BeoLink Gateway to run - it is untested with the BeoLiving Intelligence

##Basic Setup and Use
1. Install the plugin from the Indigo Plugin Store.
2. Configure the plugin providing the following information for your gateway: 
   1. IP address, 
   2. port, 
   3. login and password
3. Select the default audio source for devices. You can toggle Apple Music control On/Off and assign it to a particular source
4. The plugin will download the configuration from the gateway and create AV renderer devices accordingly
5. Devices can only access sources defined in their config on the gateway and will recognise at least the channel/tracks included in their favourites lists. Some sources (e.g. NetworkLink sources) may recognise additional channels and track data.
6. Devices can be switched On/Off and toggled via the indigo UI

##Advanced Functions
###Plugin Events/Triggers
The plugin can respond to various events on the B&O network including:
- All Standby Events
- Light Commands
- Control Commands
- Beo4/BeoRemote One Commands to a Specific Source
- Virtual Button presses 

These events can be found under the 'BeoGateway Plugin Event' list in Indigo's Create New Trigger dialogue 

###Plugin Actions
Indigo Events can trigger a number of actions on the B&O Network including:
####BeoGateway Plugin Actions:
- Request BLGW Home Integration Protocol State Updates for all devices
- Send a BLGW Home Integration Protocol Command (*only on BLGW - see below*)
- Send Free Text Integration Protocol Command (*for advanced users - see below*)
- Send Virtual Button
- Post a Message to the Notification Centre (*see below*)
- Send All Standby Command

####BeoGateway Device Actions:
- Send Beo4 Source Selection Command
- Send Beo4 Key
- Send BeoRemote One Source Selection Command
- Send BeoRemote One Key
- Request Device State Update

###Protocol Monitoring
Network traffic monitoring to the Indigo log be toggled in the plugin config menu:
- [x] Verbose Mode

A typical message is formatted as follows:
```
BeoGateway Plugin               
    ----------------------------------------------------------------------------
    BLGW Home Integration Protocol: <--DATA-RECEIVED!-<< on 05/02/22 at 17:13:32
    ============================================================================
    Header: ['s Downstairs', 'Dining Room', 'AV renderer', 'BeoMaster 7000']
    Payload: ['nowPlaying=', 'nowPlayingDetails=type: Legacy; track number: 2',
	 'online=Yes', 'sourceName=RADIO', 'sourceUniqueId=RADIO:1790.1179011.2
	6002135@products.bang-olufsen.com', 'state=Play', 'volume=26']
    ----------------------------------------------------------------------------
    Zone: DOWNSTAIRS 
    Room: DINING ROOM 
    Type: AV RENDERER 
    Device: BeoMaster 7000 
    State_Update: 
        nowPlaying: BBC Radio 2 
        nowPlayingDetails: 
            type: Legacy 
            channel_track: 2
         
        online: Yes 
        sourceName: RADIO 
        source: RADIO 
        sourceUniqueId: RADIO:1790.1179011.26002135@products.bang-olufsen.com 
        state: Play 
        volume: 26
```

###Apple Music Control
Apple Music control can be toggled in the plugin config menu:
- [x] Control Apple Music

It will also report the current track information to the indigo log if 'post notifications' is toggled:
- [x] post notifications

If the plugin is configured to map a source to Apple Music, selection of that source on your remote will initiate playback immediately, shuffling from the entire library. 
If other AV renderers join the music experience playback is unaffected. Apple Music will stop playing when all active audio renderers go into a Standby state.
The controls are mapped as follows:

| Beo4 Key | BeoRemote One Key | Apple Music Action |
| ----------- | ----------- | ----------- |
| Go | Play | Play
| Stop | Pause | Pause
| Wind | Wind | Scan Forwards 15 Seconds
| Rewind | Rewind | Scan Backwards 15 Seconds
| Step Up | P+ | Next Track
| Step Down | P- | Previous Track
| Shift-1/Random | Random | Toggle Shuffle
| - | Info | Produce Notification of Current Track Info and Print to Indigo Log
| - | Guide | Print this table to Indigo Log
| Green | Green | Shuffle Playlist 'Recently Played'
| Yellow | Yellow | Play Digital Radio Stations from Playlist 'Radio'
| Red | Red | More of the Same
| Blue | Blue | Play the Album that the Current Track Resides On 

###State Reporting in Apple Notification Centre
State reports in the notification centre can be toggled in the config menu
- [x] Post Notifications

![](Resources/Notification.png)

It is also possible to trigger notifications via any Indigo event using the action:
"BeoGateway Plugin Actions/Post Message in Notification Centre"

###Home Integration Protocol Commands
The BeoLink Gateway (BLGW) provides a Home Integration Protocol for external automation services to communicate with devices ont he B&O Network.
A copy of the documentation for the protocol is included in the plugin's Resources/Documentation folder, and the overview below is lifted from that document.
>With the introduction of BLGW, there is a standard way of identifying resources and specifying
activity and state in the connected systems. Such activity can be represented unambiguously in
the form of a text string.
Home Integration Protocol allows external applications to directly interact with BLGW. This is done
by means of a minimalist line-based protocol that directly transports the text representation of all
activity.  
 
>A resource is uniquely identified by the combination of area, zone, type and name, and is represented
uniquely in string form as a path with the form zone/room/type/name. 
>
>For example:
 
```
Guest house/Kitchen/AV_RENDERER/BeoVision/
```
>An event or command is represented by a resource path followed by an action (event or command),
optionally followed by attributes and values.
> 
>Example of a simple command, and a command with 2 attributes:
```
Guest house/Kitchen/BUTTON/Lights ON/PRESS
```
```
Guest house/Kitchen/AV_RENDERER/BeoVision/Beo4 command?Command=TV&Destination selector=Video_source
```
>Example state change event, with 1 attribute.
```
Guest house/Kitchen/BUTTON/Lights ON/STATE_UPDATE?STATE=1
```
>Example generic event matching all state updates (see documentation for generic programming):
```
*/*/*/*/STATE_UPDATE
```
The following commands are supported on HIP:

| Command | Arguments | Description |
| ----------- | ----------- | ----------- |
| c | Generic ID | Command, from client to server.
| f | Generic resource | State filter request, client to server.
| e | Code, message | Error code, server to client.
| q | Generic resource | State query, client to server.
| s | Specific ID | State update, server to client.
| r | Specific ID | State response, client to server.

>All commands from client to server take a single argument, which is an identifier for resources,
commands or events.

>A complete message consists of:
>1. The command (1 character)
>2. Space (ASCII 0x20)
>3. The argument, which is an encoded string
>4. Line termination, consisting of CR+LF (the server will also accept a single CR)

>For example, to press all buttons in the installation, the client sends (do not try this at home):
```
c */*/BUTTON/*/PRESS" + CR + LF
```
##Credits
The code draws heavily on the existing [MLGW](https://github.com/giachello/mlgw) project by user Giachello,
but is recoded for Python 2.7. His work underpins the decoding of raw MasterLink packets for the ML Command Line Protocol.