lenovo-gentoo/scripts/battery-setup/README.md

# Battery Setup Tool

Manage battery charge thresholds for extended battery lifespan on ThinkPad laptops.

## Features

- 🔋 Show current battery status and health
- ⚡ Conservation mode (20-80%) for battery longevity
- 🔌 Full charge mode (0-100%) for maximum capacity
- 🎛️ Custom threshold ranges
- 🔄 Persistent settings across reboots (OpenRC service)
- ✨ Color-coded output with health indicators
- ⚡ ZSH autocompletion support

## Why Battery Conservation?

**Modern lithium-ion battery science (2025):**
- High voltage states (90-100%) accelerate degradation
- Deep discharges (below 20%) cause additional stress
- Keeping batteries at 50-80% significantly extends lifespan
- **Conservation mode can double battery cycle life**

**For docked/frequent AC usage:**
- Keeping battery at 100% for 8+ hours/day degrades it faster
- 20-80% mode stops charging at 80%, resumes below 20%
- Laptop runs on AC power while maintaining healthy battery level

## Installation

```bash
# From the scripts folder
cd scripts/battery-setup

# Install the main script
sudo cp battery-setup /usr/local/bin/battery-setup
sudo chmod +x /usr/local/bin/battery-setup

# Install ZSH autocompletion
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _battery-setup /usr/local/share/zsh/site-functions/_battery-setup

# Install OpenRC service (for persistent thresholds)
sudo cp battery-thresholds /etc/init.d/battery-thresholds
sudo chmod +x /etc/init.d/battery-thresholds

# Install service configuration
sudo cp battery-thresholds.conf /etc/conf.d/battery-thresholds

# Enable service at boot
sudo rc-update add battery-thresholds boot

# Start service now
sudo rc-service battery-thresholds start

# Reload ZSH completions (or restart your shell)
autoload -U compinit && compinit
```

## Requirements

- ThinkPad laptop with `thinkpad_acpi` kernel module
- Battery charge threshold support (available on most ThinkPads)
- Root/sudo access for changing thresholds

```bash
# Check if your system supports battery thresholds
ls /sys/class/power_supply/BAT*/charge_control_*_threshold
```

## Usage

### Show current battery status
```bash
battery-setup
# or
battery-setup status
```

Shows:
- Current battery level and charging status
- Active charge thresholds
- Battery mode (Conservation/Full/Custom)
- Battery health percentage
- Charge cycle count
- Manufacturer and model info

### Enable conservation mode (20-80%)
```bash
sudo battery-setup conservation
```

**Recommended for:**
- Daily use with frequent docking
- Laptops plugged in most of the time
- Maximizing battery lifespan

**How it works:**
- Battery charges to 80% then stops
- Resumes charging if it drops below 20%
- Laptop runs on AC power at 80%
- Significantly extends battery lifespan

### Enable full charge mode (0-100%)
```bash
sudo battery-setup full
```

**Use when:**
- Traveling or away from AC power
- Need maximum battery capacity
- Extended unplugged usage

**Note:** Higher wear on battery over time. Switch back to conservation mode for normal use.

### Set custom thresholds
```bash
sudo battery-setup custom 30 90
```

Set any custom range where start < end (both 0-100).

### Get help
```bash
battery-setup help
```

## Making Thresholds Persistent

The OpenRC service ensures your chosen thresholds are restored after every reboot.

**Configure persistent thresholds:**
```bash
# Edit the configuration file
sudo nano /etc/conf.d/battery-thresholds

# Set your preferred values:
START_THRESHOLD="20"
END_THRESHOLD="80"

# Restart service to apply
sudo rc-service battery-thresholds restart
```

**Service management:**
```bash
# Check service status
rc-service battery-thresholds status

# Restart service
sudo rc-service battery-thresholds restart

# Enable at boot
sudo rc-update add battery-thresholds boot

# Disable at boot
sudo rc-update del battery-thresholds boot
```

## Battery Health Explained

The tool calculates battery health by comparing current full capacity to design capacity:

