Skip to content

About

Linux web-based PWM fan controller and daemon with hardware auto-detection, custom fan curves, and systemd auto-start support.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🌬️ AirController

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.

AirController 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.


✨ Features

  • 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/hwmonX indexes.
  • 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.

📋 Prerequisites

  • 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.

🚀 Novice Step-by-Step Setup Guide

Follow these steps to get AirController up and running on your system.

Step 1: Clone the Application

Download or clone this project folder into your user directory. Open your terminal and navigate to the folder:

cd ~/Apps/air-controller

Step 2: Install dependencies

AirController includes a setup script that automates package installation. Run the setup script:

chmod +x scripts/setup.sh
./scripts/setup.sh

Note: 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.


Step 3: Load the Motherboard Fan Driver

Most desktop motherboards keep fan controls hidden from Linux by default. To unlock them:

  1. Test load the motherboard driver:
    sudo modprobe nct6775
  2. Verify sensors are found: Run sensors. You should see a section titled nct6798-isa-... or similar listing multiple fan RPM numbers.
  3. Troubleshooting (ACPI Resource Busy): If modprobe fails or prints "Device or resource busy" in the system logs, the motherboard BIOS is conflicting with the kernel.
    • Open /etc/default/grub in a text editor as administrator:
      sudo nano /etc/default/grub
    • Find the line starting with GRUB_CMDLINE_LINUX_DEFAULT and add acpi_enforce_resources=lax inside the quotes. E.g.:
      GRUB_CMDLINE_LINUX_DEFAULT="quiet splash acpi_enforce_resources=lax"
      
    • Save and exit (in Nano, press Ctrl+O then Enter to save, and Ctrl+X to exit).
    • Update your boot configuration and restart:
      sudo update-grub
      sudo reboot
    • Once restarted, run sudo modprobe nct6775 again.

Step 4: Run the Application

Start the control loop and web interface manually:

python3 src/main.py

You will see logs showing that the hardware sensor chips are successfully matched.


Step 5: Map Your Fan Channels

Now, let's link the physical headers on your PC to the AirController interface:

AirController Settings & Mapping Wizard

  1. Open your browser and navigate to: http://localhost:5000.
  2. In the upper right corner of the page, click the ⚙️ Settings button.
  3. Click 🔄 Scan Hardware to populate your scanned hardware list.
  4. In the right panel under Mapped Fan Targets, click + Add Fan.
  5. Set up your mapping:
    • ID: Enter a lowercase identifier with no spaces (e.g. rear_fan or aio_radiator).
    • Display Label: Type a name (e.g. "Chassis Exhaust", "Radiator Fans").
    • Controller / Device: Choose the device from the dropdown menu (e.g., nct6798 or nct* for your motherboard, kraken2023 for liquid cooling).
    • PWM: Select the speed slider channel (e.g. pwm1 controls fan header 1).
    • RPM Sensor: Select the tachometer speed sensor to read speeds from (e.g. fan1 reads RPM feedback for header 1).
  6. Click Save & Apply Settings. The dashboard will instantly reload and display your newly mapped fans!

Step 6: Draw Custom Fan Curves

With your fans mapped, you can edit curves visually:

  1. In the Fan Curve Configuration section on the right side of the main dashboard, select a fan tab.
  2. Toggle the mode to Automatic Curve.
  3. Choose the Temperature Sensor Source (e.g. CPU Core (Tctl) or AIO Coolant).
  4. 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.
  5. Click Apply Configuration to save your curve!

Step 7: Auto-Start on System Boot

To keep your fans regulated automatically in the background without keeping a terminal open:

  1. Copy the generated helper service file to the system services directory:
    sudo cp air-controller.service /etc/systemd/system/
  2. Reload the service list and enable the autostart daemon:
    sudo systemctl daemon-reload
    sudo systemctl enable --now air-controller.service
  3. You can verify the status or read the logs anytime:
    sudo systemctl status air-controller.service

📁 File Structure

  • 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 for config.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.

About

Linux web-based PWM fan controller and daemon with hardware auto-detection, custom fan curves, and systemd auto-start support.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages