batterycapacity

README

batterycapacity

Convert between the capacity units printed on battery packs and the figures that actually matter: real delivered energy, and the watt-hour rating airlines regulate by.

Install

go get github.com/taysirco/batterycapacity

Usage

import "github.com/taysirco/batterycapacity"

// Airlines regulate by watt-hours, not mAh
batterycapacity.WattHours(20000, batterycapacity.NominalCellVolts)  // 74 Wh
batterycapacity.FlightStatus(74)                                    // "allowed"
batterycapacity.FlightStatus(120)                                   // "airline approval required"

// What a 20000mAh pack actually delivers at USB voltage
batterycapacity.UsableMAh(20000, 3.7, 0.85)                         // ~12580 mAh

// Real number of phone charges, not the marketing number
batterycapacity.PhoneCharges(20000, 3.7, 0.85, 4500)                // ~2.8

// Capacity remaining after 400 full cycles
batterycapacity.CyclesToPercent(400, 0.0005)                        // ~81.9%

Why the printed number misleads

A lithium-ion cell stores charge at roughly 3.7 V nominal, but USB delivers at 5 V. Boosting the voltage conserves energy, not charge — so the mAh figure shrinks by the voltage ratio before any losses are counted. Add conversion inefficiency and the pack's own control circuitry, and a 20000 mAh pack realistically delivers around 12500 mAh at 5 V.

This is also why airline rules are written in watt-hours: Wh accounts for voltage and is therefore comparable across chemistries, while mAh alone is not. Most carriers allow up to 100 Wh in the cabin without approval, 100–160 Wh with airline consent, and refuse anything above.

License

MIT

Documentation

Overview

Package batterycapacity converts between the capacity units printed on battery packs and the figures that actually matter: real delivered energy, and the watt-hour rating airlines regulate by.

The number on a power bank's shell (mAh) measures raw cell charge, not the energy that reaches a device. Conversion losses, the pack's own control circuitry, and cell voltage all sit between the two.

Index

• Constants
• func CyclesToPercent(cycles int, fadePerCycle float64) float64
• func FlightStatus(wh float64) string
• func PhoneCharges(ratedMAh, cellVolts, efficiency, phoneMAh float64) float64
• func UsableMAh(ratedMAh, cellVolts, efficiency float64) float64
• func WattHours(ratedMAh, cellVolts float64) float64

Constants

const (
	// NominalCellVolts is the typical nominal voltage of a single lithium-ion cell.
	NominalCellVolts = 3.7
	// USBOutputVolts is the baseline USB output voltage packs convert up to.
	USBOutputVolts = 5.0
	// TypicalEfficiency is a conservative real-world conversion efficiency for a
	// well-built pack (boost conversion plus control-circuit overhead).
	TypicalEfficiency = 0.85
	// IATALimitWh is the watt-hour ceiling most airlines allow in cabin baggage
	// without prior approval.
	IATALimitWh = 100.0
	// IATAApprovalLimitWh is the ceiling above which carriage is refused outright.
	IATAApprovalLimitWh = 160.0
)

Functions

func CyclesToPercent

func CyclesToPercent(cycles int, fadePerCycle float64) float64

CyclesToPercent estimates remaining capacity after a number of full charge cycles, using a per-cycle fade rate. Lithium-ion cells commonly retain about 80% after 300-500 cycles.

func FlightStatus

func FlightStatus(wh float64) string

FlightStatus reports how a pack of the given watt-hour rating is treated in cabin baggage: "allowed", "airline approval required", or "prohibited".

func PhoneCharges

func PhoneCharges(ratedMAh, cellVolts, efficiency, phoneMAh float64) float64

PhoneCharges estimates how many full charges a pack delivers to a device of the given battery size, using real usable capacity rather than the rating.

func UsableMAh

func UsableMAh(ratedMAh, cellVolts, efficiency float64) float64

UsableMAh estimates the charge a pack actually delivers at USB output voltage, after boost conversion and control-circuit losses.

A 20000 mAh pack at 3.7 V nominal yields roughly 12500 mAh at 5 V, which is why "20000 mAh" never means five 4000 mAh phone charges.

func WattHours

func WattHours(ratedMAh, cellVolts float64) float64

WattHours converts a rated capacity in mAh at a given cell voltage into watt-hours — the unit airline regulations are written in.