github-mirrors/BeoGateway
1
0
Fork 0
mirror of https://github.com/LukeSpad/BeoGateway.git synced 2024-12-23 21:51:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
BeoGateway/ReadMe
LukeSpad b0154051e5
Add files via upload 
Branch from pre-release migrating to a fully featured Indigo Domotics plugin
2022-02-05 18:06:47 +00:00

204 lines
No EOL
17 KiB
Text
Raw Blame History

#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.424 228.099,309.431 229.636 C 310.035 229.822,310.912 226.304,310.348 225.955 C 309.029 225.140,303.949 224.844,301.685 225.451 M33.146 239.078 L 33.146 252.595 38.553 252.453 C 42.652 252.345,44.366 252.188,45.635 251.802 C 51.570 249.996,52.407 242.156,46.955 239.429 L 45.195 238.548 46.025 238.259 C 50.408 236.731,51.217 229.886,47.331 227.196 C 45.485 225.918,43.453 225.562,38.003 225.562 L 33.146 225.562 33.146 239.078 M65.646 225.761 C 65.490 226.023,54.819 250.973,54.468 251.896 C 54.231 252.518,54.263 252.528,56.397 252.527 L 58.567 252.525 59.868 249.226 L 61.168 245.927 67.697 245.927 L 74.225 245.927 75.525 249.226 L 76.826 252.525 79.003 252.527 C 80.200 252.527,81.180 252.432,81.180 252.314 C 81.180 252.197,78.670 246.161,75.603 238.902 L 70.027 225.702 67.902 225.621 C 66.734 225.576,65.718 225.639,65.646 225.761 M86.798 239.045 L 86.798 252.528 88.901 252.528 L 91.005 252.528 91.078 241.890 L 91.152 231.251 96.961 241.820 L 102.771 252.388 105.318 252.468 L 107.865 252.549 107.865 239.055 L 107.865 225.562 105.902 225.562 L 103.939 225.562 103.866 236.078 L 103.792 246.593 98.039 236.078 L 92.285 225.562 89.542 225.562 L 86.798 225.562 86.798 239.045 M224.438 239.045 L 224.438 252.528 232.022 252.528 L 239.607 252.528 239.607 250.702 L 239.607 248.876 233.989 248.876 L 228.371 248.876 228.371 237.219 L 228.371 225.562 226.404 225.562 L 224.438 225.562 224.438 239.045 M244.439 235.323 C 244.541 246.255,244.614 246.698,246.779 249.533 C 249.975 253.719,258.891 253.958,262.507 249.955 C 265.009 247.186,265.449 244.729,265.449 233.547 L 265.449 225.562 263.363 225.562 L 261.276 225.562 261.186 234.902 C 261.064 247.501,260.326 249.157,254.831 249.157 C 249.306 249.157,248.321 246.705,248.317 232.935 L 248.315 225.562 246.332 225.562 L 244.349 225.562 244.439 235.323 M274.157 239.045 L 274.157 252.528 276.264 252.528 L 278.371 252.528 278.371 246.489 L 278.371 240.449 283.287 240.449 L 288.202 240.449 288.202 238.624 L 288.202 236.798 283.287 236.798 L 278.371 236.798 278.371 233.006 L 278.371 229.213 283.567 229.213 L 288.764 229.213 288.764 227.388 L 288.764 225.562 281.461 225.562 L 274.157 225.562 274.157 239.045 M320.225 239.045 L 320.225 252.528 327.809 252.528 L 335.393 252.528 335.393 250.702 L 335.393 248.876 329.916 248.876 L 324.438 248.876 324.438 244.669 L 324.438 240.462 329.424 240.386 L 334.410 240.309 334.494 238.553 L 334.577 236.798 329.508 236.798 L 324.438 236.798 324.438 233.006 L 324.438 229.213 329.916 229.213 L 335.393 229.213 335.393 227.388 L 335.393 225.562 327.809 225.562 L 320.225 225.562 320.225 239.045 M344.101 239.035 L 344.101 252.528 346.064 252.528 L 348.027 252.528 348.101 241.746 L 348.174 230.963 354.073 241.738 L 359.972 252.512 362.570 252.520 L 365.169 252.528 365.169 239.045 L 365.169 225.562 363.065 225.562 L 360.962 225.562 360.888 235.938 L 360.815 246.315 355.173 236.009 L 349.532 225.702 346.816 225.622 L 344.101 225.541 344.101 239.035 M207.820 229.612 C 214.130 232.809,214.257 245.086,208.013 248.298 C 201.601 251.597,195.646 247.141,195.646 239.045 C 195.646 230.933,201.491 226.405,207.820 229.612 M42.993 229.213 C 46.106 230.078,46.764 234.465,44.026 236.101 C 43.321 236.523,42.444 236.668,40.098 236.752 L 37.079 236.860 37.079 232.896 L 37.079 228.933 39.537 228.934 C 40.888 228.935,42.444 229.061,42.993 229.213 M70.204 235.885 C 71.485 239.091,72.596 241.871,72.673 242.065 C 72.782 242.338,71.677 242.416,67.697 242.416 C 63.716 242.416,62.611 242.338,62.720 242.065 C 66.530 232.516,67.550 230.056,67.697 230.056 C 67.795 230.056,68.923 232.679,70.204 235.885 M43.039 240.743 C 45.343 241.382,46.611 243.518,46.082 245.865 C 45.596 248.018,44.053 248.817,39.891 249.071 L 37.079 249.242 37.079 244.846 L 37.079 240.449 39.537 240.451 C 40.888 240.452,42.464 240.583,43.039 240.743 M166.149 242.975 L 168.663 245.501 167.281 246.905 C 162.747 251.507,157.494 246.756,161.849 241.992 C 163.593 240.084,163.176 239.988,166.149 242.975 " stroke="none" fill="#000000" fill-rule="evenodd"></path></g></svg>
*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.
Reference in a new issue View git blame Copy permalink