FanFrame
FanFrame is a manual per-fan control application with live temperature and RPM readouts for the Framework Desktop (AMD Ryzen AI MAX) on Linux. Developed by community member iovis801, it provides a GTK4 GUI with per-fan duty sliders backed by a minimal privileged root daemon that communicates with Framework's official framework_tool CLI1.
Why It Exists
The Framework Desktop's fans are driven by a Chromium-style embedded controller (cros_ec), not a standard Super I/O chip. The kernel exposes fan readings under /sys/class/hwmon, but there are no writable PWM nodes — so tools like CoolerControl or lm-sensors can only read the fans, never set them. The only way to control the fans is through the embedded controller via Framework's official framework_tool12.
FanFrame wraps that EC interface in a desktop GUI with a safe privilege model, addressing the community need for per-fan control that existing tools could not provide34.
Features
| Feature | Details |
|---|---|
| Per-fan sliders | 0–100% duty, each showing that fan's live RPM |
| Per-fan Auto toggle | Switch any individual fan back to EC control; slider greys out when automatic |
| Global Auto button | Reset every fan to automatic at once |
| Renamable fans | Click a fan's name to rename it (e.g., "CPU", "Intake"); names saved per user at ~/.config/fanframe/labels.json |
| Live readouts | All cros_ec temperatures and fan speeds, refreshed once per second from the kernel |
| Thermal failsafe | Restores automatic control if a CPU sensor crosses a critical threshold (default 92 °C) |
| Unprivileged GUI | GUI never runs as root; only a tiny daemon exposes status/set_duty/auto over a group-restricted Unix socket |
Manual duty does not persist across reboot or suspend — the EC reverts to automatic control. The failsafe forces automatic control if the CPU gets too hot, but a fan controller is still a foot-gun: don't pin a low duty under sustained load and walk away1.
Architecture
GUI (GTK4, unprivileged)
|- reads temps/RPM directly from sysfs (cros_ec hwmon)
'- sends set_duty / auto --unix socket--> fanframed (root)
|- framework_tool --fansetduty / --autofanctrl
'- thermal failsafe (manual + too hot -> auto)
The embedded-controller fan index is 0-based, so sysfs fan1 maps to framework_tool --fansetduty 0 <pct>1.
Requirements
- A Framework Desktop (or another Framework device whose fans are exposed via
cros_ec). Developed and tested on the Ryzen AI MAX Desktop, Fedora 431. systemd, Python 3.11+, GTK 4 + PyGObject.- Framework's
framework_toolbinary (FrameworkComputer/framework-system)15.
Installation
# Fedora: GUI dependencies
sudo dnf install -y python3-gobject gtk4
# Get framework_tool (official release binary) into your PATH
mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/framework_tool \
https://github.com/FrameworkComputer/framework-system/releases/latest/download/framework_tool
chmod +x ~/.local/bin/framework_tool
# Install FanFrame
git clone https://github.com/iovis801/Fanframe.git
cd Fanframe
sudo ./install.sh
fanframe-gui # or launch "FanFrame" from your application menu
install.sh copies framework_tool to /usr/local/bin (if not already there), installs the sources to /opt/fanframe, adds the fanframe-gui launcher, and enables the fanframed systemd service. The control socket is restricted to your login group1.
Configuration
Set environment variables in /etc/systemd/system/fanframed.service (Environment=...)1:
| Variable | Default | Meaning |
|---|---|---|
FANFRAME_SOCKET | /run/fanframe.sock | Control socket path |
FANFRAME_GROUP | Your login group | Group allowed to drive the fans |
FANFRAME_TOOL | /usr/local/bin/framework_tool | EC CLI path |
FANFRAME_CRITICAL_C | 92 | Failsafe trip temperature (°C) |
After edits: sudo systemctl daemon-reload && sudo systemctl restart fanframed.
Uninstall
sudo ./uninstall.sh # restores automatic fan control, then removes everything
Technical Details
| Detail | Value |
|---|---|
| Language | Python |
| License | MIT |
| Stars | 0 |
| Commits | 2 |
| GUI framework | GTK 4 + PyGObject |
| Tested on | Fedora 43 |
| Test coverage | ~87% (logic modules; GUI validated by running it) |
| Hardware interface | framework_tool (--fansetduty, --autofanctrl) via cros_ec |
| Affiliation | Unofficial community tool, not affiliated with Framework Computer Inc. |
Related Projects
| Project | Description |
|---|---|
| fw-fanctrl | Custom fan speed controller for Framework laptops (FW13/FW16) |
| Framework Control | GUI tool with fan control for Framework laptops (Windows/Linux) |
| Framework Tool TUI | Terminal dashboard with fan RPM readout |
| framework-dotnet | .NET library for Framework EC APIs including fan control |