ZsiBot RoamerX Lite

Open-source navigation stack for ZsiBot robots. Enables intelligent SLAM, path planning and autonomous movement. Free community version (Lite). Contributions welcome!

🚀 Features

Complete Navigation Stack: Based on ROS2 Nav2 with custom enhancements
Multi-Platform Support: Gazebo/UE simulation, NX/3588 hardware platforms
Advanced Path Planning: NavFn planner with MPPI controller
Flexible Communication: Support for UDP and LCM protocols
Behavior Trees: Sophisticated autonomous navigation logic
Real-time Obstacle Avoidance: Advanced costmap-based collision detection
Transform Management: Comprehensive coordinate frame handling
Open Source: Community-driven development with full source access

🔧 System Requirements

Operating System

Ubuntu 22.04 LTS (Jammy)
ROS2 Humble Hawksbill

Hardware Requirements

CPU: x86_64 or ARM64 (for hardware deployment)
RAM: Minimum 4GB (8GB recommended)
Storage: At least 10GB free space

Dependencies

Gazebo (for simulation)
OpenCV
PCL (Point Cloud Library)
OMPL (Open Motion Planning Library)
Behavior Tree CPP

📦 Installation

1. Install ROS2 Humble

# Add ROS2 apt repository
sudo apt update && sudo apt install curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# Install ROS2 Humble
sudo apt update
sudo apt install ros-humble-desktop

2. Clone and Setup the Repository

# Clone the repository
git clone https://github.com/zsibot/zsibot_roamer-x_lite.git
cd zsibot_roamerx_lite

# Install all dependencies
chmod +x script/dep/install_all.sh
./script/dep/install_all.sh

3. Build the Project

# Source ROS2 environment
source /opt/ros/humble/setup.bash

# Build all packages
./build.sh all

4. Source the Workspace

# Source the built workspace
source install/setup.bash

🚀 Quick Start

🔹 Simulation with ZsiBot-MATRiX

Welcome to explore our another open-source simulation project, MATRiX: 👉 https://github.com/zsibot/matrix

Launch the Navigation Stack:

bash script/bash/start_navigation.sh

Launch UE and MuJoCo Simulation

cd matrix/        # Make sure you have already cloned the MATRiX project!
bash run_sim.sh 1 3

Send Navigation Goals via RViz2
- In RViz2, use the “nav2_rviz_plugins” panel to send navigation commands.
- The robot will execute navigation tasks such as waypoint patrols with static and dynamic obstacle avoidance.
- Demo results (Note: Check the clear GIFs in the demo_gif folder.):
  - patrol task with multiple midpoints
Stop the Navigation Stack

bash script/bash/stop_navigation.sh

Simulation with Gazebo

🔹 Single Point Navigation

Launch the Navigation Stack:

ros2 launch robot_navigo navigation_bringup.launch.py \
    platform:=GAZEBO \
    mc_controller_type:=RL_TRACK_VELOCITY \
    communication_type:=LCM \
    map:=/path/to/map/map.yaml

ros2 launch pub_tf pub_tf.launch.py tf_type:=gazebo_tf

Launch Gazebo to Give Odom Info Make sure the Gazebo simulation is running to publish odometry (/odom/gazebo) and other necessary topics for navigation.
Send Navigation Goals via RViz2
- Open RViz2 and use the “2D Goal Pose” tool to send navigation targets.
- The robot will autonomously navigate to the goal position, avoiding both static and dynamic obstacles.
- Demo results:
  - 🟢 Static Avoidance
  - 🔵 Dynamic Avoidance

Patrol Task Navigation

Launch Navigation Stack:

ros2 launch robot_navigo navigation_bringup.launch.py \
    platform:=GAZEBO \
    mc_controller_type:=RL_TRACK_VELOCITY \
    communication_type:=LCM \
    map:=/path/to/map/map.yaml

ros2 launch pub_tf pub_tf.launch.py tf_type:=gazebo_tf

rviz2 -d /path/to/your/rviz2_config.rviz

Launch Gazebo to Give Odom Info
Launch RViz to Send Navigation Goals:
- Use "nav2_rviz_plugins" Panel in RViz2 to send navigation commands
- Demo results:
  - patrol task with multiple midpoints

Hardware Deployment

For physical robot deployment:

