Installing and Configuring Your ROS Environment

Description: This tutorial walks you through installing ROS and setting up the ROS environment on your
computer.
Tutorial Level: BEGINNER
Next Tutorial: Navigating the ROS Filesystem

Contents
1. Install ROS
2. Managing Your Environment
3. Create a ROS Workspace

Install ROS
Before starting these tutorials please complete installation as described in the ROS installation instructions.
Note: If you installed ROS from a package manager like apt, then those packages will not be write
accessible and should not be edited by you the user. When working with ROS packages from source or when
creating a new ROS package, you should always work in a directory that you have access to, like your home
folder.

Managing Your Environment

During the installation of ROS, you will see that you are prompted to source one of several setup.*sh files,
or even add this 'sourcing' to your shell startup script. This is required because ROS relies on the notion of
combining spaces using the shell environment. This makes developing against different versions of ROS or
against different sets of packages easier.
If you are ever having problems finding or using your ROS packages make sure that you have your
environment properly setup. A good way to check is to ensure that environment variables like ROS_ROOT
and ROS_PACKAGE_PATH are set:
$ printenv | grep ROS

If they are not then you might need to 'source' some setup.*sh files.
Environment setup files are generated for you, but can come from different places:

ROS packages installed with package managers provide setup.*sh files

rosbuild workspaces provide setup.*sh files using tools like rosws

Setup.*sh files are created as a by-product of building or installing catkin packages

Note: Throughout the tutorials you will see references to rosbuild and catkin. These are the two available
methods for organizing and building your ROS code. Generally, rosbuild is easy to use and simple, where as
catkin uses more standard CMake conventions, so it is more sophisticated, but provides more flexibility

especially for people wanting to integrate external code bases or who want to release their software. For a
full break down visit catkin or rosbuild.
If you just installed ROS from apt on Ubuntu then you will have setup.*sh files in '/opt/ros/<distro>/',
and you could source them like so:
# source /opt/ros/<distro>/setup.bash

Using the short name of your ROS distribution instead of <distro>

If you installed ROS Indigo, that would be:

$ source /opt/ros/indigo/setup.bash

You will need to run this command on every new shell you open to have access to the ros commands, unless
you add this line to your .bashrc. This process allows you to install several ROS distributions (e.g. fuerte and
groovy) on the same computer and switch between them.
On other platforms you will find these setup.*sh files where ever you installed ROS to.

Create a ROS Workspace

These instructions are for ROS Groovy and later. For ROS Fuerte and earlier, select rosbuild.
Let's create a catkin workspace:
$ mkdir -p ~/catkin_ws/src
$ cd ~/catkin_ws/src
$ catkin_init_workspace

Even though the workspace is empty (there are no packages in the 'src' folder, just a single CMakeLists.txt
link) you can still "build" the workspace:
$ cd ~/catkin_ws/
$ catkin_make

The catkin_make command is a convenience tool for working with catkin workspaces. If you look in your
current directory you should now have a 'build' and 'devel' folder. Inside the 'devel' folder you can see that
there are now several setup.*sh files. Sourcing any of these files will overlay this workspace on top of your
environment. To understand more about this see the general catkin documentation: catkin. Before continuing
source your new setup.*sh file:
$ source devel/setup.bash

To make sure your workspace is properly overlayed by the setup script, make sure ROS_PACKAGE_PATH
environment variable includes the directory you're in.
$ echo $ROS_PACKAGE_PATH
/home/youruser/catkin_ws/src:/opt/ros/indigo/share:/opt/ros/indigo/stacks

Navigating the ROS Filesystem

Description: This tutorial introduces ROS filesystem concepts, and covers using the roscd,
rosls, and rospack commandline tools.
Tutorial Level: BEGINNER
Next Tutorial: Creating a ROS package

Contents
1. Prerequisites
2. Quick Overview of Filesystem Concepts
3. Filesystem Tools
1. Using rospack
2. Using roscd
3. roscd log
4. Using rosls
5. Tab Completion
4. Review

Prerequisites
For this tutorial we will inspect a package in ros-tutorials, please install it using
$ sudo apt-get install ros-<distro>-ros-tutorials

Replace '<distro>' with the name of your ROS distribution (e.g. hydro, groovy, electric, fuerte etc.)
Quick Overview of Filesystem Concepts
Packages: Packages are the software organization unit of ROS code. Each package can contain
libraries, executables, scripts, or other artifacts.

Show

Manifest (package.xml): A manifest is a description of a package. Its serves to define dependencies

between packages and to capture meta information about the package like version, maintainer,
license, etc...
note about stacks

Filesystem Tools
Code is spread across many ROS packages. Navigating with command-line tools such as ls and cd can be
very tedious which is why ROS provides tools to help you.
Using rospack

rospack allows you to get information about packages. In this tutorial, we are only going to cover the find
option, which returns the path to package.
Usage:
# rospack find [package_name]

Example:

$ rospack find roscpp

Would return:

If you

YOUR_INSTALL_PATH/share/roscpp
installed ROS from apt on Ubuntu Linux

you would see exactly:

