Lua API#

Mosaic controllers offer a Lua API providing access to system information, playback functions and trigger operations.

Standard Libraries#

The following standard Libraries are imported

Functions#

The following functions are available in trigger action scripts and in IO modules. In trigger action scripts they are added directly to the environment; in IO modules they are available in the controller namespace.

Queries#

get_current_project#

Returns a Project object.

For example:

project_name = get_current_project().name

get_current_replication#

Returns a Replication object.

For example:

rep_name = get_current_replication().name

get_location#

Returns a Location object.

For example:

lat = get_location().lat

get_timeline#

get_timeline(timelineNum)

Returns a single Timeline object for the timeline with user number timelineNum.

For example:

tl = get_timeline(1)
name = tl.name
state = tl.state

if (tl.source_bus == TCODE_1) then
  -- do something
end

get_scene#

get_scene(sceneNum)

Returns a single Scene object for the scene with user number sceneNum.

For example:

scn = get_scene(1)
name = scn.name
state = scn.state

get_group#

get_group(groupNum)

Returns a single Group object for the group with user number groupNum.

For example:

grp = get_group(1)
name = grp.name

Note

Passing 0 as groupNum will return Group for the All Fixtures group. This can also be used on Atlas family projects to master the intensity of the entire unit.

get_fixture_override#

get_fixture_override(fixtureNum)

Returns an Override object for the fixture with user number fixtureNum.

For example:

-- Get override for fixture 22
override = get_fixture_override(22)
-- Set the override colour to red (and full intensity)
override:set_irgb(255, 255, 0, 0)

get_group_override#

get_group_override(groupNum)

Returns an Override object for the group with user number groupNum.

Note

Passing 0 as groupNum will return an Override for the All Fixtures group.

For example:

-- Get override for group 3
override = get_group_override(3)
-- Set the intensity to 50% in 2 seconds
override:set_intensity(128, 2.0)

get_current_controller#

Returns the Controller that the script is being executed on.

For example:

cont = get_current_controller()
name = cont.name

get_network_primary#

Returns the Controller in the project that is set as the network primary.

is_controller_online#

is_controller_online(controllerNum)

Returns true if the controller with user number controllerNum has been discovered, or false otherwise.

For example:

if (is_controller_online(2)) then
  log("Controller 2 is online")
else
  log("Controller 2 is offline")
end

get_temperature#

Returns a Temperature object with measurements from the controller’s temperature sensors.

For example:

temp = get_temperature()
log(temp.ambient_temp)

get_rio#

get_rio(type, num)

Returns a RIO object representing a RIO matching the parameters:

type can be one of the constants RIO80, RIO44 or RIO80.
num is the remote device number within the Designer project.

For example:

rio = get_rio(RIO44, 1)
input = rio:get_input(1)
output_state = rio:get_output(1)

Note

The constants for type are in the controller namespace within IO modules, e.g. controller.RIO44.

get_bps#

get_bps(num)

Returns a BPS object with remote device number num.

For example:

bps = get_bps(1)
btn = bps:get_state(1)

get_text_slot#

get_text_slot(slotName)

Returns the value of the text slot with name slotName. If no such text slot exists in the project then an empty string will be returned.

For example:

log(get_text_slot("my text slot"))

get_dmx_universe#

get_dmx_universe(idx)

Returns a Universe object for the DMX universe with number idx.

For example:

uni = get_dmx_universe(1) -- get DMX Universe 1
level = uni:get_channel_value(1) -- get channel 1 from the returned universe

get_artnet_universe#

get_artnet_universe(idx)

Returns a Universe object for the Art-Net universe with number idx.

get_pathport_universe#

get_pathport_universe(idx)

Returns a Universe object for the Pathport universe with number idx.

get_sacn_universe#

get_sacn_universe(idx)

Returns a Universe object for the sACN universe with number idx.

get_kinet_universe#

get_kinet_universe(power_supply_num, port_num)

