Battery¶
Each BatteryAPI_1 prim is a pack of cells in series and in parallel. The electrical domain
runs it with the motors, every 50–100 µs, and gives its terminal voltage to the bus and its
state of charge to the signals (battery/<b>/terminal_voltage, soc, current, power).
The equivalent circuit¶
flowchart LR
OCV["OCV(SoC)<br/>a curve from the file"] --- R0["R0(T)"] --- RC1["R1 ∥ C1<br/>seconds"] --- RC2["R2 ∥ C2<br/>minutes"] --- V["terminal<br/>voltage"]
Per cell, with \(I\) the current (positive discharging):
Open-circuit voltage: interpolated from the pack’s
elec:battery:ocvSocandocvVoltagetable.Series resistance: \(R_0\) gives the instant drop when the current changes. It rises linearly with temperature, \(R_0(T) = R_0\,(1 + \alpha\,(T - T_{ref}))\).
RC pairs: the two pairs give the slower sag and recovery, one over seconds and one over minutes. Each is solved exactly over the step.
State of charge: counted from the charge drawn, \(\mathrm{SoC} \mathrel{-}= I\,\Delta t / Q\).
The pack: cells in series add voltage; cells in parallel share the current.
Empty: the pack is empty when its open-circuit voltage reaches
cutoffVoltage. The bus browns out when its voltage falls underundervoltageTrip.
Checked against a real cell¶
The LG 18650HG2 data set (Kollmeyer, Naguib and Skells, 2020, CC BY 4.0) has pulse tests and car drive cycles measured on one cell. The circuit’s resistances and capacitances were fitted to one cycle (UDDS) and then compared with cycles it had never seen:
Data |
RMS voltage error |
Target |
Result |
|---|---|---|---|
Pulses, 46–89 % SoC |
5.4–6.2 mV |
20 mV |
met |
Pulses, 24 % SoC |
21.5 mV |
20 mV |
not met: \(R_0\) and the OCV slope rise at low charge |
LA92 drive cycle, 25 °C (unseen) |
11.7 mV |
20 mV |
met |
US06 drive cycle, 25 °C (unseen, aggressive) |
20.1 mV |
20 mV |
not met by 0.1 mV |
US06 at 0 °C |
145 mV |
— |
far off: only \(R_0\) follows temperature, and nothing follows the charge yet |
All in BatteryDataset.* (test_battery_dataset); tools/ci/realism.sh runs them.
What this means for a drone: at room temperature and above about 30 % charge, the voltage under a changing load is within about 20 mV per cell (80 mV for a 4S pack). In the cold or near empty, it reads too high, so a simulated drone flies longer than a real one would. Resistances that change with charge and temperature need a schema addition, which is owed.
The Holybro sample’s pack values (4S 5000 mAh, \(R_0\) 4 mΩ per cell) are illustrative, not measured on a real pack. The model and its signals are in electrical.md §2.