Skip to content

Setting up Turtlesim - how-to #6935

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kacperbojakowski-3di wants to merge 12 commits into
base: rolling
Choose a base branch
from
+152 −137
Open

Setting up Turtlesim - how-to #6935

Changes from 9 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
b849ab2
Update Setting up turtlesim how-to
kacperbojakowski-3di Jun 1, 2026
20de3f6
Implement peer review feedback
kacperbojakowski-3di Jun 15, 2026
0898950
Merge branch 'rolling' of upstream into setting-up-turtlesim-howto
kacperbojakowski-3di Jun 15, 2026
c26469d
Peer review updates to Turtlesim topic
dmarshant Jul 1, 2026
62f117f
Merge branch 'rolling' into setting-up-turtlesim-howto
dmarshant Jul 1, 2026
ddec86c
Peer review update
kacperbojakowski-3di Jul 2, 2026
1f8c7d6
Merge branch 'setting-up-turtlesim-howto' of https://github.com/3di-f…
kacperbojakowski-3di Jul 2, 2026
43f4be8
Update Introducing-Turtlesim.rst
kacperbojakowski-3di Jul 2, 2026
8404b2f
Merge remote-tracking branch 'upstream/rolling' into setting-up-turtl…
kacperbojakowski-3di Jul 6, 2026
27b29d0
Implement SME feedback
kacperbojakowski-3di Jul 19, 2026
152ebd0
Merge remote-tracking branch 'upstream/rolling' into setting-up-turtl…
kacperbojakowski-3di Jul 19, 2026
00019e9
Fix links
kacperbojakowski-3di Jul 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 142 additions & 139 deletions ...ce/Tutorials/Beginner-CLI-Tools/Introducing-Turtlesim/Introducing-Turtlesim.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,49 @@

.. _Turtlesim:

Using ``turtlesim``, ``ros2``, and ``rqt``
==========================================
Setting up Turtlesim - how-to
=============================

**Goal:** Install and use the turtlesim package and rqt tools to prepare for upcoming tutorials.
Turtlesim is a simple simulator to demonstrate core ROS concepts without any hardware.
This article walks you through installation of Turtlesim and the rqt GUI.
A short exercise provides you with basic experience with these tools.

**Tutorial level:** Beginner

**Time:** 15 minutes
**Area: Framework | Content-type: how-to | Experience: beginner**

.. contents:: Contents
:depth: 2
:depth: 3
:local:

Background
----------

Turtlesim is a lightweight simulator for learning ROS 2.
It illustrates what ROS 2 does at the most basic level to give you an idea of what you will do with a real robot or a robot simulation later on.

The ros2 tool is how the user manages, introspects, and interacts with a ROS system.
It supports multiple commands that target different aspects of the system and its operation.
One might use it to start a node, set a parameter, listen to a topic, and many more.
The ros2 tool is part of the core ROS 2 installation.
Summary
-------

rqt is a graphical user interface (GUI) tool for ROS 2.
Everything done in rqt can be done on the command line, but rqt provides a more user-friendly way to manipulate ROS 2 elements.
Turtlesim is a lightweight simulator for learning ROS basics.
Install the package ``ros-{DISTRO}-turtlesim``.

This tutorial touches upon core ROS 2 concepts, like nodes, topics, and services.
All of these concepts will be elaborated on in later tutorials; for now, you will simply set up the tools and get a feel for them.
The rqt tool is a graphical interface for interacting with ROS.
Install the package ``ros-{DISTRO}-rqt``.

Prerequisites
-------------

The previous tutorial, :doc:`../Configuring-ROS2-Environment`, will show you how to set up your environment.
Before you start, make sure ROS is installed and your environment is configured.

To learn how to set up your environment, see :doc:`../Configuring-ROS2-Environment`.

Tasks
Steps
-----

1 Install turtlesim
.. note::
Do not forget to source ROS in every new terminal you open.
See :doc:`Configuring environment <../Configuring-ROS2-Environment>`.

1 Install Turtlesim
^^^^^^^^^^^^^^^^^^^

As always, start by sourcing your setup files in a new terminal, as described in the :doc:`previous tutorial <../Configuring-ROS2-Environment>`.
Turtlesim is a lightweight simulator that represents a robot as a turtle you can control on the screen.
It lets you practice core ROS concepts without the need for any real hardware.

Install the turtlesim package for your ROS 2 distro:
Install the Turtlesim package for your ROS distribution:

.. tabs::

