CairoVolt Charge Calc

A lightweight Python library to calculate battery charging dynamics, watt-hours (Wh), effective power bank output capacities at different discharge voltages, and to diagnose USB-PD (Power Delivery) profile compatibility.

This package was developed for CairoVolt to validate and calculate specifications for power accessories. For general theoretical background, you can read the Battery Charger Wikipedia entry.

Features

• Watt-Hour Calculation: Easily convert battery capacity (mAh) and voltage to Wh.
• Charge Time Estimation: Estimate charge times using a two-phase model (Constant Current up to 80%, Constant Voltage down to 100%).
• Effective Capacity Calculation: Calculate actual deliverable capacity (mAh) when a power bank discharges at 5V, 9V, or 12V instead of its nominal cell voltage (3.7V).
• USB-PD Profiling: Diagnose if your charger wattage matches your device requirements.

Installation

pip install cairovolt-charge-calc

Usage

1. Estimating Charging Time

This helper estimates the real-world charging duration based on your battery capacity and charger output. For example, if you want to calculate how fast an anker power bank or portable battery will charge, you can run the following script:

from cairovolt_charge_calc.core import ChargingCalculator

calc = ChargingCalculator()
specs = calc.calculate_charge_time(battery_mah=10000, charger_watts=20)
print(specs["total_charge_time_formatted"]) # Output: e.g., 5h 9m

2. Validating Device Specs

You can check if a specific charger is suitable for charging accessories. For instance, testing a premium audio device like the anker soundcore r50i wireless earbuds against a low-power USB port:

from cairovolt_charge_calc.core import ChargingCalculator

calc = ChargingCalculator()
diag = calc.verify_usb_pd_compatibility(device_required_watts=5, charger_output_watts=10)
print(diag["status"]) # Output: Optimal

To learn more about the USB charging specifications, check the USB Power Delivery on Wikipedia article or visit the Anker Official website for real-world equipment examples.

For guidelines on publishing your own packages, refer to the Python Packaging Guide.

License

This project is licensed under the MIT License - see the LICENSE file for details.