Venator for Linux

A Linux replacement for Acer's Windows-only PredatorSense utility, built for the Acer Predator Helios 16 (PH16‑71) and related Predator laptops. It gives you full control of the per‑key RGB keyboard, the rear lightbar, power/thermal profiles, and battery health — from a CLI, a terminal UI, or systemd at login.

Status: actively developed and daily‑driven on a PH16‑71. Keyboard RGB, rear lightbar, power profiles (with AC/battery policy & live switching), battery health limit, fans/thermals, profiles and boot‑restore all work today. See the Roadmap for what's next.

---

Table of contents

• Features
• Supported hardware
• Requirements
• Dependencies
• Installation
• Uninstall
• Usage
  • Terminal UI
  • Keyboard RGB
  • Designs, animations & per‑key paint
  • Rear lightbar
  • Unified keyboard + lightbar
  • Power & thermal
  • Battery health
  • Profiles & restore‑at‑login
• How it works
• Project layout
• Roadmap
• Troubleshooting
• Contributing
• Credits
• License

---

Features

• Per‑key RGB keyboard — 13 named hardware effects (breathing, wave, rainbow, ripple, …), solid colours, brightness control, and a full 384‑byte per‑key framebuffer for arbitrary layouts and images.
• Designs & animations — ship‑with presets plus a dead‑simple Python API for your own. Animations run as a detached background worker.
• Per‑key painting by name — paint W,A,S,D or F1 directly once you've recorded a keymap.
• Rear lightbar — all firmware effect modes including the Wireshark‑recovered Static (Direct) mode, with colour/brightness/speed.
• Unified mode — drive keyboard and lightbar in lockstep from one theme or one synchronised animation.
• Power & thermal — switch platform profiles (Eco/Quiet/Balanced/ Performance/Turbo), read live fan RPMs and CPU/GPU/chassis temps.
• AC/battery power policy — separate profile for plugged‑in vs on‑battery, applied live the instant you plug/unplug, restored at login. Battery is limited to low‑heat profiles unless you opt in.
• Plays nice with other power managers — detects and can detach power-profiles-daemon, tuned, auto-cpufreq, system76-power, and tlp.
• Battery health — 80 % charge cap and calibration cycle.
• Restore at login — your last keyboard + lightbar scheme and the right power profile come back automatically.
• CLI + TUI, one brain — the CLI and the Textual TUI drive the same logic; sysfs stays canonical.
• Survives kernel upgrades — on Fedora a kernel-install hook rebuilds and re‑signs the module on every new kernel (on Arch/CachyOS, re-run the installer after an upgrade).

Supported hardware

Component	Status	Notes
Keyboard RGB	✅	Chicony MCU 04F2:0117, USB‑HID FF02 vendor interface
Rear lightbar	✅	EC via WMBH AcerGamingFunction (method 20)
Power profiles	✅	mainline acer-wmi platform_profile
Fans / temps	✅	acer hwmon
Battery limit	✅	our kernel module (WMBE), with mainline fallback
Per‑zone RGB	🚧	works in Windows; no working Linux path found yet (Roadmap)

Primary target is the PH16‑71. Other Predator/Helios models with the same keyboard MCU and WMI GUIDs are likely to work — reports and PRs to docs/MODELS.md welcome.

Tested on:

Device	OS	Kernel	BIOS
PH16‑71	Fedora 43	7.0.9-105.fc43.x86_64	1.16
PH16‑71	Fedora 43	7.0.10-101.fc43.x86_64	1.16
PH16‑71	CachyOS	7.0.12-1-cachyos	1.16

Requirements

• A recent kernel with acer-wmi (Fedora 43+ exposes platform_profile, fans, and temps out of the box).
• The module is built unsigned by default. If Secure Boot enforces module signatures, install with --secureboot and enroll a key once (the installer walks you through it). See With Secure Boot.

See Dependencies for the exact packages to install per distro.

Dependencies

