Open topic with navigation

Q-SYS Communications Library

CAUTION: The Q-SYS Communications Library interface, or its functional details, may change from release to release. Please be sure to check the Release Notes before installing subsequent releases of Q-SYS Designer. QSC is not responsible for the compatibility of your code with the Q-SYS Communications Library.

Note: Please read the External Control Overview first.

Note: An External Control client must communicate with the Q-SYS Core at least once every 60 seconds, or the socket connection will be closed by the Core. This is a form of "keep-alive" to make sure that abandoned connections get reclaimed by the Core. Most client programs poll a Change Group at a much higher rate which serves as a keep-alive. If not, the client program can issue a "Status Get" command periodically, or a "Control Set Value" on an unused control if no return response is desired.

Connect to Q-SYS

As an alternative to connecting and controlling a Core directly via a TCP/IP connection, you can use the same communications library used by Q-SYS Designer. This library presents connection, status, control and monitoring of a Core at a higher level than direct TCP/IP socket communications, and thus is easier to use.

The Q-SYS Communications Library uses a library assembly in Microsoft .NET framework. The library, named QSysControl.dll, can be found in the Q-SYS Designer install directory. (typically "\program files\qscaudio\qsys\qsyscontrol.dll") The Q-SYS Communications Library supports multi-threading, creating one thread for each client the host application creates.

Requirements

• Windows-based PC running Microsoft XP-Pro, Vista, or Windows 7.
• .NET Framework 3.5 SP1

General

Vector Type Controls

A vector type control has multiple strings, values and positions at a time, for example, a meter bar. A meter displays peak and RMS values. The GetControl Method returns ControlResponse (for non-vector controls) and ControlVectorResponse for vector type controls. You cannot set the values of a vector type control.

Metadata Type Controls

Metadata means "data about data". In Q-SYS, some controls have metadata attached that describe aspects of the control. These aspects can include the range of the control, its color, whether it is disabled or invisible or its value is indeterminate, or a list of legal values for the control.

As an example, take the Crossover component. The Slope, Type and Bessel Normalization controls all have metadata that describe the choices available in the drop-down list. The Bessel Normalization control also has metadata to make it invisible when the filter type is not Bessel-Thomson. When a Link button is pressed, all of the controls on the high frequency side of the crossover point are disabled using metadata.

Numbers and Strings

• Unsigned integers are 32-bit numbers.
• Floats are IEEE single precision floating numbers (32-bit)
• Strings

AsciiClient

The AsciiClient class provides simple methods for connecting, monitoring and controlling a Q-SYS system over a network.

In order to connect and control a Q-SYS system, an AsciiClient needs to be created using the host name or IP Address and port number (1702) of the Q-SYS Core. If the system has a redundant Core, you must use its host name or IP Address.

Excluding the initial Constructor, all methods are asynchronous - they do not block waiting for a network response. Any responses or errors are registered through Events.

AsciiClient Constructor(String, Int32)

Purpose:    Initializes a new instance of the AsciiClient class and connects to the specified port on the specified host.

Syntax:     public AsciiClient(

string hostname,

int port

)

Parameter: hostname

Type: System.String

Definition: The DNS name or IP Address of the remote host to which you intend to connect.

port

Type: System.Int32

Definition: The port number of the remote host to which you intend to connect.

Exceptions: ArgumentNullException : hostname is a null reference

ArgumentOutOfRangeException : port is not between MinPort and MaxPort

SocketException : An error occurred when accessing the socket.

AsciiClient Events

AsciiClient Methods

AsciiClient.AddControlToChangeGroup (Uint32, String)

Purpose:    Add a control to a change group.

