ReloBot ROS 2 Development

Development instructions for ReloBot, a ROS 2 Humble robotics platform running on Raspberry Pi 5 with differential drive, mower blades, IMU, ToF camera, and Lidar sensors.

Project Context

ReloBot uses a distributed architecture:

Architecture Guidelines

Container Architecture

FastDDS Communication Pattern

All ROS 2 nodes MUST have these environment variables set:

```yaml

ROS_DISCOVERY_SERVER=${HOST_IP}:11811

ROS_SUPER_CLIENT=True

```

The `ds` service in docker-compose runs the centralized Discovery Server that all nodes connect to.

Hardware Abstraction Layers

Critical Workflows

Starting and Stopping Services

**ALWAYS use the startup script instead of docker compose directly:**

```bash

Start all services

./start_robot.sh up

Start specific service

./start_robot.sh up ros2_lidar

Stop all services

./start_robot.sh down

```

The script handles:

**NEVER run:**

```bash

docker compose up # Missing HOST_IP and connectivity checks

```

Building ROS 2 Packages

Inside a container, use colcon:

```bash

Build all packages

colcon build --symlink-install

Build specific package

colcon build --packages-select diff_drive_hardware

After building, source the workspace

source install/setup.bash

```

The `--symlink-install` flag creates symlinks for Python packages and launch files, enabling changes without rebuilding.

Device Detection and Mapping

Before starting services after hardware changes:

```bash

python3 finddevice.py

```

This script identifies connected serial devices and their paths. Update `ros2_ws/docker-compose.yml` if device paths have changed (e.g., `/dev/ttyACM0` → `/dev/ttyACM1`).

Visualization with RViz2

**ALWAYS use the RViz2 startup script:**

```bash

./start_rviz2.sh

or if alias is configured:

rviz

```

This script sets the correct `ROS_DISCOVERY_SERVER` environment variable to connect to the robot's FastDDS network.

**NEVER run:**

```bash

rviz2 # Won't see any topics without discovery server config

```

Code Organization Conventions

Programming Languages

File Structure

Launch Files

Prefer Python launch files over XML for better readability and dynamic configuration:

```python

from launch import LaunchDescription

from launch_ros.actions import Node

def generate_launch_description():

return LaunchDescription([

Node(

package='my_package',

executable='my_node',

name='my_node',

parameters=[{'param': value}]

)

])

```

Common Issues and Solutions

Nodes Can't Communicate

**Symptom**: `ros2 topic list` shows no topics, or nodes can't see each other's messages.

**Cause**: Incorrect or missing `ROS_DISCOVERY_SERVER` configuration.

**Solution**:

1. Verify `HOST_IP` is set correctly in the environment

2. Check that all containers have `ROS_DISCOVERY_SERVER=${HOST_IP}:11811`

3. Ensure the `ds` Discovery Server container is running

4. Confirm `network_mode: host` is set for all containers

Serial Device Not Found

**Symptom**: Container fails to start with "device not found" error.

**Cause**: Microcontroller unplugged, USB hub issue, or device path changed.

**Solution**:

1. Run `python3 finddevice.py` to locate current device paths

2. Check physical connections

3. Update device paths in `docker-compose.yml` if needed

4. Consider adding udev rules for persistent device names

Build Failures

**Symptom**: `colcon build` fails with dependency errors.

**Cause**: Missing dependencies or incorrect build order.

**Solution**:

1. Ensure all dependencies are declared in `package.xml`

2. Run `rosdep install --from-paths src --ignore-src -r -y` inside the container

3. Check for circular dependencies between packages

4. Build packages in dependency order if needed: `colcon build --packages-up-to my_package`

Key Configuration Files

docker-compose.yml

Defines all services, environment variables, device mappings, and network configuration. Each service entry must include:

package.xml

Standard ROS 2 package manifest. Declare all dependencies here for proper build ordering and `rosdep` resolution.

CMakeLists.txt (C++ packages)

Use modern CMake patterns with `ament_cmake`. Export libraries, dependencies, and include directories properly for downstream packages.

setup.py (Python packages)

Use `setuptools` with proper entry points for executables. List all dependencies in `install_requires`.

Security Considerations

Testing and Validation

Before committing changes:

1. Build all affected packages: `colcon build --packages-select <pkg>`

2. Run unit tests: `colcon test --packages-select <pkg>`

3. Test in simulation if available

4. Verify hardware integration with physical robot

5. Check that Discovery Server connectivity works after changes