Eruption Support Library

Overview

Eruption provides a small, but hopefully useful library of functions that are intended to be used by Lua scripts. Functions can be exported either by the daemon core, by Eruption plugins, or are provided via the Eruption Lua support library. Plugin specific functions are only available if the respective plugin is loaded. Functions provided by the Lua support library are available only if the respective file was loaded previously via a call to require "...".

Available Plugins

Keyboard: Keyboard related functions
Mouse: Mouse related functions
System: Basic system information and status, like e.g. running processes. Execute external commands, ...
Sensors: Query system sensor values, like e.g. CPU package temperature
Audio: Audio related tasks, like playing sounds, also used by audio visualizers, ...
Introspection: Provides internal status information of the Eruption daemon
Persistence: Provides a persistence layer for the Lua scripts to store data
Profiles: Switch slots, switch profiles based on system state, ...
Macros: Inject programmable key stroke sequences
Linux ULEDs: Userspace LEDs interface, support for kernel-based LED-triggers
SDK Support: Support for the Eruption SDK
Animal: Simulation of organic movements (support library)

Available Support Library Functions

Eruption currently ships with the following support library functions:

Name	File	Since	Description
`key_index(x, y)`	`utilities.lua`	since 0.1.9	Returns the index of the key with the specified coordinates
`debug_print_led_state(color_map)`	`debug.lua`	since 0.1.9	Prints a table, showing LED states in `color_map`
`debug_print_led_state(color_map)`	`debug.lua`	since 0.1.9	Prints a table, showing LED states in `color_map`
`linear(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inQuad(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outQuad(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutQuad(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInQuad(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inCubic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outCubic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutCubic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInCubic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inQuart(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outQuart(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutQuart(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInQuart(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inQuint(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outQuint(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutQuint(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInQuint(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inSine(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outSine(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutSine(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInSine(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inExpo(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outExpo(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutExpo(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInExpo(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inCirc(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outCirc(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutCirc(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInCirc(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inElastic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outElastic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutElastic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInElastic(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inBack(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outBack(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutBack(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInBack(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inBounce(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outBounce(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`inOutBounce(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function
`outInBounce(t, b, c, d)`	`easing.lua`	since 0.1.17	Easing function

For all easing functions:

t = elapsed time
b = begin
c = change == ending - beginning
d = duration (total time)

Core Functions

Core functions are written in Rust, and are exported to the Lua VMs. Eruption currently ships with the following core functions:

Name	Plugin	Lib	Since	Description
`trace(message)`	core	Std	since before 0.0.9	Log message with severity: `trace`
`debug(message)`	core	Std	since before 0.0.9	Log message with severity: `debug`
`info(message)`	core	Std	since before 0.0.9	Log message with severity: `info`
`warn(message)`	core	Std	since before 0.0.9	Log message with severity: `warn`
`error(message)`	core	Std	since before 0.0.9	Log message with severity: `error`
`delay(millis)`	core	Std	since before 0.0.9	Delay script execution for `millis` milliseconds
`stringify(arg)`	core	Std	since 0.3.0	Best effort to stringify the argument. Useful for debugging.
`abs(f) -> f`	core	Math	since before 0.0.9	Returns the absolute value of `f`
`sin(a) -> f`	core	Math	since before 0.0.9	Returns the sine of angle `a`
`cos(a) -> f`	core	Math	since 0.1.4	Returns the cosine of angle `a`
`pow(f, p) -> f`	core	Math	since before 0.0.9	Returns `f` to the power of `p`
`sqrt(f) -> f`	core	Math	since before 0.0.9	Returns the square root of `f`
`asin(f) -> f`	core	Math	since 0.1.17	Returns the arcus sine of `f`
`atan2(y, x) -> f`	core	Math	since 0.1.17	Returns the arcus tangens of (`y`, `x`)
`ceil(f) -> f`	core	Math	since 0.1.17	Returns the ceiling of `f`
`floor(f) -> f`	core	Math	since 0.1.17	Returns the floor of `f`
`round(f) -> f`	core	Math	since 0.1.17	Returns rounded value of `f`
`rand(l, h) -> f`	core	Math	since before 0.0.9	Returns a random number in the range `l..h`
`trunc(f) -> i`	core	Math	since before 0.0.9	Truncate the fractional part of `f`
`lerp(f0, f1, f) -> f`	core	Math	since 0.0.9	Linear interpolation of `f` to `f0`..`f1`, where `f` should lie in the range of -1.0..+1.0
`invlerp(f0, f1, f) -> f`	core	Math	since 0.1.9	Inverse linear interpolation of `f` to `f0`..`f1`. Returns a value in the range -1.0..+1.0
`range(f0, f1, f2, f3, f) -> f`	core	Math	since 0.1.9	Linear interpolation of `f` from the range `f0`..`f1`, to the range `f2`..`f3`
`min(f1, f2) -> f`	core	Math	since before 0.0.9	Returns the smaller one of the two values
`max(f1, f2) -> f`	core	Math	since before 0.0.9	Returns the greater one of the two values
`clamp(f, l, h) -> f`	core	Math	since before 0.0.9	Clamp `f` to range `l..h`
`color_to_rgb(color) -> (r, g, b)`	core	Color	since before 0.0.9	Returns the red, green and blue components of `color`
`color_to_hsl(color) -> (h, s, l)`	core	Color	since 0.0.10	Returns the hue, saturation and lightness components of `color`
`rgb_to_color(r, g, b) -> color`	core	Color	since before 0.0.9	Returns a color, constructed from the r, g and b components
`hsl_to_color(h, s, l) -> color`	core	Color	since 0.0.9	Returns a color, constructed from hue [0..360), saturation [0.0...1.0] and lightness [0.0..0.5] and (0.5..1.0] components
`color_to_rgba(color) -> (r, g, b, a)`	core	Color	since 0.0.12	Returns the red, green blue and alpha components of `color`
`color_to_hsla(color) -> (h, s, l, a)`	core	Color	since 0.0.12	Returns the hue, saturation, lightness and alpha components of `color`
`rgba_to_color(r, g, b, a) -> color`	core	Color	since 0.0.12	Returns a color, constructed from the r, g, b and alpha components
`hsla_to_color(h, s, l, a) -> color`	core	Color	since 0.0.12	Returns a color, constructed from hue [0..360), saturation [0.0...1.0], lightness [0.0..0.5], (0.5..1.0] and alpha components
`parse_color(val) -> color`	core	Color	since 0.1.19	Parses a CSS compatible color definition and returns the corresponding color value
`gradient_from_name(stock_name) -> handle`	core	Gradients	since 0.1.19	Allocates a new stock-gradient object and returns a handle to it. (Available stock gradients: "rainbow-smooth", "sinebow-smooth", "spectral-smooth", "rainbow-sharp", "sinebow-sharp", "spectral-sharp")
`gradient_destroy(handle)`	core	Gradients	since 0.1.19	Destroys a gradient object that was previously allocated by `gradient_from_name()`
`gradient_color_at(handle, pos) -> color`	core	Gradients	since 0.1.19	Returns the color value of the gradient referenced by `handle` at the position `pos`
`linear_gradient(start_color, end_color, p) -> color`	core	Color	since before 0.0.9	Returns the interpolated color at position `p` located between `start_color`..`end_color`. The value of `p` should lie in the range of 0..1
~~`noise(f1, f2, f3) -> f`~~	core	Noise	removed in 0.0.11	Computes an Open Simplex Noise value
`checkerboard_noise(f1, f2, f3) -> f`	core	Noise	since 0.1.12	Computes a Checkerboard noise value
`gradient_noise_2d(f1, f2) -> f`	core	Noise	since 0.1.5	Computes a Gradient noise value (requires SIMD/AVX2 support)
`gradient_noise_3d(f1, f2, f3) -> f`	core	Noise	since 0.1.5	Computes a Gradient noise value (requires SIMD/AVX2 support)
`turbulence_noise_2d(f1, f2) -> f`	core	Noise	since 0.1.5	Computes a Turbulence noise value (requires SIMD/AVX2 support)
`turbulence_noise_3d(f1, f2, f3) -> f`	core	Noise	since 0.1.5	Computes a Turbulence noise value (requires SIMD/AVX2 support)
`perlin_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes a Perlin noise value
`billow_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes a Billow noise value
`voronoi_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes a Voronoi noise value
`fractal_brownian_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes a Fractal Brownian Motion noise value
`ridged_multifractal_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes a Ridged Multifractal noise value
`open_simplex_noise(f1, f2, f3) -> f`	core	Noise	since 0.0.11	Computes an Open Simplex Noise value (3 dimensions)
`open_simplex_noise_2d(f1, f2) -> f`	core	Noise	since 0.1.4	Computes an Open Simplex Noise value (2 dimensions)
`open_simplex_noise_4d(f1, f2, f3, f4) -> f`	core	Noise	since 0.1.4	Computes an Open Simplex Noise value (4 dimensions)
`super_simplex_noise(f1, f2, f3) -> f`	core	Noise	since 0.1.4	Computes a Super Simplex Noise value
`get_canvas_size() -> i`	core	Hw	since 0.1.19	Returns the number "pixels" on the primary canvas
`get_canvas_width() -> i`	core	Hw	since 0.1.19	Returns the width of the primary canvas
`get_canvas_height() -> i`	core	Hw	since 0.1.19	Returns the height of the primary canvas
`get_num_keys() -> i`	core	Hw	since before 0.0.9	Returns the number of keys of the connected device
~~`get_key_color(key_index) -> color`~~	core	Hw	removed in 0.1.18	Returns the current color of the key `key_index`
~~`set_key_color(key_index, color)`~~	core	Hw	removed in 0.1.18	Sets the current color of the key `key_index` to `color`
~~`set_color_map([color_map])`~~	core	Hw	removed in 0.1.18	Set all LEDs at once to the colors specified in the array `color_map`. This will directly access the hardware. Please see also: submit_color_map()
`submit_color_map([color_map])`	core	Hw	since 0.0.12	Set all LEDs at once to the colors specified in the array `color_map`. Color maps of all scripts will be alpha blended together, and then sent to the hardware once for each render frame.
`get_color_map() -> [color_map]`	core	Hw	since 0.4.0	Returns the current composited color map
`get_saved_color_map() -> [color_map]`	core	Hw	since 0.4.0	Returns the last successfully rendered composited color map
`get_local_color_map() -> [color_map]`	core	Hw	since 0.4.0	Returns the current local color map of the running Lua script
`inject_key(ev_key, down)`	core	Hw	since 0.1.1	Inject a key event on the virtual keyboard
`inject_key_with_delay(ev_key, down, millis)`	core	Hw	since 0.1.9	Inject a key event on the virtual keyboard, after `millis` milliseconds has passed
`inject_mouse_button(button_index, down)`	core	Hw	since 0.1.10	Inject a mouse button event on the virtual mouse
`inject_mouse_wheel(direction)`	core	Hw	since 0.1.10	Inject a wheel scroll event on the virtual mouse
`get_current_load_avg_1() -> f`	System	Sys	since before 0.0.9	Returns the system load average of the last 1 minute
`get_current_load_avg_5() -> f`	System	Sys	since before 0.0.9	Returns the system load average of the last 5 minutes
`get_current_load_avg_15() -> f`	System	Sys	since 0.4.0	Returns the system load average of the last 15 minutes
~~`get_current_load_avg_10() -> f`~~	System	Sys	removed in 0.4.0	Returns the system load average of the last 10 minutes
`get_runnable_tasks() -> i`	System	Sys	since before 0.0.9	Returns the number of runnable tasks on the system
`get_total_tasks() -> i`	System	Sys	since before 0.0.9	Returns the total number of tasks on the system
`system(cmd, [args]) -> i`	System	Sys	since 0.1.8	Run a shell command
`get_button_state(button_index) -> bool`	Mouse	Mouse	since 0.1.10	Returns `true` when mouse button `button_index` is pressed, otherwise returns `false`
`get_key_state(key_index) -> bool`	Keyboard	Keyboard	since 0.1.8	Returns `true` when key `key_index` is pressed, otherwise returns `false`
`get_current_slot() -> i`	Profiles	Profiles	since 0.1.8	Returns the currently active slot (0-3)
`switch_to_slot(index)`	Profiles	Profiles	since 0.1.8	Switch to slot `index`
`get_package_temp() -> f`	Sensors	Hw	since before 0.0.9	Returns the temperature of the CPU package
`get_package_max_temp() -> f`	Sensors	Hw	since before 0.0.9	Returns the max. temperature of the CPU package. (Approx. 80-100°C)
`get_mem_total_kb() -> i`	Sensors	Hw	since before 0.0.9	Returns the total installed memory size
`get_mem_used_kb() -> i`	Sensors	Hw	since before 0.0.9	Returns the amount of used memory
`get_swap_total_kb() -> i`	Sensors	Hw	since before 0.0.9	Returns the total size of the swap space
`get_swap_used_kb() -> i`	Sensors	Hw	since before 0.0.9	Returns the amount of used swap space
`get_audio_volume() -> i`	Audio	dsp	since 0.1.12	Returns the current master volume of the configured audio device in the range [0..100]
`is_audio_muted() -> i`	Audio	dsp	since 0.1.21	Returns the current master audio devices mute state
`get_audio_loudness() -> i`	Audio	dsp	since 0.0.11	Returns the current RMS loudness of the configured audio input
`get_audio_spectrum() -> [f]`	Audio	dsp	since 0.0.11	Returns a vector of 1024 floats, containing results of a fourier transform (FFT) of the configured audio input
`get_audio_raw_data() -> [i]`	Audio	dsp	since 0.0.11	Returns a buffer of 16-bit wide signed integer values, containing samples from the configured audio input
`store_int(key, value)`	Persistence	core	since 0.1.11	Store an integer value with `key` in the persistent storage
`load_int(key, default) -> int`	Persistence	core	since 0.1.11	Load an integer value from the persistent storage, or return default instead if `key` does not exist
`store_float(key, value)`	Persistence	core	since 0.1.11	Store a float value with `key` in the persistent storage
`load_float(key, default) -> float`	Persistence	core	since 0.1.11	Load a float value from the persistent storage, or return default instead if `key` does not exist
`store_bool(key, value)`	Persistence	core	since 0.1.11	Store a boolean value with `key` in the persistent storage
`load_bool(key, default) -> bool`	Persistence	core	since 0.1.11	Load a boolean value from the persistent storage, or return default instead if `key` does not exist
`store_string(key, value)`	Persistence	core	since 0.1.11	Store a string value with `key` in the persistent storage
`load_string(key, default) -> string`	Persistence	core	since 0.1.11	Load a string value from the persistent storage, or return default instead if `key` does not exist
`store_color(key, value)`	Persistence	core	since 0.1.11	Store a color value with `key` in the persistent storage
`load_color(key, default) -> color`	Persistence	core	since 0.1.11	Load a color value from the persistent storage, or return default instead if `key` does not exist
`store_int_transient(key, value)`	Persistence	core	since 0.1.11	Store an integer value with `key` in the ephemeral storage
`load_int_transient(key, default) -> int`	Persistence	core	since 0.1.11	Load an integer value from the ephemeral storage, or return default instead if `key` does not exist
`store_float_transient(key, value)`	Persistence	core	since 0.1.11	Store a float value with `key` in the ephemeral storage
`load_float_transient(key, default) -> float`	Persistence	core	since 0.1.11	Load a float value from the ephemeral storage, or return default instead if `key` does not exist
`store_bool_transient(key, value)`	Persistence	core	since 0.1.11	Store a boolean value with `key` in the ephemeral storage
`load_bool_transient(key, default) -> bool`	Persistence	core	since 0.1.11	Load a boolean value from the ephemeral storage, or return default instead if `key` does not exist
`store_string_transient(key, value)`	Persistence	core	since 0.1.11	Store a string value with `key` in the ephemeral storage
`load_string_transient(key, default) -> string`	Persistence	core	since 0.1.11	Load a string value from the ephemeral storage, or return default instead if `key` does not exist
`store_color_transient(key, value)`	Persistence	core	since 0.1.11	Store a color value with `key` in the ephemeral storage
`load_color_transient(key, default) -> color`	Persistence	core	since 0.1.11	Load a color value from the ephemeral storage, or return default instead if `key` does not exist
`animal_create(name, speed, len_min, len_max, gradient_stop_1, gradient_stop_2, gradient_stop_3, opacity, { coefficient_1, coefficient_2, coefficient_3, coefficient_4, coefficient_5 }) -> handle`	Animal	core	since 0.1.20	Creates an animal object and returns an opaque handle to it
`animal_destroy(handle)`	Animal	core	since 0.1.20	Destroys the animal referenced by `handle`
`animal_tick(handle, delta)`	Animal	core	since 0.1.20	Advances the notion of time of the animal referenced by `handle` by the amount `delta`
`animal_render(handle) -> [u32]`	Animal	core	since 0.1.20	Returns a color map of a rendering of the animal references by `handle`, the color map may be modified afterwards and is suitable to be used with `submit_color_map()`

Non-exhaustive, more documentation coming soon

Please Note:

All color values should lie in the range [0..255] unless otherwise specified
Some API calls currently involve bringing up of threads for each call, especially the System and Sensor ones, so better don't call them in a tight loop

Available Callback Functions (Events)

Eruption currently calls the following event handler functions, if they are present in a Lua script:

Name	Class	Parameters	Description
`on_startup()`	core	n/a	Sent on startup, e.g. when a script is loaded
`on_quit()`	core	n/a	Sent on daemon exit
`on_render()`	core	n/a	Request to submit the current color map for compositing/blending
`on_tick(delta)`	core	delta: Timer delta since last tick	Timer tick event. Used to update the internal state of the script
`on_apply_parameter(parameters)`	core	parameters: An array of the changed parameter names	Sent whenever a script parameter shall be updated
`on_key_down(key_index)`	Keyboard	key_index: Key index (column major order)
`on_key_up(key_index)`	Keyboard	key_index: Key index (column major order)
`on_mouse_button_down(button_index)`	Mouse	button_index: Index of mouse button
`on_mouse_button_up(button_index)`	Mouse	button_index: Index of mouse button
`on_mouse_wheel(direction)`	Mouse	direction: 1 == up, 2 == down, 3 == left, 4 == right
`on_mouse_move(rel_x, rel_y, rel_z)`	Mouse	x, y, z coordinate updates	Coordinates are relative (delta values)
`on_hid_event(event_type, arg1)`	Hardware	event_type: 0 == unknown, 1 == KeyUp, 2 == KeyDown, 3 == MuteButton, 4 == Volume knob, 5 == Brightness knob, 6 == Set Brightness, 7 == Next/previous Profile, arg1: data payload e.g.: scan codes/status codes
`on_mouse_hid_event(event_type, arg1)`	Hardware	event_type: 0 == unknown, 1 == DPI changed, 2 == Button Down, 3 == Button Up, arg1: data payload e.g.: scan codes/status codes/button index

Exhaustive listing of all currently available event callbacks

Example Code

The following code will change a key's color to bright red after it has been pressed.

Listing 01

-- global array that stores each key's current color
color_map = {}

function on_startup()
    -- turn off all LEDs
    for i = 1, get_canvas_size() do
        color_map[i] = 0x00000000
    end

    -- update LED state
    submit_color_map(color_map)
end

function on_key_down(key_index)
    info("Pressed key: " .. key_index)

    -- set color of pressed key to red
    color_map[key_index] = rgba_to_color(255, 0, 0, 255)
    submit_color_map(color_map)
end

Please see the directories src/scripts/ and src/scripts/examples/ for further information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LIBRARY.md

LIBRARY.md

Eruption Support Library

Overview

Available Plugins

Available Support Library Functions

Core Functions

Available Callback Functions (Events)

Example Code

Listing 01

Files

LIBRARY.md

Latest commit

History

LIBRARY.md

File metadata and controls

Eruption Support Library

Overview

Available Plugins

Available Support Library Functions

Core Functions

Available Callback Functions (Events)

Example Code

Listing 01