swarm_description

Robot description package for CHARS containing URDF/Xacro models, control configs, Nav2 params, and launch files for Jackal, UR5, and mobile manipulator agents.

What This Package Provides

• Robot models in swarm_description/urdf.
• Controller, bridge, EKF, and Nav2 configs in swarm_description/config.
• Bringup and navigation launch files in swarm_description/launch.
• A helper node for odometry frame offset handling in swarm_description/swarm_description/odom_transform_node.py.

Repository Structure

swarm_description/
    urdf/
        jackal.urdf.xacro
        ur5_assembly.xacro
        mobile_manipulator.urdf.xacro
        camera.urdf.xacro
        ...
    launch/
        mobile_manipulator.launch.py
        mobman_nav2.launch.py
        jackal_nav2.launch.py
        jackal_control.launch.py
        ur5_control.launch.py
        bringup.launch.py
        ...
    config/
        jackal_control.yaml
        ur5_control.yaml
        mobman_control.yaml
        jackal_nav2_params.yaml
        mobman_nav2_params.yaml
        agent1_nav2_params.yaml
        agent2_nav2_params.yaml
        agent3_nav2_params.yaml
        jackal_bridge.yaml
        ur5_bridge.yaml
        mobman_bridge.yaml
        ...
    map/
        empty_world_map.yaml
        empty_world_map.pgm

Dependencies

Key runtime dependencies from swarm_description/package.xml:

• robot_state_publisher
• joint_state_publisher
• joint_state_publisher_gui
• rviz2
• xacro
• ros2_control
• ros2_controllers
• controller_manager
• diff_drive_controller
• joint_state_broadcaster
• ros_gz_bridge
• robot_localization

Build

From your workspace root:

colcon build --packages-select swarm_description
source install/setup.bash

Typical Launch Workflows

1) Mobile manipulator robot model and controllers

ros2 launch swarm_description mobile_manipulator.launch.py \
    robot_namespace:=agent1 pose_x:=1.0 pose_y:=-3.0 pose_z:=0.22

2) Mobile manipulator Nav2 stack

ros2 launch swarm_description mobman_nav2.launch.py \
    robot_namespace:=agent1

This launch dynamically merges:

• robot-specific Nav2 params (<namespace>_nav2_params.yaml)
• proximity wait plugin settings from nav2_proximity_wait package

3) Jackal bringup

ros2 launch swarm_description jackal_control.launch.py robot_namespace:=jackal

4) UR5 control bringup

ros2 launch swarm_description ur5_control.launch.py robot_namespace:=ur5

Namespacing Model

URDF generation uses xacro argument robot_namespace and applies frame prefixing, enabling multiple robots to coexist with isolated TF trees and topic spaces.

Example:

• agent1/base_link
• agent2/base_link

CHARS Integration

This package is the foundation layer for CHARS execution:

• Defines robot kinematics and frames consumed by MoveIt/Nav2.
• Provides per-agent Nav2 configuration profiles.
• Supplies bridge and localization settings used by swarm bringup and allocator packages.

Notes for GitHub Publishing

1. The package includes swarm_description/log with a COLCON_IGNORE marker. Keep it ignored in GitHub unless you intentionally want build logs tracked.
2. Some launches in this workspace rely on local absolute model paths set by higher-level bringup packages; include setup instructions at repo root for GZ_SIM_RESOURCE_PATH and IGN_GAZEBO_RESOURCE_PATH.
3. Ensure repository-level documentation explains how this package pairs with swarm_bringup and moveit config packages.

License

Apache-2.0 (as declared in swarm_description/package.xml).

Controller Management

# List available controllers
ros2 control list_controllers --controller-manager /robot1/controller_manager

# Load controller manually
ros2 control load_controller diff_drive_controller \
    --controller-manager /robot1/controller_manager

# Activate controller
ros2 control set_controller_state diff_drive_controller active \
    --controller-manager /robot1/controller_manager

# Check controller status
ros2 control list_hardware_interfaces --controller-manager /robot1/controller_manager

Navigation Testing

# Check map
ros2 topic echo /robot1/map --once

# Monitor AMCL pose
ros2 topic echo /robot1/amcl_pose

# Visualize costmaps
ros2 run nav2_costmap_2d nav2_costmap_2d_markers \
    voxel_grid:=/robot1/global_costmap/voxel_grid \
    visualization_marker:=/robot1/global_costmap_marker