/opt/ros/indigo/share/roscpp

Using roscd
roscd

is part of the rosbash suite. It allows you to change directory (cd) directly to a package or a stack.

Usage:
# roscd [locationname[/subdir]]

Run this example:

$ roscd roscpp

To verify that we have changed to the roscpp package directory. Now let's print the working directory using
the Unix command pwd:
$ pwd

You should see:

YOUR_INSTALL_PATH/share/roscpp
can see that YOUR_INSTALL_PATH/share/roscpp

You
previous example.

is the same path that rospack find gave in the

Note that roscd, like other ROS tools, will only find ROS packages that are within the directories listed in
your ROS_PACKAGE_PATH. To see what is in your ROS_PACKAGE_PATH, type:
$ echo $ROS_PACKAGE_PATH

Your ROS_PACKAGE_PATH should contain a list of directories where you have ROS packages separated
by colons. A typical ROS_PACKAGE_PATH might look like this:

/opt/ros/indigo/base/install/share:/opt/ros/indigo/base/install/stacks

Similarly to other environment paths, you can add additional directories to your ROS_PACKAGE_PATH,
with each path separated by a colon ':'.
Subdirectories

roscd can also move to a subdirectory of a package or stack.

Try:
$ roscd roscpp/cmake
$ pwd

You should see:

YOUR_INSTALL_PATH/share/roscpp/cmake

roscd log

will take you to the folder where ROS stores log files. Note that if you have not run any ROS
programs yet, this will yield an error saying that it does not yet exist.
roscd log

If you have run some ROS program before, try:

$ roscd log

Using rosls

rosls is part of the rosbash suite. It allows you to ls directly in a package by name rather than by absolute
path.
Usage:
# rosls [locationname[/subdir]]

Example:
$ rosls roscpp_tutorials

Would return:

cmake launch package.xml

srv

Tab Completion

It can get tedious to type out an entire package name. In the previous example, roscpp_tutorials is a
fairly long name. Luckily, some ROS tools support TAB completion.
Start by typing:
# roscd roscpp_tut<<< now push the TAB key >>>

After pushing the TAB key, the command line should fill out the rest:
$ roscd roscpp_tutorials/
This works because roscpp_tutorials

is currently the only ROS package that starts with roscpp_tut.

Now try typing:

# roscd tur<<< now push the TAB key >>>

After pushing the TAB key, the command line should fill out as much as possible:
$ roscd turtle

However, in this case there are multiple packages that begin with turtle. Try typing TAB another time.
This should display all the ROS packages that begin with turtle:

turtle_actionlib/

turtlesim/

turtle_tf/

On the command line you should still have:

$ roscd turtle
Now type a s after turtle

and then push TAB:

# roscd turtles<<< now push the TAB key >>>

Since there is only one package that starts with turtles,

you should see:

$ roscd turtlesim/

Review
You may have noticed a pattern with the naming of the ROS tools:

rospack = ros + pack(age)

roscd = ros + cd

rosls = ros + ls

Creating a ROS Package

Description: This tutorial covers using roscreate-pkg or catkin to create a new package, and
rospack to list package dependencies.
Tutorial Level: BEGINNER
Next Tutorial: Building a ROS package

Contents
1. What makes up a catkin Package?
2. Packages in a catkin Workspace
3. Creating a catkin Package
4. Building a catkin workspace and sourcing the setup file
5. package dependencies
1. First-order dependencies
2. Indirect dependencies
6. Customizing Your Package
1. Customizing the package.xml
1. description tag
2. maintainer tags
3. license tags
4. dependencies tags
5. Final package.xml
2. Customizing the CMakeLists.txt
What makes up a catkin Package?

For a package to be considered a catkin package it must meet a few requirements:

The package must contain a catkin compliant package.xml file

o

That package.xml file provides meta information about the package

The package must contain a CMakeLists.txt which uses catkin. Catkin metapackages must have a
boilerplate CMakeLists.txt file.

There can be no more than one package in each folder

o

This means no nested packages nor multiple packages sharing the same
directory

The simplest possible package might look like this:

my_package/
CMakeLists.txt
package.xml

Packages in a catkin Workspace

The recommended method of working with catkin packages is using a catkin workspace, but you can also
build catkin packages standalone. A trivial workspace might look like this:

workspace_folder/
src/
CMakeLists.txt
package_1/
CMakeLists.txt
package.xml
...
package_n/
CMakeLists.txt
package.xml

-- WORKSPACE
-- SOURCE SPACE
-- 'Toplevel' CMake file, provided by catkin
-- CMakeLists.txt file for package_1
-- Package manifest for package_1

-- CMakeLists.txt file for package_n

-- Package manifest for package_n

Before continuing with this tutorial create an empty catkin workspace by following the Creating a
workspace for catkin tutorial.
Creating a catkin Package

This tutorial will demonstrate how to use the catkin_create_pkg script to create a new catkin package, and
what you can do with it after it has been created.
First change to the source space directory of the catkin workspace you created in the Creating a Workspace
for catkin tutorial:
# You should have created this in the Creating a Workspace Tutorial
$ cd ~/catkin_ws/src
Now use the catkin_create_pkg script to create a new package called 'beginner_tutorials'

