Open topic with navigation

Q-SYS External Control Protocol

CAUTION: The Q-SYS External Control Protocol, 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 External Control Protocol.

This topic describes the protocol for controlling a Q-SYS Core in Run Mode using TCP/IP on port 1702.

Note: Please read the External Control Overview and Named Controls 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.

Basic Data Types and Encoding

Data Types

Messages in the protocol are ASCII, composed of the following basic types of data.

Data Type

Definition

Beginning of message

There is no beginning of message indicator in the protocol. White space is discarded after the previous null character and the first non-whitespace character is assumed to be the beginning the next message.

End of message (EOM)

All commands and responses end with the End of Message (EOM) character.

The EOM character is <LF> (0x0A).

The Core waits until the EOM is received before parsing and executing the command.

The Core will ignore a <CR> (0x0D) character if it precedes the EOM. (This allows the use of telnet for debugging because telnet generates <CR><LF> when you press the Enter key.)

The Core terminates all responses with <CR><LF>. (This makes the responses readable when using telnet for debugging, but it also means the client must ignore the <CR> character.)

If a command contains extra arguments before the EOM, a "bad_command" error will be returned.

cg text extra

-> bad_command "expected EOM"

If a string argument contains the <LF> character, it must be encoded as "\n" (the character back slash followed by the character n)

If a string argument contains the <CR> character, it must be encoded as "\r" (the character back slash followed by the character r)

cg text

-> cv "text" "" 0 0

css text "multi\r\nline" <-- in the GUI this will show up as 2 lines

-> cv "text" "multi\r\nline" 0 0

unsigned integer

Whole number between 0 and 4294967294 inclusive

floating point number

32 -bit floating point number

string

Sequence of ASCII characters.

Since arguments are separated by spaces, strings containing spaces must be enclosed in double quotation marks. If the string contains a quotation mark, the quotation mark must be escaped (preceded) with a back slash. If the string contains a back slash, the back slash must be escaped with another back slash. If the string contains the line feed character (0x0A) it must be encoded as back slash n. If the string contains the carriage return character (0x0D), it must be encoded as back slash r.

Arguments

The following arguments are used in commands. All arguments are separated by spaces. In order to reduce network traffic, it is suggested that you use short numbers and names for the arguments.

Argument Name

Data Type

Definition

Command string

string

This is the short string that begins each message. It indicates what action is to take place. None contain spaces and they do not need to be enclosed in quotation marks. Command strings are case sensitive.

Response string

string

This the short string that begins a response to a command message.

CONTROL_ID

string

Identifies a control as defined as a Named Control in Q-SYS Designer. See Named Controls.

CONTROL_VALUE

floating point number

Represents the numerical value of a control. The range of this number depends on the particular control.

CONTROL_POSITION

floating point number

Between 0.00 and 1.0 inclusive. Indicates where the value lies within the range of the control. Subject to a mapping.

CONTROL_STRING

string

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

COUNT

unsigned integer

Indicates the count of elements that follow.

CHANGE_GROUP_ID

unsigned integer

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. You can create up to four Change Groups, and poll the groups at separate rates.

DESIGN_ID

string

A unique ID given to a design every time it is compiled or emulated.

DESIGN_NAME

string

The name of the design currently running on the Core.

IS_ACTIVE

unsigned integer

Is a 1 if this is the active Core of a redundant pair or the design is not redundant, 0 if it is not active

IS_PRIMARY

unsigned integer

Is a 1 if this is the primary Core of a redundant pair, or the design is not redundant, 0 otherwise

NAME

string

The user name assigned to an external control system. The name is assigned in the Q-SYS Administrator, User tab.

PIN

string

Size is unlimited.

The personal identification number assigned to a User along with the NAME. The User must have privileges enabledfor external control. The PIN is assigned in the Q-SYS Administrator, User tab.

RAMP_TIME_SEC

floating point number

Used as an argument in Snapshot Load for the ramp time in seconds.

SNAPSHOT_BANK

string

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

SNAPSHOT_NUMBER

unsigned integer

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

POLL_PERIOD_MS

unsigned integer

Used as an argument in Change Group Schedule for the poll period in milliseconds.

Command Quick Reference

Command Title

Command String

Syntax

Response

Change Group Add

cga

cga CHANGE_GROUP_ID CONTROL_ID

none

bad_change_group_handle

bad_id

Change Group Clear

cgclr

cgclr CHANGE_GROUP_ID

none

bad_change_group_handle

