Skip to content

ChepuriNatraj/Squarobot-Robotry-

BranchesTags

Repository files navigation

Squarobot ROS 2 Navigation System

Autonomous mobile robot with SLAM mapping and Nav2 navigation
ROS 2 Jazzy | Gazebo Harmonic | Nav2 Navigation | SLAM Toolbox

ROS 2 Gazebo

🚀 Quick Start Guide

Prerequisites Check

# Verify ROS 2 Jazzy is installed
ros2 --version

# Verify Gazebo Harmonic is installed
gz sim --version

# Install required packages if missing
sudo apt install ros-jazzy-navigation2 ros-jazzy-nav2-bringup
sudo apt install ros-jazzy-slam-toolbox

🛠️ Build Workspace (First Time Only)

cd ~/Final
colcon build --packages-select squarobot_gazebo
source install/setup.bash

📍 Usage Options

Quick Start: Simulation with Visualization 🚀

Use this when: You want to see the robot immediately with RViz

Steps:

  1. Launch simulation with RViz:

    cd ~/Final
source install/setup.bash
ros2 launch squarobot_gazebo simulation_with_rviz.launch.py

  2. Control the robot (in another terminal):

    ros2 run teleop_twist_keyboard teleop_twist_keyboard

  3. What you'll see:

    • ✅ Gazebo simulation window
    • ✅ RViz with robot model
    • ✅ Real-time lidar visualization
    • ✅ TF frames (odom → base_link → sensors)

Controls:

  • i = Forward
  • , = Backward
  • j = Turn Left
  • l = Turn Right
  • k = Stop

Option 1: Navigation with Pre-Saved Map ⭐ (Recommended for Production)

Use this when: You already have a map and want autonomous navigation

Steps:

  1. Launch the navigation system:

    cd ~/Final
source install/setup.bash
ros2 launch squarobot_gazebo navigation_with_map.launch.py

  2. Wait for all nodes to start (5-10 seconds)

  3. Set initial robot pose in RViz:

    • Click "2D Pose Estimate" button (toolbar at top)
    • Click on the center of the map where robot spawned (~0, 0)
    • Drag to set the robot's orientation

  4. Verify everything is working:

    • ✅ Map appears (gray/white/black)
    • ✅ Robot model is visible
    • ✅ Green particle cloud around robot (AMCL)
    • ✅ No red errors in terminal
    • ✅ "Global Status: OK" in RViz

  5. Send navigation goal:

    • Click "Nav2 Goal" button
    • Click destination on map
    • Drag to set goal orientation
    • Robot navigates autonomously! 🤖

Map file location: ~/Final/my_maze_map.yaml (already included)

Option 2: SLAM + Navigation (Create Map While Navigating)

Use this when: You want to explore and map a new environment while navigating

Steps:

  1. Launch SLAM + Navigation:

    cd ~/Final
source install/setup.bash
ros2 launch squarobot_gazebo slam_nav_simulation.launch.py

  2. Activate SLAM Toolbox (in another terminal):

    cd ~/Final
source install/setup.bash
ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

  3. Set initial pose in RViz (same as Option 1, step 3)

  4. Navigate and map:

    • Use "Nav2 Goal" to send robot to unexplored areas
    • Map builds as robot moves
    • Watch map expand in RViz

  5. Save the map when complete:

    ros2 run nav2_map_server map_saver_cli -f ~/Final/my_new_map

Option 3: Manual SLAM Mapping (Teleoperation)

Use this when: You want to manually drive and create a map

Steps:

  1. Launch SLAM mapping:

    cd ~/Final
source install/setup.bash
ros2 launch squarobot_gazebo slam_simulation.launch.py

  2. Activate SLAM (in another terminal):

    ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

  3. Drive robot manually:

    ros2 run teleop_twist_keyboard teleop_twist_keyboard

    Controls:

    • i = Forward
    • , = Backward
    • j = Turn Left
    • l = Turn Right
    • k = Stop

  4. Save map:

    ros2 run nav2_map_server map_saver_cli -f ~/Final/my_map

🔧 Understanding Robot Frames

What are Frames?

Frames (coordinate systems) tell the robot where everything is in 3D space. Think of them like GPS coordinates but for the robot.

Frame Hierarchy:

Basic Simulation (testing, teleoperation):

odom (tracks where robot has moved)
 └─ base_link (robot body)
     ├─ wheels (drive the robot)
     └─ lidar (sees obstacles)

With Navigation/SLAM (autonomous):