which depends

on std_msgs, roscpp, and rospy:

$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp
This will create a beginner_tutorials folder which contains a package.xml and

a CMakeLists.txt, which

have been partially filled out with the information you gave catkin_create_pkg.
requires that you give it a package_name and optionally a list of dependencies on
which that package depends:
catkin_create_pkg

# This is an example, do not try to run this

# catkin_create_pkg <package_name> [depend1] [depend2] [depend3]
catkin_create_pkg also has more advanced functionalities which is described in

catkin/commands/catkin_create_pkg.
Building a catkin workspace and sourcing the setup file

Now you need to build the packages in the catkin workspace:

$ cd ~/catkin_ws
$ catkin_make

After the workspace has been built it has created a similar structure in the devel subfolder as you usually
find under /opt/ros/$ROSDISTRO_NAME.

To add the workspace to your ROS environment you need to source the generated setup file:
$ . ~/catkin_ws/devel/setup.bash

package dependencies

First-order dependencies
When using catkin_create_pkg earlier, a few package dependencies were provided. These first-order
dependencies can now be reviewed with the rospack tool.
(Jan 9, 2013) There is a bug reported and already fixed in rospack in groovy, which takes sometime until the
change gets reflected on your computer. If you see a similar issue like this with the next command, you can
skip to the next command.
$ rospack depends1 beginner_tutorials
std_msgs
rospy
roscpp
As you can see, rospack lists the same dependencies

that were used as arguments when running

catkin_create_pkg. These dependencies for a package are stored in the package.xml file:
$ roscd beginner_tutorials
$ cat package.xml
<package>
...

<buildtool_depend>catkin</buildtool_depend>

<build_depend>roscpp</build_depend>

<build_depend>rospy</build_depend>

<build_depend>std_msgs</build_depend>
...
</package>

Indirect dependencies
In many cases, a dependency will also have its own dependencies. For instance, rospy has other
dependencies.
(Jan 9, 2013) There is a bug reported and already fixed in rospack in groovy, which takes sometime until the
change gets reflected on your computer. If you see a similar issue like this with the next command, you can
skip to the next command.
$ rospack depends1 rospy
genpy
rosgraph
rosgraph_msgs
roslib
std_msgs

A package can have quite a few indirect dependencies. Luckily rospack can recursively determine all nested
dependencies.
$ rospack depends beginner_tutorials
cpp_common
rostime
roscpp_traits
roscpp_serialization
genmsg
genpy
message_runtime
rosconsole
std_msgs

rosgraph_msgs
xmlrpcpp
roscpp
rosgraph
catkin
rospack
roslib
rospy

Customizing Your Package

This part of the tutorial will look at each file generated by catkin_create_pkg and describe, line by line, each
component of those files and how you can customize them for your package.
Customizing the package.xml
The generated package.xml should be in your new package. Now lets go through the new package.xml and
touch up any elements that need your attention.
description tag

First update the description tag:

Toggle line numbers
5

<description>The beginner_tutorials package</description>

Change the description to anything you like, but by convention the first sentence should be short while
covering the scope of the package. If it is hard to describe the package in a single sentence then it might
need to be broken up.
maintainer tags

Next comes the maintainer tag:

Toggle line numbers
7
8
9
10

<!-- One maintainer tag required, multiple allowed, one person per tag -->
<!-- Example: -->
<!-- <maintainer email="jane.doe@example.com">Jane Doe</maintainer> -->
<maintainer email="user@todo.todo">user</maintainer>

This is a required and important tag for the package.xml because it lets others know who to contact about the
package. At least one maintainer is required, but you can have many if you like. The name of the maintainer
goes into the body of the tag, but there is also an email attribute that should be filled out:
Toggle line numbers
7

<maintainer email="you@yourdomain.tld">Your Name</maintainer>

license tags

Next is the license tag, which is also required:

Toggle line numbers
12
13
14
15

<!-- One license tag required, multiple allowed, one license per tag -->
<!-- Commonly used license strings: -->
<!-BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, LGPLv3 -->
<license>TODO</license>

You should choose a license and fill it in here. Some common open source licenses are BSD, MIT, Boost
Software License, GPLv2, GPLv3, LGPLv2.1, and LGPLv3. You can read about several of these at the
Open Source Initiative. For this tutorial we'll use the BSD license because the rest of the core ROS
components use it already:
Toggle line numbers
8

<license>BSD</license>

dependencies tags

The next set of tags describe the dependencies of your package. The dependencies are split into
build_depend, buildtool_depend, run_depend, test_depend. For a more detailed explanation of these
tags see the documentation about Catkin Dependencies. Since we passed std_msgs, roscpp, and rospy as
arguments to catkin_create_pkg, the dependencies will look like this:
Toggle line numbers
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

All of

<!-- The *_depend tags are used to specify dependencies -->

