You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Kilted.

Battery State Broadcaster

The Battery State Broadcaster publishes battery status information as sensor_msgs/msg/BatteryState messages.

It reads battery-related state interfaces from one or more batteries and exposes them in a standard ROS 2 message format. This allows easy integration with monitoring tools, logging systems, and higher-level decision-making nodes.

Interfaces

The broadcaster can read the following state interfaces from each configured battery:

battery_voltage (mandatory) (double)
battery_temperature (optional) (double)
battery_current (optional) (double)
battery_charge (optional) (double)
battery_percentage (optional) (double)
battery_power_supply_status (optional) (double)
battery_power_supply_health (optional) (double)
battery_present (optional) (bool)

Published Topics

The broadcaster publishes two topics:

~/raw_battery_states (control_msgs/msg/BatteryStateArray) Publishes per-battery state messages, containing the raw values for each configured battery.
~/battery_state (sensor_msgs/msg/BatteryState) Publishes a single aggregated battery message representing the combined status across all batteries.

Field	`battery_state`	`raw_battery_states`
`header.frame_id`	Empty	Battery name
`voltage`	Mean across all batteries	From battery’s `battery_voltage` interface (mandatory) (NaN if unmeasured)
`temperature`	Mean across batteries reporting temperature	From battery’s `battery_temperature` interface if enabled, otherwise nan.
`current`	Mean across batteries reporting current	From battery’s `battery_current` interface if enabled, otherwise nan.
`charge`	Sum across batteries reporting charge	From battery’s `battery_charge` interface if enabled, otherwise nan.
`capacity`	Sum across all batteries	From battery’s `capacity` parameter if provided, otherwise nan.
`design_capacity`	Sum across all batteries	From battery’s `design_capacity` parameter if provided, otherwise nan.
`percentage`	Mean across batteries reporting/calculating percentage	From battery’s `battery_percentage` interface if enabled, otherwise calculated from battery’s `minimum_voltage` and `maximum_voltage` parameters.
`power_supply_status`	Highest reported enum value	From battery’s `battery_power_supply_status` interface if enabled, otherwise 0 (unknown).
`power_supply_health`	Highest reported enum value	From battery’s `battery_power_supply_health` interface if enabled, otherwise 0 (unknown).
`power_supply_technology`	Reported as-is if same across all batteries, otherwise set to Unknown	From battery’s `power_supply_technology` parameter if provided, otherwise 0 (unknown).
`present`	True	From battery’s `battery_present` interface if enabled, otherwise true if the battery voltage value is valid (not NaN and not 0.0).
`cell_voltage`	Empty	Empty
`cell_temperature`	Empty	Empty
`location`	All battery locations appended	From battery’s `location` parameter if provided, otherwise empty.
`serial_number`	All battery serial numbers appended	From battery’s `serial_number` parameter if provided, otherwise empty.

Parameters

This controller uses the generate_parameter_library to manage parameters. The parameter definition file contains the full list and descriptions.

List of parameters

batteries (string_array)

List of batteries from which battery state interfaces will be read.

Read only: True

Constraints:

contains no duplicates

sensor_name (string)

[DEPRECATED] Sensor name of the battery. If provided, the ‘voltage’ state interface of this sensor will be used to populate the voltage field in the BatteryState message. If this parameter is used, the batteries and interfaces parameters are ignored.

Read only: True

Default: “”

design_capacity (double)

[DEPRECATED] Design capacity of the battery [Ah] for the sensor_name mode (If unmeasured NaN).

Read only: True

Default: std::numeric_limits<double>::quiet_NaN()

power_supply_technology (int)

[DEPRECATED] Battery chemistry type as an enum for the sensor_name mode (see https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/BatteryState.msg). If unmeasured, the technology is set to unknown.

Read only: True

Default: 0

Constraints:

parameter must be within bounds [0, 8]

interfaces.<batteries>.battery_temperature (bool)

Whether to read battery temperature [°C] from this battery’s state interface (If unmeasured NaN).

Read only: True

Default: false

interfaces.<batteries>.battery_current (bool)

Whether to read battery current [A] from this battery’s state interface (If unmeasured NaN).

Read only: True

Default: false

interfaces.<batteries>.battery_charge (bool)

Whether to read battery charge [Ah] from this battery’s state interface (If unmeasured NaN).

Read only: True

Default: false

interfaces.<batteries>.battery_percentage (bool)

Whether to read charge level [%] (0.0 to 100.0) from this battery’s state interface. If unmeasured, linear percentage is calculated using the minimum_voltage and maximum_voltage parameters (if provided), otherwise NaN.