map (the global map - like Google Maps)
 └─ odom (where robot thinks it is)
     └─ base_link (actual robot)
         └─ sensors

Why Multiple Frames?

Frame Purpose Analogy
map Global reference, never moves Street address
odom Tracks movement (drifts over time) Counting steps
base_link Robot body Your body

Key Insight:

  • odom drifts (wheels slip, errors accumulate) ❌
  • map corrects this drift (SLAM/AMCL fixes it) ✅
  • Both together = accurate navigation!

📚 Deep dive: Complete Frames and Transforms Guide

🎯 Complete Step-by-Step Navigation Process

Goal: Create a map and use it for autonomous navigation

Phase 1: Create the Map

  1. Launch SLAM mapping:

    ros2 launch squarobot_gazebo slam_simulation.launch.py

  2. Activate SLAM (new terminal):

    cd ~/Final && source install/setup.bash
ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

  3. Drive around to map environment:

    ros2 run teleop_twist_keyboard teleop_twist_keyboard

  4. Save map:

    ros2 run nav2_map_server map_saver_cli -f ~/Final/my_maze_map

  5. Stop launch (Ctrl+C)

Phase 2: Navigate Using the Map

  1. Launch navigation with saved map:

    cd ~/Final && source install/setup.bash
ros2 launch squarobot_gazebo navigation_with_map.launch.py

  2. Set initial pose in RViz (2D Pose Estimate tool)

  3. Send navigation goals (Nav2 Goal tool)

  4. Robot navigates autonomously! ✨

📁 Project Structure

Final/
├── src/
│   ├── squarobot_gazebo/              # Main robot package
│   │   ├── launch/
│   │   │   ├── navigation_with_map.launch.py    ⭐ Map-based navigation
│   │   │   ├── slam_nav_simulation.launch.py    SLAM + Navigation
│   │   │   ├── slam_simulation.launch.py        SLAM mapping only
│   │   │   └── simulation.launch.py             Basic simulation
│   │   ├── config/
│   │   │   ├── nav2_params.yaml        # Navigation parameters
│   │   │   ├── slam_params.yaml        # SLAM parameters
│   │   │   ├── nav.rviz               # Navigation RViz config
│   │   │   └── slam.rviz              # SLAM RViz config
│   │   ├── worlds/                     # Gazebo environments
│   │   ├── gazebo/                     # Robot URDF/Xacro
│   │   └── src/
│   │       └── odom_to_tf.py          # Odometry TF broadcaster
│   └── squarobot_urdf/                # Additional URDF files
├── docs/                               # 📚 Documentation
│   ├── AUTONOMOUS_NAVIGATION_DOCUMENTATION.md   # Main docs
│   ├── TROUBLESHOOTING_GUIDE.md                 # Error solutions
│   ├── QUICK_START_NAVIGATION.md
│   ├── COMPLETE_NAVIGATION_GUIDE.md
│   └── SYSTEM_ARCHITECTURE.md
├── my_maze_map.yaml                    # Saved map metadata
├── my_maze_map.pgm                     # Saved map image
├── build/                              # Build artifacts (generated)
├── install/                            # Installed packages (generated)
└── log/                                # ROS 2 logs (generated)

🧰 Available Launch Files

Launch File Description Frames Use Case
simulation.launch.py Basic robot simulation odom, base_link Testing, development, teleoperation
simulation_with_rviz.launch.py ⭐ Simulation + RViz visualization odom, base_link Testing with visual feedback
slam_simulation.launch.py SLAM mapping with teleoperation map, odom, base_link Create/update maps manually
slam_nav_simulation.launch.py SLAM + Navigation simultaneously map, odom, base_link Explore unknown environments
navigation_with_map.launch.py Navigation with pre-saved map ⭐ map, odom, base_link Production navigation, fastest setup

Frame Hierarchy

All launch files maintain proper TF tree structure:

Basic Simulation:

odom
 └─ base_link
     ├─ left_wheel_1, right_wheel_1, caster_1
     └─ lidar_1

With Navigation/SLAM:

map (global reference)
 └─ odom (continuous tracking)
     └─ base_link (robot body)
         └─ sensors

📚 Learn more: Frames and Transforms Guide

🔍 Troubleshooting

Common Issues

❌ "Frame [map] does not exist" in RViz

Solution:

  1. Wait 5-10 seconds for all nodes to start
  2. Set initial pose using "2D Pose Estimate" in RViz
  3. See docs/TROUBLESHOOTING_GUIDE.md

❌ Transform timeout errors