Returns a Universe object for the KiNET power supply port matching the parameters:

power_supply_num is the KiNET power supply number in the project.
port_num is the port number of the KiNET power supply.

get_edn_universe#

get_edn_universe(remote_device_type, remote_device_num, port_num)

Returns a Universe object for the EDN output matching the parameter:

remote_device_type is be one of the constants EDN10 or EDN 20.
remote_device_num is the remote device number of the EDN in the project.
port_num is the DMX output port number of the EDN.

Note

The constants for remote_device_type are in the controller namespace within IO modules, e.g. controller.EDN20.

get_input#

get_input(idx)

Returns the state of the controller’s input numbered idx as a boolean (for digital inputs) or an integer (for analog inputs, 0-100).

For example:

in1 = get_input(1)

if in1 == true then
  log("Input 1 is digital and high")
elseif in1 == false then
  log("Input 1 is digital and low")
else
  log("Input 1 is analog at " .. in1)
end

get_dmx_input#

get_dmx_input(channel)

Returns the value of the DMX channel number as an integer. If no DXM input is detected then nil will be returned.

get_trigger_variable#

get_trigger_variable(idx)

Returns the trigger variable at index idx as a Variant.

For example:

-- Use with a Touch Colour Move Trigger
red = get_trigger_variable(1).integer
green = get_trigger_variable(2).integer
blue = get_trigger_variable(3).integer

-- Use with Serial Input "<s>\r\n"
input = get_trigger_variable(1).string

get_trigger_number#

get_trigger_number()

Returns the number of the trigger that ran this script. Will return nil if called from another context.

get_resource_path#

get_resource_path(filename)

Returns the path to the resource file, where filename is the name of a file on the controller’s internal storage.

For example:

dofile(get_resource_path("my_lua_file.lua"))

get_content_target#

Note

Only supported on Atlas and Atlas Pro.

On a Atlas: get_content_target(compositionNum)

On a Atlas Pro: get_content_target(compositionNum, type)

Returns a Content Target object representing the Content Target in the project that matches the parameters:

compositionNum is the user number of the composition containing the desired Content Target.
type describes the Content Target type and can be one of the constants PRIMARY, SECONDARY or TARGET_3 … TARGET_8.

Note

The constants for type are in the controller namespace within IO modules, e.g. controller.TARGET_5.

Will return nil if no matching Content Target exists in the project.

For example, on a Atlas:

target = get_content_target(1)
current_level = target.master_intensity_level

And on a Atlas Pro:

target = get_content_target(1, PRIMARY)
current_angle = target.rotation_offset

get_adjustment#

Note

Only supported on Atlas Pro.

get_adjustment(num)

Returns an Adjustment Target object representing the Adjustment Target in the project with the integer user number num:

Will return nil if no matching Adjustment Target exists in the project.

For example:

target = get_adjustment(1)
target:transition_x_position(10,1,5) -- Move 10 pixels right in 5 seconds
target:transition_y_position(10,1,5) -- Move 10 pixels down in 5 seconds
target:transition_rotation(90,1,5) -- Rotate by 90 degrees in 5 seconds

get_log_level#

Returns the current log level of the controller, which can be one of the following constants:

LOG_DEBUG
LOG_TERSE
LOG_NORMAL
LOG_EXTENDED
LOG_VERBOSE
LOG_CRITICAL

Note

These constants are in the controller namespace within IO modules, e.g. controller.LOG_NORMAL.

get_syslog_enabled#

Returns true if Syslog is enabled, or false otherwise.

get_syslog_ip_address#

Returns the IP address of the Syslog server as a string.

get_ntp_enabled#

Returns true if NTP is enabled.

get_ntp_ip_address#

Returns the IP address of the NTP server as a string.

Actions#

log#

log([level, ]message)

Write a message to the controller’s log according to the parameters:

