Optimus WINCONTROL SER. User manual

Brand: Optimus

Model: WINCONTROL SER.

Type: User manual

JBL Professional

8500 Balboa Boulevard

Northridge, CA 91329

U.S.A.

Phone: (818) 894 8850

Web: www.jblpro.com

Technical development by:

Duran Audio BV

Koxkampseweg 10

5301 KK Zaltbommel

The Netherlands

Phone: 31(0)418-515583

Web: www.duran-audio.com

GvB February 2015

WinControl External Control

API

v2.11

Doc type

WinControl External Control API v2.11 2

Contents.

1. OBJECTIVE. ...............................................................................................................5

2. GENERAL. .................................................................................................................7

2.1 SERIAL PORT SETTINGS ............................................................................................................ 7

2.2 PROTOCOL OPTIONS............................................................................................................... 8

2.3 TRANSMIT DELIMITERS............................................................................................................ 8

2.4 MONITORING OF THE CONNECTION. .......................................................................................... 9

2.5 REDUNDANT HOST............................................................................................................... 10

2.6 REDUNDANT AMPLIFIERS....................................................................................................... 12

3. COMMANDS...........................................................................................................13

3.1 GENERAL. .......................................................................................................................... 13

3.1.1 Command structure. ................................................................................................ 13

3.1.2 Little endian coding. ................................................................................................ 14

3.1.3 PC response.............................................................................................................. 15

3.2 ADDRESS. .......................................................................................................................... 16

3.2.1 Address specifier format convention. ...................................................................... 16

3.2.2 Master and slave devices......................................................................................... 18

3.2.3 Address translation for redundant amplifier control............................................... 18

3.3 COMMAND ID AND VALUE.................................................................................................... 19

3.3.1 Failure & status request........................................................................................... 19

3.3.2 Select a section. ....................................................................................................... 48

3.3.3 Select a combination of sections. ............................................................................ 50

3.3.4 Un-mute a section. .................................................................................................. 51

3.3.5 Mute a section. ........................................................................................................ 53

3.3.6 Duck a section.......................................................................................................... 55

3.3.7 Duck a combination of sections............................................................................... 57

3.3.8 Pre-recorded message control................................................................................. 59

3.3.9 Autogain control. ..................................................................................................... 64

3.3.10 Mute/ducking control........................................................................................... 64

3.3.11 Output mute control............................................................................................. 66

3.3.12 Output ducking control......................................................................................... 67

3.3.13 Select preset. ........................................................................................................ 69

3.3.14 Input mute control................................................................................................ 70

3.3.15 Redundant host control........................................................................................ 71

3.4 TERMINATOR...................................................................................................................... 72

3.4.1 Terminator code. ..................................................................................................... 72

3.4.2 Terminator value. .................................................................................................... 76

WinControl External Control API v2.11 3

Figures list.

FIG 1 GENERAL EXTERNAL CONTROL PORT CONFIGURATION OPTIONS IN WINCONTROL............................ 7

FIG 2 EXTERNAL CONTROL WATCHDOG TIMER CONFIGURATION IN WINCONTROL. .................................. 9

FIG 3 AVAILABILITY SCORE CALCULATION CONFIGURATION IN WINCONTROL. ....................................... 31

FIG 4 SECTION EDITING EXAMPLE FROM WINCONTROL.................................................................... 49

FIG 5 DEVICE WITH OUTPUT DUCKING SUPPORT (L) AND WITHOUT OUTPUT DUCKING SUPPORT (R)........... 56

FIG 6 WAVE PLAYER RELATED EXTERNAL CONTROL OPTIONS............................................................. 59

WinControl External Control API v2.11 4

Tables list.

TABLE 1 DOCUMENT REVISIONS. ...................................................................................................... 6

TABLE 2 RS-232 PIN DESCRIPTION. .................................................................................................. 8

TABLE 3 GENERAL COMMAND STRUCTURE OF INCOMING PACKET - BINARY PROTOCOL............................... 13

TABLE 4 GENERAL COMMAND STRUCTURE OF INCOMING PACKET - ASCII HEX PROTOCOL. ......................... 13