Solution:

  • Verify all nodes are running: ros2 node list
  • Check TF tree: ros2 run rqt_tf_tree rqt_tf_tree
  • Set initial pose in RViz

❌ Robot doesn't move after setting goal

Solution:

  1. Ensure initial pose was set correctly
  2. Check goal is in free space (white area on map)
  3. Verify /cmd_vel is publishing: ros2 topic hz /cmd_vel

❌ Docking server errors

Already fixed! This was resolved by excluding docking_server from the launch file.

📖 For detailed troubleshooting: See docs/TROUBLESHOOTING_GUIDE.md

🧪 Verification & Testing

Check if everything is working:

# 1. List all running nodes
ros2 node list

# 2. Check TF tree is complete
ros2 run rqt_tf_tree rqt_tf_tree

# 3. Verify map is loaded
ros2 topic echo /map --once

# 4. Check AMCL is localizing
ros2 topic hz /amcl/pose

# 5. Verify odometry is publishing
ros2 topic hz /odom

# 6. Check laser scan
ros2 topic hz /scan

Expected nodes for navigation_with_map.launch.py:

  • /amcl - Localization
  • /bt_navigator - Behavior tree navigator
  • /controller_server - Path following
  • /planner_server - Path planning
  • /map_server - Map provider
  • /lifecycle_manager_localization
  • /lifecycle_manager_navigation
  • /lifecycle_manager_map

📚 Documentation

All documentation is organized in the docs/ folder:

📖 User Guides

🔧 Technical Documentation

🛠️ Troubleshooting

📚 Reference

📋 Full Documentation Index: docs/README.md

⚙️ System Requirements

Required Software

  • OS: Ubuntu 24.04 (Noble)
  • ROS 2: Jazzy Jalisco
  • Gazebo: Harmonic
  • Python: 3.12+

Required ROS 2 Packages

sudo apt install ros-jazzy-navigation2
sudo apt install ros-jazzy-nav2-bringup
sudo apt install ros-jazzy-nav2-amcl
sudo apt install ros-jazzy-slam-toolbox
sudo apt install ros-jazzy-teleop-twist-keyboard

Hardware Requirements

  • RAM: 8GB minimum (16GB recommended)
  • CPU: 4 cores minimum
  • GPU: Integrated graphics sufficient for Gazebo

🎓 ROS 2 Topics Reference

Key Topics

Topic Type Description
/scan sensor_msgs/LaserScan Lidar data
/odom nav_msgs/Odometry Robot odometry
/cmd_vel geometry_msgs/Twist Velocity commands
/map nav_msgs/OccupancyGrid Static map
/amcl/pose geometry_msgs/PoseWithCovarianceStamped Estimated robot pose
/initialpose geometry_msgs/PoseWithCovarianceStamped Initial pose for AMCL
/goal_pose geometry_msgs/PoseStamped Navigation goal

🐛 Development & Debugging

Rebuild after changes:

cd ~/Final
colcon build --packages-select squarobot_gazebo
source install/setup.bash

View logs:

# Latest logs
cd ~/.ros/log/latest

# Specific node log
cat ~/.ros/log/latest/amcl-*.log

Check for errors:

# Monitor all topics for issues
ros2 topic list

# Check node info
ros2 node info /amcl

# View parameters
ros2 param list /amcl

🤝 Contributing

This project implements:

  • ✅ Differential drive robot simulation
  • ✅ SLAM Toolbox integration
  • ✅ Nav2 navigation stack
  • ✅ AMCL localization
  • ✅ Map-based autonomous navigation
  • ✅ Comprehensive error handling
  • ✅ Complete documentation

📄 License

This project follows ROS 2 conventions and best practices.

🆘 Getting Help

  1. Check documentation: docs/
  2. Troubleshooting guide: TROUBLESHOOTING_GUIDE.md
  3. Error history: All fixed errors are documented
  4. ROS 2 resources:

🎉 Success Indicators

You know it's working when:

  • ✅ Gazebo shows robot in maze environment
  • ✅ RViz displays the map clearly
  • ✅ Robot model appears on the map
  • ✅ Green particle cloud visible (AMCL)
  • ✅ Setting nav goal shows green path
  • ✅ Robot moves smoothly to goal
  • ✅ Obstacle avoidance works
  • ✅ No error messages in terminal

🚀 Ready to navigate! Launch the system and explore autonomous robotics with ROS 2!

Last Updated: January 17, 2026
Status: Fully Functional ✅
ROS 2 Version: Jazzy Jalisco
Gazebo Version: Harmonic

About

Implementation of the SLAM & NAV2 for the Squareobot

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages