Lua

Lua API

The WordClock application integrates the Lua scripting language for configuration and individual LED animations.

General functions

These functions can be used to manipulate settings or to react on certain events. However, they should be avoided in renderer contexts because of performance and concurrency reasons.

get_settings( path )

Get current settings as JSON string

Parameter	Type	Required	Default	Description
path	string	no	empty	Sub path inside JSON object

Return value:

• string JSON object

set_settings( json, path )

Set settings given as JSON string

Parameter	Type	Required	Default	Description
json	string	yes		JSON object
path	string	no	empty	Sub path inside target JSON object

Return value:

• booltrue on success, false on failure

register_signal( pattern, function, before )

Register Lua function as signal sink

Parameter	Type	Required	Default	Description
pattern	string	yes		Trigger if signal name matches regular expression
function	string | function	yes		Lua function to call (see below)
before	bool	no	false	Trigger function before or after signal sinks in settings.json

Return value:

• int >= 0 on success (Sink ID, needed for unregister_signal() )
• int < 0 on failure (probably regular expression error)

Signal function

Parameter	Type	Description
signal	string	Triggered signal name

Return value	Type	Required	Default	Description
handled	bool	no	true	Signal was handled (e.g. makes beep sound on button press)
proceed	bool	no	true	Proceed executing following signal sinks

unregister_signal( id )

Unregister Lua function from signal router

Parameter	Type	Required	Default	Description
id	int	yes		Sink ID from register_signal()

Return value:

• booltrue on success, false on failure

trigger_signal( signal )

Trigger signal by name (in the same way as e.g. a button would do)

Parameter	Type	Required	Default	Description
signal	string	yes		Signal name (usually: "source_name,action_name")

Return value:

• booltrue if signal was handled, false otherwise

beep( msec, freq, volume )

Play beep sound (asynchronous)

Parameter	Type	Required	Default	Description
msec	int	no	250	Duration (ms)
freq	int	no	2000	Frequency (Hz)
volume	int	no	255	Volume (0-255)

pause( msec )

Play beep pause (asynchronous)

Parameter	Type	Required	Default	Description
msec	int	no	250	Duration (ms)

message( text, count, message_type )

Display message overlay

Parameter	Type	Required	Default	Description
text	string	yes		Message
count	int	no	1	Number of passes (-1 = infinity)
message_type	string	no	INFO	Message type (ERROR, WARNING, SUCCESS or INFO)

Return value:

• int Message ID, needed for stop_message()

stop_message( id )

Stop message overlay

Parameter	Type	Required	Default	Description
id	int	yes		Message ID from message()

get_hwinfo( path )

Get hardware information as JSON string

Parameter	Type	Required	Default	Description
path	string	no	empty	Sub path inside JSON object

Return value:

• string JSON object

Render functions

These functions can be used to create own renderers, but they are only available inside a LuaRenderer context! They allow setting and getting of LED color values at a given position. The HSV color space specification can be found here.

set_matrix_led_rgb( x, y, r, g, b, a )

Set the RGB color of a matrix LED

Parameter	Type	Required	Default	Description
x	int	yes		X position (0-10)
y	int	yes		Y position (0-9)
r	int	yes		Red value (0-255)
g	int	yes		Green value (0-255)
b	int	yes		Blue value (0-255)
a	int	no	255	Alpha value (0-255)

set_backlight_led_rgb( x, r, g, b, a )

Set the RGB color of a backlight LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-59)
r	int	yes		Red value (0-255)
g	int	yes		Green value (0-255)
b	int	yes		Blue value (0-255)
a	int	no	255	Alpha value (0-255)

set_dots_led_rgb( x, r, g, b, a )

Set the RGB color of a dots LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-3)
r	int	yes		Red value (0-255)
g	int	yes		Green value (0-255)
b	int	yes		Blue value (0-255)
a	int	no	255	Alpha value (0-255)

set_matrix_led_hsv( x, y, h, s, v, a )

Set the HSV color of a matrix LED

Parameter	Type	Required	Default	Description
x	int	yes		X position (0-10)
y	int	yes		Y position (0-9)
h	int	yes		Hue (0-255)
s	int	yes		Saturation (0-255)
v	int	yes		Value (0-255)
a	int	no	255	Alpha value (0-255)

set_backlight_led_hsv( x, h, s, v, a )

Set the HSV color of a backlight LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-59)
h	int	yes		Hue (0-255)
s	int	yes		Saturation (0-255)
v	int	yes		Value (0-255)
a	int	no	255	Alpha value (0-255)

set_dots_led_hsv( x, h, s, v, a )

Set the HSV color of a dots LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-3)
h	int	yes		Hue (0-255)
s	int	yes		Saturation (0-255)
v	int	yes		Value (0-255)
a	int	no	255	Alpha value (0-255)

get_matrix_led_rgb( x, y )

Get the RGB color of a matrix LED

Parameter	Type	Required	Default	Description
x	int	yes		X position (0-10)
y	int	yes		Y position (0-9)

Return value:

• int Red value (0-255)
• int Green value (0-255)
• int Blue value (0-255)

get_backlight_led_rgb( x )

Get the RGB color of a backlight LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-59)

Return value:

• int Red value (0-255)
• int Green value (0-255)
• int Blue value (0-255)

get_dots_led_rgb( x )

Get the RGB color of a dots LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-3)

Return value:

• int Red value (0-255)
• int Green value (0-255)
• int Blue value (0-255)

get_matrix_led_hsv( x, y )

Get the HSV color of a matrix LED

Parameter	Type	Required	Default	Description
x	int	yes		X position (0-10)
y	int	yes		Y position (0-9)

Return value:

• int Hue (0-255)
• int Saturation (0-255)
• int Value (0-255)

get_backlight_led_hsv( x )

Get the HSV color of a backlight LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-59)

Return value:

• int Hue (0-255)
• int Saturation (0-255)
• int Value (0-255)

get_dots_led_hsv( x )

Get the HSV color of a dots LED

Parameter	Type	Required	Default	Description
x	int	yes		Position (0-3)

Return value:

• int Hue (0-255)
• int Saturation (0-255)
• int Value (0-255)