Parameter	Value Type	Description	Value Example
`level`	Integer value of constants: `LOG_DEBUG`, `LOG_TERSE`, `LOG_NORMAL`, `LOG_EXTENDED`, `LOG_VERBOSE`, `LOG_CRITICAL`; defaults to `LOG_NORMAL`	Optional. The log level to apply to the message.	`LOG_VERBOSE`
`message`	string	The message to add to the log.	`"Your log message"`

For example:

log(LOG_CRITICAL, "This is a critical message!") -- logs a message at Critical log level
log("This is a normal message.") -- logs a message at Normal log level.

set_log_level#

set_log_level(log_level)

Changes the log level of the controller, showing more or less detailed information, where log_level is an integer value of the constants:

LOG_DEBUG (5)
LOG_TERSE (4)
LOG_NORMAL (3)
LOG_EXTENDED (2)
LOG_VERBOSE (1)
LOG_CRITICAL (0)

pause_all#

Pause all timelines in the project.

resume_all#

Resume all timelines in the project.

release_all#

release_all([fade,] [group])

Release all timelines and scenes in the project.

Note

You can provide:

No arguments - this will release all with the default fade time.
A fade time, which will be used to release all.
Or, both a fade time and a group.

Parameter	Value Type	Description	Value Example
`fade`	float	Optional. Release fade time in seconds. If not provided, the default fade time will be used.	`2.0`
`group`	string	Optional. Group name: `A` through `H`. Prepend the group name with `!` to apply the action to all groups except the specified group, e.g. `!A`.	`"B"`

release_all_timelines#

release_all_timelines([fade,] [group])

Release all timelines in the project.

Note

You can provide:

No arguments - this will release all with the default fade time.
A fade time, which will be used to release all.
Or, both a fade time and a group.

Parameter	Value Type	Description	Value Example
`fade`	float	Optional. Release fade time in seconds. If not provided, the default fade time will be used.	`2.0`
`group`	string	Optional. Group name: `A` through `H`. Prepend the group name with `!` to apply the action to all groups except the specified group, e.g. `!A`.	`"B"`

release_all_scenes#

release_all_scenes([fade,] [group])

Release all scenes in the project.

Note

You can provide:

No arguments - this will release all with the default fade time.
A fade time, which will be used to release all.
Or, both a fade time and a group.

Parameter	Value Type	Description	Value Example
`fade`	float	Optional. Release fade time in seconds. If not provided, the default fade time will be used.	`2.0`
`group`	string	Optional. Group name: `A` through `H`. Prepend the group name with `!` to apply the action to all groups except the specified group, e.g. `!A`.	`"B"`

clear_all_overrides#

clear_all_overrides([fade])

Removes all overrides from all fixtures and groups. Optionally specify a fade time in seconds as a float, e.g. 2.0.

enqueue_trigger#

enqueue_trigger(num[,var...])

Queue trigger number num to be fired on the next controller playback refresh. The trigger’s conditions will be tested. Optional variables var can be passed in as additional arguments.

For example:

-- enqueue trigger 2, passing in three variables: 255, 4.0 and "string"
enqueue_trigger(2,255,4.0,"string")

enqueue_local_trigger#

enqueue_local_trigger(num[,var...])

Same behaviour as for enqueue_trigger but the trigger num will only be queued on the controller that ran the function - the trigger will not propagate to other controllers in the project.

force_trigger#

force_trigger(num[,var...])

Queue trigger number num to be fired on the next controller playback refresh without testing the trigger’s conditions - the trigger actions will always run. Optional variables var can be passed in as additional arguments.

For example:

-- force the execution of trigger 2's actions
-- pass in three variables: 255, 4.0 and "string"
force_trigger(2,255,4.0,"string")

force_local_trigger#

force_local_trigger(num[,var...])

Same behaviour as for force_trigger but the trigger num will only be queued on the controller that ran the function - the trigger will not propagate to other controllers in the project.

set_text_slot#

set_text_slot(name, value)

Set the value of the text slot named name in the project to value, for example:

-- Set "My slot" to value "Hello world!"
set_text_slot("My slot", "Hello world!")