<!-- Dependencies can be catkin packages or system dependencies -->
<!-- Examples: -->
<!-- Use build_depend for packages you need at compile time: -->
<!-<build_depend>genmsg</build_depend> -->
<!-- Use buildtool_depend for build tool packages: -->
<!-<buildtool_depend>catkin</buildtool_depend> -->
<!-- Use run_depend for packages you need at runtime: -->
<!-<run_depend>python-yaml</run_depend> -->
<!-- Use test_depend for packages you need only for testing: -->
<!-<test_depend>gtest</test_depend> -->
<buildtool_depend>catkin</buildtool_depend>
<build_depend>roscpp</build_depend>
<build_depend>rospy</build_depend>
<build_depend>std_msgs</build_depend>
our listed dependencies have been added as a build_depend for us, in addition to the default

on catkin. In this case we want all of our specified dependencies to be available at build
and run time, so we'll add a run_depend tag for each of them as well:
buildtool_depend

Toggle line numbers

12
13
14
15
16
17
18
19
20

<buildtool_depend>catkin</buildtool_depend>
<build_depend>roscpp</build_depend>
<build_depend>rospy</build_depend>
<build_depend>std_msgs</build_depend>
<run_depend>roscpp</run_depend>
<run_depend>rospy</run_depend>
<run_depend>std_msgs</run_depend>

Final package.xml

As you can see the final package.xml, without comments and unused tags, is much more concise:
Toggle line numbers
1 <?xml version="1.0"?>
2 <package>
3
<name>beginner_tutorials</name>
4
<version>0.1.0</version>
5
<description>The beginner_tutorials package</description>
6
7
<maintainer email="you@yourdomain.tld">Your Name</maintainer>
8
<license>BSD</license>
9
<url type="website">http://wiki.ros.org/beginner_tutorials</url>
10
<author email="you@yourdomain.tld">Jane Doe</author>
11
12
<buildtool_depend>catkin</buildtool_depend>
13
14
<build_depend>roscpp</build_depend>
15
<build_depend>rospy</build_depend>
16
<build_depend>std_msgs</build_depend>
17
18
<run_depend>roscpp</run_depend>
19
<run_depend>rospy</run_depend>
20
<run_depend>std_msgs</run_depend>
21
22 </package>

Customizing the CMakeLists.txt

Now that the package.xml, which contains meta information, has been tailored to your package, you are
ready to move on in the tutorials. The CMakeLists.txt file created by catkin_create_pkg will be covered in
the later tutorials about building ROS code.
Now that you've made a new ROS package, let's build our ROS package.

Building a ROS Package

Description: This tutorial covers the toolchain to build a package.
Tutorial Level: BEGINNER
Next Tutorial: Understanding ROS Nodes

Contents
1. Building Packages
1. Using catkin_make
2. Building Your Package

Building Packages
As long as all of the system dependencies of your package are installed, we can now build your new
package.
Note: If you installed ROS using apt or some other package manager, you should already have all of your
dependencies.
Before continuing remember to source your environment setup file if you have not already. On Ubuntu it
would be something like this:
$ source /opt/ros/%YOUR_ROS_DISTRO%/setup.bash
$ source /opt/ros/indigo/setup.bash

(For Indigo for instance)

Using catkin_make

catkin_make is a command line tool which adds some convenience to the standard catkin workflow. You can
imagine that catkin_make combines the calls to cmake and make in the standard CMake workflow.
Usage:
# In a catkin workspace
$ catkin_make [make_targets] [-DCMAKE_VARIABLES=...]

For people who are unfamiliar with the standard CMake workflow, it breaks down as follows:
Note: If you run the below commands it will not work, as this is just an example of how CMake generally
works.
#
$
$
$
$
$

In a CMake project
mkdir build
cd build
cmake ..
make
make install # (optionally)

This process is run for each CMake project. In contrast catkin projects can be built together in workspaces.
Building zero to many catkin packages in a workspace follows this work flow:
# In a catkin workspace
$ catkin_make
$ catkin_make install # (optionally)

The above commands will build any catkin projects found in the src folder. This follows the
recommendations set by REP128. If your source code is in a different place, say my_src then you would call
catkin_make like this:
Note: If you run the below commands it will not work, as the directory my_src does not exist.
# In a catkin workspace
$ catkin_make --source my_src
$ catkin_make install --source my_src

# (optionally)

For more advanced uses of catkin_make see the documentation: catkin/commands/catkin_make

Building Your Package

For readers of this page who are about to build your own codes, please also take a look at later tutorial (C+
+)/(Python) since you may need to modify CMakeLists.txt.
You should already have a catkin workspace and a new catkin package called beginner_tutorials from
the previous tutorial, Creating a Package. Go into the catkin workspace if you are not already there and look
in the src folder:
$ cd ~/catkin_ws/
$ ls src
beginner_tutorials/

CMakeLists.txt@
a folder called beginner_tutorials

You should see that there is

which you created with catkin_create_pkg
in the previous tutorial. We can now build that package using catkin_make:
$ catkin_make

You should see a lot of output from cmake and them make, which should be similar to this:

Base path: /home/user/catkin_ws