Change Group Create

cgc

cgc CHANGE_GROUP_ID

none

bad_change_group_handle

Change Group Destroy

cgd

cgd CHANGE_GROUP_ID

none

bad_change_group_handle

Change Group Invalidate

cgi

cgi CHANGE_GROUP_ID

none

The next Change Group Poll, returns all the controls, including their: values, positions, and so on.

Change Group Poll

cgp

cgp CHANGE_GROUP_ID

cv

cmvv

cgpa

bad_change_group_handle

Change Group Poll No ACK

cgpna

cgpna CHANGE_GROUP_ID

cv

cmvv

bad_change_group_handle

Change Group Remove

cgr

cgr CHANGE_GROUP_ID CONTROL_ID

none

bad_change_group_handle

bad_id

After a control has been removed from a Change Group, it may still be returned from the next polling.

Change Group Schedule

cgs

cgs CHANGE_GROUP_ID POLL_PERIOD_MS

none

bad_change_group_handle

Based on the schedule, a cgp response will be sent.

Change Group Schedule No ACK

cgsna

cgsna CHANGE_GROUP_ID POLL_PERIOD_MS

none

bad_change_group_handle

Control Get

cg

cg CONTROL_ID

cv

cvv

bad_id

Control Get Metadata

cgm

cgm CONTROL_ID

cmv

cmvv

bad_id

zero or more

Control Set Position

csp

csp CONTROL_ID CONTROL_POSITION

cv

bad_id

Control Set Position Ramp

cspr

cspr CONTROL_ID CONTROL_POSITION RAMP_TIME

nothing or bad_id

Control Set Position Vector

cspv

cspv CONTROL_ID NUM_POSITIONS CONTROL_POS1 CONTROL_POS2 CONTROL_POS3…CONTROL_POSx

nothing or bad_id

Control Set Position Vector Ramp

cspvr

cspv CONTROL_ID NUM_POSITIONS CONTROL_POSITION1 CONTROL_POS2.. CONTROL_POSx RAMP_TIME

nothing or bad_id

Control Set String

css

css CONTROL_ID CONTROL_STRING

cv

bad_id

Control Set String Vector

cssv

cssv CONTROL_ID NUM_STRINGS CONTROL_STRING1 CONTROL_STRING2 CONTROL_STRING3…CONTROL_STRINGx

nothing or bad_id

Control Set Value

csv

csv CONTROL_ID CONTROL_VALUE

cv or bad_id

Control Set Value Ramp

csvr

csvr CONTROL_ID CONTROL_VALUE RAMP_TIME

nothing or bad_id

Control Set Value Vector

csvv

csvv CONTROL_ID NUM_VALUES CONTROL_VALUE1 CONTROL_VALUE2.. CONTROL_VALUEx

nothing or bad_id

Control Set Value Vector Ramp

csvvr

csvvr CONTROL_ID CONTROL_VALUE1 CONTROL_VALUE2 CONTROL_VALUE3…CONTROL_VALUExRAMP_TIME

nothing or bad_id

Control Trigger

ct

ct CONTROL_ID

nothing or bad_id

Login

login

login NAME PIN

login_succes

login_failed

An attempt to access a Core that requires an external control system to login, receives a login_required response.

Snapshot Load

ssl

ssl SNAPSHOT_BANK SNAPSHOT_NUMBER FLOATING_POINT_NUMBER

none

Snapshot Save

sss

sss SNAPSHOT_BANK SNAPSHOT_NUMBER

none

Status Get

sg

sg

sr

Response Quick Reference

Response Title

Response String

Syntax

Response To

Change Group Poll Ack

cgpa

cgpa

cgp

Control Metadata Value

cmv

cmv CONTROL_ID metadata_aspec CONTROL_STRING CONTROL_VALUE CONTROL_POSITION

cgm

Control Metadata Vector Value

cmvv

cmvv CONTROL_ID metadata_aspec COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ...

cgm

Control Read Only

core_read_only

cro <CONTROL_ID>

csp

css

csv

Control Value

cv

cv CONTROL_ID CONTROL_STRING CONTROL_VALUE CONTROL_POSITION

cgp

cg

csp

css

Control Vector Value

cvv

cvv CONTROL_ID COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ...

cg

Core Not Active

core_not_active

core_not_active

csp

css

csv

ssl

sss

ct

Invalid Change Group Handle

bad_change_group_handle

bad_change_group_handle CHANGE_GROUP_ID

cga

cgclr

cgc

cgd

cgp

cgr

cgs

Invalid Command

bad_command

bad_command STRING

Any command

Invalid Control Id

bad_id

bad_id CONTROL_ID

cga

cgr

cg

cgm

csp

css

ct

Login Failed

login_failed

login_failed

login

Login Required

login_required

login_required

Attempt to access a Core that requires a login.

Login Success

login_success

login_success

login

Status Response

sr

sr DESIGN_NAME DESIGN_ID IS_PRIMARY IS_ACTIVE

sg

Too Many Change Groups

too_many_change_groups

too_many_change_groups

cgc

Change Groups

Note: Please read the External Control Overview, Change Groups section for information about change groups.

Commands

Change Group Add

Purpose:    Add a control to a Change Group.

Syntax:     cga CHANGE_GROUP_ID CONTROL_ID

Example:    cga 2 slope

Response:   none

bad_change_group_handle

bad_id

Change Group Clear

Purpose:    Remove all of the controls from a Change Group.

Syntax:     cgclr CHANGE_GROUP_ID

Example:    cgclr 2

Response:   none

bad_change_group_handle

Change Group Create

Purpose:    Create a Change Group. You can create up to four Change Groups on a single external client. The CHANGE_GROUP_ID is a 32-bit unsigned integer, however, it is recommended that you use smaller numbers to reduce network traffic. The bad_change_group_handle 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 CHANGE_GROUP_ID that is already in use. For more information on Change Groups refer to Change Groups in the External Control Overview.

Syntax:     cgc CHANGE_GROUP_ID

Example:    cgc 2

Response:   none

bad_change_group_handle

Change Group Destroy

Purpose:    Destroy a Change Group.

Syntax:     cgd CHANGE_GROUP_ID

Example:    cgd 2

Response:   none

bad_change_group_handle

Change Group Invalidate

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:     cgi CHANGE_GROUP_ID

Example:    cgi 1

Response:   none

Change Group Poll

Purpose:    To poll a Change Group. This returns the state of all controls that have been added to the Change Group and/or that have changed since the last time the group was polled. The cgpa response is sent at the end of the response, or by itself if nothing in the Change Group has changed.

Syntax:     cgp CHANGE_GROUP_ID

Example:    cgp 2

Response:   cv

cmvv

cgpa

bad_change_group_handle

Example:    cv "slope" "12dB/Oct" 12 0.142857cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0 cgpa

cv "gain1" "0dB" 0 0.833333 cgpa

Change Group Poll No ACK

Purpose:    To poll a Change Group without an acknowledgement response. This returns the state of all controls that have been added to the Change Group and/or that have changed since the last time the group was polled. A cgpa response is not sent.

Syntax:     cgpna CHANGE_GROUP_ID

Example:    cgpna 2

Response:   cv

cmvv

bad_change_group_handle

Example:    cv "slope" "12dB/Oct" 12 0.142857cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0

cv "gain1" "0dB" 0 0.833333

Change Group Remove

Purpose:    Remove a control from a Change Group.

Syntax:     cgr CHANGE_GROUP_ID CONTROL_ID

Example:    cgr 2 slope

Response:   none

bad_change_group_handle

bad_id

After a control has been removed from a Change Group, it may still be returned from the next cgp.

Change Group Schedule

Purpose:    Schedule a Change Group to be automatically polled periodically. The POLL_PERIOD_MS argument is an unsigned integer for the poll period in milliseconds. Minimum for POLL_PERIOD_MS 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 POLL_PERIOD_MS. To change the schedule, issue this command with a new POLL_PERIOD_MS.

Syntax:     cgs CHANGE_GROUP_ID POLL_PERIOD_MS

Example:    cgs 2 100

Response:   none

bad_change_group_handle

Periodically, the response from cgp will be sent.

Change Group Schedule No ACK

Purpose:    Schedule a Change Group to be automatically polled periodically without an acknowledgement response. The POLL_PERIOD_MS argument is an unsigned integer for the poll period in milliseconds. Minimum for POLL_PERIOD_MS 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 POLL_PERIOD_MS. To change the schedule, issue this command with a new POLL_PERIOD_MS.

Syntax:     cgsna CHANGE_GROUP_ID POLL_PERIOD_MS

Example:    cgsna 2 100

Response:   none

bad_change_group_handle

Instead of periodically issuing a cgp, a cgpna is issued, so there is no cgpa sent.

Control Get

