Skip to content

Latest commit

 

History

65 Commits

Folders and files

Repository files navigation

OMEN Gaming Hub for Linux

CI Release License: MIT

Version: v1.2.0 · License: MIT · Language: English

An OMEN Gaming Hub analogue for Linux: HP Victus/OMEN keyboard backlight, power modes, fans, monitoring and overlay (Shift+F2 replacement).

Vibe Coding — the project is built with active support of an AI agent together with the user. Development starts at docs/DEVELOPMENT.md (current state, roadmap, agent rules).

Strategy — simple first: stage 1 (basic CLI: light, fans, temperatures), stage 2 (TUI on Textual), stage 3 (effects and power profiles). Details — docs/DEVELOPMENT.md §4.

Keywords: HP Victus keyboard backlight Linux, OMEN Gaming Hub for Linux, laptop fan control, CPU/GPU power limits 5–25 W, Textual TUI, Arch/Hyprland.

Contents: Screenshots · Installation · Commands · TUI · Fans · Power · Localization · Project structure · Contributing

Screenshots (TUI)

Victus Suite TUI screenshot: Power tab with the whole-laptop watt slider on fixed 8/10/15/20/25 W steps, CPU cap and on-screen power hints

Power tab — whole-laptop power cap on fixed watt steps, with on-screen hints, a settling timer and battery ETA.

Victus Suite TUI screenshot: Backlight tab with keyboard brightness slider and per-key RGB controls

Backlight tab — HP Victus keyboard brightness 0–100 % and per-key RGB.

Victus Suite TUI screenshot: Fans tab with fan curve editor and live RPM readout

Fans tab — fan curves, manual control and SMART autopilot with live RPM.

Installation (v1.2.0)

From a release (recommended):

# dependencies (Arch/Omarchy)
sudo pacman -S --needed python python-gobject ayatana-appindicator3 foot
python -m pip install --user textual      # TUI engine (8.x)

mkdir -p ~/Work && cd ~/Work
curl -L -o vs.tar.gz https://github.com/bleiz2000/victus-suite/releases/download/v1.2.0/victus-suite.tar.gz
tar xzf vs.tar.gz && cd victus-suite
./install.sh                              # symlinks + menu entry

From source:

git clone https://github.com/bleiz2000/victus-suite.git ~/Work/victus-suite
cd ~/Work/victus-suite && ./install.sh

./install.sh also creates the Victus Suite entry in your application menu (~/.local/share/applications/victus-suite.desktop, Exec=… --window, black-and-white icon in ~/.local/share/icons/hicolor/) — launch it from the launcher, no terminal needed.

Optional — passwordless EC writes (otherwise every write asks for sudo):

echo "$USER ALL=(root) NOPASSWD: $PWD/bin/victus-kbd" | sudo tee /etc/sudoers.d/victus-suite
sudo chmod 440 /etc/sudoers.d/victus-suite

The same rule covers the fan backend: the TUI writes PWM as sudo -n …/bin/victus-kbd fans <cmd> (fans → vertil/tools/fanctl.py), so the vertil tab never asks for a password either.

Run:

victus_tui --window    # floating 960×540 window (foot)
victus_tui             # in the current terminal
victus_tui --tray      # background daemon + tray icon only
victus-tray            # tray icon: open window / start-stop effect / quit

…or simply press Victus Suite in your application menu.

Remove with ./install.sh --remove (symlinks, menu entry and icons).

What Works Right Now

Command What It Does Root
victus-kbd <preset|RGB> Backlight color (EC write) yes
victus-kbd cycle <c...> [--delay S] [--bg] Color loop in background yes
victus-kbd stop Stop the loop yes
victus-kbd get / dump [start] [len] Current RGB / EC dump yes
victus-kbd power on|off|toggle Backlight on/off — writes EC and state/last_state.json (the tab follows it) yes
victus-kbd fans status|set-pwm A B|set-mode 0|1|2|hold N vertil fans (hwmon PWM) via the rule above
victus-power status|snapshot|apply|restore|watts N|cascade N|cascade-off|brightness N|measure|draw Power modes: rollback point, Typewriter, 5–25 W system cap, whole-laptop cascade (screen/radio/USB) with a 60 s post-apply measurement, honest draw over a 40 s window, live CPU draw (RAPL) via the NOPASSWD rule
ColorMaker list|add|rm|palette Named colors (English only) no
Changer <name|R G B|#RRGGBB|random|off> Apply color asks sudo
Changer cycle-red Bright red loop (red/fire/scarlet/darkred) asks sudo
Changer cycle <colors> [--delay S] Custom loop asks sudo
Changer stop Stop the loop asks sudo
victus_tui [--window|--tray] TUI (v1.2.0) — RGB sliders + effects, fans + power tabs asks sudo
victusd [--verbose|--quit] Background daemon (unix socket, keeps effects alive) no
victus-tray Tray icon: open window / start-stop effect / quit no
victus-report [--with-ec] Diagnostics + logs into one file no