Source space: /home/user/catkin_ws/src
Build space: /home/user/catkin_ws/build
Devel space: /home/user/catkin_ws/devel
Install space: /home/user/catkin_ws/install
####
#### Running command: "cmake /home/user/catkin_ws/src
-DCATKIN_DEVEL_PREFIX=/home/user/catkin_ws/devel
-DCMAKE_INSTALL_PREFIX=/home/user/catkin_ws/install" in
"/home/user/catkin_ws/build"
####
-- The C compiler identification is GNU 4.2.1
-- The CXX compiler identification is Clang 4.0.0
-- Checking whether C compiler has -isysroot
-- Checking whether C compiler has -isysroot - yes
-- Checking whether C compiler supports OSX deployment target flag
-- Checking whether C compiler supports OSX deployment target flag - yes
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Using CATKIN_DEVEL_PREFIX: /tmp/catkin_ws/devel
-- Using CMAKE_PREFIX_PATH: /opt/ros/indigo
-- This workspace overlays: /opt/ros/indigo
-- Found PythonInterp: /usr/bin/python (found version "2.7.1")

-- Found PY_em: /usr/lib/python2.7/dist-packages/em.pyc

-- Found gtest: gtests will be built
-- catkin 0.5.51
-- BUILD_SHARED_LIBS is on
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~ traversing packages in topological order:
-- ~~ - beginner_tutorials
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- +++ add_subdirectory(beginner_tutorials)
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/catkin_ws/build
####
#### Running command: "make -j4" in "/home/user/catkin_ws/build"
####

Note that catkin_make first displays what paths it is using for each of the 'spaces'. The spaces are described
in the REP128 and by documentation about catkin workspaces on the wiki: catkin/workspaces. The
important thing to notice is that because of these default values several folders have been created in your
catkin workspace. Take a look with ls:
$ ls
build
devel
src
The build folder

is the default location of the build space and is where cmake and make are called to
configure and build your packages. The devel folder is the default location of the devel space, which is
where your executables and libraries go before you install your packages.
Now that you have built your ROS package let's talk more about ROS Nodes.

Understanding ROS Nodes

Description: This tutorial introduces ROS graph concepts and discusses the use of roscore,
rosnode, and rosrun commandline tools.
Tutorial Level: BEGINNER
Next Tutorial: Understanding ROS topics

Contents
1. Prerequisites
2. Quick Overview of Graph Concepts
3. Nodes
4. Client Libraries
5. roscore
6. Using rosnode
7. Using rosrun
8. Review

Prerequisites
For this tutorial we will use a lightweight simulator, please install it using
$ sudo apt-get install ros-<distro>-ros-tutorials

Replace '<distro>' with the name of your ROS distribution (e.g. hydro, groovy, electric, fuerte etc.)
Quick Overview of Graph Concepts
Nodes: A node is an executable that uses ROS to communicate with other nodes.

Messages: ROS data type used when subscribing or publishing to a topic.

Topics: Nodes can publish messages to a topic as well as subscribe to a topic to receive messages.

Master: Name service for ROS (i.e. helps nodes find each other)

rosout: ROS equivalent of stdout/stderr

roscore: Master + rosout + parameter server (parameter server will be introduced later)

Nodes
A node really isn't much more than an executable file within a ROS package. ROS nodes use a ROS client
library to communicate with other nodes. Nodes can publish or subscribe to a Topic. Nodes can also provide
or use a Service.
Client Libraries
ROS client libraries allow nodes written in different programming languages to communicate:

rospy = python client library

roscpp = c++ client library

roscore
roscore

is the first thing you should run when using ROS.

Please run:
$ roscore

You will see something similar to:

... logging to ~/.ros/log/9cf88ce4-b14d-11df-8a75-00251148e8cf/roslaunchmachine_name-13039.log

Checking log directory for disk usage. This may take awhile.
Press Ctrl-C to interrupt
Done checking log file disk usage. Usage is <1GB.

started roslaunch server http://machine_name:33919/

ros_comm version 1.4.7

SUMMARY
========

PARAMETERS

* /rosversion

* /rosdistro

NODES

auto-starting new master

process[master]: started with pid [13054]
ROS_MASTER_URI=http://machine_name:11311/

setting /run_id to 9cf88ce4-b14d-11df-8a75-00251148e8cf

process[rosout-1]: started with pid [13067]
started core service [/rosout]
roscore does not initialize, you probably have a network configuration issue.

If
Machine Configuration

See Network Setup - Single

If roscore does not initialize and sends a message about lack of permissions, probably the ~/.ros folder is
owned by root, change recursively the ownership of that folder with:
$ sudo chown -R <your_username> ~/.ros

Using rosnode
Open up a new terminal, and let's use rosnode to see what running roscore did...
Note: When opening a new terminal your environment is reset and your ~/.bashrc file is sourced. If you
have trouble running commands like rosnode then you might need to add some environment setup files to
your ~/.bashrc or manually re-source them.
displays information about the ROS nodes that are currently running. The rosnode list
command lists these active nodes:
rosnode

$ rosnode list

You will see:

/rosout