TABLE 5 ADDRESS SPECIFIER FORMAT............................................................................................... 17

TABLE 6 COMMAND ID - FAILURE & STATUS REQUEST, OVERVIEW OF BIT MAPPING. ................................ 19

TABLE 7 COMMAND ID - FAILURE & STATUS REQUEST, VALID VALUE PARAMETERS.................................. 23

TABLE 8 COMBINED FAILURE REQUEST FORMAT - BINARY PROTOCOL..................................................... 24

TABLE 9 GENERAL FAILURE REQUEST RESPONSE MAPPING. ................................................................... 27

TABLE 10 DETAILED FAILURE REQUEST RESPONSE FORMAT - BINARY PROTOCOL. ....................................... 29

TABLE 11 CONTROLLER AVAILABILITY SCORE RESPONSE FORMAT - BINARY PROTOCOL................................. 31

TABLE 12 REDUNDANT AMPLIFIER SYSTEM 'TAKEN OVER' RESPONSE FORMAT - BINARY PROTOCOL............... 33

TABLE 13 REDUNDANT AMPLIFIER 'DISABLED' RESPONSE FORMAT - BINARY PROTOCOL.............................. 34

TABLE 14 COMBINED GENERAL STATUS REQUEST FORMAT - BINARY PROTOCOL......................................... 35

TABLE 15 GENERAL STATUS REQUEST RESPONSE MAPPING. ................................................................... 37

TABLE 16 DETAILED GENERAL STATUS REQUEST RESPONSE FORMAT - BINARY PROTOCOL. ........................... 38

TABLE 17 AUXILIARY STATUS REQUEST RESPONSE FORMAT - BINARY PROTOCOL. ....................................... 40

TABLE 18 AUXILIARY STATUS REQUEST RESPONSE MAPPING (STATUS WORD1). ......................................... 41

TABLE 19 AUXILIARY STATUS REQUEST RESPONSE MAPPING (STATUS WORD2). ......................................... 42

TABLE 20 DETAILED INPUT/OUTPUT MUTE STATUS REQUEST RESPONSE FORMAT - BINARY PROTOCOL. .......... 44

TABLE 21 DETAILED LOGIC I/O STATUS FOR CERBERUS REQUEST RESPONSE - BINARY PROTOCOL.................. 46

TABLE 22 COMMAND ID - SELECT A SECTION. .................................................................................... 48

TABLE 23 COMMAND ID - SELECT A COMBINATION OF SECTIONS. .......................................................... 50

TABLE 24 COMMAND ID - UN-MUTE A SECTION................................................................................. 51

TABLE 25 COMMAND ID - MUTE A SECTION...................................................................................... 53

TABLE 26 COMMAND ID - DUCK A SECTION....................................................................................... 55

TABLE 27 COMMAND ID - DUCK A COMBINATION OF SECTIONS............................................................. 57

TABLE 28 COMMAND ID - PLAY PRE-RECORDED MESSAGE.................................................................... 60

TABLE 29 COMMAND ID - STOP PRE-RECORDED MESSAGE. .................................................................. 62

TABLE 30 COMMAND ID - GET WAVE PLAYER STATUS.......................................................................... 63

TABLE 31 GET WAVE PLAYER STATUS RESPONSE FORMAT - BINARY PROTOCOL. ......................................... 63

TABLE 32 WAVE PLAYER STATUS WORD RESPONSE MAPPING. ................................................................ 63

TABLE 33 COMMAND ID - AUTOGAIN CONTROL. ................................................................................ 64

TABLE 34 COMMAND ID - MUTE/DUCKING CONTROL. ........................................................................ 64

TABLE 35 COMMAND ID - OUTPUT MUTE CONTROL............................................................................ 66

TABLE 36 COMMAND ID - OUTPUT DUCKING CONTROL. ...................................................................... 67

TABLE 37 COMMAND ID - SELECT PRESET. ........................................................................................ 69

TABLE 38 COMMAND ID - INPUT MUTE CONTROL............................................................................... 70