set_control_value#

set_control_value(name, [index,] value[, emitChange])

Set the value on a Touch Slider or Colour Picker according to the parameters:

Parameter	Value Type	Description	Value Example
`name`	string	The Key of the Touch Control.	`slider001`
`index`	integer (1-3)	Optional. Axis of movement - a slider has 1; a colour picker has 3. Will default to 1 if this parameter isn’t specified.	`1`
`value`	integer (0-255)	New value to set.	`128`
`emitChange`	boolean	Optional. Whether to fire associated triggers as a result of the control value change. Defaults to `false`.	`true`

For example:

-- Set slider001 to half (and don't fire any associated triggers)
set_control_value("slider001", 128)
-- Set the second axis (green) to full on colour020
set_control_value("colour020", 2, 255)

set_control_state#

set_control_state(name, state)

Set the state on a Touch control according to the parameters:

Parameter	Value Type	Description	Value Example
`name`	string	The Key of the Touch Control.	`slider001`
`state`	string	The name of the state as defined in the Touch theme.	`Green`

For example:

-- Set slider001 to a state called "Green"
set_control_state("slider001", "Green")

set_control_caption#

set_control_caption(name, caption)

Set the caption on a Touch control according to the parameters:

Parameter	Value Type	Description	Value Example
`name`	string	The Key of the Touch Control.	`button001`
`caption`	string	The text to display as the control’s caption.	`On`

For example:

-- Set button001's caption to "On"
set_control_caption("button001", "On")

set_interface_page#

set_interface_page(number[, transition])

Change the current page on the Touch interface according to the parameters:

Parameter	Value Type	Description	Value Example
`number`	integer	Touch interface page to change to.	`2`
`transition`	integer	Optional page transition. Integer value of constants: `SNAP`, `PAN_LEFT`, `PAN_RIGHT`	`PAN_LEFT`

Note

Must be executed on the MTPC that hosts the interface.

For example:

-- Change the touch screen interface to page 4 with a snap transition
set_interface_page(4, SNAP)

set_interface_enabled#

set_interface_enabled([enabled])

Enable/disable the touchscreen, according to the optional boolean parameter enabled (default: true).

Note

Must be executed on the MTPC that hosts the interface.

For example:

-- Disable the touchscreen
set_interface_enabled(false)

set_interface_locked#

set_interface_locked([lock])

Lock/unlock the touchscreen, according to the optional boolean parameter lock (default: true).

Note

Must be executed on the MTPC that hosts the interface.

For example:

-- Lock the touchscreen
set_interface_locked()
-- Unlock the touchscreen
set_interface_locked(false)

push_to_web#

push_to_web(name, value)

Sends data as JSON to clients who are subscribed to the relevant websocket channel, e.g. custom web interfaces using subscribe_lua in the query.js library. The parameters are as follows:

Parameter	Value Type	Description	Value Example
`name`	string	JSON attribute name	`"myVar"`
`value`	Variant	Value for the JSON, which will be sent as a string.	`"String value"` or `1234`

For example:

myData = 1234
-- Will push JSON object {"my_data":"1234"}
push_to_web("my_data", myData)

disable_output#

disable_output(protocol)

Disables the output of a single protocol from the controller, where protocol is the integer value of the constants:

DMX
PATHPORT
ARTNET
KINET
SACN
DVI
RIO_DMX
EDN_DMX
EDN_SPI

For example:

-- Disable the DMX output from the controller
disable_output(DMX)

enable_output#

enable_output(protocol)

Enables the output of a single protocol from the controller, where protocol is the integer value of the constants defined for disable_output.

For example:

-- Enable the DMX output from the controller
enable_output(DMX)

set_timecode_bus_enabled#

set_timecode_bus_enabled(bus[, enable])

Enable or disable a timecode bus, where bus is the integer value of the constants TCODE_1 … TCODE_6 and enable is a boolean, determining whether the bus is enabled (default true) or not.