Lesson Description
Part C: Managing Change Groups
7m 52s
Poll multiple controls at once using change groups and schedule change groups to automatically report their status
Video Transcript
Part C: Managing Change Groups
7m 52s
0:08
Welcome back. We’ve gone over a variety of commands to change our controls via external devices,
0:14
and one of the most common commands is to poll a control’s status.
0:18
If you frequently need to poll a lot of controls,
0:20
you’ll be interested in using Change Groups and Change Group Scheduling.
0:25
One of the most frequent tech support questions we get is about how to use these features
0:29
and its one of the main reasons we decided to make this video.
0:32
Once we’ve taken you through this, creating Change Groups and Scheduling them will be perfectly clear.
0:37
To keep this example as simple as possible,
0:40
we’ll continue with our current design in Emulation Mode and issue commands using our Telnet session.
0:45
First we need to create a Change Group, which will let us efficiently poll the values of both
0:50
the Gain and Mute controls. We’ll use the “cgc 1” command, or “Change Group Create.”
0:57
We’re labeling this Change Group as the number 1
1:00
you could use any positive number of virtually any length,
1:03
but only four change groups can be created per remote session so the number 1 will work fine.
1:09
When you hit enter, the Change Group is created, even though you won’t receive a response.
1:13
Next let’s add some controls into this Change Group. We’ll use the “cga” command, or “Change Group Add”.
1:21
Type “cga 1 GainGain” and press Enter, and “cga 1 GainMute” and press Enter.
1:30
Once again, there is no response to these commands,
1:32
but you have successfully added controls to your Change Group.
1:36
Now we can poll the change group to find out what all of its controls are currently set to.
1:40
Type ‘cgp 1’ (or Change Group Poll 1) and press Enter.
1:47
You will get a list of the Control Value responses for all controls within the group.
1:51
This is what always happens the first time you issue a Change Group Poll on a change group.
1:56
You will also see ‘cgpa’, which means Change Group Poll Acknowledge.
2:02
Depending on how you’re using the data from this poll,
2:04
parsing these acknowledgements may be burdensome,
2:07
so there’s an alternative called “cgpna” or “Control Group Poll No Ack”.
2:14
This gives you the same Control Values, but doesn’t include the ‘cgpa’ acknowledgement.
2:19
But wait - not only did we not get that cgpa, we didn’t get any control values at all. Why?
2:26
Well this is a good time to explain how Change Groups work internally.
2:31
When you add controls to a Change Group, they are marked internally as ‘Dirty Controls’
2:36
meaning that they have not yet reported their current status.
2:39
Once a polling response occurs, every control is marked as a ‘Clean Control’
2:43
and won’t report its value again when the next poll is requested.
2:47
Only if someone changes the control, within Q-Sys or via an external control method,
2:52
will the control be considered ‘dirty’ again.
2:55
Let’s go back to Designer and move the knob to a different setting.
2:58
Now go back to the Telnet session and type ‘cgpna 1’ and Enter.
3:05
We see the Control Value for the Gain control but not the Mute button.
3:09
This is because the Gain became ‘dirty’ when we changed it, yet the Mute button is still ‘clean.’
3:14
And now that the Gain control value has been reported, it’s clean again too.
3:18
So, Change Groups make it easy to poll a few, dozens or hundreds of controls with a single command.
3:24
But, what if you need to have Q-Sys automatically send updates out without being sent poll commands?
3:31
That is the purpose of Change Group Schedules.
3:33
A Change Group Schedule is basically a timer that tells Q-Sys to automatically issue a
3:38
Change Group Poll command to itself and return to results to you.
3:42
This command is called ‘cgs’ or Change Group Schedule,
3:47
but this command also adds that Poll Acknowledge response each time the timer expires.
3:51
You don’t want to receive a “cgpa” report every 100 ms,
3:55
so we recommend using the Change Group Schedule No Ack command instead, or ‘cgsna.’
4:03
We’re going to poll Change Group 1, and we just need to tell Q-Sys how often we want to
4:07
receive an update on this group. We’ll enter 100 for 100ms.
4:12
This can be set as low a 30ms or as high as you want. A value of 5000 would represent 5 seconds.
4:19
As the programmer of the control system, only you will know what to make this value.
4:24
Your control system processor might be a little slow and you need updates to come less frequently.
4:29
Or your system could be perfectly capable of receiving anything Q-Sys can throw at it
4:34
and you choose the minimum of 30ms. It’s up to you and you can change the polling interval at any time,
4:40
even after the schedule is already running.
4:42
Alright, let’s press enter to launch this command. You won’t receive a response,
4:47
but it worked. You will see that any changes to the controls within Q-Sys is reflected by ‘cv’
4:52
updates reported by the protocol.
4:54
These updates will continue to occur whenever any member control of the Change Group changes
4:59
until the TCP socket connection is broken or you destroy the change group.
5:03
The reason you might want to use multiple Change Groups
5:06
is for when you want to poll different types of controls differently.
5:10
You might not want to poll all controls at the same frequency.
5:13
You might want to poll a meter value every 250ms,
5:17
while you might only poll a Softphone Ringing LED every second or two.
5:22
For these type of needs, just put your controls into different Change Groups
5:25
and set different schedules for each change group.
5:29
If you would like to mark all Change Group controls as ‘dirty’
5:34
and therefore receive the complete list on the next poll interval,
5:37
use the Change Group Invalidate command with the Change Group’s ID.
5:42
The command for that is, you guessed it, cgi 1. Since our Change Group Schedule is running,
5:48
you’ll receive a list of the current values of all controls in the Change Group.
5:52
One other topic that should be mentioned is that you can restrict access to this protocol using the
5:57
Q-Sys Administrator. As long as you have multiple users set up in Administrator,
6:02
you can require that an external control inputs a PIN matching a User Account
6:07
that has External Control privileges. Here, I have disabled External Control access on the default Guest account
6:15
and added an Admin account with the PIN 1234. I’ll save this change,
6:21
which will take effect upon the next new connection from a client.
6:24
Here, I have opened a new Telnet session to my emulated design on port 1702.
6:30
We can type “status get” and receive the expected response, but if we try to change a control,
6:36
let’s use “control set value GainGain 0” and press enter. Aha.
6:43
Doing anything of substance now requires logging in via an account PIN.
6:48
I can type “login Admin 1234” and press Enter, and it tells me I am successful.
6:56
Now I can perform all the usual tasks, as that login is maintained until the TCP socket is disconnected.
7:03
Let’s try our control change again, [csv GainGain 0] … and success.
7:09
One last thing to keep in mind that we mentioned earlier.
7:12
ECP will timeout and close the TCP socket after 60 seconds of inactivity.
7:17
it would be good practice to create a program within your third-party controller that issues a
7:23
simple command such as “status get” every 50 seconds to prevent the port from closing.
7:28
So that’s it for external control. You now have all the tools to control Q-Sys from the outside,
7:34
and make it do your bidding, like your own personal … puppet.
Tips and Definitions
Part C: Managing Change Groups
7m 52s
CGPA = Change Group Poll Acknowledge, a confirmation of the information requested
CGPNA = Command to ask for Change Group Poll without receiving acknowledgement
Dirty/Clean: When a change group's control changes, it's 'dirty' and will report its status at next poll, making it 'clean,' and will not report in future polls until it is changed again.
Downloads and Links
Part C: Managing Change Groups
7m 52s