TABLE 39 COMMAND ID - REDUNDANT HOST CONTROL....................................................................... 71

TABLE 40 TERMINATOR CODE - BIT MAPPING..................................................................................... 73

TABLE 41 SIZE/STATUS HEADER - BIT MAPPING. ................................................................................. 75

TABLE 42 TERMINATOR VALUE. ....................................................................................................... 76

TABLE 43 CRC CALCULATION CODE. ................................................................................................. 76

Objective.

WinControl External Control API v2.11 5

1. Objective.

The objective of this document is to describe the Application Programmer’s Interface (API)

for remote control of the WinControl software through an auxiliary serial port (COM port or

virtual COM port). This document focuses on the interface format which is described in

section 3. Refer to the External Control related topics in the WinControl help file for detailed

information regarding the WinControl related configuration options.

This document is written for WinControl revision 2.72.0.0.

Terminology:

PC or Controller

PC running the WinControl software (must be at least the Service version of WinControl).

Front-end

External machine controlling the PC (e.g. a PLC).

Network or Net

RS-485 or Ethernet network with JBL Intellivox or JBL AXYS devices controlled by the PC. It

may consist of multiple subnets.

Subnet

Section of the complete Net. All units that are connected to a single COM port make up one

subnet connected to this port (in case of an RS-485 network). The number of subnets can be

configured in WinControl.

MaxInt

Maximum 32 bit integer value (2

32-1

- 1).

MaxWord

Maximum 32 bit word value (2

- 1).

Conventions:

- Hex values are indicated with a 0x prefix.

- Bit 0 indicates the LSB (Least Significant Bit).

Objective.

WinControl External Control API v2.11 6

Revision history:

Revision Date Description

1.91 22122009 Start of revision control.

2.00 03102011 Various additions for redundant amplifier control (section 2.6).

2.01 21112011 Minor changes.

2.02 03052012 CRC calculation procedure added.

2.03 06062012 Minor changes.

2.04 30052013 Duck a section (3.3.6) and Duck a combination of sections

(3.3.7) command descriptions added.

2.05 06062013 Output ducking control (3.3.12) command description added.

2.06 07052014 Changes for maximum number of subnets increased from 16 to

20 for WinControl v2.70 and up.

2.10 20102014 Re-branded and small changes.

2.11 18022015 Additions for terminator code.

Front-end ID specifier field and additional response

SizeandStatus header specifier added (see 3.4.1).

Table 1 Document revisions.

General.

WinControl External Control API v2.11 7

2. General.

2.1 Serial port settings

Default baud-rates from 1200 to 115k2 bits/s are supported, the connection can be set-up

for 5 to 8 data bits, 1 or 2 stop bits can be used and various parity related options are

available. Refer to Fig 1 for a WinControl configuration example. Note that at least the

Service version of WinControl is required for any External Control related editing.

Fig 1 General External Control port configuration options in WinControl.

Table 2 shows the RS-232 connection on the PC side (9p male d-Sub connector). For an un-

balanced serial connection only RX, TX and GND are required.

A balanced serial connection is advised for cable lengths exceeding a few meters. If a

balanced connection has to be made, the modem control signals (DTR, DSR, RTS and CTS)

can be used to power a RS-232 to RS-422/RS-485 converter on the PC side. In this case the

serial connection must support full-duplex mode.

General.

WinControl External Control API v2.11 8

RS-232

mnemonic

RS-232 pin #

Description (PC)

CD 1 Carrier Detect

RX 2 Data received by the PC

TX 3 Data transmitted by the

DTR 4 Data Terminal Ready

GND 5 Ground

DSR 6 Data Set Ready

RTS 7 Request to Send

CTS 8 Clear to Send

RI 9 Ring Indicator

Table 2 RS-232 pin description.

If communication over Ethernet is required, a 3

party Ethernet to Serial device (which

registers itself as a virtual COM port) can be used.

2.2 Protocol options.

Since WinControl v2.6.0.5 two protocols are supported, the required protocol can be set in