Code: bin/ (symlinks into ~/.local/bin are created by ./install.sh) Config: config/colors.conf, language: config/locale Locales: locales/ru.json, locales/en.json Log: logs/victus.log (rotation 512 KiB × 5) Reports: state/report-<date>.txt

Examples

Changer red                  # pure red 255,0,0 (most visible)
Changer cycle-red            # bright red loop in background
Changer stop                 # stop
Changer cycle red fire darkred --delay 1   # custom loop
Changer pink                 # pink 255,105,180
Changer "#ff00ff"            # arbitrary hex
Changer 120 200 255          # arbitrary RGB
Changer random
ColorMaker add mycolor 30 144 255   # your own name (English)
Changer mycolor
victus_tui                   # TUI (v1.2.0)

TUI (v1.2.0)

victus_tui                   # launch (asks sudo on EC writes)
victus_tui --window          # floating 960×540 window (foot, kitty fallback)
victus_tui --tray            # daemon + tray icon, no window
VICTUS_DRY_RUN=1 victus_tui  # launch without EC writes (safe preview)

The TUI is a thin wrapper over the CLI: every EC write goes through victus-kbd, the palette comes from victus_palette, state is kept in state/last_state.json.

  • Both tabs share one dense layout: every panel is packed top-down with a single blank line between blocks, and whatever space is left becomes one even band at the bottom of the panel (at the usual 110×31 window that band is 1–2 rows, so nothing is clipped and nothing floats in the middle).
  • The left COLOR PICKER panel opens with Cycle/Fade/Static and the power switch under a divider, then the sliders, and a bottom block with Hex, the 10×5 preview and Apply · Copy hex; the right column stacks Custom Effect Creator (live sine, 1fr — the wave fills the panel) over LIGHTING EFFECTS (Effect Speed and Start / Stop).
  • The tab is painted in golden glow: gold panel frames and titles, gold slider bars, gold frame around the preview, gold Apply / Start and a gold highlight on the active tab (the Fans tab is gold as well).
  • Three long ticked sliders — Red/Green/Blue (0…255), each with an exact numeric box beside it: click it and type the value — plus one thin brightness line under them: 0 = light off, 100 = your colour at full strength, the middle is half strength (the hardware has no brightness byte, so strength = colour × level: the diode really emits less light while the hue stays the same). The line is one label-less row drawn like a panel divider, and the → #hex 66% line under the Hex box shows what actually went to the keyboard and at what strength.
  • The brightness line writes to the keyboard immediately, without Apply — the same scheme as the fan knobs: 0.4 s of quiet after the last step and the level goes to the EC; while an effect is running the loop is not killed — the daemon just rebuilds its colours with the new level.
  • Mouse input is rate-limited: drag refreshes at 60 Hz and wheel bursts (touchpad, smooth wheel) collapse into a few steps — the bar follows the pointer instead of lagging and jumping around.
  • The Hex field previews live while you type; Enter (or Apply) sends it to the keyboard, a broken hex only restores the field.
  • Effect Speed (0.2…5.0, also typeable) sits in the LIGHTING EFFECTS panel together with Start / Stop; the modes and the power switch live in the COLOR PICKER panel, above the sliders.
  • Apply · Copy hex, status line.
  • Wave speed follows Effect Speed: amplitude and period are lerped toward the target every 0.12 s, no jumps.
  • Calm mode: after Stop the sine keeps its shape — it still fills the Creator panel, but the colours stand still and the phase drifts very slowly, so the light rests instead of going dark.
  • Smart permission probe (probe_access): direct write / sudo / EC module missing — the hint matches what is actually broken.
  • Language button in the title row: RU ↔ EN without restart.
  • Colour cycles are smooth: up to 64 steps per loop keeping the same loop period (4 s at speed 1) — the EC is written below its ~19 writes/s ceiling, so the fade never stutters.

