USB-Meter
/
Documentation
/
No Ampere-Hours in UI or Model.md
Newer
■
■
■
■
■
■
■
■
■
■
Older
53 lines
|
3.409kb
| 1 |
# No Ampere-Hours (Ah) in UI or Model |
|
| 2 | ||
| 3 |
## Decision |
|
| 4 | ||
| 5 |
The application does not display, expose, or compute user-visible measurements in ampere-hours (Ah or mAh). This is a deliberate policy, not an omission. |
|
| 6 | ||
| 7 |
## Rationale |
|
| 8 | ||
| 9 |
### The physics |
|
| 10 | ||
| 11 |
Ampere-hours measure **electric charge** — the integral of current over time (∫ I·dt). They express how many coulombs of charge flowed through a circuit, independent of voltage. |
|
| 12 | ||
| 13 |
Watt-hours measure **energy** — the integral of power over time (∫ V·I·dt). Energy is what actually matters for a battery: it tells you how much work the battery can do, accounting for the voltage at which charge is delivered. |
|
| 14 | ||
| 15 |
For a battery with a flat discharge curve these two metrics are proportional, but real batteries have voltage that drops as they discharge. A 3.5 V lithium cell and a 5.0 V USB output delivering the "same" mAh are not delivering the same energy. The difference can be 30% or more. |
|
| 16 | ||
| 17 |
### The marketing abuse |
|
| 18 | ||
| 19 |
Consumer electronics marketing adopted mAh as a proxy for battery capacity because the number is conveniently large: |
|
| 20 |
- "10,000 mAh power bank" sounds more impressive than "37 Wh power bank" |
|
| 21 |
- But 10,000 mAh at 3.7 V (lithium cell voltage) ≈ 37 Wh, while 10,000 mAh at 5 V (USB output voltage) ≈ 50 Wh |
|
| 22 |
- Manufacturers measure at cell voltage; the useful output is at USB voltage — the same number means different things depending on context |
|
| 23 | ||
| 24 |
This ambiguity has been widely documented and is a known source of consumer confusion. Rating bodies and careful reviewers use Wh. |
|
| 25 | ||
| 26 |
### For this app specifically |
|
| 27 | ||
| 28 |
USB Meter measures charge delivered over USB, where voltage is never constant. Reporting in Ah would require specifying *which voltage* to use, and any fixed reference (3.7 V, 5 V, nominal) would be arbitrary and misleading. Wh is unambiguous: it is always the integral of V·I·dt as measured at the USB port. |
|
| 29 | ||
| 30 |
## What this means in practice |
|
| 31 | ||
| 32 |
### UI |
|
| 33 |
- No measurement expressed in Ah or mAh should appear in any view |
|
| 34 |
- Battery capacity is expressed exclusively in Wh (`capacityEstimateWh`) |
|
| 35 |
- Session energy is expressed exclusively in Wh (`measuredEnergyWh`, `effectiveBatteryEnergyWh`) |
|
| 36 | ||
| 37 |
### Model layer (Swift) |
|
| 38 |
- `ChargeSessionSummary`, `ChargeCheckpointSummary`, and `ChargeSessionSampleSummary` do not expose Ah fields |
|
| 39 |
- `TypicalChargeCurvePoint` carries only `averageEnergyWh` |
|
| 40 |
- `ChargedDeviceSummary` capacity estimates are always in Wh |
|
| 41 | ||
| 42 |
### Internal / hardware layer |
|
| 43 |
- The USB meters (UM25C, UM34C, TC66C) report both a Wh counter (`recordedWH`) and an Ah counter (`recordedAH`) over Bluetooth |
|
| 44 |
- `Meter.recordedAH` and `Meter.chargeRecordAH` exist as raw hardware counters and are used only internally — they are never surfaced in summaries or shown to users |
|
| 45 |
- The CoreData schema retains `measuredChargeAh`, `meterChargeBaselineAh`, and `meterLastChargeAh` as legacy attributes (data already stored in existing records is preserved), but these attributes are no longer read into Swift model summaries |
|
| 46 | ||
| 47 |
## Enforcement |
|
| 48 | ||
| 49 |
When adding new features involving energy or capacity: |
|
| 50 |
- Always use Wh as the unit |
|
| 51 |
- Do not introduce new Ah-denominated properties in any public summary struct |
|
| 52 |
- Do not display Ah or mAh strings in any view, label, or tooltip |
|
| 53 |
- If a hardware counter comes in Ah (e.g., from a new meter protocol), store it as a private implementation detail and convert to energy only if an average voltage is reliably known |