Skip to main content

​
Overview

This guide will help you launch your first TurtleBot3 simulation in Gazebo and control the robot using keyboard teleoperation. The entire process takes less than 5 minutes once the container is built.
Make sure you’ve completed the installation steps before proceeding.

​
Verify setup

Before launching the simulation, verify that everything is properly configured: 
bash verify-setup.sh
You should see green checkmarks for all critical tests. If any tests fail, refer to the installation troubleshooting section.

​
Launch your first simulation

Let’s start with a simple empty world to verify everything works.
1

Open terminal in VS Code

The terminal in VS Code is already connected to the container. If you need a new terminal, press Ctrl+` or select Terminal → New Terminal
2

Launch Gazebo with TurtleBot3

tb3_empty
This starts Gazebo Harmonic with the TurtleBot3 Burger robot in an empty world.
3

Wait for Gazebo to initialize

The first launch takes 30-60 seconds as Gazebo downloads models and initializes. Subsequent launches are much faster.
4

Access the GUI

Open your web browser and navigate to:
http://localhost:6080
Password: ros
You should now see a full Linux desktop with Gazebo running and the TurtleBot3 robot visible in the simulation!
The noVNC desktop may take 30-90 seconds to fully initialize on first access. If you see a black screen, wait a moment and refresh your browser.

​
Control the robot

Now that Gazebo is running, let’s control the robot using keyboard teleoperation.
1

Open a second terminal

In VS Code, press Ctrl+` or click the + icon in the terminal panel to open a new terminal
2

Start teleoperation

tb3_teleop
This launches the keyboard control node
3

Control the robot

Use these keys to move the robot:
  • i - Move forward
  • , - Move backward
  • j - Rotate left
  • l - Rotate right
  • k - Stop
  • u - Forward + left
  • o - Forward + right
  • m - Backward + left
  • . - Backward + right
4

Adjust speed (optional)

  • w - Increase linear speed
  • x - Decrease linear speed
  • a - Increase angular speed
  • d - Decrease angular speed
Make sure the teleoperation terminal window is focused (clicked) for keyboard input to work.

​
Explore different worlds

The container includes three pre-configured simulation environments: 
# Simple empty world - good for basic testing
tb3_empty

​
Understanding the command aliases

These shortcuts expand to full ROS2 launch commands: 
# tb3_empty expands to:
ros2 launch turtlebot3_gazebo empty_world.launch.py

# tb3_world expands to:
ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py

# tb3_house expands to:
ros2 launch turtlebot3_gazebo turtlebot3_house.launch.py

# tb3_teleop expands to:
ros2 run turtlebot3_teleop teleop_keyboard

​
Access the desktop environment

The container provides a full Linux desktop accessible through your browser:
1

Open browser

Navigate to http://localhost:6080
2

Enter password

When prompted, enter: ros
3

Explore the desktop

You now have access to:
  • Gazebo simulator
  • RViz2 for visualization
  • Terminal applications
  • File manager
  • Any GUI tools you need

​
Alternative VNC access

You can also use a standalone VNC client for better performance: 
# Connect to: localhost:5901
# Password: ros
Recommended VNC clients:
  • Windows: TigerVNC, RealVNC
  • macOS: Built-in Screen Sharing, TigerVNC
  • Linux: Remmina, TigerVNC

​
Inspect ROS2 topics

While the simulation is running, you can inspect ROS2 topics and nodes: 
# List all active topics
ros2 topic list

# View robot sensor data (laser scan)
ros2 topic echo /scan

# Check odometry data
ros2 topic echo /odom

# List all running nodes
ros2 node list

# Get info about a specific node
ros2 node info /turtlebot3_node

# Check topic publish rate
ros2 topic hz /scan
These commands help you understand how ROS2 nodes communicate through topics. This is fundamental to ROS2 development.

​
Build a map with SLAM

Now let’s create a map of the environment using SLAM (Simultaneous Localization and Mapping).
1

Launch TurtleBot3 world

Terminal 1:
tb3_world
This provides a more interesting environment with obstacles to map
2

Start SLAM

Terminal 2:
tb3_slam
This launches Cartographer for SLAM. RViz2 will open automatically showing the map being built in real-time
3

Drive and explore

Terminal 3:
tb3_teleop
Drive the robot slowly around the environment. Watch the map appear in RViz2 as you explore
4

Save the map

Once you’ve mapped the entire environment, save it:
mkdir -p ~/maps
ros2 run nav2_map_server map_saver_cli -f ~/maps/my_map
This creates two files: my_map.pgm (image) and my_map.yaml (metadata)
Move the robot slowly and systematically to build an accurate map. Fast movements can reduce map quality.

​
Autonomous navigation

Use your saved map for autonomous navigation with Navigation2.
1

Launch simulation

Terminal 1:
tb3_world
2

Start navigation with your map

Terminal 2:
ros2 launch turtlebot3_navigation2 navigation2.launch.py \
  use_sim_time:=True \
  map:=$HOME/maps/my_map.yaml
RViz2 will open with navigation tools
3

Set initial pose

In RViz2 (via VNC at http://localhost:6080):
  1. Click the “2D Pose Estimate” button in the toolbar
  2. Click on the map where the robot is currently located
  3. Drag to set the robot’s orientation
4

Set navigation goal

  1. Click the “Navigation2 Goal” button in the toolbar
  2. Click on your desired destination on the map
  3. Drag to set the final orientation
  4. Watch the robot autonomously navigate to the goal, avoiding obstacles!
The initial pose estimate must be accurate for navigation to work properly. If the robot doesn’t navigate correctly, reset the pose estimate.

​
Workspace commands

Here are essential commands for working with the ROS2 workspace: 
# Full command
cd /workspace/turtlebot3_ws
colcon build --symlink-install

# Or use alias
cb

​
Troubleshooting

​
Gazebo won’t start

Solution: 
# Kill any existing Gazebo processes
pkill -9 gz
pkill -9 gzserver
pkill -9 gzclient

# Try again
tb3_empty

​
No robot appears in Gazebo

Solution: 
# Verify environment variable
echo $TURTLEBOT3_MODEL
# Should output: burger

# If empty, set it
export TURTLEBOT3_MODEL=burger

# Source workspace and retry
sb
tb3_empty

​
VNC shows black screen

Solution:
  1. Wait 30-90 seconds for desktop to initialize
  2. Refresh your browser
  3. If still black, restart VNC: 
    sudo supervisorctl restart desktop-lite
  4. Wait 30 seconds and refresh browser

​
Graphics issues or crashes

Solution: 
# Use software rendering
export LIBGL_ALWAYS_SOFTWARE=1
tb3_empty

# Or use the software rendering aliases
tb3_empty_sw
tb3_world_sw
tb3_house_sw

​
ROS2 topics not visible

Solution: 
# Source the workspace
source /opt/ros/jazzy/setup.bash
source /workspace/turtlebot3_ws/install/setup.bash

# Or use alias
sb

# Check if simulation is running
ros2 node list

​
Next steps

Now that you’ve successfully launched and controlled TurtleBot3, you can:

Learn ROS2 development

Create custom packages and nodes in the development guide

Explore advanced features

Try custom worlds, different robot models, and advanced navigation scenarios

Read ROS2 documentation

Visit docs.ros.org/en/jazzy for comprehensive ROS2 tutorials

Join the community

Ask questions on ROS Discourse and contribute to the project
The workspace at /workspace/turtlebot3_ws is mounted from your host machine. All your code and files persist even if you delete the container.

Build docs developers (and LLMs) love

Get started for freeTalk to us