Purpose:    For non-vector controls, get the string description, value, and position of a control's state.
For vector controls, get the count of string elements, string array, count of value elements, value array, count of position elements, and position array.

Syntax:     cg CONTROL_ID

Example:    cg gain1

Response:   cv

cvv

bad_id

Example:     cv "gain1" "-100dB" -100 0

cvv "meter1" 4 "-100dB" "-100dB" "-100dB" "-100dB" 4 -100 -100 -100 -100 4 0 0 0 0

Vector Control

A Vector Control has multiple strings, values and positions at a time, for example, a meter bar. A meter displays RMS, Max RMS, Peak, and Max Peak values. The Control Get command (cg) returns Control Vector Value response (cvv) when the control is a vector type control. You cannot set the values of a Vector Control.

Example:    cvv "meter1" 4 "-100dB" "-100dB" "-100dB" "-100dB" 4 -100 -100 -100 -100 4 0 0 0 0

Note: For a Meter component, the strings, values, and positions are RMS, Max RMS, Peak, and Max Peak, in that order.

Control Get Metadata

Purpose:    Get all metadata attached to a control. This command does not give you the current state of a control, just the state of the metadata. Use the Control Get command to get the current state of the control. For more information about metadata see Metadata Controls.

Syntax:     cgm CONTROL_ID

Example:    cgm slope

Response:   cmv

cmvv

bad_id

Example:    cmv "load1" 6 "false" 0 0

cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0

Control Set Position

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

Syntax:     csp CONTROL_ID CONTROL_POSITION

Example:    csp gain1 1

Response:   cv

bad_id

Example:    cv "gain1" "20.0dB" 20 1

Control Set Position Ramp

Purpose:    Set a control's position from a number, with ramp time

Syntax:     cspr CONTROL_ID CONTROL_POSITION RAMP_TIME

Example:    cspr id4 0.7 5

Response:   nothing

bad_id

Note: cspr does not return a "cv" response of the final value. To check the value after a ramp has completed use the "cg" command.

Control Set Position Vector

Purpose:    Sets a control position vector.

Syntax:     cspv CONTROL_ID NUM_POSITIONS CONTROL_POS1 CONTROL_POS2 CONTROL_POS3…CONTROL_POSx

Example:    cspv id4 3 0.2 0.5 0

Response:   nothing

bad_id

Control Set Position Vector Ramp

Purpose:    Sets a control value vector with ramp time.

Syntax:     csvvr CONTROL_ID CONTROL_VALUE1 CONTROL_VALUE2 CONTROL_VALUE3…CONTROL_VALUExRAMP_TIME

Example:     csvvr id4 3 2.1 3.2 5.3 10

Control Set String

Purpose:    Set a control's state from a text string.

Syntax:     css CONTROL_ID CONTROL_STRING

Example:    css id4 5.0db

Response:   cv

bad_id

Example:    cv "id4" "5.00dB" 5 0.75

Control Set String Vector

Purpose:    Sets a control string vector.

Syntax:     cssv CONTROL_ID NUM_STRINGS CONTROL_STRING1 CONTROL_STRING2 CONTROL_STRING3…CONTROL_STRINGx

Example:    cssv textbox14"one" "two" "dog" "cat"

Response:   nothing

bad_id

Control Set Value

Purpose:    Set a control's state from a number.

Syntax:     csv CONTROL_ID CONTROL_VALUE

Example:    csv id4 6.2

Response:   cv

bad_id

Example:    cv "id4" "6.20dB" 6.2 0.77

Control Set Value Ramp

Purpose:    Set a control's value from a number, with ramp time

Syntax:     csvr CONTROL_ID CONTROL_VALUE RAMP_TIME

Example:    csvr id4 6.2 5

Response:   nothing

bad_id

Note: csvr does not return a cv response of the final value. To check the value after a ramp has completed the cg command should be used.

Control Set Value Vector

Purpose:    Sets a control value vector.

Syntax:     csvv CONTROL_ID NUM_VALUES CONTROL_VALUE1 CONTROL_VALUE2 CONTROL_VALUE3…CONTROL_VALUEx

Example:    csvv id4 4 7.0 2 3.2 5.3

Response:   nothing

bad_id

Control Set Value Vector Ramp

Purpose:    Sets a control value vector with ramp time.

Syntax:     csvvr CONTROL_ID CONTROL_VALUE1 CONTROL_VALUE2 CONTROL_VALUE3…CONTROL_VALUExRAMP_TIME

Example:    csvvr id4 3 2.1 3.2 5.3 10

