Set up the environment

Get something moving before reading anything

Understand localization

How does the robot know where it is?

Understand collision avoidance

How does the robot avoid obstacles in real time?

Understand the full system

How do all the modules fit together?

Prepare the Ubuntu, Docker, and ROS 2 layer

Get a reproducible container environment ready before anything else

What this step does: Creates a reproducible robotics environment inside a container. The host Ubuntu VM only needs Docker and GUI forwarding; ROS 2 Jazzy, Nav2, Gazebo, and TurtleBot4 run inside Docker.

sudo apt update
sudo apt install -y ca-certificates curl
docker run hello-world
sudo usermod -aG docker $USER
docker pull osrf/ros:jazzy-desktop-full

Timing: docker pull downloads several GB and can take 10–30 minutes on a typical connection. A long pause with no output is normal — do not interrupt it.

Expected result: Hello from Docker! appears, docker ps works without sudo after re-login or a new shell, and docker run --rm osrf/ros:jazzy-desktop-full printenv ROS_DISTRO prints jazzy. Note: the docker ps permission only takes effect after you log out and back in (or open a fresh shell) following usermod.

Install rocker for GUI forwarding

Bridge containerized ROS tools to the VM display

What this step does: Allows graphical applications inside Docker, such as RViz and Gazebo, to appear on the Ubuntu desktop. This is the bridge between containerized ROS and the VM display.

sudo apt install -y pipx
pipx install rocker
pipx ensurepath
source ~/.bashrc
rocker --version

Expected result: The terminal prints a rocker version, for example rocker 0.3.0. If rocker is not found immediately after install, run source ~/.bashrc or open a new terminal.

Build the TurtleBot4 Docker image

Produce the reusable tb4-jazzy image for the whole project

What this step does: Extends the official ROS 2 Jazzy desktop image with TurtleBot4 simulation, Nav2 bringup, and SLAM Toolbox. This produces the reusable tb4-jazzy image used by the rest of the project.

FROM osrf/ros:jazzy-desktop-full

