MrBlakeandClaude Opus 5.5
571cfcca2a
New Power page: - toggle for the firmware's 30 s keyboard backlight timeout - idle timeout for keyboard and lightbar, separately for AC and battery; predatord watches all input devices and restores the lighting on the next input - battery rules: dimmed keyboard brightness, keyboard off, lightbar off The rules only change what is sent to the hardware; the saved lighting settings stay untouched. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
196 lines
9.6 KiB
Markdown
196 lines
9.6 KiB
Markdown
# Predator Control
|
||
|
||
An open-source **PredatorSense replacement for Linux**, built for the
|
||
**Acer Predator Helios 16 (PH16-71)** and tested on CachyOS with KDE Plasma 6.
|
||
|
||
It gives you everything the Windows control center does – performance modes,
|
||
fan control, per-key keyboard RGB, the rear lightbar and battery health – as a
|
||
desktop app, a **Plasma panel widget**, and a command line tool.
|
||
|
||
|
||
|
||
## Features
|
||
|
||
| Area | What you get |
|
||
|------|--------------|
|
||
| **Performance** | Eco / Quiet / Balanced / Performance / Turbo (ACPI platform profiles), separate profiles for AC and battery with automatic switching when you plug in or unplug |
|
||
| **Fans** | Auto, Max (cooler boost), manual speed per fan, or a **custom temperature curve** for CPU and GPU with drag-and-drop editor |
|
||
| **Keyboard RGB** | 12 hardware effects (static, breathing, rainbow wave, ripple, neon, rain, explosion, pulse, stars, meteor, aura, …), colour, brightness, hidden effect variants, presets |
|
||
| **RGB Studio** | Paint individual keys with the mouse, live preview on the keyboard, quick fills (WASD, arrows, F-row, numpad …), German ISO and US ANSI layouts |
|
||
| **Lightbar** | All rear lightbar effects with colour, brightness and speed – or let it follow the keyboard |
|
||
| **Battery** | live charging indicator in watts with power graph and time until full / remaining, 80 % charge limit, calibration, health and cycles |
|
||
| **Firmware options** | Boot animation & sound, LCD overdrive, keyboard backlight timeout, USB charging while off |
|
||
| **Monitoring** | CPU/GPU temperatures, fan RPM, CPU load and clock, memory – without waking the dGPU |
|
||
| **Panel widget** | Click the icon in the Plasma panel to change everything quickly; buttons open the full app directly on the right page (e.g. RGB Studio). Middle-click cycles the performance mode |
|
||
| **Persistence** | All settings are restored at boot and after suspend/resume |
|
||
|
||
<p>
|
||
<img src="docs/screenshots/rgb.png" width="49%" alt="RGB Studio">
|
||
<img src="docs/screenshots/fans.png" width="49%" alt="Fan curves">
|
||
</p>
|
||
|
||
## Supported hardware
|
||
|
||
| Model | Keyboard MCU | Status |
|
||
|-------|--------------|--------|
|
||
| Acer Predator Helios 16 **PH16-71** | Chicony `04F2:011A` / `04F2:0117` | primary target |
|
||
|
||
Other Predator/Helios models with the same keyboard controller and WMI
|
||
interfaces will likely work. Reports are welcome – please include the output of
|
||
`predatorctl status`, `lsusb | grep 04f2` and `cat /sys/class/dmi/id/product_name`.
|
||
|
||
## Installation
|
||
|
||
### pacman package (Arch, CachyOS, Manjaro, EndeavourOS …) – recommended
|
||
|
||
Download `predator-control-<version>-any.pkg.tar.zst` from the
|
||
[releases page](https://git.mrblake.cc/MrBlake/Cachy-Predator-Keyboard/releases) and install it:
|
||
|
||
```bash
|
||
sudo pacman -S --needed linux-cachyos-headers clang lld llvm # headers for your kernel (stock Arch: linux-headers)
|
||
sudo pacman -U predator-control-*-any.pkg.tar.zst
|
||
```
|
||
|
||
The service starts automatically and the kernel module is built by DKMS for every installed kernel.
|
||
To build the package yourself: `cd packaging/arch && makepkg -f`.
|
||
|
||
> Switching from `install.sh` to the package? Run `sudo ./uninstall.sh` first (your settings are kept).
|
||
|
||
### Install script (any distribution)
|
||
|
||
Requirements: a kernel with `acer-wmi` (any recent kernel), Python 3, PySide6,
|
||
DKMS and kernel headers. On Arch / CachyOS / Manjaro the installer pulls in everything.
|
||
|
||
```bash
|
||
git clone https://git.mrblake.cc/MrBlake/Cachy-Predator-Keyboard.git
|
||
cd Cachy-Predator-Keyboard
|
||
sudo ./install.sh
|
||
```
|
||
|
||
Then:
|
||
|
||
* **App:** start *Predator Control* from the application menu, or run `predator-control`
|
||
* **Panel widget:** right-click the panel → *Add or Manage Widgets…* → search for *Predator Control*
|
||
and drag it into the panel – or enable it under *System Tray Settings → Entries*.
|
||
If it does not show up yet, log out and back in.
|
||
* **CLI:** `predatorctl status`
|
||
|
||
On other distributions install the dependencies yourself and run `sudo ./install.sh --no-deps`.
|
||
|
||
**Secure Boot:** the kernel module is unsigned. With Secure Boot enforcing module
|
||
signatures you have to sign `predator_wmi` yourself (e.g. with `sbctl` or a MOK key).
|
||
Keyboard RGB and performance profiles work without the module.
|
||
|
||
Uninstall with `sudo pacman -R predator-control` (package) or `sudo ./uninstall.sh` (add `--purge` to also delete your settings).
|
||
|
||
## Power settings
|
||
|
||
The **Power** page controls when the lighting switches off: the firmware's 30-second backlight
|
||
timeout can be disabled, a custom idle timeout can be set separately for AC and battery, and on
|
||
battery the keyboard can be dimmed or turned off and the lightbar disabled.
|
||
|
||
## Predator key
|
||
|
||
Pressing the **Predator key** opens Predator Control, just like PredatorSense on Windows.
|
||
On the **System** page you can instead make it switch to the next performance mode, or disable it.
|
||
|
||
## Updates
|
||
|
||
Installed via the pacman package, Predator Control updates itself: the service checks for new
|
||
releases every 6 hours, and a notice with an *Install* button appears on the **System** page, in the
|
||
sidebar and in the panel widget. Downloads are verified with the SHA-256 from the release notes and
|
||
installed with `pacman -U`. From the terminal: `predatorctl update` (or `--check`).
|
||
Automatic checks can be turned off on the System page.
|
||
|
||
If you installed with `install.sh`, update with `git pull && sudo ./install.sh`.
|
||
|
||
## Usage
|
||
|
||
### Panel widget
|
||
|
||
| Action | Result |
|
||
|--------|--------|
|
||
| Left click | Opens the quick-settings popup |
|
||
| Middle click | Cycles to the next performance mode |
|
||
| *RGB Studio…* | Opens the app on the RGB page |
|
||
| *Manual* / *Curve* (fans) | Switches mode and opens the fan page |
|
||
|
||
### Command line
|
||
|
||
```bash
|
||
predatorctl status # overview
|
||
predatorctl profile performance # low-power | quiet | balanced | balanced-performance | performance
|
||
predatorctl profile-cycle
|
||
predatorctl fans auto | max | curve
|
||
predatorctl fans custom 60 80 # CPU 60 %, GPU 80 %
|
||
predatorctl kbd static ff0000 -b 255 # effect, colour, brightness (0-255)
|
||
predatorctl kbd off | on
|
||
predatorctl kbd-brightness +25
|
||
predatorctl lightbar wave --color 00d4ff --speed 7
|
||
predatorctl lightbar --sync on # lightbar follows the keyboard
|
||
predatorctl battery-limit on
|
||
predatorctl update # check for and install updates
|
||
predatorctl open rgb # open the app on a page
|
||
```
|
||
|
||
Tip: bind `predatorctl profile-cycle` or `predatorctl kbd-brightness +25` to a
|
||
keyboard shortcut in *System Settings → Shortcuts*.
|
||
|
||
## How it works
|
||
|
||
```
|
||
Plasma widget ──┐ ┌── /sys/firmware/acpi/platform_profile (profiles)
|
||
Qt app ─────────┼── Unix socket ──► predatord (root) ──┼── /dev/hidrawN (keyboard MCU, USB HID)
|
||
predatorctl ────┘ state.json ◄──┘ └── predator_wmi kernel module ── ACPI WMI
|
||
(fans, lightbar, battery, firmware options)
|
||
```
|
||
|
||
* **predatord** – a small Python daemon running as root. It owns all hardware access,
|
||
stores settings in `/etc/predator-control/config.json`, writes a live state snapshot to
|
||
`/run/predator-control/state.json`, restores everything at boot/resume, switches
|
||
profiles on AC changes and runs the fan curve. Only root and members of the `wheel`
|
||
group may send commands (checked via `SO_PEERCRED`; configurable via `allowed_group`).
|
||
* **predator_wmi** – a ~200 line kernel module that binds to Acer's gaming, battery and
|
||
APGE WMI interfaces and exposes a single root-only sysfs attribute to call WMI methods.
|
||
All protocol knowledge stays in user space.
|
||
* **Keyboard** – talks directly to the keyboard MCU through hidraw (8-byte feature reports
|
||
plus a 512-byte per-key frame) – no kernel driver needed.
|
||
* **Temperatures and fan RPM** come from the mainline `acer-wmi` hwmon and `coretemp`.
|
||
|
||
### Correcting the key map
|
||
|
||
The LED matrix positions of a few keys (ISO `#` and `<`) are best guesses. If a key
|
||
lights up in the wrong place in the RGB Studio, create
|
||
`~/.config/predator-control/layout.json` with `{"<key label>": <cell number>}` entries
|
||
(cell = column × 6 + row, row 0 = bottom row).
|
||
|
||
## Troubleshooting
|
||
|
||
| Problem | Fix |
|
||
|---------|-----|
|
||
| *"predatord is not running"* | `sudo systemctl enable --now predatord`, then `journalctl -u predatord` |
|
||
| *"permission denied"* | add yourself to `wheel`: `sudo usermod -aG wheel $USER`, log in again |
|
||
| Fans / lightbar / battery greyed out | the module is not loaded: `sudo modprobe predator_wmi`, check `dmesg` |
|
||
| Keyboard does not react | check `predatorctl status` and that `lsusb` shows `04f2:011a` or `04f2:0117` |
|
||
| Profile changes back on its own | another tool also manages `platform_profile` (e.g. *power-profiles-daemon* or *tuned*); disable automatic switching in either tool |
|
||
| Widget missing after install | log out and back in, or run `plasmashell --replace &` |
|
||
|
||
## Credits
|
||
|
||
The hardware protocols were reverse-engineered by others – this project would not exist without them:
|
||
|
||
* [Venator](https://github.com/Exyons/Venator) – PH16-71 keyboard MCU protocol, lightbar, key map (GPL-2.0)
|
||
* [Linuwu-Sense](https://github.com/0x7375646F/Linuwu-Sense) – fan control, battery health and firmware option WMI calls (GPL-2.0)
|
||
* The mainline Linux `acer-wmi` driver – platform profiles and sensors
|
||
|
||
## Disclaimer
|
||
|
||
This is an independent community project. It is **not affiliated with, endorsed by or
|
||
supported by Acer Inc.** "Predator", "Helios" and "PredatorSense" are trademarks of
|
||
Acer Inc. The software talks directly to firmware interfaces – use it at your own risk,
|
||
especially custom fan curves: keep an eye on temperatures.
|
||
|
||
## License
|
||
|
||
[GPL-2.0-only](LICENSE)
|