AlienFX LEDs

Keyboard and chassis lighting for Alienware and Dell machines on Linux.
Per-key colors, effects, a typing ripple, and a toggle in GNOME Quick Settings, all driven by a small, locked-down service.

Features · Supported machines · Install · Usage · Security · Development

✨ Features

Effects: one effect, applied to any mix of lights.	Ripple: color, speed and what shows underneath.
Chassis: power button, lid logo, rear strip.	Machine: detected model, key map, wizard.

💻 Supported machines

_{A Dell G15: its 4-zone keyboard is listed as zones.}

📦 Install

1. Dependencies (Python 3, PyGObject, GTK 4, libadwaita). On Ubuntu 24.04:

sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1

2. Install the service, the command line, the app and the GNOME extension:

./install.sh        # asks for sudo

3. Enable the Quick Settings toggle (GNOME 46). On X11, reload the shell with Alt+F2, r, Enter; on Wayland, log out and back in. Then:

gnome-extensions enable alienfix@zeecka.github.io

To remove everything, ./uninstall.sh deletes exactly what install.sh installed (it keeps a manifest).

🚀 Usage

The app

Open AlienFX LEDs from the GNOME menu. The pages follow your machine:

• Keyboard: the per-key drawing to scale, or the keyboard zones.
• Effects: one effect applied to any mix of lighting groups.
• Chassis: one color per zone, applied at once.
• Ripple: a ring of color from each key typed on the built-in keyboard, in any window. Color, speed and what shows underneath (the current colors or effect, or a plain color) are saved by the service.
• Machine: the detected model, the choice of model, key map import/export and the key map wizard.

The header bar holds the master switch and the brightness slider.

Quick Settings

The Lighting tile turns everything on or off. Its menu has the brightness slider, effect presets, the Typing ripple switch and a shortcut to the app.

Command line

alienfix status | layout | zones | models
alienfix color '#0050ff'                         # whole keyboard
alienfix keys ESC=#ff0000 Q=#00ff00              # per key (names from `alienfix layout`)
alienfix effect wave --tempo 5 '#ff0000' '#0000ff'
alienfix zone lid pulse --tempo 6 '#ff0000'      # zone ids from `alienfix zones`
alienfix model dell-g15-5520 | auto
alienfix brightness 60 | on | off

Tempo goes from 1 to 30; higher is slower.

🔒 Security model

• One owner. Only alienfixd opens the hidraw nodes. No udev rule opens them to users.
• Confined service. alienfixd runs as root but with no capabilities: empty CapabilityBoundingSet=, DevicePolicy=closed (hidraw, plus input devices read-only for the ripple), ProtectSystem=strict, PrivateNetwork=yes, SystemCallFilter=@system-service.
• Narrow API. The D-Bus interface only has lighting verbs, with no raw report pass-through. Every argument is re-parsed, bounded and rebuilt before it reaches a device (validate.py). The interface is described in docs/dbus-api.md.
• polkit. The active local session may change the lighting. Remote and inactive sessions may not.

🔬 How it was built

The Alienware m15 R7 support was reverse-engineered with a webcam pointed at the keyboard, because a successful command proves nothing about an LED. The full method, dead ends included, is in the write-up on the author's blog.

The other models come from the community mappings of alienfx-tools (MIT), akbl (GPL-3.0), OpenRGB (GPL-2.0) and AWCC (GPL-3.0). Only facts were taken from them (USB ids, light indices and masks, zone names), and tools/import_models.py records the exact source of each model. Thanks to their authors and contributors. 🙏

🛠️ Development

The project uses uv. PyGObject needs its build headers (sudo apt install libgirepository-2.0-dev libcairo2-dev pkg-config python3-dev), or skip it with uv sync --no-install-package pygobject --no-install-package pycairo: only the service and the app need it, not the tests.

uv sync                                                     # dev tools: ruff, ty, pylint
uv run python -m unittest discover -s tests                 # validation, encoders, models, ripple
uv run ruff check . && uv run ruff format --check .         # lint and format
uv run ty check                                             # types
uv run pylint src tests tools bin/alienfix bin/alienfixd gui/alienfx-leds

MOCK_MODEL=dell-g15-5520 python3 tests/mock_daemon.py &     # the real service, fake hardware, session bus
ALIENFIX_BUS=session gui/alienfx-leds                       # the app against it

Every push and pull request runs these checks in CI, plus ShellCheck, actionlint, zizmor, the GNOME extension and the data files; CodeQL scans the Python and JavaScript code weekly. Dependabot keeps the actions and tools up to date.

slsa-verifier verify-artifact alienfx_leds-0.2.0-py3-none-any.whl \
  --provenance-path alienfx-leds.intoto.jsonl --source-uri github.com/Zeecka/alienfx-leds --source-tag v0.2.0

📄 License

GPL-3.0-or-later.