Mouse support was added in version 0.1.10. It can be enabled in eruption.conf by setting "grab_mouse = true" in section [global]. This will enable support for mouse events and Easy Shift+ mouse button macros.
Eruption 0.1.12 somewhat relaxed the mouse grabbing mode. It now is possible for Eruption to process mouse events without grabbing the mouse exclusively. Injection of mouse events wont work in that mode though. This feature has been added to support setups, where another software should be granted exclusive access to the mouse device.

Configuration and Usage

Eruption configuration file

You may want to try the Eruption Profile Switcher GNOME Shell extension, for easy switching of profiles on the fly.

The eruption configuration file /etc/eruption/eruption.conf:

# Eruption - Realtime RGB LED Driver for Linux
# Main configuration file

[global]
enable_experimental_features = false
driver_maturity_level = "testing"

profile_dirs = ["/var/lib/eruption/profiles/"]
script_dirs = ["/usr/share/eruption/scripts/"]

# select your keyboard variant
# keyboard_variant = "ANSI"
keyboard_variant = "ISO"

# Mouse handling
enable_mouse = true
grab_mouse = true

# "Away from keyboard" handling
afk_profile = "/var/lib/eruption/profiles/rainbow-wave.profile"
afk_timeout_secs = 0

# [[devices]]
# entry_type = "device"
# device_class = "serial"
# device_name = "Adalight Custom Serial LEDs"
# device_file = "/dev/ttyACM0"

# [[devices]]
# entry_type = "blacklist"
# vendor_id = 0x1e7d
# product_id = 0x311a

Section [global]

enable_experimental_features = Enable experimental (unstable) features

driver_maturity_level = Allow drivers with this maturity levels: "stable", "testing", "experimental"

keyboard_variant = Switch between sub-variants of your device. (Only partially supported)

enable_mouse = Enable support for mouse events. This will allow Eruption to react on mouse events.

grab_mouse = Enable support for the injection of mouse events. This will allow Eruption to extend the Easy Shift+ macros to the mouse. Since the mouse is grabbed exclusively, other software will be prohibited from using the hardware mouse. Set this to false if you want Eruption to co-exist with other software, that needs to listen to mouse events, such as 3rd party device drivers.

Profiles

The file default.profile from the directory /var/lib/eruption/profiles

id = '5dc62fa6-e965-45cb-a0da-e87d29713093'
name = 'Organic FX'
description = 'Organic effects'
active_scripts = [
      'organic.lua',
      'shockwave.lua',
  #   'impact.lua',
  #   'water.lua',
  #   'raindrops.lua',
      'macros.lua',
  #   'stats.lua',
]

The file preset-red-yellow.profile from the directory /var/lib/eruption/profiles

id = '5dc62fa6-e965-45cb-a0da-e87d29713099'
name = 'Preset: Red and Yellow'
description = '''Presets for a 'red and yellow' color scheme'''
active_scripts = [
	  'batique.lua',
	  'shockwave.lua',
 	  'macros.lua',
#	  'stats.lua',
]

[[config.Batique]]
type = 'float'
name = 'color_divisor'
value = 2.0

[[config.Batique]]
type = 'float'
name = 'color_offset'
value = -90.0

This will run the batique.lua script to "paint the background", and on top of that, display the shockwave effect from shockwave.lua when a key has been pressed. Configuration values may be overridden on a per-profile basis. If a configuration value is not listed in the .profile file, the default value will be taken from the script's .manifest file.

Switching profiles and slots at runtime

You may want to install the GNOME Shell extension Eruption Profile Switcher or visit the Github page

You may switch the currently active slot to profile1.profile with the following command:

Switch Profile

eruptionctl switch profile /var/lib/eruption/profiles/profile1.profile

Switch Slot

Slots can be switched with the following command:

Switch to slot 2:

eruptionctl switch slot 2

Lua Scripts and Manifests

All script files and their corresponding manifests reside in the directory /usr/share/eruption/scripts. You may use the provided scripts as a starting point to write your own effects.

Support for Macros

Eruption 0.1.1 added the infrastructure to support injection of keystrokes (to support "macros").

This is achieved by adding a "virtual keyboard" to the system that injects keystroke sequences as needed. The "real hardware" keyboard will be grabbed exclusively on startup of the daemon. This allows Eruption to filter out keystrokes, so they won't be reported to the system twice.

Eruption 0.1.8 introduced support for dynamic switching of slots via MODIFIER + F1-F4 keys.

NOTE: MODIFIER is a placeholder for the modifier key. It is set to the FN key by default, but can be re-mapped easily to e.g. the Right Shift or Right Alt keys.

Eruption 0.1.8 also added support for the macro keys (Insert - Pagedown) in conjunction with the aforementioned MODIFIER key. So if you want to play back Macro #1 you just have to press MODIFIER + [M1] key.

Eruption 0.1.9 introduced the file /usr/share/eruption/scripts/lib/macros/user-macros.lua. You may use it to implement your own macros.

Eruption 0.1.10 introduced experimental mouse support. The mouse support is roughly implemented in the same way as the previously mentioned keyboard support, by adding a "virtual mouse" device to the system that injects events as needed. The "real hardware" mouse will be grabbed exclusively (this can be disabled) on startup of the daemon. This allows Eruption to filter out or inject "virtual" mouse events.

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

Additional Plugins:

Animal: Simulation of organic movements (support library)

Available Effects Scripts

Eruption currently ships with the following Lua scripts:

Name	Class	File	Status	Description
Afterglow	Effect	`afterglow.lua`	Ready	Hit keys are lit for a certain amount of time, then they are faded out
Afterhue	Effect	`afterhue.lua`	Ready	Hit keys cycle through the HSL color-space, using a linearly decreasing hue angle
Batique	Background	`batique.lua`	Ready	Batique effect, based on the Super Simplex Noise function that serves as input to get a HSL color
Open Simplex Noise	Background	`osn.lua`	Ready	Effect based on the Open simplex noise function that serves as input to produce a HSL color
Billow	Background	`billow.lua`	Ready	Effect based on the Billow noise function that serves as input to produce a HSL color
Fractal Brownian Motion	Background	`fbm.lua`	Ready	Effect based on the Fractal Brownian Motion noise function that serves as input to produce a HSL color
Organic	Background	`organic.lua`	Ready	Effect based on the Super Simplex noise function that serves as input to produce a HSL color
Perlin Noise	Background	`perlin.lua`	Ready	Effect based on the Perlin Noise function that serves as input to produce a HSL color
Psychedelic	Background	`psychedelic.lua`	Ready	Effect based on the Super Simplex noise function that serves as input to produce a HSL color
Ridged Multifractal Noise	Background	`rmf.lua`	Ready	Effect based on the Ridged Multifractal noise function that serves as input to produce a HSL color
Voronoi	Background	`voronoi.lua`	Ready	Effect based on the Voronoi noise function that serves as input to produce a HSL color
Checkerboard	Background	`checkerboard.lua`	Ready	Effect based on the Checkerboard noise function that serves as input to produce a HSL color
Network FX	Background	`netfx.lua`	Ready	Implements Network FX, a TCP-based network protocol
Heartbeat	Effect	`heartbeat.lua`	Ready	Heartbeat effect. The more the system is loaded the faster the heartbeat effect
Impact	Effect	`impact.lua`	Ready	Hit keys and keys in their immediate vicinity stay lit for a certain amount of time, then they are faded out
Raindrops	Effect	`raindrops.lua`	Ready	Rain effect, randomly light up keys and fade them out again
Ghost	Effect	`ghost.lua`	Ready	Ghost typing effect, randomly highlight keys and fade them out again
Phonon	Effect	`phonon.lua`	Ready	Display a propagating phonon wave effect
Water	Effect	`water.lua`	Ready	Display propagating water ripples effect
Wave	Effect	`wave.lua`	Ready	Display a colored wave where the alpha channel values are based on the sine function
Animal	Effect	`animal.lua`	Ready	Display an organically moving lifeform on the keyboard
Solid	Background	`solid.lua`	Ready	Display a solid color
Rainbow	Background	`rainbow.lua`	Ready	Display a rainbow color gradient
Stripes	Background	`stripes.lua`	Ready	Display horizontal stripes of multiple colors
Gradient	Background	`gradient.lua`	Ready	Gradient Noise, requires a CPU later than 2015 with support for SIMD/AVX2
Turbulence	Background	`turbulence.lua`	Ready	Turbulence Noise, requires a CPU later than 2015 with support for SIMD/AVX2
Color Swirls (Perlin Noise)	Background	`swirl-perlin.lua`	Ready	Color swirls effect, based on the Perlin Noise function that serves as input to produce a HSL color
Color Swirls (Simplex Noise)	Background	`swirl-simplex.lua`	Ready	Color swirls effect, based on the Simplex Noise function that serves as input to produce a HSL color
Color Swirls (Turbulence Noise)	Background	`swirl-turbulence.lua`	Ready	Color swirls effect, based on the Turbulence Noise function that serves as input to produce a HSL color
Color Swirls (Voronoi Noise)	Background	`swirl-voronoi.lua`	Ready	Color swirls effect, based on the Voronoi Noise function that serves as input to produce a HSL color
Lava Lamp	Background	`lava-lamp.lua`	Ready	Display a lava lamp like effect
Domain Coloring	Background	`domain-coloring.lua`	Ready	Visualize a mathematical function
Dim Zone	Filter	`dim-zone.lua`	Ready	Dim (darken) a zone on the canvas