Install these before running the installer.

Build (kernel module)

Kernel headers for your running kernel plus a C toolchain:

Distro	Packages
Fedora / RHEL-like	kernel-devel-$(uname -r) make gcc
Arch / CachyOS	base-devel, linux-headers (or linux-cachyos-headers); plus clang lld llvm for CachyOS's Clang/LLD-built kernels
Debian / Ubuntu (Mint, Pop!_OS, …)	linux-headers-$(uname -r) build-essential
Any other distro	your distro's kernel-headers package for $(uname -r), plus make and gcc

Runtime (CLI + TUI)

• python3 — the CLI uses the standard library only, nothing else needed.
• Optional python3-textual — the terminal UI (venator tui).
• Optional python3-pillow — image painting (venator rgb image).

Secure Boot (only with --secureboot)

• mokutil to enroll a signing key (Fedora, Debian/Ubuntu), and/or
• sbctl (Arch/CachyOS) or an existing akmods / shim-MOK key.

Details in With Secure Boot.

Installation

git clone https://github.com/Exyons/Venator.git
cd Venator

# One command does everything: userspace (CLI, assets, udev rule, systemd
# units, modules-load.d) + the kernel module for your distro.
sudo ./install.sh

With no flag, install.sh runs --auto: it reads /etc/os-release, picks the routine that fits your distro, installs the userspace half, builds + loads the kernel module, creates the venator group, and enables the user services — all in one shot. Auto-detection covers Fedora, Arch, and Debian families — just run sudo ./install.sh. On any other distro, run sudo ./install.sh --manual for the universal one-shot build.

The module is built unsigned by default (non-Secure Boot). If you run Secure Boot, add --secureboot — see With Secure Boot below.

The make targets still work as thin wrappers — sudo make module-install (= ./install.sh), hook-install, manual-install, with SECUREBOOT=1 to sign — but ./install.sh is the recommended single entry point.

What runs on your distro

The default --auto recognizes three families and runs the matching routine — no flag needed for any of them; just sudo ./install.sh. Only other, unrecognized distros need an explicit --manual.

Fedora (and RHEL-likes) — --auto picks the hook routine: installs a kernel-install hook at /etc/kernel/install.d/99-venator.install. It stages the sources to /usr/src/venator/ and rebuilds the module automatically on every kernel upgrade.

Arch / CachyOS (and derivatives) — --auto picks the manual one-shot: builds the module for the current kernel, installs to /lib/modules/$(uname -r)/extra/, and loads it. CachyOS kernels are Clang/LLD-built, so the build switches to LLVM=1 automatically (detected from CONFIG_CC_IS_CLANG) — building with GCC against a Clang kernel fails with unrecognized command-line option '-mllvm' and friends. Re-run sudo ./install.sh after each kernel upgrade.

Debian / Ubuntu (and Mint, Pop!_OS, …) — --auto picks the same manual one-shot build for the current kernel, installed to /lib/modules/$(uname -r)/extra/ and loaded. Re-run sudo ./install.sh after each kernel upgrade.

Any other distro — not auto-detected, so run sudo ./install.sh --manual explicitly. Works wherever you have the kernel headers for your running kernel, a C toolchain (make + gcc, or clang/lld for a Clang kernel), and systemd — the same one-shot build. Re-run sudo ./install.sh --manual after each kernel upgrade.

Build packages for each are listed under Dependencies. Auto-rebuild on kernel upgrade is currently Fedora-only (via the kernel-install hook); a DKMS path for the other distros is planned. Until then, re-run the installer after a kernel upgrade.

Without Secure Boot (default)

