Support Hub
  • Contact Us
  • Home
  • Sonia Series
  • Xilica API for third-party control of Solaro, Gio, Sonia, Neutrino & Uno devices
  • Products
    • Solaro Series
        • Licensing an unlicensed Xilica Solaro device
        • Using the Xilica Solaro FR1/QR1 at 96k sample rate
        • Factory resetting Solaro series devices
        • Updating XC-SUB Firmware
        • Understanding phantom power limitations with Xilica Solaro and Gio products
        • Sourcing the original Solaro QR1 external DC power supply
        • Understanding the Solaro QR1/QR1-UC fan and temperature readings
        • Summing or mixing channels pre-AEC
        • Performing a Solaro, Gio or Sonia firmware update
        • Compatibility of PoE power delivery devices for Xilica products
        • Monitoring and managing Solaro DSP device resource usage
        • Loading a pre-designed template to a Xilica Solaro device
        • Password Protecting a Solaro DSP
        • Dante routes disappear after loading the Xilica design to devices
        • Understanding Dante channels and Flows for Xilica hardware
        • Exporting system programming from Xilica hardware
        • Programming a Xilica system's power-on state
        • Enabling Dante audio IO for the Xilica FR1-D and Xilica QR1 DSPs
        • Device status indicators for Xilica Gio Bluetooth
        • Troubleshoot a boot-cycling/looping Solaro QR1/FR1
        • Can I add Dante to an existing FR1?
        • Xilica HearClear™ AEC parameters & specifications
        • Enabling and retrieving a diagnostic log file for Solaro devices
        • Downloading the diagnostic test result from a Xilica Solaro device
        • Preset trigger methods in a Solaro system
    • Sonia Series
        • Xilica Gio/Sonia support for static Dante IP addressing
        • Accessing EASE files for the Sonia C5 Speaker
        • Factory resetting the Xilica Sonia Amp
        • Daisy-chaining Sonia C5 Speakers
        • Sonia Amp Loudspeaker Compatibility
        • Sonia Amp Speaker Channel Indicators
        • Troubleshooting no audio through Sonia Speakers
        • Configuring Sonia Amp's Power Management Feature
        • Maximum cable length between Sonia Amp and Sonia C5 loudspeakers
        • Sonia Amp Power Output
        • Xilica API for third-party control of Solaro, Gio, Sonia, Neutrino & Uno devices
    • Gio Series
        • Xilica Gio/Sonia support for static Dante IP addressing
        • Troubleshooting a USB audio connection to the Xilica USB card (XC-SUB) or Gio USB network endpoint
        • Factory resetting Xilica Gio series devices
        • Controlling the Xilica Gio series products with a third-party control system
        • Programming third-party control of a Xilica system
        • Controlling Xilica Gio devices from XTouch or a third-party control system
        • Configuring Xilica Gio USB in the Designer software
        • Configuring Xilica Gio XLR's Dante networked audio
        • Configuring Xilica Gio USB's Dante networked audio
        • Configuring Gio Bluetooth's Dante networked audio
    • User Interfaces
        • Factory resetting the Xilica Lucia push-button rotary encoder
        • Handling TCP connection errors between a Xilica controller and a third-party device
        • Controlling multiple parameters simultaneously with Xilica XTouch, Lucia or XWP
        • Programming the Lucia wall panel controller
        • Managing XTouch panel resolution
        • Using Lucia’s Advanced Mode
        • Xilica XT80 touch panel network adapter capabilities and limitations
        • Creating radio-buttons on a Xilica XTouch control panel in Xilica Designer
        • Navigating between pages on a Xilica XTouch control panel
        • Create Custom GUI's in XTouch
    • Software Downloads
        • Download Xilica XTouch control app
        • Xilica Solaro (FR1/QR1) recovery firmware and instructions
        • Download the latest version of Xilica Designer
        • Accessing the configuration software for Neutrino & Uno devices
    • Customer Experience
        • Download the latest version of Xilica Designer
        • Mainboard BIOS firmware instructions and download for Xilica Solaro (FR1/QR1)
        • Download the Xilica USB driver for mainboard and recovery firmware updates
        • Download Xilica DLP/DCP/DSPX firmware
        • Download Xilica Uno template files
        • Download X Series (XP, XD, XA) firmware
        • Resetting the password for an XSeries device
        • Connecting to a Xilica system from a host computer on a different network segment
        • Download the XLink software for Xilica DLP/DCP/DSPX devices
        • Xilica end-of-life product listing
        • Xilica X Series hardware & software management
        • The Xilica Rio 1616N loses its Dante static IP address
        • Xilica Neutrino, Uno, Rio Dante device names revert to default
        • Release Notes for Designer 4.9
        • Assigning a static IP address to a Xilica Rio control port
    • Programming & Configuration
        • Download the latest version of Xilica Designer
        • Download the Xilica XConsole software for X Series devices
        • Download-Project-Backup-File option is missing
        • Handling a Dante system fatal error in Xilica Designer
        • Gio Bluetooth configurable settings in Xilica Designer
        • Creating and managing presets in the Xilica Designer software
        • Setting up mute sync between a Xilica Solaro processor and a UC app such as Teams or Zoom
        • Activating the Xilica HearClear™ AEC license for a Solaro FR1 or QR1
        • Validating or troubleshooting third-party control commands to Xilica's API
        • Ethernet networking best practices for Xilica products
        • Integrating Aver® PTZ camera control with Xilica Solaro solutions
        • Integrating Lumens® PTZ camera control with Xilica Solaro solutions
        • Integrating the Shure® MXA920™ microphone with Xilica Solaro solutions
        • Integrating the Sennheiser® TeamConnect Ceiling 2™ with Xilica Solaro solutions
        • Release notes for Designer 4.8
        • Handling a "signal loop" error in the Xilica Designer software
        • Handling Network View error messages in the Xilica Designer software
        • Download the Xilica API for third-party control of Solaro, Gio, Sonia, Neutrino & Uno devices
        • Using multiple Sennheiser TeamConnect Ceiling 2 micophones with the Solaro QR1/QR1-UC
        • Determining your host computer's IP address for Designer software communication
        • Scheduling presets in a Solaro system for a specific time/date
        • Managing, saving, and transferring Designer files (.pjxml & .sxml)
        • Loading a pre-designed template to a Xilica Solaro device
        • Exporting a blueprint of a system design from Xilica Designer software
        • Configuring Xilica Gio XLR in the Designer software
        • Configuring Xilica Dante networked audio
        • Troubleshooting Dante in the Xilica Designer Software
        • Xilica Designer software updates
        • Control Panel update is required for continued operation warning
        • Partitioning a Xilica Designer Project file
        • Loading a Project File design to device(s) and going live with a system
        • Handling a "Load Config" error in the Xilica Designer software
        • Creating User-defined devices in Xilica Designer's Project View
        • Preserving run-time parameter settings when exporting the Project File (.pjxml) from hardware
        • Exporting system programming from Xilica hardware
        • Exporting third-party control information from the Xilica Designer software
        • Using the CueCore2 Lua driver in Xilica Designer for lighting control
        • Password protecting a Solaro project file
        • Xilica ACC-POE-95W PoE injector power and data specifications
        • Lua Engine information and resources for third-party device driver creation in the Xilica Designer platform
        • Understanding carriage returns for control of third-party devices from Xilica Designer
        • Xilica Room Templates with Follow Me Auto Camera Preset Recall

    Xilica API for third-party control of Solaro, Gio, Sonia, Neutrino & Uno devices

    Back to Sonia Series

    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.

    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.

    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>

    Examples SET gain1 -3.2 SET polarity1 TRUE SET filter1 “Butterworth” SET $group1 -15.7 Set “gain1” to -3.2 dBSet “polarity1” to ON positionSet “filter1” to Butterworth FilterSet 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 $group1

    Get “EQslope” formatted value

    Get formatted value for all parameters in group1

    GETRAW <CONTROL OBJECT/GROUP>

    Example GETRAW EQslope GETRAW $group1 Get “EQslope” raw valueGet 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

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

    Example INCRAW fader3 500 INCRAW $group1 1000 Increase “fader3” by 0.5 dBIncrease all parameters in group1 by 1dB

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

    Example DEC fader3 0.5 DEC $group1 1 Decrease “fader3” by 0.5 dBDecrease all parameters in group1 by 1dB

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

    Example DECRAW fader3 500 DECRAW $group1 1000

    Decrease “fader3” by 0.5 dB

    Decrease all parameters in group1 by 1dB

    TOGGLE <CONTROL OBJECT/GROUP>

    Example TOGGLE mute1 TOGGLE $group2

    Toggle “mute1” state

    Toggle all parameters in group2

    PRESET <DATA - number/string>

    Example PRESET 4 PRESET “preset name” Recall preset #4Recall preset with name “preset name”

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

    Example SUBSCRIBE meter6 SUBSCRIBE meter6 “TCP” SUBSCRIBE meter6 “UDP” Subscribe to “meter6” via TCP UnicastSubscribe to “meter6” via TCP UnicastSubscribe 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.

    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

    xilica api control protocol

    Your feedback helps us deliver better content for you. Click here to review this article.

    Get the latest software
    Access legacy software

    Need further assistance? Simply reach out to us with your query.

    contact customer support
    • Privacy
    • Terms of Use
    • AdChoices & Cookies
    Copyright 2024 Xilica Corporation

    Knowledge Base Software powered by Helpjuice

    Back to Top
    Expand