content/guides/ros2/turtlesim-example.md
Turtlesim is a simple simulation tool that demonstrates fundamental ROS 2 concepts such as nodes, topics, and services. In this section, you'll run a complete example with Turtlesim, control the turtle, monitor topics, and visualize the system with rqt.
Allow Docker access to your X server:
$ xhost +local:docker
On macOS, use XQuartz to provide X11 support. Install XQuartz using Homebrew:
Install XQuartz using Homebrew:
$ brew install --cask xquartz
Open XQuartz from Applications, then navigate to Preferences > Security and enable Allow connections from network clients. Restart your computer to ensure the changes take effect.
After rebooting, open a terminal and allow local connections:
$ defaults write org.xquartz.X11 nolisten_tcp -bool false
$ xhost +localhost
$ xhost + 127.0.0.1
Start the container using the same Docker Compose setup from the workspace section.
For Linux:
$ cd ws_linux
$ docker compose up -d
$ docker compose exec ros2 /bin/bash
For macOS:
$ cd ws_mac
$ docker compose up -d
$ docker compose exec ros2 /bin/bash
Inside the container, install the Turtlesim package:
Update the package manager:
$ sudo apt update
Install the Turtlesim package:
$ sudo apt install -y ros-humble-turtlesim
Run the Turtlesim node:
$ ros2 run turtlesim turtlesim_node
A window should appear on your desktop showing a turtle in a grid.
Open a new terminal and connect to the same container, then start the keyboard teleop node:
$ ros2 run turtlesim turtle_teleop_key
This node allows you to control the turtle using your keyboard. Use the arrow keys to move the turtle forward, backward, left, and right. Press Ctrl+C to stop the teleop node.
Move the turtle around the window. You should see it draw a path as it moves.
Open another terminal and connect to the same container, then list all active topics:
$ ros2 topic list
You should see output similar to the following:
/parameter_events
/rosout
/turtle1/cmd_vel
/turtle1/color_sensor
/turtle1/pose
Get information about a specific topic:
$ ros2 topic info /turtle1/pose
You'll see the topic type and which nodes publish and subscribe to it.
Open another terminal and connect to the same container, then update the package manager:
$ sudo apt update
Install rqt:
$ sudo apt install -y 'ros-humble-rqt*'
Start rqt:
$ ros2 run rqt_gui rqt_gui
An rqt window should appear. rqt provides several useful plugins for visualizing and monitoring ROS 2 systems.
You can explore the node graph by navigating to Plugins > Introspection > Node Graph. A new tab opens showing nodes and topics with connections illustrated as lines. This visualization demonstrates how the teleop node sends velocity commands to the Turtlesim node, and how the Turtlesim node publishes position data back through topics.
You can monitor active topics by navigating to Plugins > Topics > Topic Monitor. A new tab opens displaying all active topics and their current values. Select the eye icon next to /turtle1/pose to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands.
You can call services from rqt using Plugins > Services > Service Caller. Select a service such as /turtle1/teleport_absolute, enter values for the request fields, and select Call to send the request.
To plot topic data over time navigate to Plugins > Visualization > Plot. For example, in the Plot window, type /turtle1/pose/x in the Topic field and press Enter. Move the turtle and watch the X position displayed as a graph over time.
Turtlesim provides services for actions such as repositioning the turtle and clearing the path.
List available services:
$ ros2 service list
You should see services such as /turtle1/set_pen (to change pen color and width), /turtle1/teleport_absolute (to move the turtle to a specific position), and /turtle1/teleport_relative (to move the turtle relative to its current position).
Teleport the turtle to a new position:
$ ros2 service call /turtle1/teleport_absolute turtlesim/srv/TeleportAbsolute "
x: 1.0
y: 3.0
theta: 0.0
"
The turtle should instantly move to the specified position (1.0, 3.0).
Create a Python script that publishes velocity commands to control the turtle programmatically. In a new terminal, create a file called move_turtle.py:
import rclpy
from geometry_msgs.msg import Twist
import time
def main():
rclpy.init()
node = rclpy.create_node('turtle_mover')
publisher = node.create_publisher(Twist, 'turtle1/cmd_vel', 10)
# Create a twist message
msg = Twist()
msg.linear.x = 2.0 # Move forward at 2 m/s
msg.angular.z = 1.0 # Rotate at 1 rad/s
# Publish the message
for i in range(50):
publisher.publish(msg)
time.sleep(0.1)
# Stop the turtle
msg.linear.x = 0.0
msg.angular.z = 0.0
publisher.publish(msg)
node.destroy_node()
rclpy.shutdown()
if __name__ == '__main__':
main()
Run the script:
$ python3 move_turtle.py
The turtle should move in a circular motion for 5 seconds and then stop.
In this section, you configured display forwarding, used the Turtlesim nodes, inspected nodes and topics, and visualized the system using rqt. Finally, you interacted with ROS 2 services and created a simple publisher to move the turtle programmatically.
These fundamental concepts apply directly to real-world robotics applications with actual sensors and actuators.