TODO

🏗️ Architecture Overview

The ZsiBot RoamerX Lite stack is organized into three main modules:

📡 Interface Module (`src/interface/`)

mc_sdk_rosmsgs: Motion controller SDK message definitions
robots_dog_msgs: Comprehensive robot message types including:
- Navigation commands and states
- Sensor data (IMU, odometry, localization)
- Motor control and telemetry
- Fault reporting and monitoring

🧭 Navigation Module (`src/navigation/src/`)

Core Navigation Components

navigo_bt_navigator: Behavior tree-based navigation orchestration
navigo_mppi_controller: Model Predictive Path Integral controller for dynamic path following
navigo_costmap_2d: 2D costmap generation with obstacle detection
navigo_path_planner: Global path planning services
navigo_navfn_planner: NavFn-based path planning algorithm

Supporting Services

navigo_behaviors: Navigation behavior implementations (spin, backup, wait)
navigo_collision_monitor: Real-time collision detection and avoidance
navigo_map_server: Map loading and serving capabilities
navigo_waypoint_follower: Multi-waypoint navigation execution
navigo_velocity_optimizer: Velocity command smoothing and optimization

Integration Layer

robot_navigo: Robot-specific integration, launch files, and parameter configurations

SLAM Module (`src/slam/src/`)

Core Mapping Components

3D pcd map: It can generate a 3D pcd point cloud global map
2D grid map: It can generate 2D global occupation raster maps

Supporting Services

**mapping state **: Control the different states of the mapping( start mapping、save map)

Localization Module (`src/localization/`)

Core Localization Components

fast_gicp: Fast Global Registration algorithm for point cloud registration
ndt_omp: Normal Distributions Transform algorithm for point cloud registration
localization: Localization algorithm for robot pose estimation

Supporting Services

load pcd map: Load 3D pcd map for localization

💡 Usage Examples

Basic Navigation Commands

# 1. Start the navigation stack
ros2 launch robot_navigo navigation_bringup.launch.py \
    platform:=GAZEBO \
    mc_controller_type:=RL_TRACK_VELOCITY \
    communication_type:=LCM

# 2. Load a map (in another terminal) 
ros2 service call /map_server/load_map nav2_msgs/srv/LoadMap \
    "{map_url: '/path/to/map.yaml'}"

# 3. Pub tf
 ros2 launch pub_tf pub_tf.launch.py tf_type:=gazebo_tf

# 4. Rviz
 rviz2 -d /path/to/your/rviz2_config.rviz

# 5. Send navigation goal
ros2 action send_goal /navigate_to_pose nav2_msgs/action/NavigateToPose \
    "{pose: {header: {frame_id: 'map'}, pose: {position: {x: 2.0, y: 1.0, z: 0.0}, 
    orientation: {w: 1.0}}}}"

Waypoint Navigation

# Navigate through multiple waypoints
ros2 action send_goal /navigate_through_poses nav2_msgs/action/NavigateThroughPoses \
    "{poses: [
        {header: {frame_id: 'map'}, pose: {position: {x: 1.0, y: 0.0, z: 0.0}, orientation: {w: 1.0}}},
        {header: {frame_id: 'map'}, pose: {position: {x: 2.0, y: 1.0, z: 0.0}, orientation: {w: 1.0}}},
        {header: {frame_id: 'map'}, pose: {position: {x: 1.0, y: 2.0, z: 0.0}, orientation: {w: 1.0}}}
    ]}"

Map Building with SLAM

# Run Robot SLAM 
ros2 launch robot_slam slam.launch.py

# Start Mapping
ros2 service call /slam_state_service robots_dog_msgs/srv/MapState "{data: 3}"

# Save Map 
ros2 service call /slam_state_service robots_dog_msgs/srv/MapState "{data: 5}"

#Note: map data is saved by default in the main directory under./jszr/map
#      For specific operations, please refer to the readme of slam

Run Localization

# Run Robot Localization 
ros2 launch localization localization.launch.py

# Load PCD Map
ros2 service call /load_map_service robots_dog_msgs/srv/LoadMap "{pcd_path: /your_pcd_map_path/map.pcd}"
#Note: Please use the right pcd path and pcd file name.
#eg: ros2 service call /load_map_service robots_dog_msgs/srv/LoadMap "{pcd_path: /home/user_name/datd/map/map.pcd}"