Nothing extra to do — sudo ./install.sh builds and loads an unsigned module. This is the right path when Secure Boot is off (and on CachyOS even with Secure Boot on, since its kernel doesn't enforce module signatures — lockdown is none). If Secure Boot is enforcing signatures, the installer warns you and the module won't load until you use the Secure Boot path below.

With Secure Boot

Add --secureboot (or SECUREBOOT=1 if you use the make wrapper):

sudo ./install.sh --secureboot

This signs the module with an auto-detected key. The installer looks, in order, for an akmods key (/etc/pki/akmods/), a shim MOK (/var/lib/shim-signed/mok/), then an sbctl db key (/var/lib/sbctl/keys/db/). Per distro:

• Fedora — if no key exists it generates an akmods-style one and prints a sudo mokutil --import … line. Run it, reboot, and enroll the key in the MOK Manager screen. The kernel-install hook re-signs on every upgrade.
• Arch / CachyOS — if you manage Secure Boot with sbctl, the installer signs with your db keypair. Note sbctl sign only handles EFI binaries; kernel modules are signed with the kernel's sign-file using that same key, which the installer does for you.
• Custom keys (any distro) — provide your own signing key explicitly with --mok-priv PATH --mok-cert PATH (these imply --secureboot). Useful if you don't use sbctl/akmods or keep your MOK elsewhere: sudo ./install.sh --manual --mok-priv ~/MOK.priv --mok-cert ~/MOK.der (swap --manual for --hook on Fedora).

If --secureboot is set but no key can be found, the install aborts with instructions rather than installing a module that won't load.

install.sh also drops two user services and enables them for you: venator-restore (restore at login) and venator-powerwatch (live AC/battery profile switching). A system venator-perms unit hands the relevant /sys entries to the venator group so you don't need sudo for everyday use:

sudo usermod -aG venator,input "$USER"   # then log out / back in

Full details in docs/INSTALL.md.

Uninstall

One command removes everything install.sh set up — the kernel module, the userspace CLI + assets, the udev rule, the systemd units, the modules-load.d entry, and the venator group:

sudo ./install.sh --uninstall

On Fedora it also tears down the kernel-install hook and the staged sources at /usr/src/venator/.

Left in place:

• Per-user data under ~/.config/venator/ (profiles, keymap, custom designs/animations) and ~/.cache/venator/.
• Signing keys at /etc/pki/akmods/ and /var/lib/sbctl/ (shared with other packages).

To also wipe the per-user data, run sudo make purge. (The make wrappers still work too: sudo make uninstall ≈ ./install.sh --uninstall.)

Usage

Terminal UI

venator tui

A Textual UI with a live keyboard preview and tabs for Home / Keyboard / Power / Battery / Lightbar / Unified. Every tab scrolls, the Power tab is split into power controls (left) and live fans/temps (right). Works over SSH.

Keyboard RGB

venator status                               # current state
venator rgb static '#ff0000'                 # solid red
venator rgb effect breathing --color '#00f'  # breathing blue
venator rgb effect rainbow                   # hardware palette
venator rgb fill '#ff00ff'                   # per-key buffer, all magenta
venator rgb off
venator brightness 200
venator effect-id 0x14                       # raw EFF byte override

High‑level rgb subcommands stage and apply in one go. Low‑level mode/color/brightness/effect-id only stage — add --apply or run venator apply.

Designs, animations & per‑key paint

# One-shot static designs
venator rgb design --list
venator rgb design pride
venator rgb design gaming --brightness 200

# Continuous animations (detached background worker)
venator rgb animate --list
venator rgb animate rolling_rainbow
venator rgb animate fire --timeout 60        # auto-off after 60s

# Paint an image across the 128 cells (needs Pillow)
venator rgb image wallpaper.png

# Paint by key name. A full PH16-71 keymap is installed by `make
# install`, so this works out of the box; run `map discover` only if you
# want to re-record it for a different layout.
sudo venator rgb key F1 '#ff0000'
sudo venator rgb keys 'W,A,S,D' '#00ff00'
sudo venator map discover                    # optional: re-record

While an animation is running, the keyboard's Fn brightness up/down keys dim/brighten it live (the MCU ignores those keys in per-key mode, so the animator watches for them and adjusts brightness itself).

Write your own designs & animations

Drop a file into your config dir and it is picked up automatically:

• designs → ~/.config/venator/designs/ (.py or .json)
• animations → ~/.config/venator/animations/ (.py)

They then appear under venator rgb design --list / venator rgb animate --list. In the TUI they show up as buttons on the Keyboard tab's Designs / Animations sub‑tabs; press Refresh (or Ctrl‑R) to rescan after adding a file. A user file that shares a name with a shipped one wins.

Both use one contract: a render(t, num_cells, keymap) that returns num_cells * 3 bytes, one R,G,B triplet per cell (128 cells on the PH16‑71). A design is rendered once with t = 0; an animation is rendered FPS times a second with t = seconds elapsed.

A design, ~/.config/venator/designs/split.py (left half red, right blue):

NAME = "split"
DESCRIPTION = "left half red, right half blue"

def render(t, num_cells, keymap):
    buf = bytearray(num_cells * 3)
    for i in range(num_cells):
        r, g, b = (255, 0, 0) if i < num_cells // 2 else (0, 0, 255)
        buf[i*3 : i*3+3] = bytes((r, g, b))
    return bytes(buf)

Apply it: venator rgb design split (or click it in the TUI).

An animation, ~/.config/venator/animations/pulse.py (whole board breathes):

import math

NAME = "pulse"
DESCRIPTION = "whole keyboard breathes magenta"
FPS = 30

def render(t, num_cells, keymap):
    level = (math.sin(t * math.pi) + 1) / 2          # 0..1, ~0.5 Hz
    r, g, b = int(255 * level), 0, int(120 * level)
    return bytes((r, g, b)) * num_cells

Run it: venator rgb animate pulse (Ctrl‑C to stop). To light specific physical keys, read keymap["keys"].get("W") for a cell index; that needs a keymap (venator map discover). Full reference: cli/designs/README.md and cli/animations/README.md.

Rear lightbar

venator lightbar status
venator lightbar modes                       # list effect modes
venator lightbar set static '#00ffcc' --brightness 150
venator lightbar mode breathing
venator lightbar off
venator lightbar wake                         # recover a stuck-off bar

Unified keyboard + lightbar

venator unified list                          # themes
venator unified apply ocean
venator unified anim list                     # synchronised animations
venator unified anim rainbow_sync
venator unified anim dawn --timeout 120

Power & thermal

venator power                                 # current + choices + active managers
venator power turbo                           # Eco/Quiet/Balanced/Performance/Turbo
venator thermal                               # fan RPMs + CPU/GPU/chassis temps

# AC vs battery policy — applied at login AND live on plug/unplug.
# First-use defaults: Balanced on AC, Quiet on battery.
venator power-policy                           # show policy + power source
venator power-policy ac performance
venator power-policy battery balanced
venator power-policy battery turbo --advanced  # high power on battery (warns)

# Other power managers (PPD, tuned, auto-cpufreq, system76-power, tlp)
# fight us for platform_profile. Detach/restore them all at once:
venator power --detach-ppd
venator power --attach-ppd

The venator-powerwatch service applies the matching profile the moment you plug or unplug — no need to wait for the next login.

Battery health

venator battery info
venator battery limit 80          # cap charge at 80% (extends pack life)
venator battery limit off         # back to 100%

Profiles & restore‑at‑login

Every rgb and lightbar command auto‑snapshots a default profile (including a running animation). The venator-restore user service replays it — keyboard, lightbar, and the power profile for the current power source — at every login.

venator profile save my-setup
venator profile load my-setup
venator profile list

How it works

flowchart LR
    subgraph Userspace
      CLI[venator CLI]
      TUI[Textual TUI]
    end
    subgraph Kernel
      MOD[venator.ko]
    end
    subgraph Firmware/HW
      HID[USB-HID keyboard MCU]
      WMI[ACPI WMI: WMBH / WMBE]
      ACER[mainline acer-wmi]
    end

    CLI & TUI --> SYSFS[/sys/class/venator/*\n/sys/firmware/acpi/platform_profile/]
    SYSFS --> MOD
    MOD -->|HID reports| HID
    MOD -->|wmi_evaluate_method| WMI
    SYSFS -.platform_profile / hwmon.-> ACER

Loading

On the PH16‑71 the keyboard LEDs hang off the keyboard MCU (04F2:0117, Chicony) and are driven over USB‑HID, not the EC/WMI RGB path that the community modules (Linuwu-Sense, acer-predator-turbo-and-rgb-keyboard-linux-module) assume — which is why those load cleanly but light nothing on this chassis. Commands are 8‑byte HID feature reports; per‑key frames are 8×64‑byte interrupt‑OUT bursts (128 cells × {0x00,R,G,B}). The rear lightbar uses the EC via the WMBH WMI method, and battery via WMBE. The userspace sysfs ABI is documented in docs/sysfs.md.

Project layout

install.sh       OS-aware kernel-module installer (build/sign/install/uninstall)
kernel/          out-of-tree module (HID + WMBH/WMBE) + DKMS config
cli/             venator — the CLI (stdlib Python); designs/, animations/, keymaps/
tui/             Textual TUI (tui.py) + shared client library (client.py)
systemd/         restore-at-login, powerwatch, and perms units
udev/            group-based sysfs permissions
modules-load.d/  auto-load the module at boot
packaging/fedora Fedora kernel-install hook (99-venator.install) used by install.sh
docs/            sysfs.md, INSTALL.md, MODELS.md

Roadmap

Planned / wanted — contributions very welcome:

1. Custom boot logo — replace the BIOS splash image.
2. USB powered‑off charging — toggle charging the USB‑A port while the laptop is asleep/off.
3. Per‑zone Lightbar RGB control — works in Windows but no working Linux WMI path has been found on the PH16‑71 yet.
4. Hosted documentation wiki — move the deep docs to a browsable web wiki.

Also on the list: broader model coverage.

Troubleshooting

• Module loads but keyboard stays dark: make sure wmbh_probe isn't holding the WMI GUID (sudo rmmod wmbh_probe) and that you're on a PH16‑71‑class board.
• Key was rejected by service on load: Secure Boot — enroll the signing cert: sudo mokutil --import /etc/pki/akmods/certs/*.der, reboot, choose Enroll MOK.
• Power profile keeps reverting on plug/unplug: another power manager is active. Run venator power to see which, then venator power --detach-ppd.
• Hook built nothing after a kernel upgrade: install matching kernel-devel and check journalctl -t venator-hook -b.
• unrecognized command-line option '-mllvm' (and friends) on CachyOS: the kernel is Clang/LLD-built and the module tried to build with GCC. The installer auto-detects this and passes LLVM=1; if you build by hand, run make -C kernel LLVM=1. Needs clang lld llvm installed.
• Kernel headers missing: install.sh aborts with a per-distro install hint. Install the headers for your running kernel (see Dependencies) and re-run.

Contributing

Issues and PRs welcome — especially keymaps for new models, additional designs/animations, and anything on the Roadmap. The kernel module is GPL‑2.0, so kernel contributions must be GPL‑2.0 compatible. Keep the CLI dependency‑free (stdlib only) so it runs anywhere.

Credits

• The Acer Linux community, including Linuwu‑Sense and acer‑predator‑turbo‑and‑rgb‑keyboard‑linux‑module, for prior reverse‑engineering of the WMI paths.
• OpenRGB — the SDK capture that revealed the lightbar's Static (Direct) mode.

License

GPL‑2.0‑only. See LICENSE.

Disclaimer: this is an unofficial project, not affiliated with or endorsed by Acer. It writes to embedded‑controller / WMI interfaces; use at your own risk. Every command corresponds to a method or HID report observed on real hardware, but firmware varies between models and BIOS revisions.