Open topic with navigation

Using Lua in Q-SYS Overview

Control scripting uses the Lua.org programming language with extensions that allow it to control Q-SYS hardware and software. Refer to the Lua 5.3 Reference manual for complete information. The Q-SYS specific extensions to Lua are documented in the following sections. The book "Programming in Lua" is highly recommended for learning Lua.

For examples of solutions using scripting refer to the Scripting Solutions topic.

The Q-SYS Extensions to Lua

The following Q-SYS extensions to Lua are covered in individual topics. For Lua code examples, see Code Examples.

• Controls IO
• ChannelGroup
• dir (Directory)
• Email
• HttpClient
• Log
• Mixer
• NamedControl
• Named Components
• Qlib.base64 (Encode and Decode)
• SerialPorts
• System
• Timer
• UDP Socket
• TcpSocket
• TcpSocketServer

Introduction

A Q-SYS control script is written in the Lua language, within Q-SYS designer, for the purpose of automatically accomplishing tasks or creating other control mechanisms by associating the control script with standard controls in the Schematic Elements of a Q-SYS design. The Control Script component allows you to write scripts to perform operations on values, positions, strings, colors and other metadata, and timing of controls in the Schematic Elements. An alternative scripting component is Scriptable Controls, which incorporates the functionality of both the Custom Controls component

• 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.
• Control Scripts use an Event/EventHandler model. EventHandlers (functions) are attached to an Event. When that Event takes place, the EventHandler is invoked.
• EventHandlers can be attached to Control Input objects that are invoked when the value of the Control changes.
• Both the input and output objects are in arrays called Controls.Inputs and Controls.Outputs. Access to these objects is accomplished with the [] operator. For example, Controls.Inputs[1].Value gives you access to the value of the Control assigned to input 1.
• Q-SYS specific functions are capitalized, while native Lua functions are lower case (e.g. Q-SYS’ Timer.Start vs Lua’s math.abs)
• Code changes can be made in a Control Script without redeploying a design.  A yellow notification bar appears at the top of the Control Panel window alerting the user that code is out of sync with the running design.  Clicking the yellow bar allows the script to be updated without having to redeploy the design or interrupting audio.
• Statements entered in the main body of a script  (outside of functions) are executed when a design is deployed and when Control Scripts are updated in a running design.

Notes

Maximum Execution Error

The Maximum Execution Error is thrown when an individual call of a Lua function exceeds the maximum allowed number of CPU cycles. Infinite loops are the most common cause of this error. “Max execution limits exceeded” is displayed in the debug log when this error occurs.

Arrays

Lua Arrays are 1 based.