Firmware control for the Framework Laptop 13 on Ubuntu — fan curves, power limits, battery charge limit, and performance profiles in one tray application.
Inspired by G-Helper, which does this for ASUS laptops on Windows. This shares no code with it — see ADR 0001.
Status: 0.1.0, first public preview. Fan control (with a graphical curve editor), power limits, the battery charge limit and profiles all work and are verified on real hardware. Expect rough edges and read the known issues before filing anything — several are already measured and understood. See docs/plan.md for what is measured and what is assumed, and CHANGELOG.md for the release notes.
The pieces already exist on Linux — powercap, cros_ec hwmon, power-profiles-daemon,
fw-fanctrl — but they are scattered across sysfs paths, CLIs, and daemons that do not know
about each other. fw-helper is the unifying layer: named profiles that set all of them at
once, switchable from a tray icon or a hotkey.
| Feature | Status |
|---|---|
| Live telemetry | Working — temps, fan RPM, CPU and whole-machine power, battery life |
| Capability detection | Working — every knob reports available, or why not |
| Battery charge limit | Working — verified to actually stop charging: from below the limit, on AC, it halted at exactly 80% with current_now=0. Drives Framework's custom EC command (ADR 0012); the standard sysfs interface is inert on this board |
| Fan control | Working — manual duty or a curve, with every ADR 0006 safety layer verified on hardware |
| Power limits (PL1) | Working — a 15 W setpoint held 15.02 W sustained, +0.1% |
| Performance profiles | Working — layered over power-profiles-daemon; the GNOME slider stays in sync |
| Custom profiles | Working — saved from the app, or written by hand in /etc/fw-helper/profiles.d/ |
| Fan curve editing | Working — graphical editor in the app, or fw-helperctl fan curve |
| Session recording | Working — record a run, come back and read the graph. CPU/GPU/RAM load, temps, power against the limit, fan, throttle events |
| In-game numbers | Working via MangoHud — no ordinary window can be drawn over a fullscreen game on Wayland, so fw-helper feeds the overlay that can. See below |
| PL2 (short-term limit) | Not touched — it governs burst response, not sustained thermals |
| Undervolting | Not possible. See below |
Every mechanism above was exercised on real hardware before any application code was written, and the measurements are recorded in docs/hardware-baseline.md. Several of them contradicted what the design assumed — the EC's fan curve has ~20 °C of hysteresis, its duty read-back is quantized to whole percent, and this machine reaches 92.8 °C in ordinary use rather than the 76.8 °C an early test suggested.
Intel locked the undervolting MSR as the mitigation for Plundervolt / CVE-2019-11157. It is unreachable on Core Ultra parts and Framework's BIOS does not expose an unlock. This is a firmware/silicon limitation, not something a Linux application can work around.
Power limits (PL1/PL2) deliver most of what people actually want from undervolting on a laptop — lower sustained temperatures, quieter fan, longer battery. Measured on this machine: dropping the sustained limit from 25 W to 15 W took the CPU from 76.8 °C to 64.8 °C under full load. See ADR 0007.
The question this started from was "is 35 W actually the ceiling on this laptop?", and answering it once took a bespoke script and four manual runs. Now, on the Monitor page: Record, play, Stop. Or from a terminal:
fw-helperctl record start "cyberpunk at 35W"
# ... play something ...
fw-helperctl record stopOr press Ctrl+Shift+F5 in the game, once the Monitor page's Add Ctrl+Shift+F5
Shortcut button has set it up. Wayland gives an application no global hotkey, so this
is a GNOME custom shortcut running fw-helperctl record toggle; on another desktop, bind
that command yourself.
Recording happens in the daemon, not the app, for two reasons. energy_uj is
root-only (the PLATYPUS mitigation), so an unprivileged recorder cannot read package
power at all; and a recording has to survive the window being closed.
When a recording stops it is saved to ~/Documents/FW Benchmark - the folder the
Windows build uses too - with three things the daemon cannot add itself:
- the frame rate, second by second, from MangoHud's frame log (below), and a
.frames.csvof every frame time, which is what the 1 % and 0.1 % lows come from; - run notes (
.notes.json): BIOS, EC, kernel and fan filled in automatically, the game settings and anything else typed when the window asks; - on request, a summary (
.html): one self-contained page with tiles, every reading second by second, where the watts went, what held the GPU clock, and the figures over the steady seconds only - loading, the first 10 s and uncapped menus left out.
Compare puts several saved runs against a baseline - "25 W against 35 W", "quiet fan
against the EC" - and writes a report of what changed: FPS, 1 % lows, package watts,
FPS per watt, and which recorded settings differ. Project files use the Windows build's
format. From a terminal: fw-helperctl bench lists what is saved, bench report NAME
and bench compare PROJECT make the pages.
The Monitor page itself shows nine cards - load, CPU clock, GPU clock (asked against actual), power, temperature, fan, memory, frame rate and battery - live over the last five minutes, or for any saved run or unsaved recording.
How to tell whether the power limit was the thing holding you back. The package publishes no "I am power limited" flag — unlike the GPU, which publishes real throttle reasons. So the PL1 setpoint is drawn as a dashed line over the power trace: draw sitting on the line is PL1 binding. That inference is how the 35 W ceiling was found.
The daemon keeps its last 20 recordings in /var/lib/fw-helper/sessions/, and a single
recording stops itself after 12 hours. What is saved to FW Benchmark is never pruned.
On GNOME/Wayland an ordinary window cannot be kept above a fullscreen window — Mutter
implements no protocol for it, so this is not something an application can work around.
fw-helper --overlay gives a compact readout that works beside a borderless game or on a
second display, and is covered by a genuinely fullscreen one.
For numbers inside a fullscreen game, use MangoHud. It is not a window: the Vulkan loader loads it into the game's own process and it paints into the frame before presentation, so the compositor never learns an overlay exists. fw-helper feeds it what it cannot know:
MANGOHUD=1 MANGOHUD_CONFIGFILE=/usr/share/fw-helper/mangohud/fw-helper.conf %command%
as Steam launch options. That adds the power limit being enforced, who owns the fan, the active profile, the battery pack temperature, and whether a recording is running.
It is also where fw-helper's frame rate comes from. The same config has MangoHud log
every frame to ~/.local/share/fw-helper/mangohud/, which fw-helper reads: live on the
Monitor page, and joined into a recording when it is saved. Nothing outside the game's
process can see its frames on Linux, and MangoHud already runs there. A log grows by roughly
20 MB an hour of play at 60 fps, so fw-helper deletes each one once nothing needs it: ten
minutes after the game stops writing it, unless a recording that has not been saved yet
overlaps it (and after 14 days regardless). A saved run keeps its own copy of the frames.
If you don't need the 1 % and 0.1 % lows, use fw-helper-per-second.conf in that launch
option instead: the same config logging once a second, about half a megabyte an hour.
Saved runs then have the average FPS for every second but no frame times. The choice is
per game, and the Monitor page has both launch options with copy buttons. To use your own
MangoHud config instead, add its four logging lines (output_folder, autostart_log,
log_interval, log_duration) from /usr/share/fw-helper/mangohud/fw-helper.conf.
It also adds GPU load, which MangoHud cannot show on this laptop. Measured with
MangoHud 0.6.9.1: its Intel support is i915-only, and this board runs xe, so it
disables gpu_stats outright and falls back to intel_gpu_top, which needs
perf_event_open and is blocked by kernel.perf_event_paranoid=4. fw-helper reads the
per-engine counters out of /proc/<pid>/fdinfo instead.
That last bit needs one capability, and the shipped systemd unit grants it: reading
another user's /proc/<pid>/fdinfo goes through a ptrace access check, which needs
CAP_SYS_PTRACE — being root is not enough, and every process using the GPU belongs to
you rather than to root. It is the only capability the daemon holds
(ADR 0013). If you run fw-helperd by
hand rather than through systemd, run it as your own user or GPU load will read as
unavailable, with the reason in the startup capability list.
Developed against:
- Framework Laptop 13 Pro (Intel Core Ultra Series 3), board
FRANMJCP07, BIOS 03.02 - Ubuntu 24.04 LTS, kernel 7.0
Other Framework 13 Intel boards will likely work — the daemon probes capabilities at startup
and disables what it cannot drive. AMD boards and the Framework 16 are not targeted for
v1; AMD in particular needs a different power-limiting mechanism (ryzenadj rather than RAPL).
- A kernel new enough for
cros_ec_hwmon(fan control) - power-profiles-daemon (optional but recommended — we integrate with it rather than replacing it, so the GNOME power slider keeps working)
- No
ectoolorframework_toolneeded — we use kernel interfaces directly (ADR 0004)
Manual fan control is genuinely risky: once userspace takes over, the EC stops managing the fan and holds the last duty written — so a crashed daemon can leave the fan stuck low under load. ADR 0006 specifies the mitigations (restore-on-exit, crash-path binary, watchdog, a floor that is never quieter than firmware, and a critical-temperature override that hands control back unconditionally).
kill -9 recovery is a release gate, not a nice-to-have. It is measured: EC control was
restored 0.27 s after the daemon was killed under load.
What the fan floor protects is worth stating precisely, because it changed once the hardware was measured. The CPU throttles itself at 100 °C, so a fan held too low costs performance rather than hardware. The component with no protection of its own is the battery, whose sensor reports a 49.9 °C limit — by far the lowest on the board (ADR 0011).
./scripts/build-deb.sh # builds fw-helper_<version>_amd64.deb
sudo apt install ./fw-helper_*.debThat installs the daemon, the GTK window (fw-helper, also in your app grid) and the CLI,
enables the service, and creates /etc/fw-helper/profiles.d/ for your own profiles.
Nothing takes manual control of the fan until you ask it to.
The charge limit needs no opt-in step. If a previous version left
/etc/modprobe.d/fw-helper.conf behind, installing removes it: it belonged to the
superseded mechanism (ADR 0008) and
was not merely useless — it produced a charge limit that reads back correctly and does not
stop charging, which is what made that mechanism look right for weeks
(ADR 0012).
cargo build --all
cargo run -p fw-helperctl -- status # reads sysfs directly; no daemon neededFor the full picture, run the daemon. It needs the D-Bus policy installed first:
sudo ./scripts/install-dev.sh --systemd # policy, polkit, unit, and start it
fw-helperctl status # unprivileged, via D-Bus
fw-helperctl profile # quiet | balanced | performance
fw-helperctl watch 10 # live power, fan, CPU temp at 1 HzPackage power needs a root daemon — energy_uj is 0400, the PLATYPUS mitigation. The
client stays unprivileged and holds no hardware access. Without the daemon, fw-helperctl
falls back to reading sysfs directly and everything except package power still works.
Not
670C
hing in fw-helperctl writes to hardware.
Tests need neither hardware nor root; they run against synthetic sysfs fixtures:
cargo test --all./scripts/fw-probe.sh # read-only survey
sudo ./scripts/fw-probe.sh --write-test # also tests whether writes are honoured--write-test briefly changes power limits and fan duty, then restores them. It only ever
spins the fan up. Read it before running it.
- framework_system — Framework's own tooling; our reference for EC host commands
- fw-fanctrl — established fan curve daemon
- LACT — GPU control, for Framework 16
- inputmodule-rs — FW16 LED matrix
- CrOS_EC_Python — third-party EC library, and the
clearest catalogue of Framework EC command numbers we have found. It independently confirms the
0x3E03charge-limit opcode of ADR 0012, which two summary lookups had disagreed about - YAFI — GTK4 EC GUI in Python, Linux and Windows. Overlaps on
fan, temperatures and charge limit; adds LED control; has no power limits and no daemon. The
daemon is the main architectural difference: it is what makes resume re-apply, the fan watchdog
and
kill -9recovery possible at all
GPL-3.0. See ADR 0001.