Q-SYS Remote WebSocket Control (QRWC)

Q-SYS Remote WebSocket Control (QRWC) is a tool designed to facilitate communication between third-party software and Q-SYS design controls. It is implemented as an NPM library, which allows developers to control and interact with Q-SYS Code Name and Script Access components via WebSocket connections.

Note: This is a BETA feature. Though it is functional, it is not feature complete and is subject to change. QSC assumes no responsibility for any issues that may arise from using this feature.

CAUTION: If you are writing your own control software to work with Q-SYS, you must have a solid understanding of JavaScript Web Apps, and using WebSockets . Forming connections across a network and handling potential error cases correctly and robustly is not a trivial task. Ignorance in this area will lead to failures and unreliable software.

  1. You must have access to the NPM Library.
  2. In Core Manager, enable the Websocket capability under the Network > Services page.
  3. Code Access must be set to 'External' or 'All' in Q-SYS Designer. See Code Name and Script Access for more information.

When using QRWC, the connection is made using a WebSocket connection on port 443.

Note: A Remote 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.

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 remote 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.

Using a WebSocket connection, you can connect using "localhost" (on your own PC), your computer's name, or IP Address on port 443.

Controlling a system that has redundant Cores is relatively straightforward:

  • A WebSocket connection should be maintained with both Cores.
  • State will be sent by both Cores automatically upon connection, or when the status changes. See EngineStatus for an example.
  • All commands should be directed to the currently "active" Core, as determined by the results of State parameter.
  • In addition, the IsRedundantand DesignCode values should be verified to ensure the two Cores are indeed a primary / backup pair running the same design.
  • Commands issued to the inactive Core are ignored, and commands issued while one Core fails and the other takes over can be missed, so if it is important that all commands issued take affect, the external control system should verify the state of the controls through polling.

For more information, visit Q-SYS Remote WebSocket Control (BETA).