The window lives in the background: victusd (unix socket $XDG_RUNTIME_DIR/victus-suite-<uid>.sock) keeps the effect running while the TUI is closed, victus-tray gives quick start/stop from the tray. Launching the TUI starts the daemon too if it is not running yet, and restarts an outdated one: ensure_daemon compares the daemon's version on every launch, so an old daemon can never ignore new state keys and fight the TUI over the EC.

Fixed since alpha: mouse-draggable ASCII sliders (no text selection).

Fans — Telemetry and Control (vertil Tab)

The TUI has two tabs: Keyboard (backlight) and Fans (vertil). The fans tab answers three questions: how hot the machine is right now, who is in charge of the blades, and what happens if something goes wrong.

What You See

 CONTROL (full width)
 [*] Manual
 [ ] SMART
 [ ] BIOS Auto
 ─────────────────────────────────────────────
 Right fan [███████░░░] 128
 Left  fan [███████░░░] 128
 set 128/128
 ~1024 / 1024 RPM
 (leftover = one even band at the panel bottom)

 TELEMETRY                      SAFETY
 CPU  61.0 °C max 99            guard   CPU 99 · GPU 88 °C
 GPU  55.0 °C 42 %              smart   60..255 PWM
 VRM* board 48.2 °C             emerg   CPU 93 · GPU 83 °C
 right  2540 RPM PWM 128 50 %   hold    180 PWM
 left   2410 RPM PWM 128 50 %   preset  victus-2026-09-30
 MODE manual                    access  passwordless
 ─────────────────────────────────────────────
 status: SMART ▸ 128/140

The knobs are the same widget as on the Backlight tab: a bar with a ruler underneath, drag / wheel / arrow keys, and an exact-number box beside it — type 128 and press Enter (or leave the box), the value is clamped to 0..255 and written 0.4 s later, like the last drag step. The tab is one column: CONTROL takes the full width (modes, knobs, set X/Y and ~RPM), and below it sit TELEMETRY and SAFETY side by side, both painted in the same gold as the Backlight tab.

Telemetry is polled once a second and is read-only, no root: hwmon temperatures/RPM/PWM plus nvidia-smi (run in a worker thread — it can take ~3 s), so the UI never freezes while the GPU answers.

Why It Exists

  • The stock firmware curve is slow and hot: handing the fans back to firmware (set-mode 2) stalls both blades for ~215 s before they spin up again (safety.auto_transition_zero_rpm_seconds, measured in the 3-phase test). On a loaded laptop that is the difference between 92 °C and 99 °C.
  • hp-wmi does not report the setpoint back: pwm* on read is the displayed RPM, jittering at ≈0.95× of what you wrote (vertil/docs/2026-09-30-fan-hw-access-report.md §7). A naive read-modify-write controller therefore oscillates — the tab shows the last command it sent instead of the trembling readback.
  • Quieting a gaming laptop without cooking it needs a controller that is fast, visible and reversible — that is SMART.

Modes

Mode What It Does Notes
Manual Two knobs set PWM 0..255 (0–100 %) per fan — drag them or type the exact number in the box, written 0.4 s after the last step Entering Manual is safe (the driver snapshots the current RPM)
SMART Autopilot: predictive controller, 1 s step, thresholds from vertil/config/presets.json Starts on TUI launch (first run) and is remembered, see below
BIOS Auto Hands both fans back to firmware Needs a second click within 30 s — see below

The hardware mode is read honestly on every launch (one snapshot, then the UI follows it). Your own choice survives a restart: first launch starts SMART, afterwards the mode you picked (Manual / SMART / AUTO) is restored from state/fan_mode.json — nothing is reset behind your back.