⚙️ Configuration

Platform Configuration

The system supports multiple platform configurations:

Platform	Description	Use Case
`GAZEBO`	Gazebo simulation	Development and testing
`NX_XG3588`	XG3588 hardware platform	High-performance deployment
`XG3588`	Standalone XG3588	Custom hardware integration

Controller Types

Controller Type	Description	Application
`RL_TRACK_VELOCITY`	Velocity-based tracking	Simple navigation tasks
`RL_TRACK_PATH`	Path-following controller	Precise trajectory following

Communication Protocols

Protocol	Description	Use Case
`UDP`	Direct UDP communication	Low-latency, embedded systems
`LCM`	Lightweight Communications	Multi-process, distributed systems

Parameter Files

Main configuration file: src/navigation/src/robot_navigo/params/navigo_params.yaml

Key configuration sections:

bt_navigator: Behavior tree settings
controller_server: MPPI controller parameters
local_costmap: Local obstacle avoidance settings
global_costmap: Global path planning costmap
planner_server: Path planning algorithm settings

🔨 Development

Building Individual Packages

# Build specific package
colcon build --packages-select <package_name>

# Build with debug symbols
./build.sh all debug

Code Formatting

# Format all C++ code
./format.sh

# Format specific directory
./format.sh /path/to/directory

Running Tests

# Run all tests
colcon test

# Run tests for specific package
colcon test --packages-select <package_name>

🐛 Troubleshooting

Common Issues

1. Build Errors

# Clean and rebuild
rm -rf build install log
./build.sh all

2. Transform Errors

# Check transform tree
ros2 run tf2_tools view_frames

# Monitor transform publication
ros2 topic echo /tf

3. Navigation Not Starting

# Check required parameters
ros2 param list /bt_navigator
ros2 param get /bt_navigator use_sim_time

4. Map Loading Issues

# Verify map file path and format
ros2 topic echo /map --once

🤝 Contributing

We welcome contributions from the community! Here's how to get involved:

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes following our coding standards
Run tests: colcon test
Format code: ./format.sh
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Submit a Pull Request

Coding Standards

Follow ROS2 C++ Style Guide
Use clang-format for consistent formatting
Write comprehensive comments and documentation
Include unit tests for new features

Reporting Issues

Please use GitHub Issues to report bugs or request features.

Include:

Operating system and ROS2 version
Hardware platform
Steps to reproduce the issue
Expected vs actual behavior
Relevant log output

📄 License

This project is released under the Open Source License. See LICENSE file for details.

🙏 Acknowledgments

ROS2 Community for the excellent navigation framework
Nav2 Team for the robust navigation stack
Contributors who help improve this project
ZsiBot Community for feedback and testing

Made with ❤️ by the ZsiBot Community

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

ZsiBot RoamerX Lite

🚀 Features

📋 Table of Contents

🔧 System Requirements

Operating System

Hardware Requirements

Dependencies

📦 Installation

1. Install ROS2 Humble

2. Clone and Setup the Repository

3. Build the Project

4. Source the Workspace

🚀 Quick Start

🔹 Simulation with ZsiBot-MATRiX

Simulation with Gazebo

🔹 Single Point Navigation

Patrol Task Navigation

Hardware Deployment

🏗️ Architecture Overview

📡 Interface Module (src/interface/)

🧭 Navigation Module (src/navigation/src/)

Core Navigation Components

Supporting Services

Integration Layer

SLAM Module (src/slam/src/)

Core Mapping Components

Supporting Services

Localization Module (src/localization/)

Core Localization Components

Supporting Services

💡 Usage Examples

Basic Navigation Commands

Waypoint Navigation

Map Building with SLAM

Run Localization

⚙️ Configuration

Platform Configuration

Controller Types

Communication Protocols

Parameter Files

🔨 Development

Building Individual Packages

Code Formatting

Running Tests

🐛 Troubleshooting

Common Issues

🤝 Contributing

Development Workflow

Coding Standards

Reporting Issues

📄 License

🙏 Acknowledgments

📡 Interface Module (`src/interface/`)

🧭 Navigation Module (`src/navigation/src/`)

SLAM Module (`src/slam/src/`)

Localization Module (`src/localization/`)