# Send simple goal
ros2 action send_goal /robot1/navigate_to_pose \
    nav2_msgs/action/NavigateToPose \
    "{pose: {header: {frame_id: 'map'}, pose: {position: {x: 2.0, y: 1.0}}}}"

Sensor Data Inspection

# LiDAR scan
ros2 topic echo /robot1/scan --once

# IMU data
ros2 topic echo /robot1/imu

# Camera feed (view in RViz or rqt_image_view)
ros2 run rqt_image_view rqt_image_view /robot1/camera/image

# Joint states (for UR5)
ros2 topic echo /ur5/joint_states

Troubleshooting

Models Not Loading in Gazebo

Issue: Missing mesh files or resource path errors.

Solution:

# Verify mesh files exist
ls $(ros2 pkg prefix swarm_description)/share/swarm_description/meshes/

# Check resource path
echo $GZ_SIM_RESOURCE_PATH
echo $IGN_GAZEBO_RESOURCE_PATH

# Rebuild with install
cd ~/swarm_ws
colcon build --packages-select swarm_description --symlink-install
source install/setup.bash

Controllers Not Starting

Issue: [ERROR] Controller 'diff_drive_controller' not loaded.

Solution:

# Check controller manager running
ros2 node list | grep controller_manager

# Verify controller params loaded
ros2 param list /robot1/controller_manager

# Check hardware interface
ros2 control list_hardware_interfaces --controller-manager /robot1/controller_manager

# Manually spawn controller
ros2 run controller_manager spawner diff_drive_controller \
    --controller-manager /robot1/controller_manager

TF Frame Errors

Issue: Frame [robot1/base_link] does not exist.

Solution:

# Check robot_state_publisher running
ros2 node list | grep robot_state_publisher

# Verify robot_description parameter
ros2 param get /robot1/robot_state_publisher robot_description

# Check TF tree
ros2 run tf2_ros tf2_echo map robot1/base_link

# List all frames
ros2 run tf2_tools view_frames

Navigation Failures

Issue: Robot not planning paths or getting stuck.

Solution:

1. Check localization:

   ros2 topic echo /robot1/amcl_pose

2. Verify map loaded:

   ros2 topic echo /robot1/map --once

3. Inspect costmaps in RViz:

   • Add "Map" display for /robot1/local_costmap/costmap
   • Check for inflation layer issues

4. Tune Nav2 parameters: Edit jackal_nav2_params.yaml:

   • Reduce inflation_radius if robot too conservative
   • Increase transform_tolerance if TF errors
   • Adjust goal_checker thresholds

Joint Limits Exceeded (UR5)

Issue: MoveIt planning fails with joint limit violations.

Solution:

# Check current joint states
ros2 topic echo /ur5/joint_states

# Verify limits in URDF
ros2 run xacro xacro $(ros2 pkg prefix swarm_description)/share/swarm_description/urdf/ur5_assembly.xacro | grep limit

# Reset to home position
ros2 service call /ur5/controller_manager/switch_controller \
    controller_manager_msgs/srv/SwitchController ...

Development Roadmap (CHARS Architecture)

• Add Velodyne 3D LiDAR sensor model
• Implement gripper attachment for UR5 arm
• Create custom sensor suite configurations
• Add battery simulation and power management
• Develop swarm-specific communication models
• Integrate semantic segmentation cameras
• Create modular accessory mounting system
• Add thermal and depth camera sensors

Best Practices

1. Namespacing: Always use unique robot_namespace for multi-robot scenarios
2. Frame Prefixes: Ensure frame_prefix parameter set in robot_state_publisher
3. Controller Scoping: Nest controller params under /**: for namespace-agnostic configs
4. Mesh Paths: Use file://$(find package) format for Gazebo compatibility
5. TF Isolation: Verify each robot has isolated TF tree with view_frames

License

Apache License 2.0

Maintainer

Viswa Teja Bottu
Email: vss.viswatejabottu@gmail.com

Contributing

This package is part of ongoing research in heterogeneous multi-robot systems. For questions or collaboration opportunities, please contact the maintainer.

See Also

• swarm_bringup - Multi-robot launch orchestration
• ur5_moveit_config - MoveIt2 configuration for UR5
• plansys2_turtlesim_example - VLM-powered planning
• ROS 2 URDF Tutorials
• ros2_control Documentation
• Nav2 Documentation