Response:   nothing

bad_id

Control Trigger

Purpose:    To trigger a trigger-type control such as the "Play" button in the Audio Player.

Syntax:     ct CONTROL_ID

Example:    ct play

Response:   none

bad_id

Login 

Purpose:    Login to a Core that requires a login for external control. The NAME and PIN arguments must be for a valid User, with the appropriate permissions, existing in the Q-SYS System. If an attempt is made to login, without a NAME and PIN, to a system requiring login, a login_required response is sent. If a login_failed response is sent, the socket is automatically closed.

Syntax:     login NAME PIN

Example:    login Joe 1234

Response:   login_success

login_failed

Snapshot Load

Purpose:    Load a snapshot. The RAMP_TIME_LOAD argument is a floating point number for the load ramp time in seconds.

Syntax:     ssl SNAPSHOT_BANK SNAPSHOT_NUMBER FLOATING_POINT_NUMBER

Example:    ssl snapshot1 2 5

Response:   none

Snapshot Save

Purpose:    Save a snapshot.

Syntax:     sss SNAPSHOT_BANK SNAPSHOT_NUMBER

Example:    sss snapshot1 3

Response:   none

Status Get

Purpose:    Request the status of the Core.

Syntax:     sg

Example:    sg

Response:   sr

Example:    sr "MyDesign" "yq81K7SOhcDT" 1 1

Responses

Change Group Poll ACK

Purpose:    Acknowledges the Change Group was polled successfully. The cgpa response is sent at the end of a response, and by itself if nothing in the Change Group has changed.

Response to: cgp

Syntax:     cgpa

Example:    cv "pos1" ".586" 0.586406 0.586406cmv "pos1" 3 "" 0 0cmv "pos1" 6 "false" 0 0cmv "pos1" 4 "false" 0 0cmv "pos1" 5 "false" 0 0cv "gain1" "-100dB" -100 0cgpa

Control Metadata Value

Purpose:    Some controls have metadata attached to them. Metadata can be: a list of choices, if the control is invisible, disabled, and so on (see table below). Each metadata aspect has three facets: string, value and position. In the first example below, the aspect value 6 has a string of "false", a value of 0, and a position of 0. The second example is the same control in a disabled state, and now shows an aspect value 6 with a string of "true", value of 1, and position of 1.

The metadata responses do not give the actual state of the control, but the state of the attached metadata. For an explanation of metadata controls refer to Control Get Metadata.

Response to: cgm or cgp

Syntax:     cmv CONTROL_ID metadata_aspect CONTROL_STRING CONTROL_VALUE CONTROL_POSITION

The metadata aspect value is an unsigned integer with one of the following values:

Value

Name

Description

0

metadata_aspect_none

Should never appear.

1

metadata_aspect_range

Minimum and maximum value as in a 2-element floating-decimal vector control

2

metadata_aspect_choices

An array of strings

3

metadata_aspect_color

A string describing the color of the control. Used when a Custom control is in a not-normal state, for example, grayed out.

4

metadata_aspect_indeterminant

Boolean control, position > 0.5 indicates the control represents an unknown value, or represents multiple different values simultaneously.

5

metadata_aspect_invisible

Boolean control, position > 0.5 means the control is invisible and should not be displayed because it is irrelevant in the current context. For example, a bandwidth control on a high-shelf equalizer.

6

metadata_aspect_disabled

Boolean control, position > 0.5 means grayed / disabled.

7

metadata_aspect_legend

String control, specifies the legend drawn on buttons

Example:    cmv "pos1" 3 "" 0 0cmv "pos1" 6 "false" 0 0cmv "pos1" 4 "false" 0 0cmv "pos1" 5 "false" 0 0

cmv "pos1" 3 "" 0 0cmv "pos1" 6 "true" 1 1cmv "pos1" 4 "false" 0 0cmv "pos1" 5 " false" 0 0

Metadata 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, consider 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 through the use of metadata.

When you ask a control for its metadata with cgm (Control Get Metadata), you get a response for each aspect of metadata attached to that control, if any. The response is either cmv (Control Metadata Value) or cmvv (Control Metadata Value Vector). These responses look very similar to the responses you get when asking for a control's state with cg (Control Get), this is because the metadata is very much like a control itself in that is has a value, a position and a string. The only difference between the cv (Control Value) response and the cmv (Control Metadata Value) response is that cmv has the extra unsigned integer second argument that identifies which aspect of metadata is being described. Similarly the only difference between cvv (Control Value Vector) and cmvv (Control Metadata Value Vector) is the same additional argument.

