The Ultimate Guide to Fan Speed: Everything You Need

import os
import time
import logging
import argparse
from typing import Dict, List, Optional

# Configure logging to stdout for container compatibility
logging.basicConfig(
    level=logging.INFO,
    format=\"%(asctime)s - %(levelname)s - %(message)s\"
)
logger = logging.getLogger(__name__)

class FanController:
    \"\"\"Userspace fan controller for Linux systems using hwmon sysfs interfaces.\"\"\"

    HWMON_BASE_PATH = \"/sys/class/hwmon\"
    FAN_LABEL_PREFIXES = [\"fan\", \"cpu_fan\", \"system_fan\"]
    PWM_LABEL_PREFIXES = [\"pwm\", \"fan_pwm\"]

    def __init__(self, dry_run: bool = False):
        self.dry_run = dry_run
        self.hwmon_devices: List[Dict] = []
        self._enumerate_hwmon_devices()

    def _enumerate_hwmon_devices(self) -> None:
        \"\"\"Scan /sys/class/hwmon for fan and PWM capable devices.\"\"\"
        try:
            hwmon_entries = os.listdir(self.HWMON_BASE_PATH)
        except FileNotFoundError:
            logger.error(f\"hwmon base path {self.HWMON_BASE_PATH} not found. Install lm-sensors.\")
            raise SystemExit(1)

        for entry in hwmon_entries:
            device_path = os.path.join(self.HWMON_BASE_PATH, entry)
            if not os.path.isdir(device_path):
                continue

            device_info = {
                \"path\": device_path,
                \"name\": self._read_sysfs_attr(device_path, \"name\"),
                \"fans\": self._find_sensors(device_path, self.FAN_LABEL_PREFIXES),
                \"pwms\": self._find_sensors(device_path, self.PWM_LABEL_PREFIXES)
            }

            if device_info[\"fans\"] or device_info[\"pwms\"]:
                self.hwmon_devices.append(device_info)
                logger.info(f\"Found hwmon device: {device_info['name']} at {device_path}\")

    def _read_sysfs_attr(self, base_path: str, attr_name: str) -> Optional[str]:
        \"\"\"Read a sysfs attribute, return None if not found.\"\"\"
        attr_path = os.path.join(base_path, attr_name)
        try:
            with open(attr_path, \"r\") as f:
                return f.read().strip()
        except FileNotFoundError:
            return None
        except PermissionError:
            logger.warning(f\"Permission denied reading {attr_path}. Run with sudo.\")
            return None

    def _find_sensors(self, base_path: str, prefixes: List[str]) -> Dict[str, str]:
        \"\"\"Find all sensors matching given prefixes in base_path.\"\"\"
        sensors = {}
        try:
            entries = os.listdir(base_path)
        except PermissionError:
            logger.warning(f\"Permission denied listing {base_path}\")
            return sensors

        for entry in entries:
            for prefix in prefixes:
                if entry.startswith(prefix) and not entry.endswith(\"_enable\"):
                    # Read label if available, fall back to entry name
                    label_path = os.path.join(base_path, f\"{entry}_label\")
                    label = self._read_sysfs_attr(base_path, f\"{entry}_label\") or entry
                    sensors[label] = os.path.join(base_path, entry)
        return sensors

    def get_fan_speeds(self) -> Dict[str, int]:
        \"\"\"Read current RPM for all detected fans.\"\"\"
        fan_speeds = {}
        for device in self.hwmon_devices:
            for fan_label, fan_path in device[\"fans\"].items():
                try:
                    with open(fan_path, \"r\") as f:
                        rpm = int(f.read().strip())
                        fan_speeds[f\"{device['name']}_{fan_label}\"] = rpm
                except (ValueError, PermissionError) as e:
                    logger.warning(f\"Failed to read fan {fan_label}: {e}\")
        return fan_speeds

    def set_pwm_value(self, pwm_label: str, value: int) -> bool:
        \"\"\"Set PWM value (0-255) for a given PWM sensor. Returns success status.\"\"\"
        if not 0 <= value <= 255:
            logger.error(f\"PWM value {value} out of range (0-255)\")
            return False

        for device in self.hwmon_devices:
            for pwm_label_dev, pwm_path in device[\"pwms\"].items():
                if pwm_label_dev == pwm_label or pwm_label_dev == f\"{device['name']}_{pwm_label}\":
                    if self.dry_run:
                        logger.info(f\"Dry run: Would set {pwm_path} to {value}\")
                        return True
                    try:
                        # Enable manual PWM control first (1 = manual mode for most devices)
                        enable_path = f\"{pwm_path}_enable\"
                        with open(enable_path, \"w\") as f:
                            f.write(\"1\")
                        with open(pwm_path, \"w\") as f:
                            f.write(str(value))
                        logger.info(f\"Set {pwm_label} to {value}/255 ({(value/255)*100:.1f}%)\")
                        return True
                    except PermissionError:
                        logger.error(f\"Permission denied writing to {pwm_path}. Run with sudo.\")
                        return False
                    except FileNotFoundError:
                        logger.error(f\"PWM path {pwm_path} not found.\")
                        return False
        logger.error(f\"PWM sensor {pwm_label} not found.\")
        return False

if __name__ == \"__main__\":
    parser = argparse.ArgumentParser(description=\"Linux Userspace Fan Controller\")
    parser.add_argument(\"--dry-run\", action=\"store_true\", help=\"Simulate changes without writing to sysfs\")
    parser.add_argument(\"--interval\", type=int, default=5, help=\"Polling interval in seconds\")
    args = parser.parse_args()

    controller = FanController(dry_run=args.dry_run)

    if not controller.hwmon_devices:
        logger.error(\"No fan/PWM devices found. Install lm-sensors and load required kernel modules.\")
        raise SystemExit(1)

    logger.info(f\"Starting fan polling every {args.interval}s. Press Ctrl+C to exit.\")
    try:
        while True:
            speeds = controller.get_fan_speeds()
            logger.info(f\"Current fan speeds: {speeds}\")
            # Example: Set CPU fan to 60% if temp > 60C (would add temp reading in full implementation)
            # controller.set_pwm_value(\"pwm1\", 153)  # 60% of 255
            time.sleep(args.interval)
    except KeyboardInterrupt:
        logger.info(\"Stopping fan controller.\")

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using OpenHardwareMonitor.Hardware;

namespace FanController
{
    /// <summary>
    /// Windows userspace fan controller using OpenHardwareMonitor library.
    /// Requires OpenHardwareMonitorLib.dll (v0.9.6+) from https://github.com/nicomp/OpenHardwareMonitor
    /// </summary>
    class Program
    {
        private static IHardware[] _hardware;
        private static Dictionary<string, float> _fanSpeeds = new Dictionary<string, float>();
        private static Dictionary<string, IControl> _fanControls = new Dictionary<string, IControl>();
        private static Timer _pollingTimer;
        private static bool _dryRun = false;

        static void Main(string[] args)
        {
            // Parse command line arguments
            foreach (var arg in args)
            {
                if (arg == \"--dry-run\") _dryRun = true;
            }

            Console.WriteLine(\"Initializing OpenHardwareMonitor...\");
            var computer = new Computer
            {
                MainboardEnabled = true,
                CPUEnabled = true,
                FanControllerEnabled = true,
                RAMEnabled = false,
                GPUEnabled = false,
                HDDEnabled = false
            };
            computer.Open();

            _hardware = computer.Hardware;
            EnumerateFanDevices();

            if (_fanControls.Count == 0)
            {
                Console.WriteLine(\"No controllable fan devices found. Run as Administrator.\");
                return;
            }

            Console.WriteLine($\"Found {_fanControls.Count} controllable fans. Starting polling every 5s.\");
            _pollingTimer = new Timer(PollFans, null, 0, 5000);

            Console.WriteLine(\"Press any key to exit.\");
            Console.ReadKey();
            _pollingTimer.Dispose();
            computer.Close();
        }

        static void EnumerateFanDevices()
        {
            foreach (var hw in _hardware)
            {
                Console.WriteLine($\"Hardware: {hw.Name} ({hw.Identifier})\");
                hw.Update();
                foreach (var subHw in hw.SubHardware)
                {
                    subHw.Update();
                    ScanForFans(subHw);
                }
                ScanForFans(hw);
            }
        }

        static void ScanForFans(IHardware hw)
        {
            foreach (var sensor in hw.Sensors)
            {
                if (sensor.SensorType == SensorType.Fan)
                {
                    var fanKey = $\"{hw.Identifier}/{sensor.Identifier}\";
                    _fanSpeeds[fanKey] = sensor.Value ?? 0;
                    Console.WriteLine($\"Found fan: {sensor.Name} ({fanKey}) - Current: {sensor.Value ?? 0} RPM\");
                }
                else if (sensor.SensorType == SensorType.Control)
                {
                    var controlKey = $\"{hw.Identifier}/{sensor.Identifier}\";
                    _fanControls[controlKey] = (IControl)sensor;
                    Console.WriteLine($\"Found controllable fan: {sensor.Name} ({controlKey}) - Current: {sensor.Value ?? 0}%\");
                }
            }
        }

        static void PollFans(object state)
        {
            foreach (var hw in _hardware)
            {
                hw.Update();
                foreach (var subHw in hw.SubHardware)
                {
                    subHw.Update();
                }
            }

            // Update fan speeds
            foreach (var hw in _hardware)
            {
                foreach (var sensor in hw.Sensors)
                {
                    if (sensor.SensorType == SensorType.Fan)
                    {
                        var fanKey = $\"{hw.Identifier}/{sensor.Identifier}\";
                        _fanSpeeds[fanKey] = sensor.Value ?? 0;
                    }
                }
            }

            Console.WriteLine($\"[{DateTime.Now}] Current fan speeds:\");
            foreach (var fan in _fanSpeeds)
            {
                Console.WriteLine($\"  {fan.Key}: {fan.Value} RPM\");
            }

            // Example: Set all fans to 60% speed
            if (!_dryRun)
            {
                foreach (var control in _fanControls)
                {
                    try
                    {
                        control.Value.SetSoftwareControlValue(60); // 60% speed
                        Console.WriteLine($\"Set {control.Key} to 60% speed\");
                    }
                    catch (UnauthorizedAccessException)
                    {
                        Console.WriteLine($\"Permission denied for {control.Key}. Run as Administrator.\");
                    }
                }
            }
            else
            {
                Console.WriteLine(\"Dry run: Would set all fans to 60% speed\");
            }
        }
    }
}

import RPi.GPIO as GPIO
import time
import logging
import argparse
from typing import Dict, Optional

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format=\"%(asctime)s - %(levelname)s - %(message)s\"
)
logger = logging.getLogger(__name__)

class RPiFanController:
    \"\"\"Fan controller for Raspberry Pi using GPIO PWM (supports 2-pin and 4-pin fans).\"\"\"

    # Default GPIO pin mappings for common Pi fan setups
    DEFAULT_GPIO_MAP = {
        \"cpu_fan\": 18,  # PWM0 on Pi 4/5
        \"case_fan\": 19  # PWM1 on Pi 4/5
    }
    PWM_FREQUENCY = 25000  # 25kHz is standard for 4-pin PWM fans
    FAN_ON_TEMP = 60.0  # Celsius, turn fan on above this
    FAN_OFF_TEMP = 55.0  # Celsius, turn fan off below this
    TEMP_PATH = \"/sys/class/thermal/thermal_zone0/temp\"  # Pi CPU temp

    def __init__(self, gpio_map: Optional[Dict[str, int]] = None, dry_run: bool = False):
        self.gpio_map = gpio_map or self.DEFAULT_GPIO_MAP
        self.dry_run = dry_run
        self.pwm_channels: Dict[str, GPIO.PWM] = {}
        self._init_gpio()

    def _init_gpio(self) -> None:
        \"\"\"Initialize RPi.GPIO and set up PWM channels.\"\"\"
        if self.dry_run:
            logger.info(\"Dry run: Skipping GPIO initialization\")
            return
        try:
            GPIO.setmode(GPIO.BCM)
            for fan_name, pin in self.gpio_map.items():
                GPIO.setup(pin, GPIO.OUT)
                pwm = GPIO.PWM(pin, self.PWM_FREQUENCY)
                pwm.start(0)  # Start with fan off
                self.pwm_channels[fan_name] = pwm
                logger.info(f\"Initialized {fan_name} on GPIO {pin} with {self.PWM_FREQUENCY}Hz PWM\")
        except RuntimeError as e:
            logger.error(f\"GPIO initialization failed: {e}. Are you running on a Raspberry Pi?\")
            raise SystemExit(1)

    def get_cpu_temp(self) -> float:
        \"\"\"Read CPU temperature in Celsius.\"\"\"
        try:
            with open(self.TEMP_PATH, \"r\") as f:
                temp_raw = f.read().strip()
                # Temp is reported in millidegrees Celsius
                return int(temp_raw) / 1000.0
        except FileNotFoundError:
            logger.error(f\"CPU temp path {self.TEMP_PATH} not found.\")
            return 0.0
        except ValueError:
            logger.error(f\"Invalid temp value read from {self.TEMP_PATH}\")
            return 0.0

    def set_fan_speed(self, fan_name: str, speed_percent: float) -> bool:
        \"\"\"Set fan speed as percentage (0-100).\"\"\"
        if not 0 <= speed_percent <= 100:
            logger.error(f\"Speed {speed_percent}% out of range (0-100)\")
            return False

        if fan_name not in self.pwm_channels:
            logger.error(f\"Fan {fan_name} not found. Available: {list(self.pwm_channels.keys())}\")
            return False

        if self.dry_run:
            logger.info(f\"Dry run: Would set {fan_name} to {speed_percent}%\")
            return True

        try:
            self.pwm_channels[fan_name].ChangeDutyCycle(speed_percent)
            logger.info(f\"Set {fan_name} to {speed_percent}% speed\")
            return True
        except RuntimeError as e:
            logger.error(f\"Failed to set {fan_name} speed: {e}\")
            return False

    def run_thermal_loop(self, interval: int = 5) -> None:
        \"\"\"Run main loop adjusting fan speed based on CPU temp.\"\"\"
        logger.info(f\"Starting thermal loop: On temp {self.FAN_ON_TEMP}C, Off temp {self.FAN_OFF_TEMP}C\")
        try:
            while True:
                cpu_temp = self.get_cpu_temp()
                logger.info(f\"CPU Temp: {cpu_temp:.1f}C\")

                for fan_name in self.pwm_channels.keys():
                    if cpu_temp >= self.FAN_ON_TEMP:
                        # Linear scaling: 60C = 30% speed, 80C = 100% speed
                        speed = min(100, max(30, (cpu_temp - 60) * 3.5))
                        self.set_fan_speed(fan_name, speed)
                    elif cpu_temp <= self.FAN_OFF_TEMP:
                        self.set_fan_speed(fan_name, 0)
                    else:
                        # Hysteresis zone: keep current speed
                        pass

                time.sleep(interval)
        except KeyboardInterrupt:
            logger.info(\"Stopping thermal loop.\")
            self.cleanup()

    def cleanup(self) -> None:
        \"\"\"Clean up GPIO resources.\"\"\"
        if not self.dry_run:
            for fan_name, pwm in self.pwm_channels.items():
                pwm.stop()
            GPIO.cleanup()
            logger.info(\"GPIO cleaned up.\")

if __name__ == \"__main__\":
    parser = argparse.ArgumentParser(description=\"Raspberry Pi Fan Controller\")
    parser.add_argument(\"--dry-run\", action=\"store_true\", help=\"Simulate changes without GPIO access\")
    parser.add_argument(\"--interval\", type=int, default=5, help=\"Polling interval in seconds\")
    parser.add_argument(\"--on-temp\", type=float, default=60.0, help=\"Turn fan on at this temp (C)\")
    parser.add_argument(\"--off-temp\", type=float, default=55.0, help=\"Turn fan off at this temp (C)\")
    args = parser.parse_args()

    controller = RPiFanController(dry_run=args.dry_run)
    controller.FAN_ON_TEMP = args.on_temp
    controller.FAN_OFF_TEMP = args.off_temp
    controller.run_thermal_loop(interval=args.interval)

# Snippet: Validate PWM range before writing
def validate_pwm_range(pwm_path: str, value: int) -> int:
    min_path = f\"{pwm_path}_min\"
    max_path = f\"{pwm_path}_max\"
    try:
        with open(min_path, \"r\") as f:
            pwm_min = int(f.read().strip())
        with open(max_path, \"r\") as f:
            pwm_max = int(f.read().strip())
        return max(pwm_min, min(pwm_max, value))
    except FileNotFoundError:
        # Fall back to 0-255 default
        return max(0, min(255, value))

# Snippet: Hysteresis-based fan speed calculation
def calculate_hysteresis_speed(current_temp: float, on_threshold: float, off_threshold: float, last_speed: float) -> float:
    if current_temp >= on_threshold:
        # Scale linearly between on_threshold and on_threshold + 20C
        return min(100, (current_temp - on_threshold) * 5)
    elif current_temp <= off_threshold:
        return 0.0
    else:
        # Keep last speed in hysteresis zone
        return last_speed

# Snippet: Structured thermal logging
import json
def log_thermal_event(event_type: str, metadata: dict):
    log_entry = {
        \"timestamp\": time.strftime(\"%Y-%m-%dT%H:%M:%SZ\", time.gmtime()),
        \"event\": event_type,
        **metadata
    }
    logger.info(json.dumps(log_entry))

fan-speed-guide/
├── linux/
│   ├── fan_controller.py       # Code Example 1: Linux hwmon controller
│   ├── requirements.txt        # Python dependencies (none required for base version)
│   └── systemd/
│       └── fan-controller.service  # Systemd unit file for auto-start
├── windows/
│   ├── FanController.cs        # Code Example 2: Windows OpenHardwareMonitor controller
│   ├── FanController.csproj    # .NET 6 project file
│   └── libs/
│       └── OpenHardwareMonitorLib.dll  # v0.9.6+
├── raspberry-pi/
│   ├── rpi_fan_controller.py   # Code Example 3: RPi GPIO PWM controller
│   └── requirements.txt        # RPi.GPIO dependency
├── benchmarks/
│   ├── latency_results.csv     # Raw benchmark data for comparison table
│   └── cost_calculator.py      # Script to calculate cooling cost savings
├── grafana/
│   └── thermal-dashboard.json  # Pre-built Grafana dashboard for thermal monitoring
└── README.md                   # Setup instructions, troubleshooting tips