Lua API#
Pharos 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 VLC 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 constantsRIO80
,RIO44
orRIO80
.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 constantsEDN10
orEDN 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 VLC and VLC+.
On a VLC: get_content_target(compositionNum)
On a VLC+: 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 constantsPRIMARY
,SECONDARY
orTARGET_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 VLC:
target = get_content_target(1)
current_level = target.master_intensity_level
And on a VLC+:
target = get_content_target(1, PRIMARY)
current_angle = target.rotation_offset
get_adjustment#
Note
Only supported on VLC+.
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 |
---|---|---|---|
|
Integer value of constants: |
Optional. The log level to apply to the message. |
|
|
string |
The message to add to the log. |
|
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 |
---|---|---|---|
|
float |
Optional. Release fade time in seconds. If not provided, the default fade time will be used. |
|
|
string |
Optional. Group name: |
|
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 |
---|---|---|---|
|
float |
Optional. Release fade time in seconds. If not provided, the default fade time will be used. |
|
|
string |
Optional. Group name: |
|
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 |
---|---|---|---|
|
float |
Optional. Release fade time in seconds. If not provided, the default fade time will be used. |
|
|
string |
Optional. Group name: |
|
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 |
---|---|---|---|
|
string |
The Key of the Touch Control. |
|
|
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. |
|
|
integer (0-255) |
New value to set. |
|
|
boolean |
Optional. Whether to fire associated triggers as a result of the control value change. Defaults to |
|
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 |
---|---|---|---|
|
string |
The Key of the Touch Control. |
|
|
string |
The name of the state as defined in the Touch theme. |
|
For example:
-- Set slider001 to a state called "Green"
set_control_state("slider001", "Green")
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 |
---|---|---|---|
|
integer |
Touch interface page to change to. |
|
|
integer |
Optional page transition. Integer value of constants: |
|
Note
Must be executed on the TPC 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 TPC 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 TPC 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 |
---|---|---|---|
|
string |
JSON attribute name |
|
|
Value for the JSON, which will be sent as a string. |
|
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.