BSS DCP-555 User Manual
DCP-555
Digital Conferencing Processor with VoIP
Control API Guide
Table of Contents
Introduction ........................................................................................................................ 3
Basic Concepts ................................................................................................................... 3
Protocol Denition .............................................................................................................. 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
2
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 specic document that details the objects and parameters
of that specic 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 dened in a separate document that is specic to the device you are wanting to control.
Protocol Denition
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
dierence 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
3
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 specic 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 specied 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:astringrepresentationofthevalueasaoatingpointnumberwithnoroundingorunits (e.g.
“1100.0”).
• Normalized(Norm):astringrepresentationofthevalueasaoatingpointnumberbetween0.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
4
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”:”/Cong/Channel4PEQ/Band_1_Frequency”, “value”:”0.5”, “format”:”Norm”}
And the model responds with:
@set {“format”:”Norm”,”path”:”/Cong/Channel4PEQ/Band_1_Frequency”,”value”:”0.49993”}
As can be seen, the model has responded with a very slightly dierent 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 dierence is small but for other parameters it may be much more signicant.
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”:”/Cong/Channel4PEQ/Band_1_Type”, “value”:”0.2”, “format”:”Norm”} @set
{“format”:”Norm”,”path”:”/Cong/Channel4PEQ/Band_1_Type”,”value”:”0”}
set {“path”:”/Cong/Channel4PEQ/Band_1_Type”, “value”:”0.4”, “format”:”Norm”} @set
{“format”:”Norm”,”path”:”/Cong/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
5
Parameter Formats and Control Types
The dierent control types will be used by dierent 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
6
Loading...