battery_life/docs/powertop-guide.md

# PowerTOP Usage Guide

## Overview

PowerTOP is a Linux tool to diagnose issues with power consumption and power management. It provides detailed information about power usage by various system components and suggests optimizations.

## Installation Verification

After running the installation script, verify PowerTOP is installed:

```bash
# Check PowerTOP version
powertop --version

# Quick test (requires sudo)
sudo powertop --time=5
```

## Basic Usage

### Interactive Mode

```bash
# Launch PowerTOP in interactive mode
sudo powertop
```

**Navigation:**
- `Tab`: Switch between tabs
- `Enter`: Toggle tunables
- `q`: Quit
- Arrow keys: Navigate lists

### Tabs Overview

1. **Overview**: General system power consumption
2. **Idle stats**: CPU idle state statistics
3. **Frequency stats**: CPU frequency usage
4. **Device stats**: Individual device power usage
5. **Tunables**: Available power optimizations

## Command Line Usage

### Generate Reports

```bash
# Generate HTML report (60 seconds)
sudo powertop --html=report.html --time=60

# Generate CSV report
sudo powertop --csv=report.csv --time=60

# Custom duration
sudo powertop --html=report.html --time=120
```

### Auto-tune Mode

```bash
# Apply all available optimizations
sudo powertop --auto-tune

# View what would be changed (dry-run)
sudo powertop --auto-tune --debug
```

**Note:** Auto-tune changes are temporary and reset on reboot.

## Using the PowerTOP Analysis Script

Our custom script (`scripts/powertop-analyze.sh`) provides enhanced functionality:

### Basic Report Generation

```bash
# Generate 60-second HTML report
./scripts/powertop-analyze.sh

# Custom duration and format
./scripts/powertop-analyze.sh --duration 120 --format csv

# Different output directory
./scripts/powertop-analyze.sh --output /tmp/reports
```

### Apply Optimizations

```bash
# Apply PowerTOP auto-tune
./scripts/powertop-analyze.sh --auto-tune

# Quick system summary
./scripts/powertop-analyze.sh --quick
```

### View Reports

```bash
# Open latest report in browser
./scripts/powertop-analyze.sh --show-report

# List all generated reports
ls -la ~/.battery-optimizer/reports/
```

## Understanding Reports

### HTML Report Sections

1. **System Information**
   - Hardware details
   - Kernel version
   - System uptime

2. **Power Consumption Overview**
   - Total system power draw
   - Battery discharge rate
   - Power source information

3. **Top Power Consumers**
   - Applications using most power
   - Hardware devices consuming power
   - System services impact

4. **Processor Information**
   - CPU frequency usage
   - Idle state statistics
   - Core utilization

5. **Device Power Management**
   - ASPM status
   - Runtime PM status
   - USB autosuspend status

6. **Tunables**
   - Available optimizations
   - Current status (Good/Bad)
   - Recommended changes

### Key Metrics to Monitor

1. **Power Consumption (Watts)**
   - Lower is better
   - Typical laptop: 8-15W idle, 25-45W under load

2. **Wakeups per Second**
   - Lower is better for battery life
   - Target: <100 wakeups/second

3. **CPU Usage**
   - Identify power-hungry applications
   - Background processes impact

## Optimization Categories

### CPU Optimizations

```bash
# CPU governor (applied by TLP)
echo 'powersave' | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# CPU idle states
# Managed automatically by kernel
```

### Device Power Management

```bash
# Enable ASPM (PCIe power saving)
echo 'powersave' | sudo tee /sys/module/pcie_aspm/parameters/policy

# Runtime PM for devices
echo 'auto' | sudo tee /sys/bus/pci/devices/*/power/control
```

### USB Power Management

```bash
# Enable USB autosuspend
echo '1' | sudo tee /sys/module/usbcore/parameters/autosuspend

# Per-device control
echo 'auto' | sudo tee /sys/bus/usb/devices/*/power/control
```

### Audio Power Saving

```bash
# Enable audio power saving
echo '1' | sudo tee /sys/module/snd_hda_intel/parameters/power_save
```

## Making Optimizations Permanent

### Method 1: Systemd Service (Recommended)

Our installation script creates a PowerTOP service:

```bash
# Check service status
systemctl status powertop.service

# Enable auto-tune on boot
sudo systemctl enable powertop.service

# Manually run auto-tune
sudo systemctl start powertop.service
```

### Method 2: Custom Scripts

Create startup scripts in `/etc/rc.local` or systemd services:

```bash
# Example optimization script
#!/bin/bash
echo 'auto' > /sys/bus/pci/devices/*/power/control
echo 'min_power' > /sys/class/scsi_host/*/link_power_management_policy
```

### Method 3: TLP Integration

Most PowerTOP optimizations are already included in our TLP configuration.

## Troubleshooting

### Common Issues

1. **PowerTOP requires root privileges**
   - This is normal for hardware access
   - Always use `sudo powertop`

2. **No power consumption data**
   - Check if running on battery
   - Ensure ACPI support in kernel
   - Some virtual machines don't report power data

3. **Optimizations not persisting**
   - Use systemd service for permanent changes
   - Check for conflicting power managers

### Debug Commands

```bash
# Check kernel power management support
ls /sys/class/power_supply/

# Verify ACPI tables
sudo acpidump | head -20

# Check for power management conflicts
systemctl list-units | grep power
```

## Best Practices

### Regular Monitoring

1. **Weekly Reports**: Generate PowerTOP reports to track trends
2. **Before/After Testing**: Measure impact of configuration changes
3. **Application Profiling**: Identify power-hungry applications

### Analysis Workflow

1. **Baseline Measurement**: Record power consumption before changes
2. **Apply Optimizations**: Use systematic approach
3. **Measure Impact**: Generate new reports
4. **Document Changes**: Keep track of what works

### Report Interpretation

1. **Focus on Top Consumers**: Address highest impact items first
2. **Check Tunables**: Apply "Bad" recommendations carefully
3. **Monitor Trends**: Look for patterns over time
4. **Validate Changes**: Ensure functionality isn't compromised

## Integration with Other Tools

### With TLP

PowerTOP and TLP complement each other:
- TLP: Provides systematic, persistent power management
- PowerTOP: Offers detailed analysis and additional optimizations

### With System Monitoring

```bash
# Combine with system monitoring
./scripts/powertop-analyze.sh &
./scripts/battery-monitor.sh --watch
```

### With Performance Tools

```bash
# Monitor performance impact
htop &
sudo powertop --auto-tune
# Check if system remains responsive
```

## Advanced Usage

### Automated Analysis

```bash
#!/bin/bash
# Daily power analysis script
DATE=$(date +%Y%m%d)
sudo powertop --html=/var/log/powertop_${DATE}.html --time=3600

# Email report or upload to monitoring system
```

### Custom Reporting

```bash
# Extract specific data from CSV reports
awk -F',' 'NR>1 {print $1,$3}' report.csv | sort -k2 -nr | head -10
```

### Integration with Monitoring Systems

PowerTOP data can be integrated with:
- Grafana dashboards
- Nagios monitoring
- Custom logging systems

---

This guide should be used alongside the PowerTOP analysis script provided in this repository for optimal power management.