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
  • iSMC for hardware sensor data
  • jq for JSON parsing
  • Standard macOS utilities (ioreg, pmset)

Installation

1. Install Homebrew if you haven't already:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/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:
  -r, --rate SECONDS          Update rate in seconds (default: 60)
  -l, --logging              Enable logging
  -f, --file PATH             Log file location
  -a, --no-adjust             Monitor only mode (no BCLM adjustments)
  -v, --target-voltage VALUE  Set target voltage (default: 3.92V)
  -d, --deadband VALUE        Set voltage deadband (default: 0.02V)
  -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 --logging --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. Test thoroughly on your MacBook model
4. Submit a pull request with detailed description

Development Notes

• The script requires battery_functions.sh with core sensor reading functions
• Filter algorithms are designed to be modular and switchable
• BCLM adjustment logic prioritizes battery safety over aggressive optimization

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