This showed us that there is only one node running: rosout. This is always running as it collects and logs
nodes' debugging output.
The rosnode info command returns information about a specific node.
$ rosnode info /rosout

This gave us some more information about rosout, such as the fact that it publishes /rosout_agg.

-----------------------------------------------------------------------Node [/rosout]
Publications:
* /rosout_agg [rosgraph_msgs/Log]
Subscriptions:
* /rosout [unknown type]
Services:
* /rosout/set_logger_level
* /rosout/get_loggers

contacting node http://machine_name:54614/ ...

Pid: 5092
Now, let's see some more nodes. For this, we're going to use rosrun

to bring up another node.

Using rosrun
rosrun allows you to use the package name to directly run a node within a package (without having to know
the package path).
Usage:
$ rosrun [package_name] [node_name]

So now we can run the turtlesim_node in the turtlesim package.

Then, in a new terminal:
$ rosrun turtlesim turtlesim_node

You will see the turtlesim window:

NOTE: The turtle may look different in your turtlesim window. Don't worry about it - there are many types
of turtle and yours is a surprise!

In a new terminal:
$ rosnode list

You will see something similar to:

/rosout
/turtlesim

One powerful feature of ROS is that you can reassign Names from the command-line.
Close the turtlesim window to stop the node (or go back to the rosrun turtlesim terminal and use ctrlC). Now let's re-run it, but this time use a Remapping Argument to change the node's name:
$ rosrun turtlesim turtlesim_node __name:=my_turtle
Now, if we go back and use rosnode list:
$ rosnode list

You will see something similar to:

/rosout
/my_turtle

Note: If you still see /turtlesim in the list, it might mean that you stopped the node in the terminal using
ctrl-C instead of closing the window, or that you don't have the $ROS_HOSTNAME environment variable
defined as described in Network Setup - Single Machine Configuration. You can try cleaning the rosnode list
with: $ rosnode cleanup
We see our new /my_turtle node. Let's use another rosnode command, ping, to test that it's up:
$ rosnode ping my_turtle
rosnode: node is [/my_turtle]
pinging /my_turtle with a timeout of 3.0s
xmlrpc reply from http://aqy:42235/
time=1.152992ms
xmlrpc reply from http://aqy:42235/
time=1.120090ms
xmlrpc reply from http://aqy:42235/
time=1.700878ms
xmlrpc reply from http://aqy:42235/
time=1.127958ms

Review
What was covered:

roscore = ros+core : master (provides name service for ROS) + rosout (stdout/stderr) +
parameter server (parameter server will be introduced later)

rosnode = ros+node : ROS tool to get information about a node.

rosrun = ros+run : runs a node from a given package.

Now that you understand how ROS nodes work, let's look at how ROS topics work. Also, feel free to press
Ctrl-C to stop turtlesim_node.

Understanding ROS Topics

Description: This tutorial introduces ROS topics as well as using the rostopic and rqt_plot
commandline tools.
Tutorial Level: BEGINNER
Next Tutorial: Understanding ROS services and parameters

Contents
1.
1. Setup
1. roscore
2. turtlesim
3. turtle keyboard teleoperation
2. ROS Topics
1. Using rqt_graph
2. Introducing rostopic
3. Using rostopic echo
4. Using rostopic list
3. ROS Messages
1. Using rostopic type
4. rostopic continued
1. Using rostopic pub
2. Using rostopic hz
5. Using rqt_plot
2. Video Tutorial

Setup
roscore

Let's start by making sure that we have roscore running, in a new terminal:
$ roscore

If you left roscore running from the last tutorial, you may get the error message:

roscore cannot run as another roscore/master is already running.

Please kill other roscore/master processes before relaunching

This is fine. Only one roscore needs to be running.

turtlesim

For this tutorial we will also use turtlesim. Please run in a new terminal:
$ rosrun turtlesim turtlesim_node

turtle keyboard teleoperation

We'll also need something to drive the turtle around with. Please run in a new terminal:
$ rosrun turtlesim turtle_teleop_key
[ INFO] 1254264546.878445000: Started node [/teleop_turtle], pid [5528], bound on
[aqy], xmlrpc port [43918], tcpros port [55936], logging to
[~/ros/ros/log/teleop_turtle_5528.log], using [real] time
Reading from keyboard
-------------------------- Use arrow keys to move the turtle.

Now you can use the arrow keys of the keyboard to drive the turtle around. If you can not drive the turtle
select the terminal window of the turtle_teleop_key to make sure that the keys that you type are recorded.

Now that you can drive your turtle around, let's look at what's going on behind the scenes.
ROS Topics
The turtlesim_node and the turtle_teleop_key node are communicating with each other over a ROS
Topic. turtle_teleop_key is publishing the key strokes on a topic, while turtlesim subscribes to the
same topic to receive the key strokes. Let's use rqt_graph which shows the nodes and topics currently
running.
Note: If you're using electric or earlier, rqt is not available. Use rxgraph instead.
Using rqt_graph

creates a dynamic graph of what's going on in the system. rqt_graph is part of the rqt package.
Unless you already have it installed, run:
rqt_graph

$ sudo apt-get install ros-<distro>-rqt

