No Ampere-Hours (Ah) in UI or Model

Decision

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.

Rationale

The physics

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.

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.

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.

The marketing abuse

Consumer electronics marketing adopted mAh as a proxy for battery capacity because the number is conveniently large: - "10,000 mAh power bank" sounds more impressive than "37 Wh power bank" - 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 - Manufacturers measure at cell voltage; the useful output is at USB voltage — the same number means different things depending on context

This ambiguity has been widely documented and is a known source of consumer confusion. Rating bodies and careful reviewers use Wh.

For this app specifically

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.

What this means in practice

UI

• No measurement expressed in Ah or mAh should appear in any view
• Battery capacity is expressed exclusively in Wh (capacityEstimateWh)
• Session energy is expressed exclusively in Wh (measuredEnergyWh, effectiveBatteryEnergyWh)

Model layer (Swift)

• ChargeSessionSummary, ChargeCheckpointSummary, and ChargeSessionSampleSummary do not expose Ah fields
• TypicalChargeCurvePoint carries only averageEnergyWh
• ChargedDeviceSummary capacity estimates are always in Wh

Internal / hardware layer

• The USB meters (UM25C, UM34C, TC66C) report both a Wh counter (recordedWH) and an Ah counter (recordedAH) over Bluetooth
• 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
• 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

Enforcement

When adding new features involving energy or capacity: - Always use Wh as the unit - Do not introduce new Ah-denominated properties in any public summary struct - Do not display Ah or mAh strings in any view, label, or tooltip - 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