WinControl (see Protocol field in Fig 1).

Binary

This is the default protocol, unless specified otherwise all information is this document

refers to the Binary protocol. The Binary protocol is always used internally, any other

protocol (currently only ASCII hex) is supported by software protocol conversion

immediately after receive and directly before transmission.

ASCII hex

This protocol can be used if the Front-end is not capable of sending packets with arbitrary

binary content. In this case the hexadecimal value of each byte is represented by two ASCII

characters (each 4-bit nibble in the binary byte maps to one ASCII character).

Section 3.1.1 describes the details related to the supported protocols.

2.3 Transmit delimiters.

Since WinControl v2.12.0.0 arbitrary start and end delimiter strings can be added to the

response (i.e. the packet that is sent from controller PC to Front-end) if the Protocol is set to

ASCII hex. The start and end delimiter can be defined in WinControl (see Fig 1).

General.

WinControl External Control API v2.11 9

2.4 Monitoring of the connection.

The External Control connection to the Front-end can be monitored by a software watchdog

timer. Any of the available commands (which will be described in section 3) can serve as a

watchdog trigger command. An example of the configuration options provided by

WinControl is shown in Fig 2.

Fig 2 External Control watchdog timer configuration in WinControl.

General.

WinControl External Control API v2.11 10

2.5 Redundant host.

For redundancy purposes it might be required to have 2 PCs controlling and monitoring the

same network. The following has been implemented in order to achieve synchronized

network access for a fully redundant 'hot system' controller pair arrangement:

- Parameters related to redundant host configuration can be set-up from within

WinControl.

- The Front-end can request the 'health status' of a controller PC (Availability score,

section 3.3.1.4).

- The Front-end can switch a controller to Master or Standby (see section 3.3.15). The

current controller status (Master or Standby) can also be requested (see Table 15).

- An additional Ethernet link between the 2 controllers is required (TCP/IP), the related

parameters can be edited from within WinControl. The link is used to synchronize the

controller status and the network access. A link failure can also be monitored by the

Front-end (see Table 9).

- Commands that write to devices on the network can be discarded if the current

controller status is Standby. This can be decided by the Front-end on a 'command-by-

command' basis (see section 3.4.1).

- All commands that access devices on the network will be discarded if the current

controller status is Standby and there is no link to the remote Master controller.

- A Standby controller has less rights compared to a Master controller:

o If the Standby controller times out during claiming of the network ownership, it

will not access the devices.

o After device access the Standby controller tries to grant the ownership of the

network to the Master controller.

o If WinControl is in Scanning mode (it is polling the status of connected devices)

the scan speed is reduced for the Standby controller.

o The Standby controller is never allowed to access devices if there is no link to the

Master.

o The Standby controller will not re-configure any redundant amplifiers (see

section 2.6).

- A controller will always start-up as a Standby controller. Secondary tasks like the initial

Netscan, loading of the WinControl Scene etc. will be delayed until the link between the

controllers has been established. Which controller will become the preferred Master can

be configured from within WinControl (this request can of course only be honoured if

both controllers are Standby during establishing of the link). If the Front-end switches a

controller to Master (see section 3.3.15), the secondary tasks as referred to above will

be scheduled for execution.

- On time-out of the external control watchdog timer (which can be used to monitor the

integrity of the connection from the Front-end, see section 2.4) the local controller will

be switched to Standby if required (and the remote to Master) after all pending

commands have been processed. Depending on the configuration of the watchdog

timer, additional commands (e.g. Un-mute all output channels) might need to be

executed before the local controller is switched from Master to Standby. Note that the

controller status is not switched if it is already Standby. In the situation where the link

between the Front-end and a single controller is interrupted, the Front-end will normally

notice this before the watchdog timer times-out because the controller does not

General.

WinControl External Control API v2.11 11

respond on a command sent by the Front-end. If the Front-end notices that the link is

broken, it will normally set the other controller to Master. The controller with broken

link then automatically becomes Standby (if the Ethernet link is established). So usually

the controller will be Standby when it's watchdog timer times out, unless the Front-end

