balance_bot

A two-wheeled self-balancing robot (inverted pendulum) simulated in ROS 2 Jazzy + Gazebo Harmonic, with wheel torque exposed through ros2_control.

The robot balances, drives, and turns on the spot. Control is a cascaded PID in scripts/balance_controller.py, driven by /cmd_vel.

Requirements

OS	Ubuntu 24.04 (Noble)
ROS 2	Jazzy
Gazebo	Harmonic (gz-sim 8.x)

Key packages: ros-jazzy-ros-gz, ros-jazzy-ros2-control, ros-jazzy-ros2-controllers, ros-jazzy-gz-ros2-control.

Build

cd ~/ros2_ws
colcon build --packages-select balance_bot
source install/setup.bash

Run

ros2 launch balance_bot sim.launch.py

Brings up Gazebo, the bridge, the ros2_control controllers and the balance node. The robot comes up balancing.

# alternate world
ros2 launch balance_bot sim.launch.py world:=$(ros2 pkg prefix balance_bot)/share/balance_bot/worlds/obstacle_world.sdf

Driving it

# forward at 0.15 m/s
ros2 topic pub -r 10 /cmd_vel geometry_msgs/msg/Twist \
  '{linear: {x: 0.15}, angular: {z: 0.0}}'

# rotate on the spot at 1 rad/s
ros2 topic pub -r 10 /cmd_vel geometry_msgs/msg/Twist \
  '{linear: {x: 0.0}, angular: {z: 1.0}}'

Layout

src/balance_bot/
├── description/          xacro source (edit here)
│   ├── balance_bot.urdf.xacro   top level, includes the rest
│   ├── robot_core.xacro         chassis, wheels, tunable geometry
│   ├── inertial_macros.xacro    box/cylinder/sphere inertia tensors
│   ├── imu.xacro                IMU link + gz sensor
│   ├── camera.xacro             front camera + optical frame
│   ├── lidar.xacro              360 deg lidar on top
│   └── ros2_control.xacro       effort interfaces + gz_ros2_control plugin
├── scripts/
│   └── balance_controller.py    cascaded PID node, all gains as parameters
├── urdf/balance_bot.urdf        generated, for viewing
├── config/
│   ├── controllers.yaml         controller_manager + balance_wheel_controller
│   └── parameters.yaml          ros_gz_bridge topic map
├── launch/sim.launch.py         sim + bridge + controllers + balance node
└── worlds/                      test_world.sdf, obstacle_world.sdf

urdf/balance_bot.urdf is generated. After editing anything under description/:

xacro description/balance_bot.urdf.xacro \
      controllers_file:=config/controllers.yaml \
      -o urdf/balance_bot.urdf