The following scripts are unfinished/still in development, and some of them have known bugs:

Name	Class	File	Progress	Description
Fire	Background	`fire.lua`	Approx. 85% done	Shows a bonfire effect on the keyboard
Fireworks	Background	`fireworks.lua`	Approx. 85% done	Shows a fireworks effect on the keyboard
Flight (Perlin)	Background	`flight-perlin.lua`	Approx. 85% done	Shows a random flight through Perlin noise
Halo	Effect	`halo.lua`	Approx. 95% done	Show a spreading rainbow colored animated halo when a key has been pressed
Heat Map	Effect	`heatmap.lua`	Approx. 50% done	Shows a heat map of recorded statistics on the keyboard
Gaming	Effect	`gaming.lua`	Approx. 85% done	Highlight a fixed set of keys, like e.g. 'WASD'
Pulse	Effect	`pulse.lua`	Approx. 85% done	Display a pulsating color on a fixed set of keys
Snake	Effect	`snake.lua`	Approx. 25% done	Displays a snake that lives on your keyboard
Linear Gradient	Background	`linear-gradient.lua`	Approx. 95% done	Display a color gradient
Multi Gradient	Background	`multigradient.lua`	Approx. 65% done	Display a color gradient, supports multiple gradient stops
Ripple	Effect	`ripple.lua`	Approx. 85% done	Display a rainbow colored ripple effect
Shockwave	Effect	`shockwave.lua`	Approx. 85% done	Like Impact, but shows propagating waves when a key has been pressed
Sysmon	Background	`sysmon.lua`	Approx. 10% done	System monitor, keyboard reflects system state
Temperature	Background	`temperature.lua`	Approx. 85% done	Temperature monitor. The keyboard reflects the CPU temperature, from 'green = cold' to 'red = hot'
Audio Visualizer 1	Background	`audioviz1.lua`	Approx 95% done	Shows the current loudness of the configured audio source as a color gradient
Audio Visualizer 2	Background	`audioviz2.lua`	Approx 85% done	Shows the current loudness of the configured audio source as HSL colors progressively
Audio Visualizer 3	Background	`audioviz3.lua`	Approx 95% done	Shows a "spectrum analyzer" visualization of the configured audio source
Audio Visualizer 4	Background	`audioviz4.lua`	Approx 85% done	VU-meter like heartbeat effect
Audio Visualizer 5	Background	`audioviz5.lua`	Approx 75% done	Like Batique, but with additional audio feedback

Scripts are combined to so called "effect pipelines" using a .profile file. E.g.: You may use one or more backgrounds, and then stack multiple effects scripts on top of that.

Available Macro Definitions

The macro files are stored in /usr/share/eruption/scripts/lib/macros/. Each file provides the Lua code that controls illumination and colors of each of the modifier layers, additionally they provide the code that gets executed when a macro key or Easy Shift shortcut is pressed. Eruption currently ships with custom keyboard macros for the following software:

Name	Class	File	Progress	Description
user-macros	Default	`user-macros.lua`	Approx 95% done	Customizable general purpose macro definitions for Eruption. Maybe use this as a starting point for your own macro files.
Star Craft 2	Game	`starcraft2.lua`	Approx 15% done	Star Craft 2 related macros

For a detailed documentation on how to write your own macros, please refer to MACROS.md

Process Monitor

Eruption 0.1.17 added a new daemon called eruption-process-monitor, which allows for dynamic switching of profiles and slots using a rule matching engine.

Effects Proxy Daemon

Eruption 0.3.0 added a new daemon called eruption-fx-proxy, that supersedes some functionality of eruption-netfx. It provides a more efficient and more robust implementation of the Ambient Effect.

Contributing

Contributions are welcome! Please see eruption/src/scripts/examples/*.lua directory for Lua scripting examples.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCUMENTATION.md

DOCUMENTATION.md

Table of Contents

Experimental Features

Configuration and Usage

Eruption configuration file

Section [global]

Profiles

Switching profiles and slots at runtime

Switch Profile

Switch Slot

Lua Scripts and Manifests

Support for Macros

Available Plugins

Available Effects Scripts

Available Macro Definitions

Further Reading

Process Monitor

Effects Proxy Daemon

Contributing

Files

DOCUMENTATION.md

Latest commit

History

DOCUMENTATION.md

File metadata and controls

Table of Contents

Experimental Features

Configuration and Usage

Eruption configuration file

Section [global]

Profiles

Switching profiles and slots at runtime

Switch Profile

Switch Slot

Lua Scripts and Manifests

Support for Macros

Available Plugins

Available Effects Scripts

Available Macro Definitions

Further Reading

Process Monitor

Effects Proxy Daemon

Contributing