BatteryState

Battery health and charge state for any battery-powered robot. Reports voltage, current draw, temperature, individual cell voltages, and charge percentage.

When to Use

Use BatteryState when your robot runs on batteries and you need to monitor power levels, trigger low-battery warnings, or initiate safe shutdown. Essential for mobile robots, drones, and any untethered system.

ROS2 Equivalent

sensor_msgs/BatteryState — similar structure (voltage, current, charge, capacity, temperature, cell voltages).

Rust Example

use horus::prelude::*;

let battery = BatteryState {
    voltage: 12.6,
    current: -2.5,              // negative = discharging
    charge: f32::NAN,           // NaN if unknown
    capacity: f32::NAN,
    percentage: 85.0,           // 85% charge
    power_supply_status: 2,     // discharging
    temperature: 32.0,          // Celsius
    cell_voltages: [0.0; 16],
    cell_count: 0,
    timestamp_ns: 0,
};

let topic: Topic<BatteryState> = Topic::new("battery.state")?;
topic.send(battery);

Python Example

import horus

battery = horus.BatteryState(
    voltage=12.6,
    current=-2.5,
    percentage=85.0,
    temperature=32.0,
)

Fields

FieldTypeUnitDescription
voltagef32VTotal pack voltage
currentf32ACurrent draw (negative = discharging)
chargef32AhRemaining charge (NaN if unknown)
capacityf32AhFull capacity (NaN if unknown)
percentagef32%State of charge (0–100)
power_supply_statusu8—0=unknown, 1=charging, 2=discharging, 3=full
temperaturef32°CPack temperature
cell_voltages[f32; 16]VPer-cell voltages (if available)
cell_countu8—Number of valid cell readings
timestamp_nsu64nsTimestamp

Common Patterns

Low Battery Warning

fn tick(&mut self) {
    // IMPORTANT: always recv() every tick
    if let Some(battery) = self.battery_sub.recv() {
        if battery.percentage < 20.0 {
            hlog!(warn, "Low battery: {:.0}% ({:.1}V)", battery.percentage, battery.voltage);
        }
        if battery.percentage < 5.0 {
            // SAFETY: trigger safe shutdown
            hlog!(error, "Critical battery: {:.0}% — shutting down", battery.percentage);
            self.cmd_pub.send(CmdVel { linear: 0.0, angular: 0.0, timestamp_ns: 0 });
        }
    }
}