Introduction

Bang & Olufsen is recognised all over the world for its unmistakable range of high-quality audio, video and multimedia products.

The TwinCAT Bang & Olufsen Server is a software package for accessing the B&O Masterlink Gateway. It makes communication between a TwinCAT PLC and Bang & Olufsen multimedia networking possible. Communication takes place by TCP/IP.


Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Hardware requirements

The TwinCAT Bang & Olufsen Server can be used on any PC controller that is compatible to TwinCAT (except for the CX9000).

The following items are required in order to install the TwinCAT Bang & Olufsen Server on a TwinCAT-compatible hardware platform:

  • TwinCAT PLC Runtime
  • Microsoft .NET Framework / .NET Compact Framework. (at least version 2.0 or higher)
  • Ethernet interface

Please refer to the Beckhoff Information System as to which hardware with which image fulfils these requirements.


User requirements

The user of this ADS server / this library requires basic knowledge of the following:

  • Handling the TwinCAT PLC Control
  • Handling the TwinCAT System Manager
  • PC and network knowledge
  • Relevant safety regulations for building technical equipment


Functional description

Calling a Virtual Button Event from the PLC.

  • 1. Calling the Virtual Button Event function block in the PLC. The Virtual Button Event is sent to the TwinCAT Bang & Olufsen Server by ADS.
  • 2. Processing of the Virtual Button Event requests. The event is passed on to the Masterlink Gateway via Ethernet.
  • 3. The event is received and the macros linked with it are implemented.

Sending a Custom String to the TwinCAT Bang & Olufsen Server

  • 5. A macro is called in the Masterlink Gateway.
  • 4. The Custom Strings linked to the called macro are processed.
  • 3. The Custom Strings are sent by the Custom String device via Ethernet to the TwinCAT Bang & Olufsen Server.
  • 2. The TwinCAT Bang & Olufsen Server processes the Custom Strings and describes the PLC variables.


Installation under Windows CE (WEC)

Transfer of the installation to the Windows CE device

If the TwinCAT Bang & Olufsen Server was successfully installed, two subfolders will be found in the folder "..\TwinCAT\CE\Bang Olufsen Server".

  • \ARMV4I
    • This folder contains the CE installation:
      TcBangOlufsenServerCe.ARMV4I.CAB for ARMV4 CPUs (e.g. CX900x)
  • \I586
    • This folder contains the CE installation:
      TcBangOlufsenServerCe.I586.CAB for X86 CPUs (e.g. CX10xx)

Transfer the file "TcBangOlufsenServerCe.I586.CAB" to the Windows CE device. This can take place via

  • a shared folder (public folder)
  • FTP
  • ActiveSync
  • Compact Flash (CF) adaptors

Installation on the Windows CE device

The "TcBangOlufsenServerCe.I586.CAB" installation can be executed with a normal double click. Confirm the preselected (default) directory "\hard disk\System\TC-BangOlufsen-Server" with "OK".

Following the installation, the file "TcBangOlufsenServerCe.I586.CAB" will be deleted automatically. Restart the device after the installation has finished.


Installation under Windows Embedded Standard (WES)

Starting the installation

Start the installation and follow the instructions in the dialogs.

After the installation.

Once the installation is finished, two new directories will be found in the TwinCAT folder: "..\TwinCAT\CE\Bang Olufsen Server" and "..\TwinCAT\Bang Olufsen Server".
The installation files (.CAB) for the different Windows CE platforms ARM and X86 can be found in the directory "..\TwinCAT\CE\Bang Olufsen Server".


Configuration

Configuration takes place via the file TcBangOlufsenServer.cfg, in which the following elements are configured:

  • a Masterlink Gateway Client for calling virtual buttons.
  • an ADS device route for describing PLC variables via Custom Strings.
Note:

