Q-SYS External Control Introduction

"Q-SYS External Control" is the name for the original "Named Control"-based external control protocol that has been available since version 1.0 of Q-SYS Designer and firmware. There are absolutely no plans to remove this functionality, especially since there are countless installations successfully using this mechanism to control Q-SYS externally. If you have developed code on a third-party control system for using this protocol to control Q-SYS, you will not be required to rewrite any code to use the newer Q-SYS Remote Control (QRC) method, unless you want to do so.

The remainder of this topic covers the original External Control Protocol only.

Requirements

If you are writing your own control software to work with Q-SYS, it is highly recommended that you have a good working knowledge of either TCP/IP socket programming or using a Microsoft .NET framework library assembly. Correctly, and robustly, forming connections across a network and handling the possible error cases is not a trivial task.

Connections

When using the Q-SYS External Control Protocol, the connection is made using a TCP/IP connection on port 1702. You can also connect to a Core using the Q-SYS Communications Library.

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.

Connecting to a Core

Q-SYS operates on a client-server basis for communication with external control systems. The Q-SYS Core is the server, the external control system is the client. A Core must have a design loaded and in Run mode for an external system to connect to it.

Connecting to Q-SYS Designer in Emulate Mode

In order to connect to a design in Emulate mode, the design must be open in Q-SYS Designer, and be in Emulate mode.

Redundant Cores

During a Core failover, where the active Core stops accepting control and the standby Core takes over, the controlling application needs to recognize the failover situation by polling the Cores in the background using Status Get. When a Core goes down, the controlling application naturally re-syncs it's state with that of the newly active Core when it connects to it. This happens in the following manner: the controlling application, after connecting to a Core, creates a change group of all controls of interest after which the first change group poll will return the values of all of the controls, thus syncing the controller to Q-SYS. Note that this "re-sync" will occur whether the controlling application is connecting to a backup Core that has become active or reconnecting to the same Core due to a network failure.

Troubleshooting

For use in debugging your code, you can access the Core on port 1703, and all of the issued commands and responses are noted in the system log.

Change Groups

Q-SYS provides monitoring capability through the use of Change Groups. A Change Group is a grouping of controls, created by your code, that is polled at a schedule interval. When the Change Group is polled, it returns the state of any controls that have changed since the last polling.

When an external control system is interested in the state of a large number of controls, it is very inefficient to ask for the state of each control individually. Q-SYS provides Change Groups to reduce network bandwidth use and improve efficiency. You can create and poll Change Groups in your code using the following procedure:

Note: In the following procedure, the Q-SYS External Control Protocol call is given first, followed by the Q-SYS Communications Library method.

  1. Create a Change Group using the Change Group Create (cgc) call or the CreateChangeGroup method.
  2. Add controls and/or indicators to the Change Group using the Change Group Add (cga) call or the AddControlToChangeGroup method.
  3. Poll the Change Group using the Change Group Poll (cgp) call or the PollChangeGroup method.
  4. In response to the polling, the Core responds (cv or cvv, or ControlResponse or ControlVectorResponse) with the state of every control in the Change Group that has changed since the last poll, if any, followed by the Change Group Poll Ack (cgpa or ChangeGroupAck) response. If the Change Group is being polled for the first time, the Core responds with all the controls in the Change Group and their states. If any metadata aspect attached to a control in the Change Group changes, the Core responds with (cmv or cmvv, or ControlMetaDataResponse or ControlMetaDataVectorResponse) in response to the Change Group Poll.

Notes:

Procedure

  1. In Q-SYS Designer, select and name the controls you want to make available to external control.
    1. Each control is selected individually.
    2. Each control has a unique identifying name.
  2. Run the design on a Core
    or
    Emulate the design.
  3. Test external control.
    1. Use the external control system to access the controls over a TCP/IP connection or using the Communications Library.
    2. Optionally, for TCP/IP use Telnet to test external Control. Refer to Test External Controls over Telnet for details.
      1. If running on a Core, connect to that Core using Telnet.
      2. If emulating, connect to the design using Telnet.
      3. Enter commands at the Telnet command prompt to verify proper operation. Refer to the Q-SYS External Control Protocol for the commands.
  4. The third-party system is now ready to use for controlling Q-SYS.

Controlling Redundant Cores

Controlling a system that has redundant Cores is relatively straightforward: