Battery
The battery module protects the battery on the DC side: it limits the generation demand to what the battery can actually accept. Two independent limiters act together, and the smaller of the two wins:
- the charging current limiter — keeps the battery charging current below a configured maximum,
- the battery voltage limiter — backs the generation off when the DC bus voltage rises above a configured level (typically a nearly full battery).
Both are smooth integrating limiters: when the measured value exceeds the limit, the generation demand is gradually reduced until it settles at the limit, and it recovers the same way. Each limiter signals its activity in the status word — CC (constant current) and CV (constant voltage), the classic charging regimes — and the limitation is reflected in the reported capability, so a host following the capability automatically backs the engine throttle off as well.
All parameters live in the /battery directory.
The driver-level limiters (/driver/limiter/ibneg, /driver/limiter/ubmax) remain active as independent low-level backstops in each controller and should still be configured as the hard safety limits.
Charging current limiter
The limiter works with the total battery current:
- With a BMS battery-current report on CAN, the reported current — which covers the whole battery — is limited to
ibneg. - Without the report (never received, or timed out after
tim), the sum of the currents measured by the controllers themselves is limited toibneg_nocomm. In a multi-master pair a missing or faulted peer contributes zero — a single healthy controller may then use the whole budget.
The battery current report is a customer-specific CAN message that is compiled in. The public firmware has no battery current input — only the ibneg_nocomm limitation of the summed controller currents is available.
ibneg [A]
Maximum battery charging current (as reported by the BMS). Generation is reduced to keep the charging current below this value. 0 disables.
ibneg_nocomm [A]
Maximum total charging current (sum of the controllers' own measurements), used when the BMS is not communicating. 0 disables.
ibgain
Integrator gain of the charging current limiter.
tim [ms]
Timeout of the BMS battery current message. After this time without a valid report, the limiter switches to the ibneg_nocomm fallback and the timeout is signalized in the status flags. 0 disables the timeout.
Battery voltage limiter
When the DC bus voltage exceeds ubmax, the generation demand is reduced centrally — in a pair, the reduction reaches both motors together. This throttles the generation back on a full battery before the hard overvoltage protection would have to act.
Beyond protection, the voltage limiter can serve as the primary regulation of the whole system: with a small DC battery or supercapacitor stabilizing the bus, the genset regulates the system voltage and dynamically follows the power draw — a standalone regulated DC source. See the typical use case under Loading.
This limiter is distinct from the MODE_OVERVOLTAGE protection: the protection kills the engine on motor-side overvoltage (overspeed), while this limiter gently unloads it on a high bus voltage. With a suitable ubmax the kill should never be reached in normal operation.
ubmax [V]
Battery voltage limit of the generation. 0 disables.
ubgain
Integrator gain of the voltage limiter.
States
| State | Unit | Description |
|---|---|---|
bms_current | A | Battery current from the BMS report, negative = charging |
bms_tmo | ms | Remaining BMS message timeout, 0 = timed out |
bms_limit | - | Charging current limiter output, 0–1, 1 = no limitation |
ub_limit | - | Voltage limiter output, 0–1, 1 = no limitation |