BSS Audio DCP-555 User manual

DCP-555
Digital Conferencing Processor with VoIP
Control API Guide

DCP-555 Control API Guide 2
Table of Contents
Introduction........................................................................................................................ 3
Basic Concepts ................................................................................................................... 3
Protocol Denition.............................................................................................................. 3
Syntax ............................................................................................................... 3
Case Sensitivity....................................................................................... 3
Path Syntax........................................................................................................ 4
Command / Reply ................................................................................... 4
Arguments............................................................................................... 4
Creating the Connection .................................................................................................... 4
Working with Parameters ................................................................................................... 4
Understanding Control Laws ............................................................................ 4
Default Format................................................................................................... 5
Parameter Formats and Control Types.............................................................................. 6
Commands.......................................................................................................................... 7
Set Value............................................................................................................ 7
Set one parameter with no format string .............................................. 7
Set one parameter with a format string ................................................ 7
Set multiple parameters with no format string ..................................... 8
Set multiple parameters with format strings......................................... 8
Set multiple parameters within same object (optimized)..................... 9
Error-handling......................................................................................... 9
Get Value .........................................................................................................10
Get one parameter................................................................................10
Get one parameter with a format string ..............................................10
Get multiple parameters.......................................................................10
Get multiple parameters with format strings ......................................11
Get multiple parameters for an object; get an attribute.....................11
Error-handling....................................................................................... 12
Subscriptions.................................................................................................................... 13
Subscribe to a Parameter Directly.................................................................. 13
Default ................................................................................................... 13
Norm...................................................................................................... 13
Number.................................................................................................. 13
Subscribe to All Parameters in an Object.......................................................14
Understanding the Parameter Value Format................................................................... 16
Metering............................................................................................................................17

DCP-555 Control API Guide 3
Introduction
This guide describes how to control and monitor the DCP-555 using third-party control. This guide
should be used in conjunction with a device specic document that details the objects and parameters
of that specic device.
Basic Concepts
• TheDCP-555APIisacommandandresponseprotocol.Eachcommandrequiresaresponse,andanother
command cannot be issued until the response has been received.
• TheDCP-555APIisdesignedforTCP/IPconnectionsandusestheregisteredport4197.
• TheDCP-555APIiscasesensitiveandallcommandsshouldbesentinlowercase.
• TheDCP-555APIdevicesaremodeledusingobjects.Objectscancontainotherobjectsandparameters.
• TheDCP-555APIobjectsandparametersareaddressedusingapath.Thepathstoobjectsand parameters
will be dened in a separate document that is specic to the device you are wanting to control.
Protocol Denition
The protocol is command/response from client to server and from server to client. A client can send
one command to the server, then it must wait for a response from the server before sending another
command. In the meantime, the server can send one command to the client, but must wait for a
response from the client before sending another command. In a way, this is peer-to-peer, but the
dierence is, the client is simply the endpoint that initiated the TCP connection.
Syntax
The general syntax of a DCP-555 API message is:
<command/reply> <JSON> [\r]\n
Spaces are used as delimiters between the items in a message, and the message is terminated by an
optional carriage return (\r) followed by a mandatory newline (\n).
Leading and trailing spaces on all arguments and commands are stripped and not preserved. Embedded
spaces are preserved, so keys and names and so on can have embedded spaces.
The JSON portion contains all the arguments for the command. The JSON portion must be a JSON
Object {}.
Case Sensitivity
Case-sensitive: commands, paths, names, replies, message-forwarding info, parameter names.
The DCP-555 API is case sensitive. All commands and keywords are lower case.
Case-insensitivity only applies to ascii, since UTF-8 may contain encodings that are not to-lower’able.

DCP-555 Control API Guide 4
Path Syntax
A crucial concept in the DCP-555 API is that of a path name. The path name is the name given to an
element. The path name includes the path and the name of the element. A forward slash “/” is used to
distinguish hierarchy in the path name. Paths can be surrounded by double quotes if required due to
white space in the path. An example of a path name is:
“/Audio/P1/Channel 1/Gain”
The forward slash at the start indicates that the path is absolute. There is no need to include the device
name in the path.
Command / Reply
Each command has a specic reply. The reply prepends @ to the original command to form the reply.
This prepending makes it easy for a parser to quickly distinguish a reply command.
command
@command
Arguments
Arguments are specied by JSON. It is possible for a command to have no arguments. If a command/
reply only ever has one argument, it may be a more simple JSON string (always quoted) or JSON
number (never quoted).
Creating the Connection
DCP-555 devices listen on port 4197 and can support multiple connections. To connect to a DCP-555
device, you must open a TCP socket to the IP address of the device. Once the connection is open, the
device will not close the connection until either the client (your program) closes the connection or
issues a goodbye command.
Working with Parameters
A DCP-555 device is made up of objects and parameters. All parameters have a parent object and some
objects may also have other objects as children. Each object and parameter is named and you can think
of the structure like s le system where objects are like folders and parameters are like les. You can
access a parameter or object using its full path name. An example of a path name could be:
“/Audio/Output Level/Gain”
In this example, Audio and Output Level are both objects, and Gain is the parameter.
Understanding Control Laws
All Parameters in the model have an underlying ‘control law’. This allows the parameter to convert between
various representations of the parameter value. The main representations (also called formats) are:
• Default:astringrepresentationofthevaluewithasensibleprecisionandunits(e.g“1.1kHz”).
• Number:astringrepresentationofthevalueasaoatingpointnumberwithnoroundingorunits (e.g.
“1100.0”).
• Normalized(Norm):astringrepresentationofthevalueasaoatingpointnumberbetween0.0and 1.0,
where 0.0 indicates the parameter is at its minimum value and 1.0 indicates the parameter is at its
maximum value. Note that the value is not always mapped linearly to the range of the parameter.
For example, frequency parameters typically use a logarithmic mapping.

