Repository navigation
docs: restructure the README around what the app looks like - #25
Merged
Merged
Conversation
The keyboard could only be set to one static colour. This adds a small animation engine in the backend that repaints the keyboard on a timer, plus the controls to drive it from the GTK app. Effects: RAINBOW (whole keyboard walks the hue wheel), BREATHE (the current colour fades in and out) and FLOW. On four-zone Omen keyboards FLOW offsets the hue across the zones in their physical left-to-right order (2, 3, 1, 0 — far left, WASD, middle, right) so the colour travels along the board like a river. Single-zone backlights have no geometry for a wave to travel across, so FLOW behaves like RAINBOW there and the dropdown label says so rather than looking broken. Protocol: SET_KBD_EFFECT <NAME> [SPEED] and GET_KBD_EFFECT. Speed is 1-100 and maps onto the cycle period; omitting it keeps the current rate. Setting a static colour cancels a running effect, since otherwise the next frame would paint straight over the user's choice. Notes on cost, which drove a few of the decisions here: - A single-zone frame is one ~0.15ms sysfs write, so it runs at 30fps for about 0.4% CPU. A four-zone frame has to go through the setuid helper, so it runs slower and all four zones are pushed in one invocation via a new set-rgb-zones.sh; doing it per zone would mean four sudo execs and four journal entries for every frame. - A udev rule grants the victus group write access to the zone files, so frames normally take a direct-write fast path and skip sudo entirely. - The loop skips writes while the backlight is off rather than repainting a dark keyboard. - Frames advance on measured elapsed time, so the rate holds steady regardless of how long a hardware write took. The chosen effect is saved under StateDirectory= and restored on start, so the lighting survives a reboot. The GTK app animates its drawn keyboard to match, seeding the preview phase from the colour the hardware is showing so it runs in step instead of at a random offset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
Some boards report software fan support through the BIOS query but then ignore per-RPM target writes. On those, Better Auto switches the fans to MANUAL (which succeeds) and then fails to set a speed, leaving the fans pinned at a fixed RPM with the firmware curve switched off. Measured on a Victus 15-fb3xxx (board 8E5F): writes to fan1_target return success while fan1_target itself reads EINVAL, the fans never change, and under an all-core load the CPU sat at 100C with the fans held at 2691 RPM and fan2 stopped for 30 seconds. The same load with the stock in-tree hp-wmi driver kept both fans running, so this is the control loop taking over and not being able to hand anything back. VICTUS_NO_FAN_CONTROL=1 skips the startup Better Auto enforcement and leaves the fans entirely to the firmware, so the backend can still serve keyboard lighting on affected hardware. Off by default; nothing changes for boards where fan control works. README documents how to tell whether a board is affected and the drop-in that sets it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
The app used stock GTK defaults: full-width stacked buttons, plain labels and no visual grouping. This gives it a look that suits the hardware it controls. - A stylesheet (frontend/src/style.cpp) with a dark carbon palette and an electric cyan accent, squared-off controls, and glow on the accented elements. Amber and red are reserved for temperature, so colour always carries meaning rather than decoration. - Controls are grouped into titled cards instead of a flat stack, each headed by a symbolic icon from the icon theme. Icons come from the theme rather than a bundled icon font, so they follow the accent colour and add no assets. - The fan tab becomes a telemetry dashboard: fan RPM and CPU/GPU temperature as large monospace readouts (monospace so digits do not jitter as values update). Temperatures turn amber at 70C and red at 85C. - The drawn keyboard is rendered as key caps in a chassis with a backlight glow, instead of flat rectangles. Unlit keys still show a dark cap, so the keyboard reads as a keyboard when it is off. - The colour readout follows the animation rather than showing whatever value was set when the effect started, which looked like a bug next to a keyboard that was visibly cycling. - Pages scroll, so a short window no longer clips the controls at the bottom. No colour scheme is forced. Asking GTK for a dark scheme makes it load the system theme's dark variant, and themes shipping only a gtk-dark.css (Yaru among them) fail that import and drop their whole base stylesheet; the rules here paint every surface the app shows instead. Also adds GET_FAN_TARGET_SUPPORT. Boards whose firmware refuses software fan control never expose fan*_target, and the manual speed slider on those machines moves but changes nothing. The fan tab now asks the backend up front and, when unsupported, disables the slider and says why rather than letting it fail silently on every drag. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
The README was a flat wall of bullets with no way in and nothing showing what the app actually is. Same information, arranged so it can be scanned. - Centred header with the project icon, a one-line pitch, and badges for licence, platform, toolkit and the supported distros. - Screenshots of both tabs near the top, so the first thing a visitor sees is the software rather than a paragraph about it. - A table of contents, and a feature table replacing the "Why" bullet list. - Support matrix, requirements and background services become tables. - Lighting effects get their own section with a table per effect. - Troubleshooting entries become collapsible <details> blocks, so the section stops dominating the page while staying complete. - GitHub alert syntax (NOTE / TIP / IMPORTANT / WARNING / CAUTION) for the hardware warning, the "do not pipe into sudo" note, and the warning against running two fan controllers at once. No technical content was dropped; every command, model number, caveat and link from the previous revision is still present. The AGENTS.md reference stays plain text, as it was, because that file is not in the repository. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
Reworks the interface around what someone actually does with it, rather than mirroring the backend's command list. Layout - The two tabs become one page with a card per subsystem. A control panel is glanced at, and tabs hid half the machine's state behind a click. - Each card leads with its visual: the backlight preview, and the fan dials. Keyboard card - A switch in the card header replaces the full-width toggle button. - Lighting style is a row of radios (Solid / Rainbow / Breathe, plus Flow on four-zone boards) instead of a dropdown, so every option is visible without opening anything. - FLOW is not offered at all on single-zone hardware. It has nowhere to travel there, and an option that quietly behaves like a different one is worse than an absent option. - Speed sits directly under the style row, and only appears for the animated styles. The colour picker only appears for Solid. Neither control is shown when it would do nothing. - The Apply button is gone: choosing a colour applies it. Every other control already applied on change, so Apply was an inconsistency. Fan card - Fan speed and temperature get analog dials with the digital value under each (frontend/src/gauges.cpp). Rotor blades turn at a rate derived from the measured RPM — scaled down, since 3000 RPM is 50 rev/s and could not be drawn honestly — and a stopped fan renders grey rather than simply still, so a stalled fan is distinguishable from a slow one. - Thermometers fill against 100C and shift cyan to amber to red on the same thresholds as the digital readouts. - Where the firmware refuses fan targets, manual speed is removed from the card and MANUAL is dropped from the profile list, instead of being shown disabled. Fixes found while testing this - The preview kept the colour it was constructed with after an effect was stopped, showing white next to a keyboard sitting on the last animated frame; the settled colour is now read back from the device. - The preview did not repaint when the backlight was switched off, so lit keys were drawn over an off keyboard. - GTK's accent colours are overridden, otherwise radios and focus rings followed the desktop accent (orange on Ubuntu) against a cyan UI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
The screenshots and wording described the previous tabbed layout. - One dashboard screenshot as the hero image instead of a pair of tab shots, plus a second showing that picking Solid swaps the speed slider for a colour picker. - "Cooling tab" / "Lighting tab" become cards, and the daily-usage section describes the switch, style radios and direct-apply behaviour. - Telemetry is described as analog dials with digital values, including that a stopped fan renders differently from a slow one. - Notes that controls which cannot do anything are absent rather than disabled: Flow on single-zone boards, manual speed where the firmware refuses targets. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
hemangjoshi37a
added a commit
to hemangjoshi37a/victus-control
that referenced
this pull request
Sep 4, 2026
If the upstream PRs are not merged, people had no documented way to install the version with the additions. Rather than replacing upstream's install instructions, both are offered side by side, with upstream credited as the origin of the project. - Quick install and the install section each list this fork and upstream, with a note explaining that the fork exists only while Batuhan4#23, Batuhan4#24 and Batuhan4#25 are in review, and to prefer upstream once they land. - Documents VICTUS_CONTROL_REPO_URL and VICTUS_CONTROL_REF for pointing either script at the other repository. - Adds a Credits section naming @Batuhan4 and @betelqeyza as the authors of the project, so the fork never reads as its origin. bootstrap.sh defaults to this repository here. It hardcoded upstream's URL, so curling the fork's copy downloaded and installed upstream's tree instead of the one it came from — the command would silently not do what it looked like it did. Verified both directions actually resolve: default -> hemangjoshi37a/victus-control VICTUS_CONTROL_REPO_URL -> Batuhan4/victus-control This commit is deliberately kept off the pull request branches: an upstream README should not advertise a fork, and upstream's bootstrap should keep its own default. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Stacked on #23 and #24. This branch is cut from #24, so their commits
appear here too. Only the last commit —
docs: restructure the README around what the app looks like— is new. The screenshots show the UI from #24, sothis reads best merged after it. Happy to rebase onto
mainand swap inscreenshots of the current UI instead if you would rather take the docs
change on its own.
What this is
The README was a flat wall of bullets with no way in and nothing showing what
the app actually is. Same information, arranged so it can be scanned.
licence, platform, toolkit and supported distros.
is the software rather than a paragraph about it.
<details>blocks, so thesection stops dominating the page while staying complete.
NOTE/TIP/IMPORTANT/WARNING/CAUTION) forthe hardware warning, the "do not pipe into sudo" note, and the warning
against running two fan controllers at once.
No content was dropped
Every command, model number, caveat and link from the previous revision is
still present — I checked the substantive ones back against the old file
(
bootstrap.sh, Secure Boot /mokutil,victus-fanco-install warning,VICTUS_NO_FAN_CONTROL,systemd-tmpfiles,dkms remove, the 10 s stagger,16-S0046NT, Ubuntu 24.04,test_backend.py, GPLv3).All relative links and all 15 table-of-contents anchors were verified to
resolve. The
AGENTS.mdreference stays plain text rather than a link,because that file is not in the repository.
Screenshots are committed under
docs/images/at ~40 KB each.🤖 Generated with Claude Code
https://claude.ai/code/session_01ELZkKrF8iHGDQG3qK19xcG