AirController is a lightweight, web-based PWM fan control application and background daemon for Linux. It allows you to monitor PC temperatures (CPU, GPU, Liquid Coolant) and dynamically adjust fan speeds using an interactive, drag-and-drop curve editor in a beautiful dark glassmorphism dashboard.
Unlike static configuration scripts, AirController features a Hardware Scanner & Mapping Wizard that auto-detects your system's hardware monitor channels (sysfs interface), making it compatible with any Linux PC without hardcoded values.
- Hardware Scanning Wizard: Automatically scans your motherboard chipsets, liquid coolers, and graphics cards to discover temperature sensors, fan RPM tacks, and PWM control nodes.
- Interactive Fan Curve Editor: Drag-and-drop node plotting on a visual grid to define customized temperature-to-speed curves.
- Reboot-Resilient Path Mapping: Matches devices by kernel driver name tags (e.g.,
kraken2023,nct6798) rather than unstable/sys/class/hwmon/hwmonXindexes. - Speed Profiles: Switch instantly between Silent, Standard, and Performance presets.
- Fail-Safe Defaults: If a temperature sensor fails to read, the target fan speed immediately overrides to
100.0%duty cycle for hardware safety.
- Linux OS (Ubuntu, Debian, Fedora, Arch, etc.)
- Python 3 (version 3.8 or newer)
- Driver Modules: Most motherboards use Nuvoton or ITE sensor chips that require loading the kernel driver (e.g.
nct6775) to expose the chassis fan controls.
Follow these steps to get AirController up and running on your system.
Download or clone this project folder into your user directory. Open your terminal and navigate to the folder:
cd ~/Apps/air-controllerAirController includes a setup script that automates package installation. Run the setup script:
chmod +x scripts/setup.sh
./scripts/setup.shNote: If your system uses a protected environment that blocks global packages (PEP 668), the script will automatically install dependencies to your user space (~/.local) using the safe --break-system-packages flag.
Most desktop motherboards keep fan controls hidden from Linux by default. To unlock them:
- Test load the motherboard driver:
sudo modprobe nct6775
- Verify sensors are found:
Run
sensors. You should see a section titlednct6798-isa-...or similar listing multiple fan RPM numbers. - Troubleshooting (ACPI Resource Busy):
If
modprobefails or prints "Device or resource busy" in the system logs, the motherboard BIOS is conflicting with the kernel.- Open
/etc/default/grubin a text editor as administrator:sudo nano /etc/default/grub
- Find the line starting with
GRUB_CMDLINE_LINUX_DEFAULTand addacpi_enforce_resources=laxinside the quotes. E.g.:GRUB_CMDLINE_LINUX_DEFAULT="quiet splash acpi_enforce_resources=lax" - Save and exit (in Nano, press
Ctrl+OthenEnterto save, andCtrl+Xto exit). - Update your boot configuration and restart:
sudo update-grub sudo reboot
- Once restarted, run
sudo modprobe nct6775again.
- Open
Start the control loop and web interface manually:
python3 src/main.pyYou will see logs showing that the hardware sensor chips are successfully matched.
Now, let's link the physical headers on your PC to the AirController interface:
- Open your browser and navigate to: http://localhost:5000.
- In the upper right corner of the page, click the ⚙️ Settings button.
- Click 🔄 Scan Hardware to populate your scanned hardware list.
- In the right panel under Mapped Fan Targets, click + Add Fan.
- Set up your mapping:
- ID: Enter a lowercase identifier with no spaces (e.g.
rear_fanoraio_radiator). - Display Label: Type a name (e.g. "Chassis Exhaust", "Radiator Fans").
- Controller / Device: Choose the device from the dropdown menu (e.g.,
nct6798ornct*for your motherboard,kraken2023for liquid cooling). - PWM: Select the speed slider channel (e.g.
pwm1controls fan header 1). - RPM Sensor: Select the tachometer speed sensor to read speeds from (e.g.
fan1reads RPM feedback for header 1).
- ID: Enter a lowercase identifier with no spaces (e.g.
- Click Save & Apply Settings. The dashboard will instantly reload and display your newly mapped fans!
With your fans mapped, you can edit curves visually:
- In the Fan Curve Configuration section on the right side of the main dashboard, select a fan tab.
- Toggle the mode to Automatic Curve.
- Choose the Temperature Sensor Source (e.g.
CPU Core (Tctl)orAIO Coolant). - Edit the Graph Nodes:
- Drag circles to change speed mappings (e.g. 50°C -> 40% speed, 75°C -> 85% speed).
- Double-click anywhere on the line to add a new control point.
- Right-click a node to delete it.
- Alternative: Type numeric values directly into the table underneath the graph.
- Click Apply Configuration to save your curve!
To keep your fans regulated automatically in the background without keeping a terminal open:
- Copy the generated helper service file to the system services directory:
sudo cp air-controller.service /etc/systemd/system/
- Reload the service list and enable the autostart daemon:
sudo systemctl daemon-reload sudo systemctl enable --now air-controller.service - You can verify the status or read the logs anytime:
sudo systemctl status air-controller.service
src/main.py: Entrypoint starting the Flask web server and the daemon loop thread.src/controller.py: Reads temperatures, executes linear interpolation, writes to sysfs, and scans devices.src/config_manager.py: Implements atomic read/write locks forconfig.json.src/web_server.py: Defines API endpoints (/api/status,/api/detect,/api/setup-hardware).src/templates/index.html: Dashboard structure.src/static/css/style.css: Glassmorphic styling sheet.src/static/js/app.js: Live polling feeds, animated SVG rotation math, and canvas mouse trackers.

