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

# 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

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

Usage

Show current battery status

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%)

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%)

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

sudo battery-setup custom 30 90

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

Get help

battery-setup help

Making Thresholds Persistent

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

Configure persistent thresholds:

# 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:

# 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:

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:

lsmod | grep thinkpad_acpi

Thresholds reset after reboot

Make sure the OpenRC service is installed and enabled:

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:

sudo battery-setup conservation

Examples

Daily use setup (recommended)

# 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

# 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

# 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