Metadata-Version: 2.4
Name: cairovolt-charge-calc
Version: 1.0.0
Summary: A utility to calculate battery charging speeds, efficiency, and verify USB-PD charging profiles compatibility.
Author-email: CairoVolt Developer <dev@cairovolt.com>
License: MIT
Project-URL: Homepage, https://cairovolt.com/en/
Project-URL: Documentation, https://github.com/cairovolt/cairovolt-charge-calc
Project-URL: Store, https://cairovolt.com/en/anker/power-banks
Project-URL: Repository, https://github.com/cairovolt/cairovolt-charge-calc
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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](https://cairovolt.com/en/) to validate and calculate specifications for power accessories. For general theoretical background, you can read the [Battery Charger Wikipedia entry](https://en.wikipedia.org/wiki/Battery_charger).

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

```bash
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](https://cairovolt.com/en/anker/power-banks) or portable battery will charge, you can run the following script:

```python
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](https://cairovolt.com/en/soundcore/audio/anker-soundcore-r50i) wireless earbuds against a low-power USB port:

```python
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](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery) article or visit the [Anker Official website](https://www.anker.com) for real-world equipment examples.

For guidelines on publishing your own packages, refer to the [Python Packaging Guide](https://packaging.python.org/en/latest/).

## License

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