$ sudo apt-get install ros-<distro>-rqt-common-plugins

replacing <distro> with the name of your ROS distribution (fuerte, groovy, etc.)
In a new terminal:
$ rosrun rqt_graph rqt_graph

You will see something similar to:

If you place your mouse over /turtle1/command_velocity it will highlight the ROS nodes (here blue and
green) and topics (here red). As you can see, the turtlesim_node and the turtle_teleop_key nodes are
communicating on the topic named /turtle1/command_velocity.

Introducing rostopic

The rostopic tool allows you to get information about ROS topics.
You can use the help option to get the available sub-commands for rostopic
$ rostopic -h
rostopic
rostopic
rostopic
rostopic
rostopic
rostopic

bw
echo
hz
list
pub
type

display bandwidth used by topic

print messages to screen
display publishing rate of topic
print information about active topics
publish data to topic
print topic type

Let's use some of these topic sub-commands to examine turtlesim.

Using rostopic echo
rostopic echo

shows the data published on a topic.

Usage:
rostopic echo [topic]

Let's look at the command velocity data published by the turtle_teleop_key node.
For ROS Hydro and later, this data is published on the /turtle1/cmd_vel topic. In a new terminal, run:
$ rostopic echo /turtle1/cmd_vel

For ROS Groovy and earlier, this data is published on the /turtle1/command_velocity topic. In a new
terminal, run:
$ rostopic echo /turtle1/command_velocity

You probably won't see anything happen because no data is being published on the topic. Let's make
turtle_teleop_key publish data by pressing the arrow keys. Remember if the turtle isn't moving you
need to select the turtle_teleop_key terminal again.

For ROS Hydro and later, you should now see the following when you press the up key:
linear:
x: 2.0
y: 0.0
z: 0.0
angular:
x: 0.0
y: 0.0
z: 0.0
--linear:
x: 2.0
y: 0.0
z: 0.0
angular:
x: 0.0
y: 0.0
z: 0.0
---

For ROS Groovy and earlier, you should now see the following when you press the up key:
--linear: 2.0
angular: 0.0
--linear: 2.0
angular: 0.0
--linear: 2.0
angular: 0.0
--linear: 2.0
angular: 0.0
--linear: 2.0
angular: 0.0

Now let's look at rqt_graph again. Press the refresh button in the upper-left to show the new node. As you
can see rostopic echo, shown here in red, is now also subscribed to the turtle1/command_velocity
topic.

Using rostopic list

rostopic list

returns a list of all topics currently subscribed to and published.

Let's figure out what argument the list sub-command needs. In a new terminal run:
$ rostopic list -h
Usage: rostopic list [/topic]

Options:

-h, --help
show this help message and exit

-b BAGFILE, --bag=BAGFILE

list topics in .bag file


-v, --verbose

-p

-s
For rostopic list use the

list full details about each topic

list only publishers
list only subscribers

verbose option:

$ rostopic list -v

This displays a verbose list of topics to publish to and subscribe to and their type.

Published topics:
* /turtle1/color_sensor [turtlesim/Color] 1 publisher
* /turtle1/command_velocity [turtlesim/Velocity] 1 publisher
* /rosout [roslib/Log] 2 publishers
* /rosout_agg [roslib/Log] 1 publisher
* /turtle1/pose [turtlesim/Pose] 1 publisher
Subscribed topics:
* /turtle1/command_velocity [turtlesim/Velocity] 1 subscriber
* /rosout [roslib/Log] 1 subscriber

ROS Messages
Communication on topics happens by sending ROS messages between nodes. For the publisher
(turtle_teleop_key) and subscriber (turtlesim_node) to communicate, the publisher and subscriber
must send and receive the same type of message. This means that a topic type is defined by the message
type published on it. The type of the message sent on a topic can be determined using rostopic type.
Using rostopic type
rostopic type

returns the message type of any topic being published.

Usage:
rostopic type [topic]

For ROS Hydro and later,

Try:
$ rostopic type /turtle1/cmd_vel
o

You should get:

geometry_msgs/Twist

We can look at the details of the message using rosmsg:

$ rosmsg show geometry_msgs/Twist
o geometry_msgs/Vector3 linear
o
float64 x
o
float64 y
o
float64 z
o geometry_msgs/Vector3 angular
o
float64 x
o
float64 y
o
float64 z

For ROS Groovy and earlier,

Try:
$ rostopic type /turtle1/command_velocity
o

You should get:

turtlesim/Velocity

We can look at the details of the message using rosmsg:

$ rosmsg show turtlesim/Velocity

o
o

float32 linear
float32 angular

Now that we know what type of message turtlesim expects, we can publish commands to our turtle.
rostopic continued
Now that we have learned about ROS messages, let's use rostopic with messages.
Using rostopic pub
rostopic pub

publishes data on to a topic currently advertised.

Usage:
rostopic pub [topic] [msg_type] [args]

For ROS Hydro and later, example:

$ rostopic pub -1 /turtle1/cmd_vel geometry_msgs/Twist -- '[2.0, 0.0, 0.0]' '[0.0, 0.0,
1.8]'

For ROS Groovy and earlier, example:

$ rostopic pub -1 /turtle1/command_velocity turtlesim/Velocity

-- 2.0

1.8

The previous command will send a single message to turtlesim telling it to move with an linear velocity of
2.0, and an angular velocity of 1.8 .

This is a pretty complicated example, so lets look at each argument in detail.

For ROS Hydro and later,

This command will publish messages to a given topic:

rostopic pub

This option (dash-one) causes rostopic to only publish one message then exit:
-1

This is the name of the topic to publish to:

/turtle1/cmd_vel

This is the message type to use when publishing to the topic:

geometry_msgs/Twist

This option (double-dash) tells the option parser that none of the following arguments is an option.
This is required in cases where your arguments have a leading dash -, like negative numbers.

As noted before, a geometry_msgs/Twist msg has two vectors of three floating point elements each:
linear and angular. In this case, '[2.0, 0.0, 0.0]' becomes the linear value with x=2.0,
y=0.0, and z=0.0, and '[0.0, 0.0, 1.8]' is the angular value with x=0.0, y=0.0, and z=1.8.
These arguments are actually in YAML syntax, which is described more in the YAML command line
documentation.
'[2.0, 0.0, 0.0]' '[0.0, 0.0, 1.8]'

For ROS Groovy and earlier,

This command will publish messages to a given topic:

rostopic pub

This option (dash-one) causes rostopic to only publish one message then exit:
-1

This is the name of the topic to publish to:

/turtle1/command_velocity

This is the message type to use when publishing to the topic:

turtlesim/Velocity

This option (double-dash) tells the option parser that none of the following arguments is an option.
This is required in cases where your arguments have a leading dash -, like negative numbers.
--

As noted before, a turtlesim/Velocity msg has two floating point elements : linear and angular. In
this case, 2.0 becomes the linear value, and 1.8 is the angular value. These arguments are actually
in YAML syntax, which is described more in the YAML command line documentation.
2.0 1.8

You may have noticed that the turtle has stopped moving; this is because the turtle requires a steady stream
of commands at 1 Hz to keep moving. We can publish a steady stream of commands using rostopic pub r command:
For ROS Hydro and later,

$ rostopic pub /turtle1/cmd_vel geometry_msgs/Twist -r 1 -- '[2.0, 0.0, 0.0]'

'[0.0, 0.0, -1.8]'

For ROS Groovy and earlier,

$ rostopic pub /turtle1/command_velocity turtlesim/Velocity -r 1 -- 2.0

This publishes the velocity commands at a rate of 1 Hz on the velocity topic.

-1.8

We can also look at what is happening in rqt_graph, The rostopic pub node (here in red) is communicating
with the rostopic echo node (here in green):

As you can see the turtle is running in a continuous circle. In a new terminal, we can use rostopic echo to
see the data published by our turtlesim:
Using rostopic hz
rostopic hz

reports the rate at which data is published.

Usage:
rostopic hz [topic]
Let's see how fast the turtlesim_node

is publishing /turtle1/pose:

$ rostopic hz /turtle1/pose

You will see:

subscribed to [/turtle1/pose]
average rate: 59.354
min: 0.005s max: 0.027s
average rate: 59.459
min: 0.005s max: 0.027s
average rate: 59.539
min: 0.004s max: 0.030s
average rate: 59.492
min: 0.004s max: 0.030s
average rate: 59.463
min: 0.004s max: 0.030s

std dev: 0.00284s window: 58

std dev: 0.00271s window: 118
std dev: 0.00339s window: 177
std dev: 0.00380s window: 237
std dev: 0.00380s window: 290

Now we can tell that the turtlesim is publishing data about our turtle at the rate of 60 Hz. We can also use
rostopic type in conjunction with rosmsg show to get in depth information about a topic:
For ROS Hydro and later,

$ rostopic type /turtle1/cmd_vel | rosmsg show

For ROS Groovy and earlier,

$ rostopic type /turtle1/command_velocity | rosmsg show

that we've examined the topics using rostopic let's use another tool to

Now
our turtlesim:

look at the data published by

Using rqt_plot
Note: If you're using electric or earlier, rqt is not available. Use rxplot instead.
displays a scrolling time plot of the data published on topics. Here we'll use rqt_plot to plot the
data being published on the /turtle1/pose topic. First, start rqt_plot by typing
rqt_plot

$ rosrun rqt_plot rqt_plot

in a new terminal. In the new window that should pop up, a text box in the upper left corner gives you the
ability to add any topic to the plot. Typing /turtle1/pose/x will highlight the plus button, previously
disabled. Press it and repeat the same procedure with the topic /turtle1/pose/y. You will now see the
turtle's x-y location plotted in the graph.

Pressing the minus button shows a menu that allows you to hide the specified topic from the plot. Hiding
both the topics you just added and adding /turtle1/pose/theta will result in the plot shown in the next
figure.

That's it for this section, use Ctrl-C to kill the rostopic terminals but keep your turtlesim running.
Now that you understand how ROS topics work, let's look at how services and parameters work.