Example:    Control Value responses from the cg command: cv "slope" "48dB/Oct" 48 1

Example:    Control Metadata Value Vector response from the cgm command: cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0

Control Metadata Value Vector Response Breakdown

Response

Description

slope

The CONTROL_ID

2

The metadata_aspect_choices

4

The COUNT of the "strings" following

"12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct"

0

The COUNT of the "values" following (in this case, none)

0

The COUNT of the "positions" following (in this case, none)

Example:    Control Value response from the cg command: cv "ssload" "" 0 0

Example:    Control Metadata Value response from the cgm command: cmv "ssload" 6 "false" 0 0

Control Metadata Value Response Breakdown

Response

Description

ssload

The CONTROL_ID

6

The metadata_aspect_disabled

false

The string describing the state of the control.

0

The "value" of the control

0

The "position" of the control

Control Metadata Vector Value

Purpose:    Returns metadata information from a vector control. Sent in response to cgm or cgp. See Control Get Metadata for details.

Response to: cgm or cgp

Syntax:     cmvv CONTROL_ID metadata_aspec COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ...

Example:    cmvv "Slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0

Control Read Only

Purpose:    Returned when a Control Set command (csp, css, csv) is performed on a read-only control.

Response to: csp, css, or csv

Syntax:     control_read_only CONTROL_ID

Control Value

Purpose:    Contains the control's ID and the three facets of the control's state: string, value and position.

Response to: css, csv, csp, cg, and cgp.

Syntax:     cv CONTROL_ID CONTROL_STRING CONTROL_VALUE CONTROL_POSITION

Example:    cv "gain1" "-100dB" -100 0

Control Vector Value

Purpose:    Contains the three facets of a vector control's state.

Response to: cg

Syntax:     cvv CONTROL_ID COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ...

Example:    cvv "meter1" 2 "-100dB" "-100dB" 2 -100 -100 2 0 0

Note: For a Meter component, the strings, values, and positions are current reading and Max reading. The readings change from RMS to Peak depending on the Peak/RMS switch on the meter.

Core Not Active

Purpose:    Returned when a Control Set command (csp, css, csv), Snapshot Load command (ssl, sss), or Control Trigger (ct) is performed on the standby Core of a redundant pair.

Response to: csp, css, csv, sslsss, ct

Syntax:     core_not_active

Invalid Change Group Handle

Purpose:    To indicate an invalid CHANGE_GROUP_ID.

Response to: Any command with a CHANGE_GROUP_ID argument that is not recognized.

Syntax:     bad_change_group_handle CHANGE_GROUP_ID

Invalid Command

Purpose:    To indicate an invalid command.

Response to: Any command that is not recognized.

Note: The "CG" command in the example below is not recognized because the commands are all lower case, and case sensitive.

Syntax:     bad_command "string"

Example:    bad_command "CG"

Invalid Control Id

Purpose:    Indicates that a CONTROL_ID argument is not recognized.

Response to: Any command with a CONTROL_ID argument that is not recognized.

Note: The "load3" command in the example below is not valid because it does not exist.

Syntax:     bad_id CONTROL_ID

Example:    bad_id "load3"

Status Response

Purpose:    Gives the status of the Core

Response to: sg

The arguments in order are:

Argument

Data Type

Description

DESIGN_NAME

string

The name with which the currently running design file was saved.

DESIGN_ID

string

A unique string generated every time a Design is deployed to a Core, or pair of Cores, or when the Design is emulated.

IS_PRIMARY

unsigned integer

Is a 1 if this is the primary Core of a redundant pair, or the design is not redundant, 0 otherwise

IS_ACTIVE

unsigned integer

Is a 1 if this is the active Core of a redundant pair or the design is not redundant, 0 if it is not active

Syntax:     sr DESIGN_NAME DESIGN_ID IS_PRIMARY IS_ACTIVE

Example:    sr "MyDesign" "NIEC2bxnVZ6a" 1 1

Too Many Change Groups

Purpose:    Returned when Change Group Create (cgc) is called and four change groups have already been created on the connection, or the total count of 256 change groups system wide would be exceeded with this command.

Response to: cgc

Syntax:     too_many_change_groups

Software and Firmware | Resources | QSC Self Help Portal | Q-SYS Help Feedback

Copyright © 2019 QSC, LLC. Click here for trademark and other legal notices. | Q-SYS 8.1.1