LumaKey for Acer ALG AL15G-53

LumaKey is a native GTK desktop keyboard-light controller for the Acer ALG AL15G-53 on Fedora Linux. It controls the built-in RGB keyboard through the laptop's CLV0001 ACPI firmware bridge. The installed controller opens as a dedicated application window—there is no browser, website, or localhost service involved.

The interface supports the hardware's real capabilities:

• 17 validated firmware colors
• Four convenient static brightness levels plus off
• Fine-grained 0–255 intensity for smooth animation frames
• Physical Breathe, Spectrum, and Pulse animations
• Screen Sync with display-driven color and intensity
• Slow, medium, and fast animation speeds
• Live keyboard preview
• Saved settings and automatic wake restoration
• Automatic driver and hardware detection

The ALG firmware controls the whole keyboard as one zone, so all keys animate together. LumaKey creates its effects in software by sequencing only the driver's validated color command. Breathe uses a 32-frame eased curve, Spectrum uses 48 interpolated RGB frames, and the fastest mode is capped at ten firmware writes per second. It does not call undocumented experimental ACPI functions. Effects run while the native LumaKey application is running.

Screen Sync

Choose Screen Sync, set a maximum intensity and response speed, then select Start screen sync. LumaKey samples the KDE desktop about once or twice per second, extracts an ambient hue and perceptual brightness, and eases the keyboard toward it at up to ten light updates per second. This keeps changes smooth while avoiding excessive screen captures or firmware calls.

Screen Sync is local-only. Spectacle captures into a private temporary directory, LumaKey opens and immediately unlinks each frame, downsamples it to 64×36 for color analysis, and does not transmit or retain screenshots. KDE Spectacle and Python Pillow are required; both are already available on the target Fedora KDE installation.

Because the ALG firmware exposes the built-in keyboard as one lighting zone, the sampled color applies to every key together rather than to individual areas of the display.

Sleep and wake recovery

The laptop firmware switches the keyboard lighting off during suspend and does not restore it on its own. LumaKey listens for the system's PrepareForSleep signal and reapplies the last saved static color, animation, or Screen Sync mode shortly after wake. It retries while the driver is coming back online.

Closing the LumaKey window hides it instead of stopping it, so animations and wake recovery continue. Click the LumaKey icon again to reopen the same window. Choose Quit LumaKey from the window menu when you really want to stop the background process. An enabled per-user background service starts wake recovery at graphical login and does not need administrator access.

Install

LumaKey targets Fedora KDE. Install its application and driver build dependencies first:

sudo dnf install python3-gobject gtk4 libadwaita python3-cairo \
  python3-pillow spectacle git patch dkms gcc make kernel-devel-$(uname -r)

Then clone the project and run its two guarded setup scripts:

git clone https://github.com/GP-commits/Acer-ALG-Keyboard-Light-Control.git
cd Acer-ALG-Keyboard-Light-Control
./setup-driver.sh
./install-app.sh

setup-driver.sh asks for administrator authentication because it builds and loads a DKMS kernel module. install-app.sh needs no administrator access: it copies the native app into your per-user data directory, adds its KDE launcher, and enables the wake-recovery service.

The driver installer verifies the laptop model and CLV0001 device before doing anything. It builds the pinned source with LumaKey's alg-rgb 0.2.1-lumakey1 smooth-intensity patch. Log out and back in after setup if the keyboard device is not immediately writable.

The application installer copies the runtime files to a stable location, so moving or deleting the clone afterward will not break the launcher. Clone or pull the project again and rerun both scripts when installing an update.

Launch

Search for LumaKey in the KDE application menu. The launcher opens a single native Wayland window; starting it again focuses the existing window. LumaKey does not open a TCP port or make keyboard controls available over the network.

For development, it can also be started directly from a checkout:

python3 launch.py

The repository retains the original local browser prototype for reference and backend compatibility, but neither the application launcher nor background service starts it.

Tests

python3 -m unittest discover -s tests -v

Driver credit and safety

Hardware access uses the GPL-licensed alg-rgb driver by Kaushik Sarkar, pinned to commit 038d6289dd38f92d9c321d87ee6203fc63767143. It was reverse engineered and verified on the AL15G-53. The local GPL-compatible patch adds validated raw RGB input, 0–255 intensity, and quiet per-frame logging. LumaKey exposes only the known keyboard ACPI function 0x67; experimental firmware functions are not used.

LumaKey and its driver patch are licensed under GPL-2.0-or-later; see LICENSE and NOTICE. LumaKey is an independent project and is not affiliated with, endorsed by, or supported by Acer Inc. Installing a third-party kernel module always carries some risk, so review the scripts and keep backups before proceeding.