SOLARO SERIES | THIRD-PARTY CONTROL API
SOLARO SERIES
Third-Party Control API
CONTENTS
1. Introduction 2
2. Overview 2
3. Syntax 2
4. Responses 3
5. Subscriptions 3
6. Control Groups 4
7. Password Protection 4
8. Verbose/Simple Mode 4
9. Control Objects Setup 5
10. Commands List 7
11. Data String 10
12. Error Codes 10
PAGE 1 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
1. Introduction
This third-party control protocol applies to the Solaro Series.
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 dependant
on the command. Refer to the Commands List section for a list of all commands, their detail usage and examples.
COMMAND 1 white space [CONTROL OBJECT/GROUP] 1 white space [DATA] <CR>
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.
PAGE 2 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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>
PAGE 3 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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>
PAGE 4 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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.
PAGE 5 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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.
PAGE 6 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
10. Commands List
SET <CONTROL OBJECT/GROUP> <DATA - number/string/Boolean>
Examples SET gain1 -3.2 Set “gain1” to -3.2 dB
SET polarity1 TRUE Set “polarity1” to ON position
SET filter1 “Butterworth” Set “filter1” to Butterworth Filter
SET $group1 -15.7 Set all parameters in group1 to -15.7dB
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>
Example GET EQslope Get “EQslope” formatted value
GET $group1 Get formatted value for all parameters in group1
GETRAW <CONTROL OBJECT/GROUP>
Example GETRAW EQslope Get “EQslope” raw value
GETRAW $group1 Get raw value for all parameters in group1
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
PAGE 7 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
INCRAW <CONTROL OBJECT/GROUP> <DATA - number>
Example INCRAW fader3 500 Increase “fader3” by 0.5 dB
INCRAW $group1 1000 Increase all parameters in group1 by 1dB
DEC <CONTROL OBJECT/GROUP> <DATA - number>
Example DEC fader3 0.5 Decrease “fader3” by 0.5 dB
DEC $group1 1 Decrease all parameters in group1 by 1dB
DECRAW <CONTROL OBJECT/GROUP> <DATA - number>
Example DECRAW fader3 500 Decrease “fader3” by 0.5 dB
DECRAW $group1 1000 Decrease all parameters in group1 by 1dB
TOGGLE <CONTROL OBJECT/GROUP>
Example TOGGLE mute1 Toggle “mute1” state
TOGGLE $group2 Toggle all parameters in group2
PRESET <DATA - number/string>
Example PRESET 4 Recall preset #4
PRESET “preset name” Recall preset with name “preset name”
SUBSCRIBE <CONTROL OBJECT/GROUP> <DATA - string>*
Example SUBSCRIBE meter6 Subscribe to “meter6” via TCP Unicast
SUBSCRIBE meter6 “TCP” Subscribe to “meter6” via TCP Unicast
SUBSCRIBE meter6 “UDP” Subscribe to “meter6” via UDP Broadcast
* <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.
PAGE 8 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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
PAGE 9 OF 10 COPYRIGHT (2022) XILICA CORPORATION
SOLARO SERIES | THIRD-PARTY CONTROL API
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
THIS DOCUMENT CONTAINS THE PROPRIETARY INTELLECTUAL PROPERTY OF XILICA. WHILE XILICA AIMS TO ENSURE ALL
DOCUMENTATION IS CORRECT PRIOR TO ISSUE, IT CAN ACCEPT NO LIABILITY FOR ERRORS, OMISSIONS OR OTHERWISE THAT
MAY IMPACT YOUR ABILITY TO USE THE PRODUCT(S) AND SERVICE(S). TRADEMARKS AND/OR REGISTERED TRADEMARKS
PAGE 10 OF 10 MENTIONED HEREIN ARE THE PROPERTY COPYRIGHT
OF THEIR RESPECTIVE (2022) XILICA
OWNERS. CORPORATION
ALL RIGHTS RESERVED.