Safety

  1. Leaving for BIOS Auto is confirmed twice (30 s window): the transition stalls the fans for ~215 s, one accidental click should not do that.
  2. Closing the TUI in Manual mode does not leave the blades unattended: the backend holds safety.hold_pwm_on_controller_loss (180 PWM ≈ 70 %) — the same rule the lab guard.sh uses for a dead controller.
  3. SMART stops after 10 consecutive failed writes and says why; nothing is retried forever in the background.
  4. Emergency chip: CPU ≥ 93 °C or GPU ≥ 83 °C turns the status line red; the controller itself enters emergency only after 2 consecutive hot samples and then ramps to 100 % at 4× the normal rise rate (~5 s) — a single temperature spike no longer slams both fans to full speed.
  5. No pretend-OK: if hp hwmon or the passwordless rule is missing, the probe verdict is printed in the SAFETY panel (passwordless / sudo / need password / no hwmon) instead of silently failing on the next write.

How It Works

VertilTab (Textual, 1 s poll, all blocking calls in worker threads)
 ├─ read  ─► tui/vertil_core.snapshot() ─► vertil/tools/fanlib.Sensors   no root
 │            hwmon temps/RPM/PWM + nvidia-smi
 ├─ write ─► tui/vertil_core.call("set-pwm" | "set-mode" | "hold")
 │            └─► sudo -n bin/victus-kbd fans <cmd>   ← NOPASSWD rule above
 │                └─► vertil/tools/fanctl.py ─► fanlib ─► /sys/.../hwmon*  root
 └─ controller: vertil/tools/fanlib.Smart (1 s step) lives in the TUI —
                 fanctl only writes, it contains no policy
  • vertil/ is self-contained: config/presets.json (device, thresholds, provenance), tools/fanlib.py (sensors + controller), tools/fanctl.py (one-command-per-process write CLI), tools/lab/ (the 3-phase test bench), docs/ (hardware reports). Nothing is installed system-wide — only hwmon registers are written.
  • One fan = one physical side: right = CPU = pwm1/fan1, left = GPU = pwm2/fan2.
  • The SMART loop keeps running while you use the keyboard tab; the telemetry poll pauses only when the fans tab is hidden and no autopilot is active.
  • The same backend is usable without the TUI: victus-kbd fans status | set-pwm A B | set-mode 0|1|2 | hold N.

Status: console pult + TUI tab are integrated, verified with a headless smoke suite and validated live on this machine: SMART starts from the tab, the chosen mode is restored on relaunch, closing the window holds 180 PWM (logs + vertil/docs/2026-09-30-tui-integration-session.md §7).

Power — Typewriter Mode (Power Tab)

Battery is 52.7 Wh, the target is 5 h → the machine must sit under ~9.4 W on average. The tab toggles a system-wide, fully reversible cap.

Control What It Does
Typewriter switch PL1 = N W, PL2 = 2·N, max_perf_pct = 20 + (N-5)·2, per-CPU frequency ceiling 1.0 + 0.08·(N-5) GHz (clamped by cpuinfo_max_freq), dGPU → power/control=auto (parks in D3cold). Every value it overwrites is captured first.
Watt slider — five fixed steps 8/10/15/20/25 W The same system-wide cap, retuned live; click, arrows, PgUp/PgDn, Home/End and the wheel all snap to the nearest step and the caption lists them, so the UI can never promise a wattage the hardware does not hold; dead while the mode is off.
Readout CPU watts from RAPL (reacts to the slider immediately) and a running average from energy_now — the EC's power_now lags by seconds and steps, so it is not shown as a live figure; plus charge %, ETA to empty — so the honest answer is visible when 5 h is out of reach (a browser + editor sits at 12-16 W).
Switch off Full revert: PL1/PL2, perf cap, freq ceiling, dGPU control and the previous fan mode all come back (.bak in state/power_prev.json).

sudo victus-power watts N applies the same plan from the CLI (refuses with rc=1 while the mode is off).

One Slider for the Whole Laptop (Cascade on Fixed 8/10/15/20/25 W Steps)

Throttling the CPU alone cannot hit a watt target: the measured non-CPU floor (screen, SoC, radio, board) is ~4.5–7 W depending on load, and brightness alone spans +3.6 W between 3 % and 65 %. So the single watt slider on the Power tab plans the whole machine, applies the plan, and then — this is the part that matters — measures what the laptop actually draws and says so out loud (report: vertil/docs/2026-10-03-power-floor-report.md):