has no connection to both controllers.

Redundant host related support is implemented for WinControl >= v2.6.0.0.

General.

WinControl External Control API v2.11 12

2.6 Redundant amplifiers.

Some installations require the application of redundant/spare amplifiers that can

automatically replace/'take over' a 'faulty' amplifier. WinControl Service version allows the

configuration and control of redundant amplifiers.

Redundant amplifier control operates on 'systems', each system consists of:

- A redundant amplifier.

- Up to 8 normal amplifiers.

- A control device (Cerberus) that senses the failure relays of the amplifiers and

autonomously controls external relays to replace a 'faulty' amplifier with the redundant

amplifier.

- External (loudspeaker) relays with power supply and redundant amplifier dummy loads.

The following has been added to the External Control interface in order to support the

monitoring/control of redundant amplifier systems:

- Automatic re-mapping of addressed devices (address 'translation') to ensure that the

proper commands are sent to the redundant amplifier in case it has replaced a 'faulty'

amplifier, see section 3.2.3.

- Automatic preset re-mapping for the redundant amplifier. If a Select preset command is

received (see section 3.3.13) for a device that is currently 'taken over' by a redundant

device (amplifier), this preset command will be re-mapped in order to select the preset

of the redundant amplifier as configured in WinControl's Redundant amplifier

configuration GUI. This preset re-mapping is dependent on the redundant amplifier re-

configuration options (see WinControl help file). The associated redundant amplifier

system must be enabled in order for preset re-mapping to take place.

- Redundant amplifier related system combined failure flags (see Table 9), these indicate

for example if at least one of the available systems has it's redundant amplifier activated

or if there are errors related to the configuration (e.g. missing files that are required to

re-configure a redundant amplifier after 'take over').

- Failure request command values for 64 bit general failure word (in order to

accommodate the additional redundant amplifier system related failure flags), see Table

6 and Table 7.

- Detailed redundant amplifier related failure request commands, e.g. to indicate for

which system(s) the redundant amplifier has 'taken over' an amplifier, see section

3.3.1.5 and 3.3.1.6.

- Added status information to check if redundant amplifier control is enabled in

WinControl, see Table 15.

- Added status request commands to obtain the status of the digital inputs and outputs of