Expand All @@ -66,206 +65,210 @@ Install the turtlesim package for your ROS 2 distro:

.. group-tab:: macOS

As long as the archive you installed ROS 2 from contains the ``ros_tutorials`` repository, you should already have turtlesim installed.
As long as the archive you installed ROS from contains the ``ros_tutorials`` repository, you should already have Turtlesim installed.

.. group-tab:: Windows

As long as the archive you installed ROS 2 from contains the ``ros_tutorials`` repository, you should already have turtlesim installed.
As long as the archive you installed ROS from contains the ``ros_tutorials`` repository, you should already have Turtlesim installed.

To check if the package is installed, run the following command, which should return a list of turtlesim's executables:
To check if the package is installed, run:

.. code-block:: console

$ ros2 pkg executables turtlesim

The output should list Turtlesim's executables:

.. code-block:: console

turtlesim draw_square
turtlesim mimic
turtlesim turtle_teleop_key
turtlesim turtlesim_node

2 Start turtlesim
^^^^^^^^^^^^^^^^^

To start turtlesim, enter the following command in your terminal:
2 Install rqt (recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

$ ros2 run turtlesim turtlesim_node
[INFO] [turtlesim]: Starting turtlesim with node name /turtlesim
[INFO] [turtlesim]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000]
The rqt tool is a graphical interface for ROS.
For more information about rqt, see :doc:`../../../../Concepts/Intermediate/About-RQt`.

Under the command, you will see messages from the node.
There you can see the default turtle's name and the coordinates where it spawns.
Instead of typing commands by hand, you can use rqt to explore and call Turtlesim's services with a few clicks.

The simulator window should appear, with a random turtle in the center.
In a new terminal, install ``rqt`` and the common plugins:

.. image:: images/turtlesim.png
.. tabs::

.. group-tab:: Ubuntu

3 Use turtlesim
^^^^^^^^^^^^^^^
.. code-block:: console

Open a new terminal and source ROS 2 again.
$ sudo apt update
$ sudo apt install ros-{DISTRO}-rqt ros-{DISTRO}-rqt-common-plugins

Now you will run a new node to control the turtle in the first node:
.. group-tab:: RHEL

.. code-block:: console
.. code-block:: console

$ ros2 run turtlesim turtle_teleop_key
$ sudo dnf install 'ros-{DISTRO}-rqt*'

At this point you should have three windows open: a terminal running ``turtlesim_node``, a terminal running ``turtle_teleop_key`` and the turtlesim window.
Arrange these windows so that you can see the turtlesim window, but also have the terminal running ``turtle_teleop_key`` active so that you can control the turtle in turtlesim.
.. group-tab:: macOS

Use the arrow keys on your keyboard to control the turtle.
It will move around the screen, using its attached "pen" to draw the path it followed so far.
The standard archive for installing ROS on macOS contains ``rqt`` and its plugins, so you should already have ``rqt`` installed.

.. note::
.. group-tab:: Windows

Pressing an arrow key will only cause the turtle to move a short distance and then stop.
This is because, realistically, you wouldn't want a robot to continue carrying on an instruction if, for example, the operator lost the connection to the robot.
The standard archive for installing ROS on Windows contains ``rqt`` and its plugins, so you should already have ``rqt`` installed.

You can see the nodes, and their associated topics, services, and actions, using the ``list`` subcommands of the respective commands:
To check if the packages are installed, in a terminal, run:

.. code-block:: console

$ ros2 node list
$ ros2 topic list
$ ros2 service list
$ ros2 action list
$ ros2 pkg list | grep -E '^rqt_gui$|^rqt_common_plugins$'

You will learn more about these concepts in the coming tutorials.
Since the goal of this tutorial is only to get a general overview of turtlesim, you will use rqt to call some of the turtlesim services and interact with ``turtlesim_node``.
The output should include:

4 Install rqt
^^^^^^^^^^^^^
.. code-block:: console

Open a new terminal to install ``rqt`` and its plugins:
rqt_common_plugins
rqt_gui

.. tabs::
.. note::

.. group-tab:: Ubuntu
If the packages do not appear in the list, make sure you have sourced ROS in the current terminal.

.. code-block:: console
3 Try out Turtlesim with rqt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

$ sudo apt update
$ sudo apt install ros-{DISTRO}-rqt ros-{DISTRO}-rqt-common-plugins
The following example uses rqt but you can also operate Turtlesim by entering the same commands in the command line.

.. group-tab:: RHEL
#. Start Turtlesim:

