SOLARO SERIES | THIRD-PARTY CONTROL API

1. Introduction

This third-party control protocol applies to the Solaro, Gio & Sonia Series products.

2. Overview

For Ethernet connection, the user should send out messages using TCP port #10007. The server will Response to the message using the same TCP connection. A keep-alive message must be sent over this TCP connection every 60 seconds, otherwise, the server end will disconnect the TCP connection and all subscriptions associated with the connection will end.

Users also have the choice of using UDP port #10008 to listen to Subscription messages from the device. The user can select whether a particular parameter send out its change via TCP Unicast or UDP Broadcast when issuing a subscription command. If left unspecified, by default a parameter will notify via TCP Unicast. A separate TCP connection is mandatory for status update, and a keep-alive message must continuously be sent over this TCP connection even if the user choose to use UDP Broadcast for all their interested parameters. If at any instance the TCP connection is dropped, all subscriptions and groups settings in the device must be reconfigured again.

3. Syntax

The third-party controller string is composed with human readable ASCII characters. Each field in separated by one single white space, using more than one white space in between fields will result in command parsing error. A carriage-return (<CR>) is sent to mark the end of the message. Fields enclosed in square brackets are dependent on the command. Refer to the Commands List section for a list of all commands, their detail usage and examples.

The CONTROL OBJECT is a string of up to 32 characters assigned by the user in software for individual parameters. It can contain any readable ASCII characters except double quotes. However, the first character cannot be a dollar sign ($) because a preceding ‘$’ is used to distinguish between a CONTROL OBJECT with a CONTROL GROUP.

A CONTROL GROUP is a string of up to 32 characters created using the CREATE command for use as a group name. It can also contain any readable ASCII characters except double quotes. The first character of the CONTROL GROUP will always begin with a ‘$’ to denote it as a group name.

For CONTROL OBJECT/GROUP, if any white spaces are used as part of the string, then it must be encapsulated by double quotes. In addition, note that both COMMAND and CONTROL OBJECT/GROUP are case-sensitive.

DATA can be either:

› a number (positive, negative, floating point, integer represented in ASCII) › a string (must always be inside double quotes, case-sensitive) › a Boolean (TRUE or FALSE, case-sensitive)

Refer to the Commands List section for details on the data type accepted by each command.

4. Responses

The device end will response to a third-party control command regardless it is correct or not. If no response is received, it is likely an indication of a connection problem. All response messages from the device will end with a carriage-return (<CR>).

If an invalid command is sent, the last encountered Error Code will be returned as: ERROR=<ERROR CODE><CR>

For GET or GETRAW command, the response will be:

<CONTROL OBJECT>=<DATA><CR> For REFRESH command, the response will be:

<CONTROL OBJECT>=<DATA><CONTROL OBJECT>=<DATA> … <CR> For KEEPALIVE command, there is no response from device end.

For REBOOT command, the behavior in Neutrino system is different from Solaro system.

in Neutrino system, it will reply “OK<CR>”

in Solaro system, there is no response and device will be rebooted For all other commands, the device will return:

OK<CR>

5. Subscriptions

The external controller can subscribe to control objects to get a notification for any data changes on the subscribed objects.

To subscribe/unsubscribe to a control object, simply send the command:

SUBSCRIBE <CONTROL OBJECT> [“TCP”/”UDP”] <CR> UNSUBSCRIBE <CONTROL OBJECT> <CR>

The notification will then be automatically sent to the external control system via TCP Unicast or UDP Broadcast as specified in the command. The notification string received by the external controller will be:

#<CONTROL OBJECT>=<DATA><CR>

The string is similar to a GET command, with a # character added in front to distinguish between an explicit read or a notification.

The interval in which the device sent out notifications is global for all subscribed control objects, it can be configured by:

INTERVAL <TIME in milliseconds> <CR>

6. Control Groups

Control groups allow a user to control multiple parameters at once using a single command. The user must first create a group by:

CREATE <CONTROL GROUP> <CR>

After a group is created, individual control objects can join or leave the group by:

JOIN <CONTROL GROUP> <CONTROL OBJECT> <CR> LEAVE <CONTROL GROUP> <CONTROL OBJECT> <CR>

Cautious must be used when adding parameters to a group to ensure that the parameters are all of the same type and support the same commands.

When a group is longer used, resource can be free up by:

REMOVE <CONTROL GROUP> <CR>

Similar to subscription, Control Groups are persistent for the duration of the active connection only. When a connection is lost, the groups must be recreated again.

7. Password Protection

If a device is protected with a password, then the user must unlock the device first before sending any commands. The authentication persists only for the duration of the connection, so if a TCP disconnection occurs, the user have to unlock the device again.

To unlock the device, send the following command:

LOGIN <PASSWORD> <CR>

The password used in the command is the same password setup in software.

8. Verbose/Simple Mode

<Future Implementation - mainly used to configure the amount of details for Responses. This will help some external controller parsing the response more easily>

9. Control Objects Setup

