Add README.md

2025-08-17 20:14:33 +00:00
parent 26f2f73926
commit c513928e3a
1 changed files with 199 additions and 0 deletions
--- a/README.md
+++ 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! ⭐