.. code-block:: console
.. code-block:: console

$ sudo dnf install 'ros-{DISTRO}-rqt*'
$ ros2 run turtlesim turtlesim_node
[INFO] [turtlesim]: Starting turtlesim with node name /turtlesim
[INFO] [turtlesim]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000]

.. group-tab:: macOS
The simulator window opens with a random turtle in the center.

The standard archive for installing ROS 2 on macOS contains ``rqt`` and its plugins, so you should already have ``rqt`` installed.
.. image:: images/turtlesim.png

.. group-tab:: Windows
#. In a new terminal, source ROS again and start keyboard teleoperation:

The standard archive for installing ROS 2 on Windows contains ``rqt`` and its plugins, so you should already have ``rqt`` installed.
.. code-block:: console

To run rqt:
$ ros2 run turtlesim turtle_teleop_key

.. code-block:: console

$ rqt
Keep the ``turtle_teleop_key`` terminal active and use arrow keys to move the turtle.

5 Use rqt
^^^^^^^^^
.. note::

When running rqt for the first time, the window will be blank.
No worries; just select **Plugins** > **Services** > **Service Caller** from the menu bar at the top.
Pressing an arrow key causes the turtle to move a short distance and then stop.
This behaviour ensures a robot doesn't continue carrying on an instruction if, for example, the operator loses connection to the robot.

.. note::
#. (Optional) In a new terminal, source ROS again and inspect the running system:

It may take some time for rqt to locate all the plugins.
If you click on **Plugins** but don't see **Services** or any other options, you should close rqt and enter the command ``rqt --force-discover`` in your terminal.
.. code-block:: console

.. image:: images/rqt.png
$ ros2 node list
$ ros2 topic list
$ ros2 service list
$ ros2 action list

Use the refresh button to the left of the **Service** dropdown list to ensure all the services of your turtlesim node are available.
#. Start rqt:

Click on the **Service** dropdown list to see turtlesim's services, and select the ``/spawn`` service.
.. code-block:: console

5.1 Try the spawn service
~~~~~~~~~~~~~~~~~~~~~~~~~
$ rqt

Let's use rqt to call the ``/spawn`` service.
You can guess from its name that ``/spawn`` will create another turtle in the turtlesim window.
#. In rqt, select **Plugins** > **Services** > **Service Caller**.

Give the new turtle a unique name, like ``turtle2``, by double-clicking between the empty single quotes in the **Expression** column.
You can see that this expression corresponds to the value of **name** and is of type **string**.
.. note::

Next enter some valid coordinates at which to spawn the new turtle, like ``x = 1.0`` and ``y = 1.0``.
It may take some time for rqt to locate all the plugins.
If you click on **Plugins** but don't see **Services** or any other options, close rqt and enter the command ``rqt --force-discover`` in your terminal.

.. image:: images/spawn.png
.. note::

.. note::
You might need to select the **Refresh Service** button to the left of the **Service** drop-down.

If you try to spawn a new turtle with the same name as an existing turtle, like the default ``turtle1``, you will get an error message in the terminal running ``turtlesim_node``:
.. image:: images/rqt.png

.. code-block:: console
#. To spawn a second turtle, select the ``/spawn`` service, then enter:

[ERROR] [turtlesim]: A turtle named [turtle1] already exists
- ``name`` = ``turtle2``
- ``x`` = ``1.0``
- ``y`` = ``1.0``

To spawn ``turtle2``, you then need to call the service by clicking the **Call** button on the upper right side of the rqt window.
Click **Call**.

If the service call was successful, you should see a new turtle (again with a random design) spawn at the coordinates you input for **x** and **y**.
.. image:: images/spawn.png

If you refresh the service list in rqt, you will also see that now there are services related to the new turtle, ``/turtle2/...``, in addition to ``/turtle1/...``.
.. note::

5.2 Try the set_pen service
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each turtle needs a unique name.
If you spawn a turtle with an existing name, you get an error message in the terminal that runs ``turtlesim_node``:

Now let's give ``turtle1`` a unique pen using the ``/set_pen`` service:
.. code-block:: console

.. image:: images/set_pen.png
[ERROR] [turtlesim]: A turtle named [turtle1] already exists

The values for **r**, **g** and **b**, which are between 0 and 255, set the color of the pen ``turtle1`` draws with, and **width** sets the thickness of the line.
#. Set the turtle to draw a red, thicker line.
Select the ``/turtle1/set_pen`` service, then set:

To have ``turtle1`` draw with a distinct red line, change the value of **r** to 255, and the value of **width** to 5.
Don't forget to call the service after updating the values.
- ``r`` = ``255``
- ``width`` = ``5``

If you return to the terminal where ``turtle_teleop_key`` is running and press the arrow keys, you will see ``turtle1``'s pen has changed.
Click **Call**, then use arrow keys in the teleoperation terminal to confirm the turtle draws a red, thicker line.

.. image:: images/new_pen.png
.. image:: images/set_pen.png

You've probably also noticed that there's no way to move ``turtle2``.
That's because there is no teleop node for ``turtle2``.
.. image:: images/new_pen.png

6 Remapping
^^^^^^^^^^^
#. In a new terminal, control ``turtle2`` by remapping:

@kscottz kscottz Jul 13, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like I said, I know we're simply following the previous material but this is really unsatisfying. There's no definition of what we mean by remapping or why we would have to do that to control a second turtle. If we're going to update this page we should aim for it to more informative than it was before.

@kacperbojakowski-3di kacperbojakowski-3di Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kscottz Thanks! That was indeed too sparse and vague, I should have noticed. Fixed now, hopefully – let me know.


You need a second teleop node in order to control ``turtle2``.
However, if you try to run the same command as before, you will notice that this one also controls ``turtle1``.
The way to change this behavior is by remapping the ``cmd_vel`` topic and the ``rotate_absolute`` action.
.. code-block:: console

In a new terminal, source ROS 2, and run:
$ ros2 run turtlesim turtle_teleop_key --ros-args --remap turtle1/cmd_vel:=turtle2/cmd_vel --remap turtle1/rotate_absolute:=turtle2/rotate_absolute

.. code-block:: console
Keep this new terminal active to move ``turtle2``.
Continue using the original teleoperation terminal to move ``turtle1``.

$ ros2 run turtlesim turtle_teleop_key --ros-args --remap turtle1/cmd_vel:=turtle2/cmd_vel --remap turtle1/rotate_absolute:=turtle2/rotate_absolute
.. image:: images/remap.png

#. Close Turtlesim:

Now, you can move ``turtle2`` when this terminal is active, and ``turtle1`` when the other terminal running ``turtle_teleop_key`` is active.
- In the ``turtlesim_node`` terminal, press ``Ctrl + C``.
- In ``turtle_teleop_key`` terminals, press ``q``.

.. image:: images/remap.png
Related content
---------------

7 Close turtlesim
^^^^^^^^^^^^^^^^^
More articles:

To stop the simulation, you can enter ``Ctrl + C`` in the ``turtlesim_node`` terminal, and ``q`` in the ``turtle_teleop_key`` terminals.
* :doc:`First steps with ROS <../../../First-Steps>`
* :doc:`../Configuring-ROS2-Environment`
* :doc:`../Understanding-ROS2-Nodes/Understanding-ROS2-Nodes`
* :doc:`../Understanding-ROS2-Topics/Understanding-ROS2-Topics`

Summary
-------
Packages/reference:

Using turtlesim and rqt is a great way to learn the core concepts of ROS 2.
* `Turtlesim package in ros_tutorials <https://github.com/ros/ros_tutorials/tree/{REPOS_FILE_BRANCH}/turtlesim>`__
* `rqt <https://index.ros.org/p/rqt/>`__
* `rqt_common_plugins <https://index.ros.org/p/rqt_common_plugins/>`__

Next steps
----------
FAQs
----

Now that you have turtlesim and rqt up and running, and an idea of how they work, let's dive into the first core ROS 2 concept with the next tutorial, :doc:`../Understanding-ROS2-Nodes/Understanding-ROS2-Nodes`.
Do I need rqt to use Turtlesim?
No.
You can use Turtlesim entirely from the command line.
The rqt tool is recommended because it helps you visualize the instructions you send to the turtle.

Related content
---------------
Why can I move only one turtle at a time?
Each ``turtle_teleop_key`` instance controls one turtle namespace.
To control ``turtle2``, run a second teleop node with topic and action remapping.

The turtlesim package can be found in the `ros_tutorials <https://github.com/ros/ros_tutorials/tree/{REPOS_FILE_BRANCH}/turtlesim>`_ repo.
Why doesn't the turtle move when I press the arrow keys?
The ``turtle_teleop_key`` terminal must be the active window for it to capture your key presses.
Each press also moves the turtle only a short distance, so you need to press the keys repeatedly to keep the turtle moving.
Loading