To setup the control object strings, you need to use Xilica Designer to setup the control object name for the DSP parameters you want to control.

In Xilica Designer under Project Design Mode, you can select the DSP module which you want to create third-party control objects. Double click on the module to bring up the module control panel. In the panel, you can select the parameter you want to control by holding down the Ctrl key and select the control object. Once selected the control object will be highlighted.

Right mouse click on the highlighted object and select “Create third party control object name” in the popup menu. A dialog will be displayed. You can enter a unique (Unique within the device) control object name. This name will be used in your third-party control protocol.

Once a third-party control object name has been defined, on the top left corner a small red indicator will be displayed to indicate that this object can be controlled through third-party control. You can also notice that the top left corner of the module will also have indicator to indicate that some of its parameters has third-party control object name defined.

To query a list of all third-party control object name defined in your project, you can select “Project” -> “Device third party control elements” from the top menu bar to display a list of all control object names. You can also export this list to Excel as reference for your third-party control programming.

10. Commands List

SET <CONTROL OBJECT/GROUP> <DATA - number/string/Boolean>

SETRAW <CONTROL OBJECT/GROUP> <DATA - number >

Examples SETRAW gain1 -3200 Set “gain1” to -3.2 dB

SETRAW polarity1 1 Set “polarity1” to ON position

SETRAW filter1 1 Set “filter1” to Butterworth Filter

SETRAW $group1 1000 Set all parameters in group1 to +1.0dB

GET <CONTROL OBJECT/GROUP>

Get “EQslope” formatted value

Get formatted value for all parameters in group1

GETRAW <CONTROL OBJECT/GROUP>

INC <CONTROL OBJECT/GROUP> <DATA - number>

Example INC fader3 0.5 Increase “fader3” by 0.5 dB

INC $group1 1 Increase all parameters in group1 by 1dB

INCRAW <CONTROL OBJECT/GROUP> <DATA - number>

DEC <CONTROL OBJECT/GROUP> <DATA - number>

DECRAW <CONTROL OBJECT/GROUP> <DATA - number>

Decrease “fader3” by 0.5 dB

Decrease all parameters in group1 by 1dB

TOGGLE <CONTROL OBJECT/GROUP>

Toggle “mute1” state

Toggle all parameters in group2

PRESET <DATA - number/string>

SUBSCRIBE <CONTROL OBJECT/GROUP> <DATA - string>*

* <DATA - string> is optional, TCP Unicast will be used by default

UNSUBSCRIBE <CONTROL OBJECT/GROUP>

Example UNSUBSCRIBE meter6 Unsubscribe “meter6”

KEEPALIVE

Example KEEPALIVE No operation. Can be used by external controller to keep the TCP connection alive.

INTERVAL <DATA - number>

Example INTERVAL 100 Set subscription interval to minimum 100ms.

* Subscription data could be delayed longer than the specify interval

due to CPU usage, but it is guarantee to wait for the configured

interval time before attempting to sent out subscription data.

* The minimum value is 100 ms.

Note

In Neutrino Series processor, Interval command applies to individual TCP connection. That mean you can have different Interval for different connection. However, in Solaro Series processor, this Internal command applies globally. All connections interval will be changed when you set this Interval command.

LOGIN <DATA - string>

Example LOGIN “password” Login for external control with “password”

REBOOT

Example REBOOT Remotely reboot device

REFRESH

Example REFRESH Get formatted data value for all control objects

CREATE <CONTROL GROUP>

Example CREATE group1 Create a group with the name “group1”

This is the only exception where CONTROL GROUP does not require a ‘$’ sign in the syntax because he ‘$’ sign will be automatically added when the group is created.

REMOVE <CONTROL GROUP>

Example REMOVE $group1 Remove the group with name “group1”

JOIN <CONTROL GROUP> <DATA - string>

Example JOIN $group1 “gain1” “gain1” will join group1

LEAVE <CONTROL GROUP> <DATA - string>

Example LEAVE $group2 “mute2” “mute2” will leave group2

11. Data String

String Values

Filter Type Butterworth, LR, Bessel

Filter Slope 6db/Oct, 12db/Oct, 18db/Oct, 24db/Oct, 30db/Oct, 36db/Oct, 42db/Oct, 48db/Oct

AFS Sensitivity Very Low, Low, Medium, High, Very High

AFS Type Dynamic, Fixed

Control Ramp Type Linear, Log, Audio

12. Error Codes

Error Code Description

101 Invalid Command

102 Bad Arguments

103 Invalid Data Format

104 Control Object Not Found

105 Parameter Not Found

106 Data Value Not Found

107 Max Subscription Reached

108 Password Error

109 Not Yet Login

110 Command Not Supported for Control Object

111 Invalid Group Name

112 Max Control Group Reached

113 Max Control Object in Group Reached

114 Object Already in Group

115 Object Not in Group

116 Conflicting With Other Objects in Group

117 Invalid Preset #

118 Invalid Preset Name