Skip to content

battery.hpp

IBattery — the V5 battery (pros::battery) behind the HAL.

This header declares 1 type (9 members).

Extracted from include/shulib/hal/battery.hpp — this page is that header's documentation, reformatted, so it cannot disagree with the code. Prose about how to think about the API lives in the user guide; worked recipes live in the cookbook; this page is the complete, mechanical list of what exists.

Contents

class IBattery

class IBattery

The V5 battery behind the HAL. Its ONLY effect on control is a CEILING, never a scale factor: shulib commands actual volts, so control::compensateForBattery() clamps a desired voltage to ±the measured battery and reports whether it saturated, while the kS/kV/kA gains stay battery-independent by construction. Nothing anywhere multiplies a command by a fraction of pack voltage — the percent-output mental model is the one this design rejects.

class, declared at include/shulib/hal/battery.hpp:28.

IBattery::~IBattery

virtual ~IBattery() = default

Abstract base, held and destroyed through IBattery*. RobotContext keeps a NON-OWNING pointer (validated non-null at construction) that the caller must keep alive for the context's whole life. Copy/move are defaulted because the interface itself carries no state, but copying THROUGH this base slices an implementation down to nothing — pass implementations by reference or pointer, never by value.

function, declared at include/shulib/hal/battery.hpp:35.

IBattery::IBattery

IBattery() = default

Covered by the comment on ~IBattery — one comment documents this run of special members.

function, declared at include/shulib/hal/battery.hpp:36.

IBattery::IBattery (overload 2)

IBattery(const IBattery&) = default

Covered by the comment on ~IBattery — one comment documents this run of special members.

function, declared at include/shulib/hal/battery.hpp:37.

IBattery::IBattery (overload 3)

IBattery(IBattery&&) = default

Covered by the comment on ~IBattery — one comment documents this run of special members.

function, declared at include/shulib/hal/battery.hpp:38.

IBattery::operator=

IBattery& operator=(const IBattery&) = default

Covered by the comment on ~IBattery — one comment documents this run of special members.

function, declared at include/shulib/hal/battery.hpp:39.

IBattery::operator= (overload 2)

IBattery& operator=(IBattery&&) = default

Covered by the comment on ~IBattery — one comment documents this run of special members.

function, declared at include/shulib/hal/battery.hpp:40.

IBattery::voltage

[[nodiscard]] virtual units::Voltage voltage() const = 0

Present battery voltage (canonical volts).

function, declared at include/shulib/hal/battery.hpp:43.

IBattery::current

[[nodiscard]] virtual units::Current current() const = 0

Present current draw (canonical amperes) — the I half of the DebugRecord battery V/I (§18.2); voltage × current is dimensionally Power.

function, declared at include/shulib/hal/battery.hpp:47.

IBattery::capacity

[[nodiscard]] virtual double capacity() const = 0

Remaining capacity in [0, 1].

function, declared at include/shulib/hal/battery.hpp:50.

Design commentary, from the header

The header opens with the reasoning behind these shapes. It is reproduced here in full because a reference that only lists signatures teaches nobody why.

The header’s own reasoning — 16 lines 
 IBattery — the V5 battery (pros::battery) behind the HAL. voltage() in canonical
 volts; capacity() in [0, 1]. Feeds voltage / brownout compensation (master plan
 §M2).

 WHAT THAT COMPENSATION IS, EXACTLY — this comment said the wrong thing until DOCS1
 (2026-08-14), and it was the ancestor of the same wrong claim in guide ch. 6. It read
 "the control layer SCALES motor commands by the measured battery voltage so a routine
 behaves the same on a full or a sagging battery." Nothing scales. shulib commands
 ACTUAL VOLTS (IMotor::setVoltage), so the only battery effect is a CEILING:
 control::compensateForBattery() clamps a desired voltage to +/-battery and flags the
 saturation, and the kS/kV/kA gains are battery-independent by construction
 (control/feedforward.hpp:13-17, which has been right all along — the two headers
 disagreed). The percent-output mental model this comment implied is precisely the one
 the design rejects. What survives unchanged: the guaranteed end-of-run park still
 fires as the battery collapses.

Last updated 2026-08-15 — published from the main release branch, commit fa545ff. This site tracks releases, so between them it can lag the repository — that lag is deliberate, and it is what keeps the development log off the public site. For the current state of the code, see the repository.