Dev Notes

Architecture decisions

Why a Dev Container?

ROS 2 + Gazebo + their dependencies are notoriously painful to install natively, especially across different OS versions. The container guarantees everyone has the same Ubuntu 22.04 + ROS Humble + Gazebo Fortress environment. No “works on my machine” issues.

Why Gazebo Fortress (not Harmonic)?

The main TrickFire robot codebase uses ROS 2 Humble, so the simulation environment matches. ROS 2 Humble officially supports Gazebo Fortress — newer Gazebo versions (like Harmonic) require ROS 2 Iron or newer. Since Humble is the current LTS and we need to stay compatible with the main robot, we use Fortress.

Why two packages per robot?

The _description / _bringup split is a ROS convention:

• _description contains the robot model (URDF + meshes) — things that change when the CAD changes
• _bringup contains runtime config (launch files, controller YAML, RViz config) — things you tweak during development

This separation means genbot update can safely replace the description without touching your launch customizations.

Useful CLI commands

Gazebo camera position

To set the camera position in the Gazebo viewer:

Inside devcontainer

gz service -s /gui/move_to/pose \
    --reqtype gz.msgs.GUICamera \
    --reptype gz.msgs.Boolean \
    --timeout 2000 \
    --req "pose: {position: {x: 0.0, y: -2.0, z: 2.0} orientation: {x: -0.2706, y: 0.2706, z: 0.6533, w: 0.6533}}"

To read the current camera position:

Inside devcontainer

gz topic -e -t /gui/camera/pose

ROS 2 inspection

Inside devcontainer

# List all topics
ros2 topic list

# See joint states in real time
ros2 topic echo /joint_states

# List active controllers
ros2 control list_controllers

# Check controller manager status
ros2 control list_hardware_interfaces

Building a single package

Inside devcontainer

cd robot-sim
colcon build --packages-select arm_description
source install/setup.bash

Community apt repository

Some ROS packages live in the universe repository rather than main. If apt can’t find a package:

Inside devcontainer

apt-get update
apt-get install -y software-properties-common
add-apt-repository -y universe
apt-get update

Note

The Dockerfile already enables universe for the packages that need it.

Common pitfalls

Forgetting to source after build: ROS 2 can’t find packages until you run source install/setup.bash. The launch script does this automatically, but if you’re running ROS commands manually, you need to source first.

Stale build artifacts: If something breaks for no obvious reason, run ./scripts/clean_build.sh and rebuild. Colcon’s incremental builds can get confused after certain types of changes.

X server not running: Gazebo and RViz will fail silently or crash if the X server isn’t started. Always run ./scripts/start_x_server.sh first.

Port conflicts: If port 6080 or 5900 is already in use, the X server script will fail. Make sure no other VNC sessions or containers are using those ports.