General:

  • The configuration file TcBangOlufsenServer.cfg is located in the installation directory.
  • If a parameter cannot be read in or if it lies outside the permissible size, then the PLC blocks from the TcBangOlufsen.Lib return a specific error.
  • If a firewall is in use, the port via which the Custom Strings are sent to the controller must be entered in the firewall configuration.
    The ports that are used by other programs, e.g. FTP, HTTP or Remote Desktop, must also be entered in the firewall configuration.

Name convention:

  • Must be unique
  • Upper/lower case is ignored
  • Letters and numbers
  • No special characters or umlauts, except “_” (underscore)
  • Minimum length 1 character
  • Maximum length 80 characters

Example: TcBangOlufsenServer.cfg file

<?xml version="1.0" encoding="utf-8" ?>
<TcBangOlufsenServerConfig>
  <MLGW Name="name" Ip="0.0.0.0" Port="9000" />
  <ADSDevice Name="name" AmsNetId="0.0.0.0.1.1" />
</TcBangOlufsenServerConfig>

Configuring a Masterlink Gateway Client

Masterlink Gateway Clients represent the connection between the TwinCAT Bang & Olufsen Server and the Bang & Olufsen Masterlink Gateway. They are needed in order to dispatch Virtual Button Events via Ethernet.

Add the following XML nodes to the <TcBangOlufsenServerConfig> section:

<MLGW Name="name" Ip="0.0.0.0" Port="9000" />

In this way you generate a new Masterlink Gateway Client in service. Repeat the procedure if you have several Bang & Olufsen Masterlink Gateways.

Parameter | Description
Name | Name of the Bang & Olufsen Masterlink Gateway. It is used in the PLC to assign requests to the MLGW Client.
Ip | Internet Protocol address (IP). Address via which the Masterlink Gateway can be reached in the network.
Port | The port is part of the address and describes the network entry point on the Masterlink Gateway. The default setting is 9000.

Configuring ADS device routes

The ADS device routes contain the parameters that are needed so that the TwinCAT Bang & Olufsen Server can assign received Custom Strings to a controller.

Add the following XML nodes to the <TcBangOlufsenServerConfig> section:

<ADSDevice Name="name" AmsPort="801" AmsNetId="0.0.0.0.1.1" />

In this way you generate a new ADS device route in service. Repeat the procedure if you have several controllers that are to be addressed via Custom Strings.

Parameter | Description
Name | Name of the controller. It is used in the Custom String configuration in order to assign Custom Strings to a controller.
AmsPort | PLC runtime system. The default setting is 801.
AmsNetId | AmsNetId of the controller.


Custom String

With a Custom String, a variable of the type BOOL can be described with the value TRUE in the PLC. In this way it is possible to release triggers or to activate scenes.

Syntax description

A Custom String is an ordered quantity of pre-defined parameters/value pairs. A Custom String begins with “<” (left angle bracket) and ends with “>” (right angle bracket). Each parameter is followed by “=” (equals signs) followed by the value. The individual parameters/value pairs are separated from each other by “|” (vertical line).

Parameter and values description

Parameter | Description
ADSDevice | ADS device route. Used in the TwinCAT Bang & Olufsen server to assign Custom Strings to a controller (see Configuration).
VarName | Variable name of the variable to be described.
IdxGroup | Index Group
IdxOffset | Index Offset
Note:

ADSDevice / VarName convention:

  • Letters and numbers
  • Upper/lower case is ignored
  • No special characters or umlauts, except “_” (underscore) and “.” (dot)
  • Minimum length 1 character
  • Maximum length 80 characters

IndexGroup / IndexOffset convention:

  • Can be specified in hexadecimal or decimal notation
  • In the case of hexadecimal notation, the prefix (0x) must be placed before the value
  • If the prefix is not set, the value is taken to be a decimal value

Examples

Describing a global variable by name

<ADSDevice=CX_123456|VarName=.LampGroupOff>
<ADSDevice=CX_123456|VarName=.LampGroupOn>

Describing a variable within the flag range by IndexGroup \ IndexOffset

<ADSDevice=CX_123456|IdxGroup=0x4020|IdxOffset=0x00>
<ADSDevice=CX_123456|IdxGroup=0x4020|IdxOffset=0x01>

Download Bang & Olufsen Masterlink-Gateway Custom String configuration example as a CSV file


Function blocks - overview

Name | Function
FB_BangOlufsenGetDeviceInfo | Reads the version and the name of the TwinCAT Bang & Olufsen Server.
FB_BangOlufsenVirtualButtonEvent | Triggers a Virtual Button Event in the Bang & Olufsen Masterlink Gateway.
FB_BangOlufsenGetClientConnectionState | Reads the status of the connection of a Masterlink Gateway Client to the Bang & Olufsen Masterlink Gateway.


FB_BangOlufsenGetDeviceInfo

Reads the version and the name of the TwinCAT Bang & Olufsen Server.

Examples

Download demo project

VAR_INPUT

sNetId                  : T_AmsNetId;
bExecute                : BOOL;
tTimeout                : TIME := t#5s;

sNetId: AMS Net ID of the target device on which the TwinCAT Bang & Olufsen Server is operated.

bExecute: The command is triggered by a rising edge at this input.

tTimeout: Indicates the time before the function is cancelled.

VAR_OUTPUT

bBusy                   : BOOL;
bError                  : BOOL;
udiErrorId              : UDINT;
udiDeviceVersion        : UDINT;
sDeviceName             : STRING;

bBusy: This output remains TRUE until the block has executed a command request, but at the longest for the time period applied at the tTimeout input. No new commands are accepted at the inputs as long as bBusy = TRUE.

bError: This output is switched to TRUE if an error occurs during the execution. The command-specific error code is contained in udiErrorId. If the function block is called again with TRUE on bExecute, then bError is reset to FALSE and udiErrorId to 0.

udiErrorId: Contains the command-specific error code of the most recently executed command. Is reset to 0 by the execution of a command at the inputs.

udiDeviceVersion: Version of the TwinCAT Bang & Olufsen Server.

sDeviceName: Name of the TwinCAT Bang & Olufsen Server.

Development environment | Target system | Required libraries
TwinCAT 2.11 R3/x64 | PC/CX | TcBangOlufsen library from V1.0.0


FB_BangOlufsenVirtualButtonEvent

Triggers a Virtual Button Event in the Bang & Olufsen Masterlink Gateway.

Examples

Download demo project

VAR_INPUT

sNetId                  : T_AmsNetId;
sMLGWClientName         : STRING;
byVirtualButtonId       : BYTE;
bExecute                : BOOL;
tTimeout                : TIME := t#5s;

sNetId: AMS Net ID of the target device on which the TwinCAT Bang & Olufsen Server is operated.

sMLGWClientName: Name of the Masterlink Gateway Client on which the Virtual Button Event is to be triggered.

byVirtualButtonId: Contains the ID of the Virtual Button whose event is to be triggered.

bExecute: The command is triggered by a rising edge at this input.

tTimeout: Indicates the time before the function is cancelled.

Note:

sMLGWClientName convention:

  • Upper/lower case is ignored
  • Letters and numbers
  • No special characters or umlauts, except “_” (underscore)
  • Minimum length 1 character
  • Maximum length 80 characters

byVirtualButtonId convention:

  • must lie between 1 and 255

VAR_OUTPUT

bBusy                   : BOOL;
bError                  : BOOL;
udiErrorId              : UDINT;

bBusy: This output remains TRUE until the block has executed a command request, but at the longest for the time period applied at the tTimeout input. No new commands are accepted at the inputs as long as bBusy = TRUE.

bError: This output is switched to TRUE if an error occurs during the execution. The command-specific error code is contained in udiErrorId. If the function block is called again with TRUE on bExecute, then bError is reset to FALSE and udiErrorId to 0.

udiErrorId: Contains the command-specific error code of the most recently executed command. Is reset to 0 by the execution of a command at the inputs.

Development environment | Target system | Required libraries
TwinCAT 2.11 R3/x64 | PC/CX | TcBangOlufsen library from V1.0.0