Syntax:     public void AddControlToChangeGroup (

unsigned int changeGroupID,

string controlID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

Response:   none

InvalidChangeGroup

InvalidControlId

AsciiClient.ClearChangeGroup (Uint32)

Purpose:    Remove all of the controls from a change group.

Syntax:     public void ClearChangeGroup (

unsigned int changeGroupID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

Response:   none

InvalidChangeGroup

AsciiClient.ControlTrigger (String)

Purpose:    To trigger a control.

Syntax:     public void ControlTrigger (

string controlID

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

Response:   none

InvalidControlId

AsciiClient.CreateChangeGroup (Uint32)

Purpose:    Creates the specified ChangeGroup. You can create up to four change groups, on a single external client, that can be polled at separate intervals. The InvalidChangeGroup response is returned if you attempt to create more than four. This command is "silently" ignored if you attempt to create a change group with a changeGroupID that is already in use.

Syntax:     public void CreateChangeGroup (

unsigned int changeGroupID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

Response:   none

InvalidChangeGroup

AsciiClient.DestroyChangeGroup (Uint32)

Purpose:    Destroy a change group.

Syntax:     public void DestroyChangeGroup (

unsigned int changeGroupID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

Response:   none

InvalidChangeGroup

AsciiClient.GetControl (String)

Purpose:    Get the value, position and string descriptions of a control's state.

Syntax:     public void GetControl (

string controlID

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

Response:   ControlResponse (for non-vector controls)

ControlVectorResponse (for vector controls)

InvalidControlId

AsciiClient.GetControlMetaData (String)

Purpose:    Returns any metadata attached to a control.

Syntax:     public void ControlTrigger (

string controlID

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

Response:   ControlMetaDataResponse

ControlMetaDataVectorResponse

InvalidControlId

AsciiClient.GetEngineStatus ()

Purpose:    Requests the status of the Core.

Syntax:     public void GetEngineStatus (

)

Parameter: none

Response:   EngineStatusResponse

AsciiClient.InvalidateChangeGroup (Uint32)

Purpose:    To mark all the controls in the Change Group as if they had changed. At the next Change Group Poll, the state of all the group's controls is returned.

Syntax:     public void InvalidateChangeGroup 9

unsigned int changeGroupID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. A client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

Response:   none

AsciiClient.Login (Uint32)

Purpose:    Initiates a login to a Q-SYS Core for an external control system. The User Name and PIN must be a valid user, with permission to access the Core using external control. If an attempt is made to access a Q-SYS Core, that requires a login for an external control system, without a user name and PIN, a LoginRequired response is sent.

Syntax:     public void login (

string name

unsigned int pin

)

Parameter: name

Type: System.String

Definition: Identifies an external control system to a Q-SYS design running on a Q-SYS Core. The name is set up in the Q-SYS Designer Administrator, on the User tab.

pin

Type: System.String

Definition: Verifies that the supplied name is a valid user in the Q-SYS design running on a Q-SYS Core. The PIN is set up in the Q-SYS Designer Administrator, on the User tab.

Response:   LoginSuccess

LoginFailed

LoginRequired

AsciiClient.PollChangeGroup (Uint32)

Purpose:    Checks the specified ChangeGroup for changes.

Syntax:     public void PollChangeGroup (

unsigned int changeGroupID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

Response:   0-n ControlResponse events

ChangeGroupAck

InvalidChangeGroup

AsciiClient.RemoveControlToChangeGroup (Uint32, String)

Purpose:    Remove a control from a change group.

Syntax:     public void RemoveControlToChangeGroup (

unsigned int changeGroupID,

string controlID

)

Parameter: changeGroupID

Type: System.Uint32

Definition: Identifies a change group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a change group on one socket and poll it on the other.

controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

Response:   none

InvalidChangeGroup

InvalidControlId

AsciiClient.ScheduleChangeGroup (String, Uint32)

Purpose:    Schedule a Change Group to be polled at the specified interval. pollPeriodMS is the interval in milliseconds. Minimum for pollPeriodMS is 30 ms, any amount less than this is changed to 30 ms. To turn off the scheduling of a group, enter 0 (zero) for pollPeriodMS. To change the schedule, issue this command with a new pollPeriodMS.

Syntax:     public void ScheduleChangeGroup (

string controlID

unsigned int pollPeriodMS

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

pollPeriodMS

Type: System.Uint32

Definition: The interval, in milliseconds, for a change group to be polled.

Response:   none

InvalidControlId

AsciiClient.SetControlPosition (String, Float)

Purpose:    Set a control's state from a position. This is converted to a value using the controls range and its mapping.

Syntax:     public void SetControlPosition (

string controlID,

float controlPosition

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

controlPosition

Type: Float

Definition: A floating point number between 0.0 and 1.0 inclusive. Indicates where the value lies within the range of the control. Subject to a mapping.

Response:   ControlResponse

InvalidControlId

AsciiClient.SetControlString (String, String)

Purpose:    Sets the specified control to the specified control string value.

Syntax:     public void SetControlString (

string controlID,

string controlString

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

controlString

Type: System.String

Definition: Contains the textual representation of a control's state such as "-2.3dB" or "3.45 kHz"

Response:   ControlResponse

InvalidControlId

AsciiClient.SetControlValue (String, Float)

Purpose:    Sets the specified control to the specified single precision value

Syntax:     public void SetControlValue (

string controlID,

float controlValue

)

Parameter: controlID

Type: System.String

Definition: Identifies a control; defined in Q-SYS Designer.

controlValue

Type: float

Definition: A floating point number representing the numerical value of a control. The range of this number depends on the particular control.

Response:   ControlResponse

InvalidControlId

AsciiClient.SnapshotLoad (String, Uint32, Float)

Purpose:    Loads a saved snapshot.

Syntax:     public void SnapshotLoad (

string SNAPSHOT_BANK,

unsigned int snapshotNumber,

float secondsToRamp

)

Parameter: SNAPSHOT_BANK

Type: System.String

Definition: Identifies a bank of snapshots. This is the name given to the bank when it was created in Q-SYS Designer.

snapshotNumber

Type: System.Uint32

Definition: Identifies a snapshot within a snapshot bank. The range is 1 to the number of snapshots in the bank, inclusive.

secondsToRamp

Type: float

Definition: A floating point number indicating the load ramp time in seconds.

Response:   none

AsciiClient.SnapshotSave (String, Uint32)

Purpose:    Saves a snapshot.

Syntax:     public void SnapshotSave (

string SNAPSHOT_BANK,

unsigned int snapshotNumber, 

)

Parameter: SNAPSHOT_BANK

Type: System.String

Definition: Identifies a bank of snapshots. This is the name given to the bank when it was created in Q-SYS Designer.

snapshotNumber

Type: System.Uint32

Definition: Identifies a snapshot within a snapshot bank. The range is 1 to the number of snapshots in the bank, inclusive.

Response:   none

QSC.QSys.ControlValue

QSC.QSys.ControlValueVector

QSC.QSys.EngineStatus

QSC.QSys.ControlMetaData