- **90-100%**: Excellent (like new)
- **80-89%**: Good (normal wear)
- **70-79%**: Fair (noticeable degradation)
- **Below 70%**: Consider replacement

**Factors affecting battery health:**
- Charge cycles (total number of full charges)
- Time spent at high charge states (90-100%)
- Temperature (heat accelerates degradation)
- Age (batteries degrade over time regardless of use)

## Understanding Charge Thresholds

**Start Threshold:**
- Minimum charge level before charging begins
- Example: 20% means charging starts when battery drops to 20%

**End Threshold:**
- Maximum charge level before charging stops
- Example: 80% means charging stops when battery reaches 80%

**Between thresholds:**
- If plugged in and between thresholds, battery doesn't charge
- Laptop runs directly on AC power
- Battery maintains current charge level

## ZSH Autocompletion

Once installed, ZSH will provide intelligent completions:

- Command completion: `battery-setup <TAB>`
- Shows available commands with descriptions

## Troubleshooting

### "Battery not found" error
Check which batteries are available:
```bash
ls /sys/class/power_supply/BAT*
```

If your battery has a different name (BAT1, etc.), edit the script or service config.

### "Charge thresholds not supported" error
Your system doesn't have threshold support. This feature requires:
- ThinkPad laptop (most models support it)
- `thinkpad_acpi` kernel module loaded
- Modern enough BIOS/firmware

Check module:
```bash
lsmod | grep thinkpad_acpi
```

### Thresholds reset after reboot
Make sure the OpenRC service is installed and enabled:
```bash
sudo rc-update add battery-thresholds boot
sudo rc-service battery-thresholds start
```

### Permission denied when setting thresholds
The battery-setup command requires root privileges to change thresholds:
```bash
sudo battery-setup conservation
```

## Examples

### Daily use setup (recommended)
```bash
# Enable conservation mode for daily docked use
sudo battery-setup conservation

# Make it persistent
sudo rc-update add battery-thresholds boot

# Check status
battery-setup status
```

### Before a trip
```bash
# Switch to full charge mode
sudo battery-setup full

# Let it charge to 100%
battery-setup status

# After trip, switch back to conservation
sudo battery-setup conservation
```

### Custom range for specific needs
```bash
# Conservative range for maximum lifespan
sudo battery-setup custom 40 60

# Balanced range
sudo battery-setup custom 30 90
```

## Integration with Power Management

This tool complements the existing power management setup:

- **Power profiles**: AC/Battery performance modes
- **Battery thresholds**: Charge level management
- **Combined benefit**: Optimal performance + battery longevity

See `Power-Management-Setup.md` for details on the power profile system.

## Science Behind 20-80% Rule

**Why not charge to 100%?**
- At 100% charge, battery cells are at maximum voltage (~4.2V)
- High voltage accelerates electrolyte decomposition
- Lithium plating occurs more readily at high voltages
- Heat + high voltage = worst combination for battery

**Why not discharge below 20%?**
- Deep discharges strain battery cells
- Increases internal resistance over time
- Can cause capacity loss with repeated deep cycles

**Sweet spot: 20-80%**
- Minimizes voltage stress
- Reduces heat generation
- Maintains optimal cell chemistry
- Can extend battery life by 2-3x compared to 0-100% cycling

**Research sources:**
- Battery University (batteryuniversity.com)
- IEEE battery research papers
- Laptop manufacturer recommendations (Lenovo, Dell, etc.)

## Related

- Power Management: See `Power-Management-Setup.md` for AC/Battery profiles
- Audio Setup: See `scripts/audio-setup/` for audio device management
- WiFi Setup: See `scripts/wifi-setup/` for WiFi management
- Bluetooth Setup: See `scripts/bluetooth-setup/` for Bluetooth management
- Monitor Setup: See `scripts/monitor-setup/` for monitor management

## Future Enhancements

Potential features for future versions:
- GUI/waybar integration for quick threshold changes
- Automatic threshold adjustment based on usage patterns
- Battery health trending over time
- Notification when battery health degrades
- Integration with TLP or other power management tools