DCP-555 Control API Guide 5
The mapping from normalized to value is part of the control law and the DCP-555 API is designed in
such a way that the GUI designer can mostly simply control the parameter using values from 0.0 to 1.0
without having to understand what is going on inside the model.
When controlling a parameter using a slider you would generally simply map the value of the slider to a
range from 0.0 to 1.0. Then you can control the parameter using the normalized format of the value. To
use the normalized value you must specify “format”:”Norm” in the set, get, or subscribe messages:
set {“path”:”/Cong/Channel4PEQ/Band_1_Frequency”, “value”:”0.5”, “format”:”Norm”}
And the model responds with:
@set {“format”:”Norm”,”path”:”/Cong/Channel4PEQ/Band_1_Frequency”,”value”:”0.49993”}
As can be seen, the model has responded with a very slightly dierent value to the one requested
(0.49993 instead of 0.5). Since the normalized value may not map precisely to an exact value in Hz it
is rounded by the model and then the actual normalized value returned. In the case of this frequency
parameter the dierence is small but for other parameters it may be much more signicant.
For example, the lter type parameter is in integer from 0 to 2 and represents the following values:
• 0: Bell
• 1: LowShelf
• 2: HighShelf
Although you would typically use a list box for this type of parameter it could be controlled by a slider
too. In this case setting a normalized value will return a rounded value:
set {“path”:”/Cong/Channel4PEQ/Band_1_Type”, “value”:”0.2”, “format”:”Norm”} @set
{“format”:”Norm”,”path”:”/Cong/Channel4PEQ/Band_1_Type”,”value”:”0”}
set {“path”:”/Cong/Channel4PEQ/Band_1_Type”, “value”:”0.4”, “format”:”Norm”} @set
{“format”:”Norm”,”path”:”/Cong/Channel4PEQ/Band_1_Type”,”value”:”0.5”}
This is because the parameter can only have 3 values and these correspond to the following normalized
values:
• 0.0: Bell
• 0.5: LowShelf
• 1.0: HighShelf
Default Format
The ‘Default’ format for a parameter varies depending on the type of the parameter. However, the
‘Default’ format is intended to be a ‘nice’ human readable string. For the frequency parameter we’ve
used above this means rounding to either Hz or kHz depending on the value and adding the correct
units after the number.
For other parameters this may mean returning a string from an enum. For example, the lter type
actually has internal values of 0, 1, and 2 but these are represented by strings “Bell”, “Low Shelf”
and High Shelf”. Therefore, the ‘Default’ format would be one of the 3 enum strings. Interestingly, the
‘Number’ format would return 0, 1, or 2, and the ‘Normalized’ format would be 0.0, 0.5, or 1.0.

DCP-555 Control API Guide 6
Parameter Formats and Control Types
The dierent control types will be used by dierent types of control in your application. Examples are:
• Slider: Generally uses normalized value from 0.0 to1.0.
• Text display or edit box: Uses the default format (text).
• List box: Uses the default format (text).
• Button: Usesnormalizedvalue0.0and1.0.

DCP-555 Control API Guide 7
Commands
Set Value
Sets one or more parameter values using paths to each element being set. The path points to a
parameter. Setting attributes from the client is not supported.
<value> is a JSON Value, so it can be true, false, null, JSON String, or JSON Number.
Set one parameter with no format string
set { “path” : “<parameter path>”, “value” : <value> }
@set { “path” : “<parameter path>”, “value” : <value> }
or
@set { “path” : “<parameter path>”, “error” : “<error message>” }
The value is echoed back in the set reply because it may have changed, rounded, or been bounded by
min/max.
Example:
set { “path” : “/channel 1/gain”, “value” : 0.5 }
@set { “path” : “/channel 1/gain”, “value” : 0.5 }
Set one parameter with a format string
The format specier is always a string.
set { “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” }
@set { “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” }
or
@set { “path” : “<parameter path>”, “error” : “<error message>” }
Example:
set { “path” : “/channel 1/gain”, “value” : 0.5, “format” : “n” }
@set { “path” : “/channel 1/gain”, “value” : 0.5, “format” : “n” }

