Running your first ROS program: turtlesim

3.2. Running your first ROS program: turtlesim#

Let’s get started with our first ROS CLI command ros2.

The ros2 CLI 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.

The first command we’ll visit is run. Let’s start by looking at the documentation for the run command:

$ ros2 run
usage: ros2 run [-h] [--prefix PREFIX] package_name executable_name ...
ros2 run: error: the following arguments are required: package_name, executable_name, argv

To get more complete information about a ROS 2 command, simply ask the command for help by adding --help to the command. Let’s try that again:

$ ros2 run --help
usage: ros2 run [-h] [--prefix PREFIX] package_name executable_name ...

Run a package specific executable

positional arguments:
  package_name     Name of the ROS package
  executable_name  Name of the executable
  argv             Pass arbitrary arguments to the executable

optional arguments:
  -h, --help       show this help message and exit
  --prefix PREFIX  Prefix command, which should go before the executable.
                   Command must be wrapped in quotes if it contains spaces
                   (e.g. --prefix 'gdb -ex run --args').

We can see that ros2 run is the command to, “Run a package specific executable.” In ROS 2 collections of ROS software are gathered into logical units called packages. Each package contains all of the source code for the package and a variety of other data that tells ROS how to build and compile the package and the names of all the programs, also called executables, that can be found in the package.

Note

Note that the output from --help gives you tips on the syntax of using ros2 run in the terminal.

The line below the description gives the positional arguments for the package. Positional arguments are the words and values that come after ros2 and the command you run. In this case the syntax for the command sentence we want to write is as follows:

ros2 run <package name> <program/executable name> <args>

There is one piece of missing information here. What is this argv that the command is asking for? The argv element is programmer short hand for variable arguments, and it simply means, “some number of additional arguments that are determined by the executable”. It is worth noting that a program can have zero arguments and you can just leave it blank. This is actually how a lot of programs work.

For example, say we had a package called math, and an executable called add that takes in two numbers and returns the result. In this case argv would be the two numbers to add. The final command would look like:

ros2 run math add 1 2

Finally, below the positional arguments we have optional arguments. You don’t need to include them, unless you need to.

3.2.1. Running Turtlesim#

Now that we’ve looked into our help file let’s run our first ROS program. For these tutorials we’re going to use a package called turtlesim, and the program we want to run is turtlesim_node.

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.

Let’s run this program (remember your tab complete!). Your command should look like the following:

$ ros2 run turtlesim turtlesim_node

If everything goes smoothly you should see the following:

[INFO] [turtlesim]: Starting turtlesim with node name /turtlesim
[INFO] [turtlesim]: Spawning turtle [turtle1] at x=[5.544445], y=[5.544445], theta=[0.000000]

A window should also pop up with a cute little turtle that looks like the one below: Turtlesim upon opening

Note

In the terminal output, you might also see warnings prefixed by Gtk-Message when you start a program that opens a window, such as turtlesim_node:

Gtk-Message: 13:49:17.364: Failed to load module "canberra-gtk-module"

Don’t worry about such warnings, they can be safely ignored.

3.2.2. What is in the turtlesim package?#

As explained before, packages can contain multiple executables. The turtlesim_node you ran in the previous steps is just one of the executables in the turtlesim package.

We can use the ros2 pkg command to inspect packages. For instance, to list all executable programs in a package we can use the ros2 pkg executables <package-name> syntax:

$ ros2 pkg executables turtlesim

The above command should return a list of turtlesim’s executables:

turtlesim draw_square
turtlesim mimic
turtlesim turtle_teleop_key
turtlesim turtlesim_node

Tip

If you test this on a clean system where ROS 2 has just been installed, but the turtlesim package is not yet available, then you may have to install it first with:

$ sudo apt update
$ sudo apt install ros-humble-turtlesim

Again, this should NOT be necessary if you use the environment provided by the RSP course!

You will learn more about ros2 pkg in a later section of the manual.

3.2.3. Running more programs from the turtlesim package#

The real power in ROS isn’t that it can run a program, it is that it can run lots of programs all at the same time, all talking together to control a robot, or multiple robots, all working together. To illustrate this let’s run a second ROS program that makes our little turtle move around.

To do this we’ll first open a new terminal (using CTRL-SHIFT-T). Next we’ll tell that terminal that we want to use ROS Humble by using the source command. Finally, we’ll run another program in the turtlesim package to draw a square. As we saw in the previous step where we inspected the turtlesim package, it also contains a turtle_teleop_key program.

Tip

If you want to run a program in a package, but forget the name of executables in a package, you actually don’t have to use ros2 pkg executables to find it first. There is a faster way!

Remember that after sourcing the ROS 2 environment, you can use TAB-completion to see suggestions for many common ROS commands, such as ros2 run <package-name>.

So, you can start typing ros2 run turtlesim (including space) and press the TAB key twice to see a list of suggestions, which for this particular command should be executables in the turtlesim package :)

If everything works you should have typed the following, and the following output should be visible:

$ ros2 run turtlesim turtle_teleop_key
Use arrow keys to move the turtle.
Use G|B|V|C|D|E|R|T keys to rotate to absolute orientations. 'F' to cancel a rotation.

As long as you have this terminal running the turtle_teleop_key program active (click on it with the mouse), you can now move and rotate the turtle using the arrow keys on your keyboard! You can also make the turtle move to a specific orientation using the keys listed on the second line of the output (G, B, etc.).

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, like this:

image

Note

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.

It is worth noting that you can stop any ROS program by pressing the Ctrl and C keys at the same time in the terminal; we call this CTRL-C (note that CTRL-SHIFT-C and CTRL-SHIFT-V are responsible for copy and paste in a Linux terminal). Feel free to try it out. Start and stop the programs, and then restart them before moving on.