Keyboard backlight: drive the ENE K5130 directly on Predator PHN16S-71

[HectorHuaripata]

Keyboard backlight: drive the ENE K5130 directly on Predator PHN16S-71

AI assistance disclosure. This work was done in a session assisted by an
AI agent (Claude): it proposed the experiments, wrote the probing tools and
authored the code. I ran everything on the affected machine and reported what
the hardware actually did. Every behavioural claim below was verified by a
human watching the keyboard, not inferred by the model — the firmware's
failure mode here is the silent no-op, so nothing was accepted on the basis
of a successful write or a matching read-back. Several intermediate
conclusions were wrong and are documented as such in docs/ENE_PROTOCOL.md.

Summary

On the Acer Predator Helios Neo 16S AI (PHN16S-71) the keyboard lighting page
looks like it works and does nothing. Setting zone colours succeeds, the value
is stored, the sysfs read-back returns exactly what was written — and the
keyboard keeps running the factory rainbow.

The cause is in firmware, not in Archer: the ACPI-WMI lighting path on this
model is partially implemented. Measured, with a single WMI call:

Field	Result
brightness	applied
per-zone RGB	stored, read back faithfully, never applied to the LEDs
effect mode	ignored

Because the read-back is faithful, every layer above it reports success. That
is what makes this bug so quiet, and it is worth stating plainly: on this model
the sysfs read-back is not evidence that anything happened.

The LEDs are actually driven by an ENE K5130 on I2C-1 at address 0x50,
exposed as a standard HID-over-I2C device (0018:0CF2:5130) carrying four
vendor feature reports. Writing those reports directly does work.

This PR adds that backend and routes the two keyboard setters through it,
keeping the existing sysfs write as a fallback for other hardware.

Changes

File	Change
gui/archer_ene.py	new — ENE K5130 protocol backend
gui/archer_daemon.py	both keyboard setters prefer ENE, sysfs fallback kept
gui/archer/pages/keyboard.py	effect list replaced with the verified effects
docs/ENE_PROTOCOL.md	new — full reverse-engineering notes
install-ene-keyboard.sh	optional deploy/rollback helper for existing installs

Nothing changes for hardware where the ENE is absent: archer_ene is imported
in a try, available() gates the feature, and the old code path is untouched.

The protocol, briefly

0xA1   4 bytes, read-only   "03 65 21 83" = device count, then device ids
0xA2   1 byte               select device            <- MANDATORY before 0xA4
0xA4  10 bytes              dev, mode, brightness, ?, ?, R, G, B, zone(16b LE)

Device ids: 0x21 keyboard (4 zones), 0x65 performance-mode button LED,
0x83 lid logo.

Two things that cost the most time to find, and that anyone extending this
should know:

Mode semantics are per device and do not carry over. On the keyboard mode 1
turns it off and mode 2 is static colour. On the button LED mode 1 is static
colour. Generalising from one device to another produces silent no-ops.

The zone field is a bitmask of the low four bits, so zones combine: 0x3
paints the left half in a single write. The high byte is ignored.

Verified keyboard effects: 2 static, 4 fade, 5 colour cycle, 6 colour cycle
fast, 7 rainbow wave. Modes 5 and 6 are not exposed by any existing tool for
this machine.

Why speed and direction are hidden in the UI

They correspond to bytes 3 and 4 of report 0xA4, whose meaning is not
established. The daemon accepts them for signature compatibility and ignores
them rather than guessing. A control that silently does nothing is worse than
no control, so both are hidden until decoded.

Safety notes

• The target is resolved by HID identity, never by hidraw number. The
  numbering is not stable on this machine: the ENE's reset times out during
  probe so it enumerates last, and the touchpad can rebind and reclaim
  hidraw0.
• The internal keyboard and the touchpad are on an explicit blacklist.
• Every value is range-checked against what the report descriptor declares.
• Modes >= 8 are rejected. While sweeping the button LED they coincided
  with fans starting and stopping, so in that range the report probably reaches
  the performance profile and not just the LED. Not thermally dangerous — the
  EC governs the fan curve — but out of scope for a lighting control.
• POLKIT_ACTIONS already maps both keyboard methods, so authorisation is
  unchanged and no new method bypasses it.

Testing

Verified on Predator PHN16S-71, BIOS V1.26, kernel 6.17 series, Arch Linux with
linuwu-sense 1.0.0 (DKMS).

Every result below was taken against a fully dark baseline — keyboard,
button LED and lid logo all off — so that anything lighting up admits no
alternative reading. That matters: an earlier round of this work reached a
wrong conclusion precisely because no baseline was recorded before the first
write.

• Zone addressing swept exhaustively: 0x1/0x2/0x4/0x8 each paint their
  own quarter, 0x3 paints the left half, 0xF and 0xFFFF the whole board,
  0x0100 does nothing.
• All five effects observed on the physical keyboard.
• Daemon restart reapplies saved lighting correctly through the new backend.

Known gaps

• 0x83 (lid logo) responds, but returned green/yellow/red for three
  consecutive writes of the same colour, so it does not interpret the RGB
  bytes the way the keyboard does. Not wired into the UI.
• Bytes 3 and 4 of 0xA4 undecoded.
• Lighting is not reapplied after suspend/resume; acer_suspend/acer_resume
  do not touch RGB.