From c513928e3a97f0d3574b3fa9f9ff70def1615f05 Mon Sep 17 00:00:00 2001 From: mike Date: Sun, 17 Aug 2025 20:14:33 +0000 Subject: [PATCH] Add README.md --- README.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fc5e28c --- /dev/null +++ b/README.md @@ -0,0 +1,199 @@ +# Dell Fan Control - Proxmox 9 / Debian Trixie Compatible + +## Overview + +This is a **Proxmox 9 / Debian Trixie compatible** version of the Dell R710/R720 fan controller that fixes critical compatibility issues with modern systems. If you've upgraded to Proxmox 9 and your fan control stopped working with pysensors errors, this is the solution you've been looking for. + +### 🚨 The Problem +The original fan controller breaks on: +- **Proxmox 9** (Debian Trixie based) +- **Python 3.13+** environments +- Systems with **updated pysensors** library +- Any modern Debian/Ubuntu installation + +### ✅ The Solution +This version eliminates the problematic `pysensors` dependency and uses the reliable `sensors` command directly, providing: +- **100% compatibility** with Proxmox 9 and Debian Trixie +- **No more API breakage** from pysensors updates +- **Simplified installation** with fewer dependencies +- **Better error handling** and safety fallbacks + +## Installation + +### Quick Install (Recommended) +```bash +git clone https://github.com/yourusername/dell-fan-control-proxmox9.git +cd dell-fan-control-proxmox9 +sudo ./install.sh +``` + +The default installation path is `/opt/fan_control` and the service will be installed as `fan-control.service`. + +### Custom Installation Path +```bash +sudo ./install.sh /custom/path +``` + +### Post-Installation +1. **Edit the configuration:** + ```bash + sudo nano /opt/fan_control/fan_control.yaml + ``` + +2. **Check the service status:** + ```bash + sudo systemctl status fan-control + ``` + +3. **Monitor the logs:** + ```bash + sudo journalctl -u fan-control.service -f + ``` + +## Upgrading from Original Version + +If you're upgrading from the original fan controller after a Proxmox 8→9 upgrade: + +```bash +# Stop the broken service +sudo systemctl stop fan-control + +# Backup your config +sudo cp /opt/fan_control/fan_control.yaml /opt/fan_control/fan_control.yaml.backup + +# Clone and install the fixed version +git clone https://github.com/yourusername/dell-fan-control-proxmox9.git +cd dell-fan-control-proxmox9 +sudo ./install.sh + +# Your configuration will be automatically preserved +``` + +## Configuration + +Edit `/opt/fan_control/fan_control.yaml` to set your temperature thresholds and fan speeds: + +```yaml +general: + debug: false + interval: 30 + +hosts: + - name: MyLocalHost + hysteresis: 3 + temperatures: + - 39 # Low temp threshold + - 45 # Medium temp threshold + - 55 # High temp threshold + speeds: + - 20 # Fan speed % for low temps + - 30 # Fan speed % for medium temps + - 40 # Fan speed % for high temps +``` + +## What's Changed + +### 🔧 Technical Fixes +- **Removed pysensors dependency** - No more API compatibility issues +- **Direct sensors command parsing** - Uses the reliable `sensors` command output +- **Simplified virtual environment** - Only requires PyYAML now +- **Better error handling** - Graceful fallback to automatic mode on errors +- **Improved safety** - Service automatically returns fans to auto mode on failure + +### 📦 Installation Improvements +- **Fewer system dependencies** - No more build tools or dev packages needed +- **Modern Python practices** - Uses `python3 -m venv` instead of legacy virtualenv +- **Better configuration handling** - Preserves existing configs during upgrades +- **Enhanced service file** - Includes resource limits and security hardening + +### 🛡️ Safety Enhancements +- **Automatic fallback** - Switches to automatic fan control if temperature reading fails +- **Service restart protection** - Ensures fans return to auto mode if service crashes +- **Resource limits** - Prevents runaway CPU/memory usage +- **Timeout handling** - Protects against hanging sensor commands + +## Compatibility + +### ✅ Tested On +- **Proxmox VE 9.x** (Debian Trixie) +- **Debian 13 (Trixie)** +- **Python 3.13+** +- **Dell PowerEdge R710, R720** + +### ⚠️ Original Version Issues +The original script fails on modern systems with errors like: +- `ModuleNotFoundError: No module named 'yaml'` +- `AttributeError: module 'sensors' has no attribute 'get_detected_chips'` +- `'Chip' object has no attribute 'get_features'` +- Virtual environment corruption after system upgrades + +## Troubleshooting + +### Service Won't Start +```bash +# Check the logs +sudo journalctl -u fan-control.service -n 50 + +# Test manually +sudo /opt/fan_control/venv/bin/python3 /opt/fan_control/fan_control.py +``` + +### No Temperature Readings +```bash +# Check if sensors work +sensors + +# Run sensor detection +sudo sensors-detect +# Answer YES to safe probes, then reboot +``` + +### Fans Still Loud +```bash +# Check if IPMI is working +sudo ipmitool sensor list | grep -i fan + +# Verify iDRAC connectivity (if using remote) +sudo ipmitool -I lanplus -H your-idrac-ip -U username -P password sensor list +``` + +## Credits + +This project is based on the excellent work by **[Niccolò Maggioni](https://github.com/nmaggioni)** in the original [r710-fan-controller](https://github.com/nmaggioni/r710-fan-controller) repository. + +### Original Author +- **Niccolò Maggioni** - [nmaggioni](https://github.com/nmaggioni) +- Original repository: https://github.com/nmaggioni/r710-fan-controller + +### Modifications for Proxmox 9 Compatibility +- **[Your GitHub Username]** - Proxmox 9 compatibility fixes and modern Python support + +## License + +This project maintains the same license as the original work. Please see the [original repository](https://github.com/nmaggioni/r710-fan-controller) for license details. + +## Contributing + +Found a bug or have an improvement? Please open an issue or submit a pull request! + +### Common Contribution Areas +- Support for additional Dell PowerEdge models +- Enhanced configuration validation +- Additional safety features +- Documentation improvements + +## Changelog + +### v2.0.0 (Proxmox 9 Compatible) +- **BREAKING**: Removed pysensors dependency +- **NEW**: Direct sensors command parsing +- **NEW**: Enhanced error handling and safety +- **NEW**: Simplified installation process +- **FIX**: Compatibility with Python 3.13+ +- **FIX**: Compatibility with Proxmox 9 / Debian Trixie +- **IMPROVE**: Better configuration preservation during upgrades +- **IMPROVE**: Enhanced systemd service with resource limits + +--- + +## ⭐ Star this repo if it saved your ears from screaming fans! ⭐ \ No newline at end of file