From 4e710f27cd3b7a446f82b895d45287d6e391baaf Mon Sep 17 00:00:00 2001 From: root Date: Thu, 11 Dec 2025 13:11:21 +0100 Subject: [PATCH] Add comprehensive README with installation and usage instructions --- README.md | 302 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b62de8e --- /dev/null +++ b/README.md @@ -0,0 +1,302 @@ +# T14 System Settings Manager + +A comprehensive GUI and system tray application for managing Lenovo ThinkPad T14 Gen 6 system settings on Linux (Kubuntu/Ubuntu). + +## Features + +### CPU Governor Control +- **Performance Mode**: Maximum CPU performance when plugged into AC power +- **Powersave Mode**: Battery-optimized CPU frequency scaling +- Automatic switching based on AC power status (via udev rules) + +### Fan Control +- **7 Fan Levels**: Manual control from L1 (silent) to L7 (maximum cooling) +- **Automatic Mode (L2)**: Temperature-based fan management via thinkfan +- **Office-Friendly**: Default configuration keeps fan at constant level 2 (~2600 RPM) up to 100°C +- Real-time fan speed monitoring + +### Battery Management +- **Conservative Mode (75-80%)**: Extends battery lifespan for daily use +- **Moderate Mode (80-90%)**: Balanced charging for regular usage +- **Full Charge (0-100%)**: Maximum capacity when needed +- **Quick Charge**: One-click charge to 100% immediately +- **Automated Management**: + - Time-based: Automatically charge to full before end of workday + - Network-based: Smart charging based on WiFi location (office vs. home) + +### System Integration +- **GUI Application**: Full-featured window with all controls +- **System Tray**: Quick access menu with status updates +- **Auto-start**: Tray icon launches automatically on login +- **Real-time Status**: CPU temperature, governor, fan speed, battery level + +## Requirements + +### Hardware +- Lenovo ThinkPad T14 Gen 6 (Intel) +- Battery with charge threshold support (BAT0) + +### Software +- Ubuntu 24.04 / Kubuntu (or compatible) +- Python 3.12+ +- Thinkfan 1.3.1+ +- Required Python packages: `tkinter`, `pystray`, `pillow` + +## Installation + +### 1. Install Dependencies + +```bash +# Install thinkfan +sudo apt install thinkfan + +# Install Python packages +pip3 install --user --break-system-packages pystray pillow +``` + +### 2. Enable ThinkPad Fan Control + +```bash +# Enable fan control parameter +echo "options thinkpad_acpi fan_control=1" | sudo tee /etc/modprobe.d/thinkpad_acpi.conf + +# Apply immediately +sudo modprobe -r thinkpad_acpi +sudo modprobe thinkpad_acpi +``` + +### 3. Configure Thinkfan + +Create `/etc/thinkfan.yaml`: + +```yaml +sensors: + - hwmon: /sys/class/hwmon/hwmon5/temp1_input # CPU core temp + indices: [1, 2, 3, 4, 5, 6, 7, 8, 9] + - hwmon: /sys/class/hwmon/hwmon7/temp1_input # ThinkPad sensor + indices: [1] + - hwmon: /sys/class/hwmon/hwmon3/temp1_input # NVMe temp + indices: [1] + +fans: + - tpacpi: /proc/acpi/ibm/fan + +levels: + - ["level 2", 0, 100] # Constant level 2 up to 100°C (ultra-silent) + - ["level 3", 98, 255] # Level 3 only above 98°C (safety) +``` + +Enable and start thinkfan: + +```bash +sudo systemctl enable thinkfan +sudo systemctl start thinkfan +``` + +### 4. Create Privilege Elevation Helper + +Create `/usr/local/bin/system-settings-helper.sh`: + +```bash +#!/bin/bash +case "$1" in + cpu-governor) + for cpu in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do + echo "$2" > "$cpu" + done + ;; + fan-level) + echo "level $2" > /proc/acpi/ibm/fan + ;; + fan-stop-thinkfan) + systemctl stop thinkfan + ;; + fan-start-thinkfan) + systemctl start thinkfan + ;; + battery-start) + echo "$2" > /sys/class/power_supply/BAT0/charge_control_start_threshold + ;; + battery-end) + echo "$2" > /sys/class/power_supply/BAT0/charge_control_end_threshold + ;; +esac +``` + +Make it executable: + +```bash +sudo chmod +x /usr/local/bin/system-settings-helper.sh +``` + +### 5. Setup CPU Governor Auto-Switching + +Create `/usr/local/bin/cpu-governor-switch.sh`: + +```bash +#!/bin/bash +if [ "$(cat /sys/class/power_supply/AC/online)" = "1" ]; then + for cpu in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do + echo "performance" > "$cpu" + done +else + for cpu in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do + echo "powersave" > "$cpu" + done +fi +``` + +Create udev rule `/etc/udev/rules.d/99-cpu-governor.rules`: + +``` +ACTION=="change", SUBSYSTEM=="power_supply", ENV{POWER_SUPPLY_ONLINE}=="*", RUN+="/usr/local/bin/cpu-governor-switch.sh" +``` + +Make executable and reload: + +```bash +sudo chmod +x /usr/local/bin/cpu-governor-switch.sh +sudo udevadm control --reload-rules +``` + +### 6. Install the Applications + +```bash +# Clone this repository +git clone ssh://git@gitea.egonetix.de:222/root/battery_management.git +cd battery_management + +# Make scripts executable +chmod +x system-settings-gui.py system-settings-tray.py + +# Create desktop entry for GUI +cat > ~/.local/share/applications/system-settings-gui.desktop << EOF +[Desktop Entry] +Type=Application +Name=T14 System Settings +Comment=Manage T14 CPU, Fan, and Battery Settings +Exec=python3 $(pwd)/system-settings-gui.py +Icon=preferences-system +Terminal=false +Categories=System;Settings; +EOF + +# Create autostart entry for tray +mkdir -p ~/.config/autostart +cat > ~/.config/autostart/system-settings-tray.desktop << EOF +[Desktop Entry] +Type=Application +Name=T14 System Tray +Comment=T14 System Settings in System Tray +Exec=python3 $(pwd)/system-settings-tray.py +Icon=preferences-system +Terminal=false +Categories=System;Settings; +StartupNotify=false +X-GNOME-Autostart-enabled=true +EOF + +# Update desktop database +update-desktop-database ~/.local/share/applications +``` + +## Usage + +### GUI Application +Launch from application menu: **System → T14 System Settings** + +Or run directly: +```bash +python3 system-settings-gui.py +``` + +### System Tray +The tray icon starts automatically on login. Right-click the icon for quick access to: +- CPU governor switching +- Fan level control (L1-L7) +- Battery management presets +- Quick charge to 100% + +### Command Line + +Check current status: +```bash +# CPU temperature +cat /sys/class/hwmon/hwmon5/temp1_input | awk '{print int($1/1000)}' + +# CPU governor +cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor + +# Fan speed +grep "^speed" /proc/acpi/ibm/fan + +# Battery status +cat /sys/class/power_supply/BAT0/capacity +cat /sys/class/power_supply/BAT0/status +cat /sys/class/power_supply/BAT0/charge_control_start_threshold +cat /sys/class/power_supply/BAT0/charge_control_end_threshold +``` + +## Fan Levels + +| Level | Speed (RPM) | Use Case | +|-------|-------------|----------| +| L1 | ~2400 | Ultra-silent (very low load) | +| L2 | ~2600 | Silent office mode (default auto) | +| L3 | ~3100 | Light work | +| L4 | ~3600 | Moderate load | +| L5 | ~3900 | Higher performance | +| L6 | ~4400 | Heavy workload | +| L7 | ~5100+ | Maximum cooling | + +**Note**: L2 is the default automatic mode managed by thinkfan. Selecting L2 re-enables automatic temperature-based fan management. All other levels disable thinkfan and use manual fan control. + +## Battery Health Tips + +- **Daily Use**: Keep at 75-80% for maximum battery lifespan +- **Before Travel**: Charge to 100% (0-100% mode) +- **Long-term Storage**: Store at 50-60% charge +- **Avoid**: Constant 100% charging when plugged in all day + +## Troubleshooting + +### Fan control not working +```bash +# Verify fan control is enabled +cat /sys/module/thinkpad_acpi/parameters/fan_control +# Should output: Y + +# Check if thinkfan is running +systemctl status thinkfan +``` + +### Permission denied errors +```bash +# Verify helper script exists and is executable +ls -l /usr/local/bin/system-settings-helper.sh + +# Test pkexec manually +pkexec /usr/local/bin/system-settings-helper.sh cpu-governor performance +``` + +### Tray icon not appearing +```bash +# Check if process is running +ps aux | grep system-settings-tray + +# Restart manually +pkill -f system-settings-tray +python3 system-settings-tray.py & +``` + +## License + +MIT License - Feel free to modify and distribute. + +## Author + +Created for Lenovo ThinkPad T14 Gen 6 on Kubuntu 24.04. + +## Contributing + +Issues and pull requests welcome at: https://gitea.egonetix.de/root/battery_management