Cerberus devices (to check which amplifier in a system has been replaced/'taken over'

by the redundant amplifier. See section 3.3.1.14 and 3.3.1.15.

Note that the re-configuration process (e.g. uploading settings and/or selecting presets after

the redundant amplifier has 'taken over') is controlled from WinControl, as configured in the

Redundant amplifier configuration GUI.

Redundant amplifiers related support is implemented for WinControl >= v2.45.0.1.

Commands.

WinControl External Control API v2.11 13

3. Commands.

3.1 General.

3.1.1 Command structure.

All commands that the Front-end should send, consist of a packet with fixed length. This

length should be 16 bytes (Binary protocol) or 32 characters (ASCII hex protocol). The packet

should be formatted according to the structures represented in Table 3 and Table 4, see

also section 2.2.

Parameter <Address> <Command

ID>

<Value> <Terminator

code>

<Terminator

value>

Nof bytes 4 4 4 2 2

Table 3 General command structure of incoming packet - Binary protocol.

Parameter <Address> <Command

ID>

<Value> <Terminator

code>

<Terminator

value>

Nof chars 8 8 8 4 4

Table 4 General command structure of incoming packet - ASCII hex protocol.

Address

The Address is used to directly access specific subnets, units and/or groups on the Network,

refer to section 3.2.

Command ID

Each command has a unique Command ID, described in section 3.3.

Value

The Value parameter is used to further characterize the Command ID, described in section

3.3.

Terminator code and value

The Terminator code and Terminator value are used for packet integrity checking and

response formatting, they are described in section 3.4.

Commands.

WinControl External Control API v2.11 14

3.1.2 Little endian coding.

All multiple byte values are ‘Little Endian’ coded. This means that if, for example, the 4 bytes

of an identifier together represent a 32-bit integer or word value (e.g. Address, Command

ID), the Least Significant Byte occurs first in the structure.

Note that for the ASCII hex protocol (see section 2.2), ‘Little Endian’ coding is not applied to

the 4-bit nibble level; only the bytes of the binary words are ‘Little Endian’ coded. For

example a binary value of 250 (0xFA) will be represented as 2 ASCII characters FA in ASCII

hex.

The example below clarifies this, note that all implemented commands are described in the

following sections.

Example:

Address = 0x0000 0000 → Global addressing

Command ID = 0x0000 00C0 → Autogain control

Value = 0x0000 0001 → Enable autogain

Terminator code = 0x0001 → Checksum enabled

Terminator value = 0x00C2 → Checksum value

Binary protocol:

Resulting packet formatted according to Table 3 (16 bytes shown as hex values):

[0x00, 0x00, 0x00, 0x00, 0xC0, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x00, 0xC2,

0x00]

Note that each individual byte value is indicated with the 0x prefix. The total command

length is 16 bytes.

ASCII hex protocol:

Resulting packet formatted according to Table 4 (32 characters shown as ASCII string):

[00000000C0000000010000000100C200]

Note that the hexadecimal value of each individual byte value is represented by 2 characters

in the string. The total string length is 32 characters. The [ and ] characters are not a part of

the actual command string. The WinControl Command/Log window (bottom pane) contains

a tab labelled External Control, this tab shows information regarding the parsed External

Control commands.

Commands.

WinControl External Control API v2.11 15

3.1.3 PC response.

Following holds with respect to the PC response (i.e. packet that is sent to the Front-end):

- Any response is initiated by a packet that is sent by the Front-end (incoming packet).

- WinControl is able to respond to all incoming packets.

- This response can be enabled or disabled for each incoming packet individually by

setting the proper bit in the Terminator code (see section 3.4.1).

- A terminator can be added to the response for each packet individually by setting the

proper bit in the Terminator code (see section 3.4.1). The length of the terminator will

be 4 bytes (Binary protocol) or 8 characters (ASCII hex protocol). The Front-end may use

the Terminator value for integrity checking of the response.

- The Address and Command ID header can be pre-pended to the response for each

packet individually by setting the proper bit in the Terminator code (see section 3.4.1).

This will increase the response length by 8 bytes (Binary protocol) or 16 characters (ASCII

hex protocol).

- The response size can be pre-pended for each packet (Size/Status header). This is also

controlled by the Terminator code (see section 3.4.1 for further details).

- The response packet is ‘Little Endian’ coded.

- Unless stated otherwise, the incoming command Value is responded after the command

has been successfully handled.

- By default 0xFFFF FFFF (-1) is responded if the incoming command could not be properly

executed. For WinControl >= v1.98.0.22 this is also the case for an unknown command

ID, lower revisions did not respond for unknown commands.

- Since WinControl v2.12.0.0 the response packet for the ASCII hex protocol can be

wrapped between arbitrary start and end delimiter strings. The delimiter strings are fully

configurable from WinControl (see also section 2.3).

- For commands that access devices on the network the total response time is depending

on:

o The baud-rate of the External Control port.

o The number of devices and number of subnets on the network for which the

command is intended.

o The complexity of the command.

o The actual baud-rate set for each of the subnets (configurable in WinControl).

o The actual configuration of WinControl’s retry scheme (in case of net access

errors).

o The setting of 'Refresh device status if not scanning' (available in WinControl

External control options on the General tab), if WinControl is not in Scanning

mode.

- A simple Front-end emulator software is available on request in order to evaluate the

response time in a specific set-up.

Commands.

WinControl External Control API v2.11 16

3.2 Address.

3.2.1 Address specifier format convention.

The 32 bits Address specifier is reserved to directly access specific subnets, devices and/or

groups on the Network. Table 5 describes the Address specifier format. Note that some

commands (e.g. Play pre-recorded message command described in chapter 3.3.8) do not use

the contents from the Address specifier. Refer to each of the command descriptions in

section 3.3 for details.

Address Description

NO DIRECT ADDRESSING

0x0000 0000

Use 0 for commands that require no direct addressing or to access all

detected devices.

DIRECT ADDRESSING

Device address (single) / device low address (range)

0 Generic (all addresses).

For generic addressing byte 0 and byte 1 must be set to 0.

1..126 Single address:

If byte 1 <= byte 0, byte 0 fully represents the single address.

Range address:

If byte 1 > byte 0 the range defined by [byte 0 .. byte 1] is

addressed (if both bytes contain a valid address).

Byte 0 (LSB)

127..255 Reserved, this represents a non-valid address.

Device high address (range)

Range addressing is added for WinControl >= v1.98.0.18.

0 The addressing is defined by byte 0.

For generic addressing byte 0 and byte 1 must be set to 0.

1..126 Single address:

If byte 1 <= byte 0, byte 0 fully represents the single address.

Range address:

If byte 1 > byte 0 the range defined by [byte 0 .. byte 1] is

addressed (if both bytes contain a valid address).

Byte 1

127..255 Reserved, this represents a non-valid address.

Commands.

WinControl External Control API v2.11 17

Subnet related

0 Generic (all subnets).

1..20 Specific subnet. This subnet must be present in WinControl else

the address is not valid. For WinControl v2.70 and up the

maximum is 20.

Byte 2

21..255 Reserved.

Byte 3 (MSB)

Reserved for groups, must be 0.

Table 5 Address specifier format.

Following notes hold for commands that use direct addressing, commands that do not use

direct addressing should set the Address specifier to 0.

Notes:

- The maximum number of supported subnets depends on the WinControl version; for

version >= v2.70.0.0 a maximum of 20 subnets is supported, for lower revisions this

maximum is 16.

- Range addressing is added for WinControl >= v1.98.0.18. For lower WinControl revisions

the value of byte 1 should be set to 0.

- Address 'translation' may occur for redundant amplifier systems (see section 3.2.3).

- Some addressing examples are listed hereafter:

o Address 0x0000 0000 accesses all devices on all available subnets.

o Address 0x0001 0000 accesses all devices on the first available subnet (note that

the subnet numbering in WinControl is 0-based by convention, i.e. the first

subnet is referred to as SubNet 00 in WinControl).

o Address 0x0001 000A (specifically) accesses device with address 10 (= 0x0A) on

the first available subnet (the device address numbering in WinControl is 1-

based).

o Address 0x0001 090A also (specifically) accesses device with address 10 (= 0x0A)

on the first available subnet, the upper range address is smaller than the lower

range address so the lower range address prevails.

o Address 0x0001 0E0A (specifically) accesses devices with addresses 10..14 (=

0x0A .. 0x0E) on the first available subnet.

o Address 0x0001 0E00 is an example of an invalid address.

o Address 0x0000 000A (specifically) accesses all devices that have unit address 10

(= 0xA) on all available subnets.

o Address 0x0000 0E0A (specifically) accesses all devices with addresses 10..14 (=

0x0A .. 0x0E) on all available subnets.

o Address 0x0000 xxxx and 0x0001 xxxx are equivalent if the network contains only

one subnet.

Commands.

WinControl External Control API v2.11 18

3.2.2 Master and slave devices.

Most commands that are described in section 3.3 which use the Address specifier, perform

no action if only a slave unit is specifically addressed (for a device that contains master and

slave DSP, e.g. an IntelliDisc-DS90). An exception to this rule are the Failure & status request

related commands described in section 3.3.1. This means that it is for example possible to

request the status properties of a single slave device, however it is not possible to mute a

single slave device.

If a master unit is specifically addressed, the corresponding slave unit (if existing) is

automatically taken into account. An exception to this rule are the Failure & status request

related commands described in section 3.3.1.

3.2.3 Address translation for redundant amplifier control.

Address 'translation' may occur in case of activated Redundant amplifier control (see section

2.6). If an amplifier in a redundant system has been 'taken over' by it's associated redundant

amplifier, the address of the 'faulty' amplifier will be automatically translated into the

address of the redundant amplifier. The front-end does not need to care about changing

command addresses in case of a 'faulty' amplifier in a redundant system.

The redundant amplifier can still be accessed (e.g. by Single device addressing) however if it

is detected that both the redundant as well as the 'faulty' amplifier are accessed by the

received command packet (which may for example occur if the Address specifier indicates a

Range address as indicated in Table 5), the command intended for the redundant amplifier

is discarded and the command intended for the 'faulty' amplifier is translated to the

redundant amplifier. The only exceptions to this rule are the Failure & status request related

commands with Address specifier that accesses all devices on the network or on a specific

subnet (in this case the redundant amplifier is also accessed, however this is a 'request only'

command so it cannot result in conflicting situations). Note that redundant amplifier control

and re-configuration can be configured within WinControl (see section 2.6 and the

WinControl help file for details). Address translation will not occur if Redundant amplifier

control is disabled (or if the associated redundant amplifier system is disabled).

In this respect it is important to observe that device network addresses in WinControl are

not affected by the status of a redundant amplifier system, only the incoming External

Control commands are automatically re-mapped to the redundant amplifier if it has taken

over a 'faulty' amplifier.

Commands.

WinControl External Control API v2.11 19

3.3 Command ID and Value.

Each command is characterized by a unique 32 bits Command ID and a 32 bits Value,

described in the following sections.

3.3.1 Failure & status request.

The Front-end can use this command to obtain failure or status information about the net

and all connected units. The Value parameter is used to specify the request (see Table 6).

Front-end command:

Command ID

Value Description

Bit 0 and 1 define the response formatting as

described below:

Combined request.

Detailed request.

Response only contains addressed devices

that currently show a failure (or are

'missing').

Full detailed request.

Response contains all addressed devices

Value bit 0 and

1 (0 = LSB)

Reserved.

Value bit 2 Bit 2 defines the request type; status or

failure:

0  Failure related request.

1  Status related request.

Value bit 3 Bit 3 defines the length of the General

failure/status word (see for example Table 9):

0  32 bit (4 bytes) length.

1  64 bit (8 bytes) length.

This was added for WinControl v2.45.0.1.

Earlier revisions only support 32 bit.

Value bit 4..7 Reserved, must be 0.

Value bit 8..15 Bit 8..15 define the request index. This should

be used to further specify the failure or status

info that is required.

0x0000 0000

0..MaxInt

Value bit

16..31

Reserved, must be 0.

Table 6 Command ID - Failure & status request, overview of bit mapping.

Commands.

WinControl External Control API v2.11 20

All valid Value parameters that are currently implemented are listed in Table 7. If a Failure &

status request command with a Value that is not listed in Table 7 is received, the response

might not be predictable. Only use the documented Values listed in Table 7.

Value Description Details

General failure related, request index = 0

0x00000000 Combined failure request

(32 bit general failure

word).

All failures are combined in a 4 byte failure

word.

See section 3.3.1.1.

0x00000008 Combined failure request

(64 bit general failure

word).

All failures are combined in a 8 byte failure

word.

See section 3.3.1.1.

Supported for WinControl >= v2.45.0.1.

0x00000001 Detailed failure request

(32 bit general failure

word).

Failure information of individual devices is

responded according to Table 10. Only

addressed devices that have a failure (or are

'missing') are included in the response. See

section 3.3.1.2.

0x00000009 Detailed failure request

(64 bit general failure

word).

As above with 8 byte general failure word.

Supported for WinControl >= v2.45.0.1.

0x00000002 Full detailed failure

request

(32 bit general failure

word).

Failure information of individual devices is

responded according to Table 10. All addressed

devices are included in the response,

regardless if they exhibit a failure or not. See

section 3.3.1.3.

0x0000000A Full detailed failure

request

(64 bit general failure

word).

As above with 8 byte general failure word.

Supported for WinControl >= v2.45.0.1.

Page is loading ...

Optimus WINCONTROL SER. User manual

Optimus WINCONTROL SER. User manual

Optimus WINCONTROL SER. User manual

Related papers

Other documents