Target Plan on Top of the CPU Cap
18–25 W brightness 35–55 %, Wi-Fi power-save
13–17 W + brightness 20 %, freq ceiling 1.7 GHz, USB autosuspend (2 s)
9–13 W + brightness 8–12 %, Bluetooth off, background polling slowed
5–8 W + brightness 3–5 %, freq ceiling ≤ 1.0 GHz, keyboard backlight off

Only five points are offered — 8, 10, 15, 20, 25 W — because those are the ones the hardware actually holds: PL1 and the frequency ceiling are whole watts and the brightness/BT/USB tiers are stepped, so a "13 W" promise would be a lie from the first second. The bar snaps to the nearest point, the caption names the steps, and a target once chosen does not drift back to the previous one while a phase is still running. A ruler sits under the bar: every step number is printed directly under its own graduation, the active one burns gold, the gaps are small dots — the scale boundaries and where the selection lands are visible at a glance.

What happens when you move the slider (two stages, so the UI never hangs on "almost done"):

  1. Stage 1 — fast (1–3 s). The cascade is written (PL1/PL2, perf cap, frequency ceiling, brightness, radio, USB, dGPU parked) and the panel is forced to 60 Hz; the hint under the slider immediately shows the plan — what was switched off, the refresh rate and the battery ETA — so you are not left waiting 34 s in silence.
  2. Stage 2 — settling with a visible timer, a 60 s window. The helper rests 4 s and measures for a full minute from the battery (energy_now / power_now): 30 s was not enough for the CPU and the background to reach a plateau, so verdicts like "target not reached" arrived on a half-settled measurement. On a 60 s window the quantum of the energy_now scale (10 mWh) drops from 1.2 to 0.6 W and the energy integral is used instead of the lagging power_now. The status line and the bottom line tick against wall-clock time (Settling before the measurement: 3 s left… → Power settling: 27 s of 60 left…, plus an extra stage if the window closes while the hardware is still settling) and the live watts are replaced by that countdown, so the jumping numbers of adaptation are not passed off as a reading.
  3. If the measured total is above the target, the CPU budget is trimmed and another phase runs (floor: 3 W on the package).
  4. Only when the run ends is the verdict fixed as a number: Target 10 W → actual 12.2 W · CPU 4 · platform 8, or Target 10 W not reached: actual 12.2 W, plan floor 11.5 W.

Monitoring does not stop with the verdict. The live-wattage line sits directly under the verdict line (target vs actual vs CPU vs platform, colour-coded; on AC it says the draw is not measurable and shows RAPL) and refreshes every 5 s for as long as the tab is open — after Target 8 W not reached: actual 11.2 W the number keeps moving while the verdict stays put. The hint under the slider repeats the last measured verdict plus the ETA — hint and status can never disagree, because both read the same measurement.

Honest limits measured on this machine with a browser + editor running: the floor sits at ~9–11 W, so targets ≥ 10–12 W are taken, and 5–8 W are reported as unreachable with the real floor — not silently "applied". Brightness, Bluetooth and USB are snapshotted first and restored by sudo victus-power cascade-off — switching the mode off does that too.

sudo victus-power cascade 10        # whole-machine plan for 10 W
sudo victus-power cascade 10 --cpu 7 --no-stabilize
sudo victus-power measure --dur 40  # honest draw over a 40 s window
sudo victus-power cascade-off        # restore brightness / Bluetooth / USB
sudo victus-power brightness 45     # backlight in percent

Keyboard Backlight Hotkeys

This laptop has no /sys/class/leds/*kbd_backlight*, so the stock Omarchy binding (omarchy-brightness-keyboard) just errors out. The three keys are rebound in ~/.config/hypr/bindings.lua:

Key Action
XF86KbdLightOnOff victus-kbd power toggle
XF86KbdBrightnessUp victus-kbd power on
XF86KbdBrightnessDown victus-kbd power off

They write EC and state/last_state.json; the Keyboard tab polls that file every 1.5 s, so the switch and the color follow within a tick.

Interface Language (Localization)

Default is English (us). Messages live in locales/<code>.json, the current language is in config/locale.

VICTUS_LANG=en Changer list        # language on the fly
echo en > config/locale            # default language
cp locales/ru.json locales/de.json # add a new language

How to add a language: copy ru.json, translate the values (keep the keys), set the code in config/locale or in VICTUS_LANG. Fallback — en.json.

Logs and Diagnostics

tail -f ~/Work/victus-suite/logs/victus.log   # what happened
VICTUS_LOG=debug Changer pink                # verbose log of one command
victus-report                                # report for a bug (no root)
victus-report --with-ec                      # + EC dump (asks sudo)

Every log line looks like this:

2026-09-25T20:27:56+04:00 ERROR pid=37009 euid=1000 Changer: unknown color 'nosuchcolor'
2026-09-25T20:27:56+04:00 INFO  pid=37011 euid=1000 victus-kbd: rgb (255,255,255) -> (255,105,180)

euid immediately shows whether a command failed because root was missing. Exceptions are logged with a full traceback, stderr gets a short reason + the path to the log.

Project Structure

victus-suite/
├── README.md                      ← this file (English)
├── CONTRIBUTING.md                ← rules: English docs & commits, tests, PR flow
├── ROADMAP.md                     ← next stage: script → installable app
├── LICENSE                        ← MIT
├── VERSION                        ← 1.2.0 (single source of truth)
├── install.sh                     ← ./install.sh [--remove] → symlinks + menu entry + icons
├── .github/                       ← issue/PR templates + CI (pytest)
├── bin/                           ← all commands (put new ones here)
│   victus-kbd  Changer  ColorMaker  victus-report
│   victus_tui  victusd  victus-tray  victus-power
│   victus_log.py (logging)   i18n.py (translations)   victus_palette.py
│   tui/                           ← TUI modules
│     core.py (EC/sudo probe, engine, delay_for_speed)
│     screens.py (Bento layout, tabs, language button)
│     kbd_tab.py (color/effect panels, kill_loop, calm)
│     power_tab.py, power_core.py (power tab + root-helper bridge)
│     vertil_tab.py, vertil_core.py (fans tab: telemetry, modes, SMART loop)
│     slider.py (ASCII sliders, SineWave)
├── tests/                          ← offline pytest suite (fanlib controller)
├── vertil/                         ← fan backend, self-contained
│   ├── config/                     ← presets.json: device, thresholds, provenance
│   ├── tools/                      ← fanlib.py (sensors + SMART), fanctl.py (write CLI)
│   │   └── lab/                    ← 3-phase test bench (cpuburn, gpuload, guard)
│   └── docs/                       ← hardware reports + measured test logs
├── locales/                        ← ru.json, en.json (interface texts)
├── config/                         ← colors.conf, locale, profiles.d/, curves.d/
├── share/icons/                    ← b&w icon: victus-suite.svg, hicolor PNGs, make_icon.py
├── logs/                           ← victus.log (+ rotation .1..5)   [not in git]
├── state/                          ← report-*.txt, last_state.json   [not in git]
└── docs/
    ├── SPECIFICATION.md            ← full technical specification
    ├── DEVELOPMENT.md              ← ENTRY POINT: state, roadmap, agent rules
    ├── 01-keyboard-backlight.md    ← how the backlight is done, what is verified
    ├── 02-system-audit.md          ← system audit for this machine
    ├── 03-rgb-backlight.md         ← RGB: EC, WMI, risks, product plan
    ├── 04-fans-and-thermal.md      ← fans: hwmon/pwm, timings, risks
    ├── 05-performance-modes.md     ← Comfort/Balanced/Performance, FAQ
    └── 06-overlay-and-monitoring.md ← overlay (Shift+F2 replacement), CPU/GPU power

Reinstall after moving/cloning: ./install.sh.

Contributing

Read CONTRIBUTING.md first. In short:

  • English everywhere — docs, code comments and commit messages (Conventional Commits: type(scope): summary).
  • Run the offline suite before pushing: pytest tests/ -q (20 tests) and python3 -m compileall -q bin vertil.
  • Never commit local artifacts — logs/, state/, __pycache__/, bench binaries; .gitignore already covers them.

Machine

  • HP Victus 16-r0xxx, i5-13500H, RTX 4060 Laptop
  • Kernel 7.2.5-3-omarchy, driver hp-wmi (upstream, with hwmon-fan support)
  • OS: Omarchy (Arch-based), Hyprland

Releases

Packages

Contributors

Languages