Change Groups for ECP and QRC
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.
Change Group Requirements
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.
When a control is added to an existing Change Group, it is considered changed so the Core responds with the new control's state even if it has not changed.
Change Group Limits
Q-SYS Designer running on a PC, External Control Systems, and UCIs are all considered clients to the Core. The maximum number of simultaneous Change Groups is 512.
| Client |
Change Groups Used |
|---|---|
|
Q-SYS Designer Instance |
1
|
|
Active iOS UCI |
1
|
|
Active UCI Instance (TSC, UCI Viewer) |
1 each |
|
Core 110 or 3100 |
2 |
|
Redundant Core (redundant networking) |
2 |
|
Redundant Core (non-redundant networking) |
1 |
|
External Control System |
0-4 |
Note: If the maximum number of Change Groups (512) is reached and another is requested, scripts will output a "Too many change groups" debug message. This behavior also applies to QRC. Offending scripts will not function correctly.
Lua Script Change Group Behavior
Each Lua script component that assigns an EventHandler on a component control (e.g., controls accessed via Component.New) consumes one Change Group. The Change Group is created only when the first EventHandler is assigned. A script that only reads or writes control values without setting an EventHandler does not consume a Change Group. Multiple EventHandlers within the same script component still only use one Change Group slot.
Note: Assigning EventHandlers to Controls.Inputs[n] or Controls.Outputs[n], which are built-in controls, does not create a Change Group, as these controls use the observer pattern instead.
Redundant Core Considerations
-
If your system has redundant Cores, each Core must be accessed by its own host name or IP Address.
-
If you access a backup Core in the standby mode, and try to change a control, you will receive an error.
Connection Loss and Re-initialization
All Change Groups are automatically deleted from the Core when the TCP/IP connection goes down, there is a CommunicationError, or when the Core goes down. In either case, the Change Group(s) need to be re-initialized. This allows each external control connection to have its own set of Change Groups, but makes sure that a memory leak is not caused if the external control system repeatedly connects and disconnects.
