Skip to content

docs: restructure the README around what the app looks like - #25

Merged
Batuhan4 merged 7 commits into
Batuhan4:mainfrom
hemangjoshi37a:feat/readme-overhaul
Sep 4, 2026
Merged

Batuhan4 merged 7 commits into
Batuhan4:mainfrom
hemangjoshi37a:feat/readme-overhaul

Conversation

@hemangjoshi37a

Copy link
Copy Markdown
Contributor

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, so
this reads best merged after it. Happy to rebase onto main and swap in
screenshots 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.

  • Centred header with the project icon, a one-line pitch, and badges for
    licence, platform, toolkit and 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.
  • 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 alerts (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 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-fan co-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.md reference 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

hemangjoshi37a and others added 7 commits September 4, 2026 18:46
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
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
Batuhan4 added a commit that referenced this pull request Sep 4, 2026
…rd, README) — 1.1.0

Combine #23 + #24 + #25 with fixes on top: animated lighting, dashboard UI, README overhaul (1.1.0)
@Batuhan4
Batuhan4 merged commit ccfc3ca into Batuhan4:main Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants