Control Script
The Control Script component is used to write scripts, using the Lua language, for control and monitoring from within Q-SYS Designer. You can change or monitor the position, value, string, metadata and other attributes of controls. The script you write interacts with components through their control pins.
For more about scripting in Q-SYS, see Control Scripting. Refer to the Lua 5.3 Reference Manual for information about native Lua commands supported in Q-SYS.
Note: This component uses the Q-SYS Scripting Engine, which is a licensed feature on certain Cores manufactured with Q-SYS 7.0 and later. For more information, see Licensing.
The Control Script component is defined, in the component Properties, by the number of inputs and outputs. The body of the script is written in the Control Script Control Panel.
- Refer to the Q-SYS Lua Environment and the Lua 5.3 Reference Manual topics for information about writing scripts.
- Click the Search bar on the right side of the page to locate text in your script. As a shortcut, press F3 to find the next item.
If you open a Q-SYS 3.3 or earlier design containing a Control Script component in Q-SYS 4.0 or later, the component with become a Control Script v1 component. The existing v1 script will continue to function as before. However, if the v1 script is pasted into a newly placed Control Script component, it will most likely fail. We have made it simpler to convert a v1 script to v2 by adding a property to the Control Script v1 block by adding a property to use the New Script Engine (Yes/No). This is to avoid having to copy and paste code to a v2 Script component.
Inputs and Outputs
Control components do not have traditional input and output pins. If a Control Pin is available for the component, an input or output will appear.
Control Pins represent the controls available in the component's Control Panel. Control Pins are used to link controls between Schematic Elements, and link to / from Control Scripts. Control Pin signal pins are represented by a square, and the wiring is represented by a thick blue / white line.
See Debug Output.
Control Script Properties
Input Count
Sets the number of inputs.
Serial Input Count
Sets the number of serial connections. Use with the Core, I/O Frame, and Page Station Serial Port components.
Output Count
Sets the number of outputs.
Virtual Serial Output Count
Sets the number of virtual serial output pins. Use these pins with the SerialServerPorts Lua library.
Start Automatically
When the property is set to no, the script will not start when entering emulation or loading a design to a core.
When the property is set to yes (Default), the script will start when entering emulation mode or when loading a design to a core.
Graphic Properties
Label
Use the Label property to change the name of the component in the schematic. The Label property defaults to the component name. To learn more about renaming schematic elements, see Organizing Your Design.
Position
The coordinates reference a specific place in the schematic - for example,"100,100" (horizontal, vertical). 0,0 is the upper left corner of the schematic.
Fill
Sets the fill color of the component in the schematic.
Script Access Properties
Code Name
Displays the currently assign name for control access. You can use the auto-assigned name or customize it. Q-SYS will automatically check all Code Names in the design to ensure name is unique.
Script Access
Defines whether the component will be accessible by script and/or externally, or not at all. Choices include All, External, None (default), and Script.
- None (default) - Not accessible by any script, plugin, or by Q-SYS Remote Control Protocol (QRC).
- Script - Can be accessed by scripts, such as Text Controller, Block Controllers, and plugins only.
- External - Can only be accessed by 3rd party controls systems using component commands from the Q-SYS Remote Control Protocol (QRC).
- All - No restrictions, can be accessed by 3rd party control systems via Q-SYS Remote Control Protocol (QRC), or script objects or plugin objects.
Tip: Use Script Programmer Mode to quickly view the Script Access setting directly on the component in the design schematic without the need to disconnect from the Q-SYS Core processor.
When you double click the Control Script component, the script editing tab displays.
Script Area
Text-edit area to write script. You can edit the script in the Design, Emulate, or Run modes, but any errors are only detected in the Run or Emulate modes.
Tip: While in the Script area, press F1 for help on the Lua scripting language.
Top Bar
Click the yellow "Save changes" bar to reload (not run) the script. Syntax errors are indicated in a red bar at top-right, as well as in the Debug Output area.
Pin Name |
Value |
String |
Position |
Pins Available |
---|---|---|---|---|
Code |
(text) Allows you to enter code. |
Input / Output |
||
Script Start |
(trigger) Starts the script running. |
Input / Output |
||
Script Status |
(text) Current status of the script. |
Output |
||
Script Stop |
(trigger) Stops the script. |
Input / Output |