Read only: True

Default: false

interfaces.<batteries>.battery_power_supply_status (bool)

Whether to read power supply status (e.g., Charging, Full, see https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/BatteryState.msg) from this battery’s state interface. If unmeasured, status is set to unknown.

Read only: True

Default: false

interfaces.<batteries>.battery_power_supply_health (bool)

Whether to read power supply health (e.g., Good, Overheat, see https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/BatteryState.msg) from this battery’s state interface. If unmeasured, health is set to unknown.

Read only: True

Default: false

interfaces.<batteries>.battery_present (bool)

Whether to read battery presence status (true if battery is present) from this battery’s state interface. If unmeasured, the presence will be inferred from the battery voltage value (true if voltage is not NaN and not 0.0, otherwise false).

Read only: True

Default: false

<batteries>.minimum_voltage (double)

Minimum battery voltage (used to calculate percentage).

Read only: True

Default: std::numeric_limits<double>::quiet_NaN()

<batteries>.maximum_voltage (double)

Maximum battery voltage (used to calculate percentage).

Read only: True

Default: std::numeric_limits<double>::quiet_NaN()

<batteries>.capacity (double)

Last known full battery capacity [Ah] (If unmeasured NaN).

Read only: True

Default: std::numeric_limits<double>::quiet_NaN()

<batteries>.design_capacity (double)

Design capacity of the battery [Ah] (If unmeasured NaN).

Read only: True

Default: std::numeric_limits<double>::quiet_NaN()

<batteries>.power_supply_technology (int)

Battery chemistry type as an enum (see https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/BatteryState.msg). If unmeasured, the technology is set to unknown.

Read only: True

Default: 0

Constraints:

parameter must be within bounds [0, 8]

<batteries>.location (string)

Physical location of the battery (e.g., slot number or plug label).

Read only: True

Default: “”

<batteries>.serial_number (string)

Serial number of the battery.

Read only: True

Default: “”

Example Parameter File

An example parameter file for this controller is available in the test directory:

test_battery_state_broadcaster:
  ros__parameters:
    batteries:
      - "battery0"
      - "battery1"
    interfaces:
      battery0:
        battery_temperature: true
        battery_current: false
        battery_charge: true
        battery_percentage: false
        battery_power_supply_status: true
        battery_power_supply_health: true
        battery_present: false
      battery1:
        battery_temperature: true
        battery_current: true
        battery_charge: true
        battery_percentage: true
        battery_power_supply_status: true
        battery_power_supply_health: true
        battery_present: false
    battery0:
      minimum_voltage: 0.0
      maximum_voltage: 10.0
      capacity: 12000.0
      design_capacity: 13000.0
      power_supply_technology: 3
      location: "slot0"
      serial_number: "serial_device_0"
    battery1:
      minimum_voltage: 0.0
      maximum_voltage: 15.0
      capacity: 17000.0
      design_capacity: 18000.0
      power_supply_technology: 3
      location: "slot1"
      serial_number: "serial_device_1"

# [deprecated] do not use for new configurations
test_battery_state_broadcaster_legacy:
      ros__parameters:
        batteries: ["battery_state"]
        battery_state:
          design_capacity: 100.0
          power_supply_technology: 2

Migration for `ipa320/ros_battery_monitoring` users

If you were previously using the battery_state_broadcaster from the ipa320/ros_battery_monitoring package, you can switch directly to this package. The configuration style using sensor_name is still supported for backward compatibility, but it may be removed in a future release.

To adapt your setup to the new battery_state_broadcaster configuration:

Update your hardware interface name from voltage → battery_voltage.
Convert your controller parameters from

battery_state_broadcaster:
  ros__parameters:
    sensor_name: "battery_state"
    design_capacity: 100.0
    # https://github.com/ros2/common_interfaces/blob/rolling/sensor_msgs/msg/BatteryState.msg
    power_supply_technology: 2

to:

battery_state_broadcaster:
  ros__parameters:
    batteries: ["battery_state"]
    battery_state:
      design_capacity: 100.0
      power_supply_technology: 2

Notes:

Parameters must provide either sensor_name or batteries.
If both are empty → the broadcaster will fail to configure.
If both are set → the broadcaster will throw an error.

Battery State Broadcaster

Interfaces

Published Topics

Parameters

List of parameters

Example Parameter File

Migration for ipa320/ros_battery_monitoring users

Migration for `ipa320/ros_battery_monitoring` users