diff --git a/source/Get-Started/Introducing-Turtlesim/Introducing-Turtlesim.rst b/source/Get-Started/Introducing-Turtlesim/Introducing-Turtlesim.rst index a7fadac919..e46a429705 100644 --- a/source/Get-Started/Introducing-Turtlesim/Introducing-Turtlesim.rst +++ b/source/Get-Started/Introducing-Turtlesim/Introducing-Turtlesim.rst @@ -1,54 +1,52 @@ .. redirect-from:: Tutorials/Turtlesim/Introducing-Turtlesim - Tutorials/Beginner-CLI-Tools/Introducing-Turtlesim/Introducing-Turtlesim .. _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:: @@ -67,206 +65,223 @@ 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 -^^^^^^^^^^^^^^^^^ +2 Install rqt (recommended) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To start turtlesim, enter the following command in your terminal: +The rqt tool is a graphical interface for ROS. +Instead of typing commands by hand, you can use rqt to explore and call Turtlesim's services with a few clicks. +For more information about rqt, see :doc:`../../Developer-Tools/Visualization/About-RQt`. -.. code-block:: console +In a new terminal, install ``rqt`` and the common plugins: - $ 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] +.. tabs:: -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. + .. group-tab:: Ubuntu -The simulator window should appear, with a random turtle in the center. + .. code-block:: console -.. image:: images/turtlesim.png + $ sudo apt update + $ sudo apt install ros-{DISTRO}-rqt ros-{DISTRO}-rqt-common-plugins + .. group-tab:: RHEL -3 Use turtlesim -^^^^^^^^^^^^^^^ + .. code-block:: console -Open a new terminal and source ROS 2 again. + $ sudo dnf install 'ros-{DISTRO}-rqt*' -Now you will run a new node to control the turtle in the first node: + .. group-tab:: macOS -.. code-block:: console + The standard archive for installing ROS on macOS contains ``rqt`` and its plugins, so you should already have ``rqt`` installed. - $ ros2 run turtlesim turtle_teleop_key + .. group-tab:: Windows -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. + The standard archive for installing ROS on Windows contains ``rqt`` and its plugins, so you should already have ``rqt`` installed. -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. +To check if the packages are installed, in a terminal, run: -.. note:: +.. code-block:: console - 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. + $ ros2 pkg list | grep -E '^rqt_gui$|^rqt_common_plugins$' -You can see the nodes, and their associated topics, services, and actions, using the ``list`` subcommands of the respective commands: +The output should include: .. code-block:: console - $ ros2 node list - $ ros2 topic list - $ ros2 service list - $ ros2 action list + rqt_common_plugins + rqt_gui -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``. +.. note:: -4 Install rqt -^^^^^^^^^^^^^ + If the packages do not appear in the list, make sure you have sourced ROS in the current terminal. -Open a new terminal to install ``rqt`` and its plugins: +3 Try out Turtlesim with rqt +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. tabs:: +The following example uses rqt but you can also operate Turtlesim by entering the same commands in the command line. - .. group-tab:: Ubuntu +#. Start Turtlesim: - .. code-block:: console + .. code-block:: console - $ sudo apt update - $ sudo apt install ros-{DISTRO}-rqt ros-{DISTRO}-rqt-common-plugins + $ 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:: RHEL + The simulator window opens with a random turtle in the center. - .. code-block:: console + .. image:: images/turtlesim.png - $ sudo dnf install 'ros-{DISTRO}-rqt*' +#. In a new terminal, source ROS again and start keyboard teleoperation: - .. group-tab:: macOS + .. code-block:: console - The standard archive for installing ROS 2 on macOS contains ``rqt`` and its plugins, so you should already have ``rqt`` installed. + $ ros2 run turtlesim turtle_teleop_key - .. group-tab:: Windows + Keep the ``turtle_teleop_key`` terminal active and use arrow keys to move the turtle. - The standard archive for installing ROS 2 on Windows contains ``rqt`` and its plugins, so you should already have ``rqt`` installed. + .. note:: -To run rqt: + 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. -.. code-block:: console +#. (Optional) List the active nodes, topics, services, and actions. + This will help you verify what is currently running and available. - $ rqt + In a new terminal, source ROS again, then run: -5 Use rqt -^^^^^^^^^ + .. code-block:: console -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. + $ ros2 node list + $ ros2 topic list + $ ros2 service list + $ ros2 action list -.. note:: + ``ros2 node list`` shows the nodes currently running in the system. + ``ros2 topic list`` shows the topics through which nodes exchange data. + ``ros2 service list`` shows the services nodes expose for request-response interactions. + ``ros2 action list`` shows the actions available for long-running tasks such as rotating the turtle. - 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. +#. Start rqt: -.. image:: images/rqt.png + .. code-block:: console -Use the refresh button to the left of the **Service** dropdown list to ensure all the services of your turtlesim node are available. + $ rqt -Click on the **Service** dropdown list to see turtlesim's services, and select the ``/spawn`` service. +#. In rqt, select **Plugins** > **Services** > **Service Caller**. -5.1 Try the spawn service -~~~~~~~~~~~~~~~~~~~~~~~~~ + .. note:: -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. + 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. -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``. + You might need to select the **Refresh Service** button to the left of the **Service** drop-down. -.. image:: images/spawn.png + .. image:: images/rqt.png -.. note:: +#. To spawn a second turtle, select the ``/spawn`` service, then enter: - 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``: + - ``name`` = ``turtle2`` + - ``x`` = ``1.0`` + - ``y`` = ``1.0`` - .. code-block:: console + Click **Call**. - [ERROR] [turtlesim]: A turtle named [turtle1] already exists + .. image:: images/spawn.png -To spawn ``turtle2``, you then need to call the service by clicking the **Call** button on the upper right side of the rqt window. + .. note:: -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**. + 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``: -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/...``. + .. code-block:: console -5.2 Try the set_pen service -~~~~~~~~~~~~~~~~~~~~~~~~~~~ + [ERROR] [turtlesim]: A turtle named [turtle1] already exists -Now let's give ``turtle1`` a unique pen using the ``/set_pen`` service: +#. Set the turtle to draw a red, thicker line. + Select the ``/turtle1/set_pen`` service, then set: -.. image:: images/set_pen.png + - ``r`` = ``255`` + - ``width`` = ``5`` -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. + Click **Call**, then use arrow keys in the teleoperation terminal to confirm the turtle draws a red, thicker line. -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. + .. image:: images/set_pen.png -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. + .. image:: images/new_pen.png -.. image:: images/new_pen.png +#. Set up a teleoperation node for ``turtle2``. -You've probably also noticed that there's no way to move ``turtle2``. -That's because there is no teleop node for ``turtle2``. + By default, ``turtle_teleop_key`` sends commands to topics and actions under the ``turtle1`` namespace. + To control ``turtle2`` instead, use the ``--remap`` option to point those topics and actions at the ``turtle2`` namespace. + This lets you reuse the same executable for a different turtle without changing any code. -6 Remapping -^^^^^^^^^^^ + In a new terminal, run: -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:`../../ROS-Framework/nodes/Working-with-nodes/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes` +* :doc:`../../ROS-Framework/interfaces/topics/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 `__ +* `rqt `__ +* `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:`../../ROS-Framework/nodes/Working-with-nodes/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 `_ 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.