FB_BangOlufsenGetClientConnectionState

Reads the status of the Ethernet connection between the Masterlink Gateway and the TwinCAT Bang & Olufsen Server.

Examples

Download demo project

VAR_INPUT

sNetId                   : T_AmsNetId;
sMLGWClientName          : STRING(80);
bExecute                 : BOOL;
tTimeout                 : TIME := t#5s;

sNetId: AMS Net ID of the target device on which the TwinCAT Bang & Olufsen Server is operated.

sMLGWClientName: Name of the Masterlink Gateway Client whose connection status is to be read.

bExecute: The command is triggered by a rising edge at this input.

tTimeout: Indicates the time before the function is cancelled.

Note:

sMLGWClientName convention:

  • Upper/lower case is ignored
  • Letters and numbers
  • No special characters or umlauts, except “_” (underscore)
  • Minimum length 1 character
  • Maximum length 80 characters

VAR_OUTPUT

bBusy                       : BOOL;
bError                      : BOOL;
udiErrorId                  : UDINT;
eMLGWClientConnectionState  : E_MLGWClientConnectionState;

bBusy: This output remains TRUE until the block has executed a command request, but at the longest for the time period applied at the tTimeout input. No new commands are accepted at the inputs as long as bBusy = TRUE.

bError: This output is switched to TRUE if an error occurs during the execution. The command-specific error code is contained in udiErrorId. If the function block is called again with TRUE on bExecute, then bError is reset to FALSE and udiErrorId to 0.

udiErrorId: Contains the command-specific error code of the most recently executed command. Is reset to 0 by the execution of a command at the inputs.

eConnectionState: This output is set to eMLGWClientConnected as soon as the connection is established. If there is no connection the output is set to eMLGWClientDisconnected.

Development environment | Target system | Required libraries
TwinCAT 2.11 R3/x64 | PC/CX | TcBangOlufsen library from V1.0.0


Enums / Structures - Overview

Enum
E_MLGWClientConnectionState


E_MLGWClientConnectionState

TYPE E_MLGWClientConnectionState:
(
    eUnknown:= 0,
    eInitialized,
    eInitializing,
    eConnected,
    eConnecting,
    eDisconnected,
    eDisconnecting
);
END_TYPE


Error codes / error messages

Hex code | Dec code | Description
0x8501 | 34049 | Invalid parameter value(s) at a PLC function block.
0x8502 | 34050 | The configuration file TcBangOlufsenServer.cfg was not found.
0x8503 | 34051 | Internal processing error while loading the configuration file TcBangOlufsenServer.cfg.
0x8504 | 34052 | Error in the configuration file. The XML node “MLGW” was not found.
0x8505 | 34053 | Error in the configuration file. The XML attribute “Ip” was not found in the MLGW XML node, or it contains an incorrect value.
0x8506 | 34054 | Error in the configuration file. The XML attribute “Port” was not found in the MLGW XML node, or it contains an incorrect value.
0x8507 | 34055 | Error in the configuration file. The XML attribute “Name” was not found in the MLGW XML node, or it contains an incorrect value.
0x8508 | 34056 | Error in the configuration file. The XML node “ADSDevice ” was not found.
0x8509 | 34057 | Error in the configuration file. The XML attribute “Name” was not found in the ADSDevice XML node, or it contains an incorrect value.
0x850A | 34058 | Error in the configuration file. The XML attribute “Port” was not found in the ADSDevice XML node, or it contains an incorrect value.
0x850B | 34059 | Error in the configuration file. The XML attribute “AmsNetId” was not found in the ADSDevice XML node, or it contains an incorrect value.
0x850C | 34060 | Internal server error while processing a request. The specified MLGW Client does not exist.
0x850D | 34061 | Internal server error while processing a Get Client Connection Status request.
0x850E | 34062 | Internal server error while processing a Virtual Button Event request.


Programming Examples

Download TwinCAT PLC Demo Project

Download Bang & Olufsen Masterlink-Gateway Custom String Example Configuration as CSV file