DCP-555 Control API Guide 8
Set multiple parameters with no format string
In the case of multiple parameters, a JSON array is used. If an error happened with one of the
parameters, an error message is returned.
set [ { “path” : “<parameter path>”, “value” : <value> },
{ “path” : “<parameter path>”, “value” : <value> } ]
@set [ { “path” : “<parameter path>”, “value” : <value> },
{ “path” : “<parameter path>”, “value” : <value> } ]
or
@set [ { “path” : “<parameter path>”, “error” : “<message>” },
{ “path” : “<parameter path>”, “value” : <value> } ]
The “error” keyword tag is used to identify which parameters could not be set.
Example:
set [ { “path” : “/channel 1/gain”, “value” : 0.5 },
{ “path” : “/channel 1/mute”, “value” : 0 } ]
@set [ { “path” : “/channel 1/gain”, “value” : 0.5 },
{ “path” : “/channel 1/mute”, “value” : 0 } ]
Set multiple parameters with format strings
set [ { “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” },
{ “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” } ]
@set [ { “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” },
{ “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” } ]
or
@set [ { “path” : “<parameter path>”, “error” : “<message>” },
{ “path” : “<parameter path>”, “value” : <value>, “format” : “<format string>” } ]

DCP-555 Control API Guide 9
Set multiple parameters within same object (optimized)
Setting multiple parameters in the same object is an optimized version of ‘set multiple parameters’. It
does not support format strings and is set using the data type of the parameter.
In the case of multiple parameters, the <path> points to the parent object instead of all the way to the
parameter name. Then the parameter names appear inside the “value” object as keyword tags.
set { “path” : “<object path>”, “value” : { “<param1>” : <value>, “<param2>” : <value> } }
@set { “path” : “<object path>”, “value” : { “<param1>” : <value>, “<param2>” : <value> } }
or
@set { “path” : “<path>”, “value” : { “<param1>” : <value>, “<param2>” : { “error” : “<message>” } } }
The “error” keyword tag is used to identify which parameters could not be set.
Example:
set { “path” : “/channel 1”, “value” : { “gain” : 0.5, “mute” : 0 } }
@set { “path” : “/channel 1”, “value” : { “gain” : 0.5, “mute” : 0 } }
Error-handling
The Set message wants to return the values that the parameters were set to, in case they were bounded
by min/max or rounded o. In case of errors, the Set message wants to return an error message
associated with each parameter that had an error (could not be set).
Attempt to set a parameter but it did not exist:
set { “path” : “/channel 1/gain”, “value” : <value> }
@set { “path” : “/channel 1/gain”, “value” : { “error” : “Parameter not found” } }
Attempt to set multiple parameters on multiple objects using format strings but one of the parameters
did not exist.
set [ { “path” : “/channel 1/gain”, “value” : 0.5, “format” : “n” },
{ “path” : “/channel 2/mute”, “value” : false, “format” : “bool” } ]
@set [ { “path” : “/channel 1/gain”, “value” : 0.5, “format” : “n” },
{ “path” : “/channel 2/mute”, “error” : “Parameter not found” } ]
Errors can be returned for just the parameters that failed, and values for the parameters that worked.
The <error message> is a JSON String.

DCP-555 Control API Guide 10
Get Value
Get is exactly like Set, except the Get Command won’t have values, but the Get Reply will. Therefore, the
Get Reply will look exactly like the Set Reply.
Get one parameter
get { “path” : “<parameter path>” }
@get { “path” : “<parameter path>”, “value” : <value> }
or
@get { “path” : “<parameter path>”, “error” : “<error message>” }
Example:
get { “path” : “/channel 1/gain” }
@get { “path” : “/channel 1/gain”, “value” : 0.5 }
Get one parameter with a format string
get { “path” : “<path>”, “format” : “<format string>” }
@get { “path” : “<parameter path>”, “format” : “<format string>”, “value” : <value> }
or
@get { “path” : “<parameter path>”, “error” : “<error message>” }
Example:
get { “path” : “/channel 1/gain”, “format” : “n” }
@get { “path” : “/channel 1/gain”, “format” : “n”, “value” : 0.5 }
Get multiple parameters
In the case of multiple parameters, a JSON array is used. If an error happened with one of the
parameters, an error message is returned.
get [ { “path” : “<parameter path>” }, { “path” : “<parameter path>” } ]
@get [ { “path” : “<parameter path>”, “value” : <value> },
{ “path” : “<parameter path>”, “value” : <value> } ]
or