RUN apt-get update && apt-get install -y \
    ros-jazzy-turtlebot4-simulator \
    ros-jazzy-turtlebot4-desktop \
    ros-jazzy-nav2-bringup \
    ros-jazzy-slam-toolbox \
    && rm -rf /var/lib/apt/lists/*

SHELL ["/bin/bash", "-c"]
CMD ["bash"]

mkdir -p ~/tb4_docker
cd ~/tb4_docker
docker build -t tb4-jazzy .

Timing: The first docker build installs many ROS packages and can take 15–40 minutes. Later rebuilds are faster because Docker caches unchanged layers.

Expected result: docker images | grep tb4-jazzy shows tb4-jazzy:latest. The image is the base for TurtleBot4, Gazebo, SLAM, and Nav2 commands.

Start RViz and Gazebo, then fix VM rendering if needed

Confirm the GUI tools open and the warehouse world renders

What this step does: Confirms that graphical ROS tools can open and that the TurtleBot4 warehouse simulation can render. In VMware, Gazebo may load the world but show a blank or blue scene unless software rendering is enabled.

rocker --x11 --user --home osrf/ros:jazzy-desktop-full rviz2

rocker --x11 --user --home --name tb4 --env LIBGL_ALWAYS_SOFTWARE=1 -- tb4-jazzy \
ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py

Timing: The first Gazebo launch downloads and caches world/robot models, so it can sit on a seemingly frozen screen for 1–3 minutes (longer with software rendering). This is normal — wait before assuming it crashed.

Expected result: RViz opens, Gazebo shows the warehouse world, and TurtleBot4 appears in the scene. If the robot seems visually slow, verify motion with /odom rather than relying only on animation.

Build a map with SLAM

Stitch a warehouse map from lidar and motion

What this step does: Uses the laser scan topic /scan and robot motion to build a map of the warehouse. SLAM is used when the robot does not already have a known map.

rocker --x11 --user --home --name tb4 --env LIBGL_ALWAYS_SOFTWARE=1 -- tb4-jazzy \
ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py slam:=true rviz:=true

Expected result: In RViz, the map grows as the robot moves. Conceptually, the robot is matching laser observations to its own motion and gradually stitching the warehouse map together.

Save and check the map

Turn the live SLAM map into reusable files

What this step does: Converts the live SLAM map into reusable files so the next run can use localization instead of rebuilding the map from scratch.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && mkdir -p ~/maps && \
ros2 run nav2_map_server map_saver_cli -f ~/maps/warehouse_map"

ls -lh ~/maps
cat ~/maps/warehouse_map.yaml

Expected result: ~/maps/warehouse_map.pgm stores the map image, and ~/maps/warehouse_map.yaml stores metadata such as resolution, origin, and the image filename.

Start localization and Nav2 with the saved map

Switch from SLAM to map_server + AMCL + Nav2

What this step does: Stops using SLAM as the main mapping process and starts the normal navigation stack: map_server provides the saved map, AMCL localizes the robot, and Nav2 plans and controls navigation.

rocker --x11 --user --home --env LIBGL_ALWAYS_SOFTWARE=1 --name tb4 -- tb4-jazzy \
ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py \
localization:=true nav2:=true rviz:=true \
map:=/home/<your-username>/maps/warehouse_map.yaml use_sim_time:=true autostart:=true

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 daemon stop || true && ros2 daemon start && \
sleep 3 && ros2 node list | sort | \
grep -E 'map_server|amcl|bt_navigator|planner_server|controller_server|costmap|lifecycle'"

Expected result: Use 2D Pose Estimate in RViz to set the robot's starting pose. Global Status should become Ok, and the Navigation 2 panel should show active localization and navigation.

Understand AMCL localization

See how particles converge to the robot's true pose

What this step does: AMCL compares the saved map with the robot's live laser scan to estimate where the robot is. The particle cloud is the set of possible robot poses; /amcl_pose is the final pose estimate.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 daemon stop || true && ros2 daemon start && \
sleep 5 && ros2 node info /amcl"

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && timeout 8 ros2 topic echo /amcl_pose \
geometry_msgs/msg/PoseWithCovarianceStamped"

Expected result: /amcl subscribes to /map, /scan, /tf, and /initialpose, and publishes /amcl_pose, /particle_cloud, and /tf. In RViz, Amcl Particle Swarm on /particle_cloud should show green particles.

Inspect global and local costmaps

See how map and sensor data become navigation risk

What this step does: Costmaps translate raw map and sensor data into navigation risk. The global costmap is used for long-range planning. The local costmap is a rolling window around the robot for immediate obstacle avoidance.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 topic list -t | grep costmap"

Expected result: RViz can show /global_costmap/costmap and /local_costmap/costmap. The local costmap should move with the robot; the global costmap covers the larger map.

Send a goal and observe planning plus control

Watch the planner and controller drive the robot

What this step does: When a user clicks Nav2 Goal, the behavior tree starts the navigation task, the planner creates a global route, and the controller converts that route into real-time velocity commands.

# In RViz:
# 1. Click Nav2 Goal.
# 2. Choose a reachable point on free space.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && timeout 10 ros2 topic echo /cmd_vel_smoothed \
geometry_msgs/msg/TwistStamped"

Expected result: The Navigation panel shows active feedback, distance remaining changes, and /cmd_vel_smoothed contains non-zero linear.x or angular.z values. If Gazebo animation is delayed, confirm motion with ros2 topic echo /odom --field pose.pose.position.

Test collision avoidance with inflation radius

Trade off safety buffer against path tightness

What this step does: inflation_radius expands obstacle cost outward. Larger values make the robot keep more distance from obstacles; smaller values let it pass closer to obstacles but increase collision risk.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 daemon stop || true && ros2 daemon start && sleep 3 && \
ros2 param set /global_costmap/global_costmap inflation_layer.inflation_radius 0.90 && \
ros2 param set /local_costmap/local_costmap inflation_layer.inflation_radius 0.90"

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 daemon stop || true && ros2 daemon start && sleep 3 && \
ros2 param set /global_costmap/global_costmap inflation_layer.inflation_radius 0.20 && \
ros2 param set /local_costmap/local_costmap inflation_layer.inflation_radius 0.20"

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 daemon stop || true && ros2 daemon start && sleep 3 && \
ros2 param set /global_costmap/global_costmap inflation_layer.inflation_radius 0.45 && \
ros2 param set /local_costmap/local_costmap inflation_layer.inflation_radius 0.45"

Expected result: At 0.90, the purple/pink safety buffer becomes wider and the robot behaves more conservatively. At 0.20, the buffer becomes narrower and paths may pass closer to obstacles. Restore 0.45 after the comparison.

Explain the complete closed loop

Turn a list of commands into a system-level understanding

What this step does: Turns the project from a list of commands into a system-level understanding. The key point is feedback: once the robot moves, /odom, /tf, and /scan update, and the whole navigation stack replans and controls again.

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 node list | sort"

docker exec -it tb4 bash -lc \
"source /opt/ros/jazzy/setup.bash && ros2 topic list -t"

Ubuntu VM / Docker / ROS 2 Jazzy
      -> tb4-jazzy image
      -> Gazebo warehouse simulation
      -> TurtleBot4 sensors: /scan, /odom, /tf
      -> SLAM or map_server
      -> AMCL localization: /amcl_pose, /particle_cloud
      -> global and local costmaps
      -> BT Navigator
      -> Planner Server
      -> Controller Server
      -> Velocity Smoother and Collision Monitor
      -> /cmd_vel_smoothed -> /cmd_vel -> /diffdrive_controller/cmd_vel
      -> Robot motion in Gazebo
      -> /odom, /tf, /scan feedback
      -> system keeps updating

Expected result: A student can explain the project in plain language: the robot sees with lidar, localizes against a map, uses costmaps to decide safe space, plans a route, converts the route into velocity commands, moves, and feeds new sensor data back into the loop.