Xilica API for Third-Party Control

Xilica devices use an intuitive, human-readable network protocol that enables third-party control systems such as Crestron, AMX, and others to communicate directly with your hardware.

Compatible devices:

• Solaro processors (FR1, FR1-D, QR1, QR1-UC)

• Gio devices (USB, Bluetooth, XLR)

• Legacy Neutrino and Uno devices

Note: Third-party control of Gio devices is supported in Designer version 4.8 and later and does not require a DSP processor to be present in your system.

Download the full API document as a PDF: Xilica Solaro API Guide (PDF)

The complete API reference is also provided inline below.

For Ethernet connections:

• Send messages using TCP port #10007

• The server responds using the same TCP connection

• Send a keep-alive message every 60 seconds to maintain the connection

You can also use UDP port #10008 to listen to subscription messages. Choose whether parameters send changes via TCP Unicast or UDP Broadcast when issuing a subscription command. By default, parameters notify via TCP Unicast.

A separate TCP connection is required for status updates, and keep-alive messages must be sent continuously even when using UDP Broadcast. If the TCP connection drops, you will need to reconfigure all subscriptions and group settings.

The third-party controller string uses human-readable ASCII characters with this format:

COMMAND [CONTROL OBJECT/GROUP] [DATA]<CR>

• Fields are separated by a single white space

• A carriage return (<CR>) marks the end of the message

• CONTROL OBJECT: Up to 32 characters assigned in software (first character cannot be a dollar sign $)

• CONTROL GROUP: Up to 32 characters created with the CREATE command (always begins with $)

• For strings with spaces, encapsulate with double quotes

• COMMAND and CONTROL OBJECT/GROUP are case-sensitive

• DATA can be a number, string (in double quotes), or Boolean (TRUE or FALSE)

The device responds to all commands. If you do not receive a response, check your connection. All responses end with <CR>.

Subscribe to control objects to receive automatic notifications when values change:

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

Notifications are sent automatically via TCP Unicast or UDP Broadcast in this format:

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

Set the notification interval with:

INTERVAL <TIME in milliseconds> <CR>

The minimum interval value is 100 ms. In Neutrino Series processors, the interval applies to individual TCP connections. In Solaro Series processors, the interval applies globally to all connections.

Control multiple parameters at once using groups:

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

Ensure parameters in a group are the same type and support the same commands. Groups persist only during active connections. The $ sign is automatically added when the group is created.

For password-protected devices, unlock before sending commands:

LOGIN <PASSWORD> <CR>

Authentication persists only for the duration of the connection.

Before you can send commands to specific parameters, you must assign control object names in Xilica Designer:

1. In Project Design Mode, select the DSP module

2. Double-click to open the module control panel

3. Hold Ctrl and select the control object

4. Right-click and select "Create third party control object name"

5. Enter a unique control object name

A small red indicator appears in the top left corner of objects with third-party control names defined.

To view all defined control object names, select Project → Device third party control elements from the menu. You can export this list to Excel for reference.

Related article: Exporting Third-Party Control Information from Xilica Designer

Sets a control object or group to a specific value.

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

Sets a control object or group using raw integer values.

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

Retrieves the current formatted or raw value of a control object or group.

GET <CONTROL OBJECT/GROUP>
GETRAW <CONTROL OBJECT/GROUP>

Increases a control object or group value by the specified amount.

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

Decreases a control object or group value by the specified amount.

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

Toggles the state of a Boolean control object or group.

TOGGLE <CONTROL OBJECT/GROUP>

Recalls a preset by number or name.

PRESET <DATA - number/string>

Subscribes to or unsubscribes from control object value changes.

SUBSCRIBE <CONTROL OBJECT/GROUP> ["TCP"/"UDP"] <CR>
UNSUBSCRIBE <CONTROL OBJECT/GROUP> <CR>

Sends a no-operation message to maintain the TCP connection.

KEEPALIVE

Authenticates for control access on password-protected devices.

LOGIN <DATA - string>

Remotely reboots the device.

REBOOT

Retrieves formatted data values for all control objects at once.

REFRESH

Creates or removes a control group.

CREATE <CONTROL GROUP>
REMOVE <CONTROL GROUP>

Adds or removes a control object from a group.

JOIN <CONTROL GROUP> <DATA - string>
LEAVE <CONTROL GROUP> <DATA - string>

When using SET commands with string-type parameters, use these predefined values: