Revision as of 14:22, 19 December 2012

About ROS in general

ROS (Robot Operating System) is an open-source framework for the creation of software for robots. It is a very interesting tool, since it promises to take care of many of the lower-level issues that make realizing the software for autonomous robots so difficult and time-consuming. By leaving such issues (e.g., communication among modules) to ROS, a researcher can focus on the more interesting high-level issues (e.g., perception). In the words of its creators:

"ROS provides libraries and tools to help software developers create robot applications. It provides hardware abstraction, device drivers, libraries, visualizers, message-passing, package management, and more."

ROS includes a large collection of packages that you can incorporate into your own system. A ROS package is a bundle of software dedicated to a single functionality (e.g., data acquisition from a laser scanner). Your own ROS-based applications will take the form of one or more ROS packages. If they can be useful to other people as well, once they are completed and tested such packages could become part of ROS: much of ROS was born in this way.

Though striving to be as easy-to-use as possible, ROS is a complex tool. This is unavoidable, as autonomous robots themselves are very complex systems. Before you can start writing your own ROS-based software, you have to devote a fair amount of time to studying how it works and how to use it. This HOWTO will help you to start using ROS as quickly as possible.

How to get ROS

This is probably the single aspect where the ROS team succeeded best in removing all the difficulties, even for beginners. Installing ROS is very simple: this webpage tells you how. At the moment ROS is only available for the Linux operating system, and support for other OSs is still experimental.

Installing additional packages

ROS packages are subdivided into groups called stacks. When you install ROS, not all the stacks are installed. You can see which of them are available on your PC by opening a terminal and running

rospack profile

Sometimes you need a ROS package that is not installed, i.e. that is not present in any of the installed stacks. For example, let's say that you need the driver for a Hokuyo laser range scanner. The best way to get it is to install the stack that includes the package. To know the name of such stack, you can go to the webpage dedicated to the package in the ROS wiki (so you need to know the name of the package). In our example the package is called hokuyo_node, and its webpage is this one. At the top of the package webpage, just under the name of the package, you will find the name of the stack it belongs to (and the name of the other packages of the stack) in the form

name_of_the_stack: name_of_package_1 / name_of_package_2 ...

In our example, the stack is called laser_drivers.

Now you can install the stack. As we said above, ROS is usually installed using the same tools used for all the other software available for your operating system. To install an additional ROS stack, you will use those same tools. For instance, in Ubuntu Linux you can use Ubuntu Software Center, Synaptic or (from the command-line) apt-get.

Generally the name of the software package corrisponding to a ROS stack is the name of the stack with additional information attached to identify what version of ROS it belongs to. For instance, if your version of ROS is the one called "electric", you will have to look for something called ros-electric-laser-drivers. If you are using apt-get you can install this software package (which, as we said, includes the ROS stack named laser_drivers) with

sudo apt-get install ros-electric-laser-drivers

(you will be asked for your administrative password).

Finally, sometimes the stack you are looking for is not available as a software package because it's experimental. In this case you can install its source code by following these instructions.

How to get information about ROS

The ROS website includes a good deal of information, structured as a wiki (just like AIRWiki). You are invited to use it heavily, and it's important that you learn to find things in it. That said, not always the information provided by the ROS wiki is very clear for someone who is not an expert in ROS, nor all topics are equally covered.

To make things worse, the ROS wiki distinctly lacks structure. It is basically a collection of pages dedicated to single packages, and little structure or classification information is provided. The result is that, more often than not, even when you are looking for information that is in the wiki you are not able to reach it easily. Usually you have to google for the topic you're interested in, read something here and there on the Internet, try to identify a set of ROS packages that could be interesting for your problem, and only then you can go to the ROS wiki and look for such packages. Often you get to interesting wiki pages by chance: i.e., by clicking on a promising link located in a page which only marginally deals with the topic. So... explore!

This page of AIRWiki tries to complement what's provided by the ROS website with additional information, instead of saying the same things in a different way. In a nutshell, this HOWTO is a structured collection of whatever it would have been nice to find in the official documentation about ROS, but wasn't there (or was hidden too well).

ROS tutorials

ROS includes a rather comprehensive set of tutorials, some of which are listed here. Most tutorials, however, are only accessible from the "Package links" section of the relevant packages: so, unfortunately, you will have to hunt through the ROS wiki to find them.

ROS tutorials are extremely useful, though not always 100% accurate. (E.g.: something does not work as described, or leads to unexpected errors, and you have to work out why for yourself. By doing so you learn a lot, but you also lose a great deal of time.) The ROS tutorials are subdivided in "difficulty levels". Currently the levels are "basic" and "intermediate". Keep in mind that the tutorials have been written by different people at different times: so don't expect two tutorial of the same "level" to be consistent in what they assume you already know!

Arguably, the most useful tools to learn how to use ROS are the basic tutorials. Be sure to go through them before writing a single line of code (except those that you will write for the tutorial, of course!). Once you have worked your way through the tutorials, the next thing to do is to write your own ROS package and apply what you have learned. The "Nodes" section below is the suggested starting point for that. Maybe you should start experimenting with a "test" package, before passing to a real application: in this way you can experiment without worrying if the end result is a mess :-) You are strongly invited to experiment: as usually happens in computer programming, that's the best way to understand and check if you have correctly understood, all at the same time.

Before you start with the tutorials, please read this introduction to the concepts behind ROS: you will not necessarily understand how things are done in practice until you will have completed the tutorials, but reading it before passing to these will provide you with useful background.

Package links

As already said, the most common page of the ROS website is the one dedicated to a specific package. It is the starting point to learn everything about that package. One of the most important elements of package pages is the blue rectangle called Package Links. It includes links to many useful resources for users of such package, such as tutorials, FAQ and more.

Programming languages

ROS, per se, does not force the developer to use a specific programming language. In practice, while there are expansion plans for the future, at present only two languages are supported: C++ and Python. That is to say, only for these two languages ROS provides client libraries that enable non-ROS software to interface with ROS. Such libraries are called roscpp (for C++) and rospy (for Python).

You can choose what language to use on a module-per-module basis, choosing C++ or Python (or whatever other language will be supported in the future) separately for each software module of your ROS system. As we will explain shortly, ROS software modules are called nodes.

Tutorials for roscpp and rospy are available: see here and here respectively.

Measurement units and conventions

ROS faces the same problems that any software system which has to deal with physical quantities (to cite but one: position in space!) has to tackle: namely, (i) choice of measurement units and (ii) choice of measurement conventions (e.g., orientation of coordinate systems). Unfortunately, programming languages do not allow physical dimensions or conventions to be attached to data; therefore, these have to be specified outside the software. For ROS, units and conventions are specified here.

In particular, ROS measurement units are those of the Metric System: metre, kilogram, second, Ampére, radian, Hertz, Newton, Watt, Volt, Celsius.

Nodes and communications

The basic element, or module, of a ROS-based software system is the node. A node executes one or more tasks and communicates with other nodes using the ROS infrastructure. Such communication takes the form of an exchange of messages. For instance, messages can be used to pass sensor data to a processing node, or to issue commands to a motor-controlling node. Many predefined types of ROS messages are available; if none of them suits your requirements, you can define new message types. A message can include a timestamp, which tells to the recipient when it has been generated: this is especially useful when dealing with sensor data. ROS usually calls "Stamped" a message type that includes a timestamp; this is useful to keep in mind while choosing among available message types.

Communications among modules of a ROS system should always be performed using ROS messages. In fact, the many powerful tools provided by ROS to collect, analyze and debug such communications are all targeted to the processing of messages, and become useless if your system does not use these.

Of course, there are real-world situations when communicating data through messages is not feasible because it would require too many resources. For instance, this happens when a large set of data (such as a complex map) has to be processed by different modules. Using messages to provide the map to each module would require the frequent generation of copies of it (thus wasting both CPU time, for creation, and RAM space, for storage). The typical solution to such problems is to let all the modules involved access the RAM area where the data are stored, thus exchanging only pointers; however, ROS provides its own solutions, which you should investigate first. One of these is the use of nodelets.

A key aspect of the communications among ROS nodes is that, as they are based on the exchange of ROS messages, they are asynchronous. Outgoing messages are delivered as soon as the ROS system manages to free the necessary resources, are stored in a queue by the receiving node(s), and the node(s) processes them as soon as it is able to (i.e., as soon as it "awakens" if it is executed periodically). An important consequence of this is that you must never count on correct message timing, or even on correct ordering, for critical aspects of your system's functioning. Your ROS system must be tolerant of alterations in the message flow such as delays, misordering, or loss.

Messages that deal with the same aspect of the functioning of the robot can be grouped by publishing them on the same topic. A topic identifies a "communication channel", shared by nodes that deal with the same aspect of the robot. Each node can subscribe to the topics it is interested in (thus receiving all the messages that are published on them, without being bothered by messages published on other topics) and/or publish messages on them (thus ensuring that its messages reach all interested nodes).

A node can perform several types of activities, including:

• publishing messages on a ROS topic;

• requesting a service from ROS servers, i.e. acting as a ROS client;

• acting as a ROS server, i.e. providing services to ROS clients;

• executing a task whenever a message is published on a ROS topic;

• managing a timeout and executing a task if it expires;

• execute a task periodically.

These are the activities that are concerned with the interaction between the node and the whole ROS system it is part of. In addition to them, the node can perform internal activities, such as (for instance) data processing. While the ways in which a node interacts with the ROS system are defined by ROS and are based on the use of ROS tools, the internal activities of a node are not constrained by ROS in any way (though of course if they use up too much resources, such as RAM or processing power, they can affect the rest of the system indirectly).

In practice, a node is implemented as a single executable file. This is produced from a source code file written in one of the programming languages supported by ROS. For instance, if you use C++ you will have to write a .cpp file comprising a main block (and anything else your program needs to work, such as additional functions, data types, #include directives and so on).

AIRLab's general node template

AIRLab's general ROS node template provides all the elements that you need to set up the structure of the .cpp file of a basic ROS node, including the elements that are required for all the types of activities that a node can perform (as described above). The template includes a single C++ class comprehending a suitable set of member variables and member functions, plus a very simple main block. By uncommenting the parts of the template that you require for your ROS node, you can quickly set up the structure of the node. Moreover, the template includes notes and comments that explain how a ROS node is built and works in practice.

ROS Tools

ROS comes with a wide set of tools that you will need while building your own ROS-based application. Among them, those listed below are especially useful. They can all be run from the command line as any Linux system command except where noted.

• roscore must be run before anything else every time you run a ROS application, and should be kept running: it sets up the ROS infrastructure that all other elements of ROS connect to;

• rosmake is necessary to compile your code as part of the ROS system;

• rosrun lets you run a single node;

• roslaunch lets you run several nodes at the same time, besides doing other things such as setting the value of ROS parameters, according to what is specified by a launchfile);

• rxgraph graphically shows how the nodes of your system interact through ROS messages;

• rxconsole is an interface to the (very comprehensive) logging system built-in in ROS: it's very useful to understand what's happening within your running ROS system;

• rosbag records or plays back ROS messages: in particular, it can be used to simulate the presence of some parts of a robot system (e.g., those dealing with hardware) even if they are not available at the moment, by playing back their output;

• rviz is a powerful visualizer for data published as ROS messages; it has to be run as a ROS node, i.e. using rosrun (command: : rosrun rviz rviz).

For quick help on ROS tools, if you enter (through the command line) the tool's name without arguments you usually get a short list of options, similar to the man pages of Linux. Should you need it, you can download the handy ROS cheat sheet.

Starting and stopping ROS components

One powerful feature of ROS is that (provided that roscore is running) you can start or stop any element of ROS (both nodes and debugging tools like rxconsole or rviz) whenever you like: the ROS system will automatically react to the changes and reconfigure itself. (To stop a ROS element you can simply highlight the terminal window where it was launched and press Ctrl+C.)

In some cases ROS or one of its elements take a few seconds to react to the starting or stopping of a ROS module. In other cases, something just gets stuck and has to be stopped and started again (rxgraph, notably): however, this happens rarely.

Internal structure of a package

In ROS, each package has its own directory on disk: all the elements of the package are contained in such directory. The ROS package takes the name of the directory. Some of the package directories are installed by ROS, and reside somewhere on your hard disk (tip: to quickly reach a ROS package from the command line, and discover where it's located, simply use roscd name_of_the_package). Other package directories are created by you, and you can put them wherever you like (usually somewhere in /home/your_username).

It doesn't matter where your packages are, provided that the directory that contains them is one where ROS looks for packages. You can't just put your ROS package directory anywhere you want: you will also need to tell ROS where it can find them. In practice, this is done by properly configuring ROS. The simplest way to create and prepare the directory for a new ROS package is to use roscreate-pkg; otherwise you can do the preparation manually.

The contents of a package directory in ROS are standardized. Most of these are only modified by ROS, and you can ignore them; however, there are some elements of your package's directory that you will have to modify manually. Let us suppose that you are creating a new ROS package called MyPkg. As said above, all the elements of your package will be contained in a directory called MyPkg, located somewhere in your PC's filesystem. The elements of MyPkg that you might need to modify while working on your new package are the following:

• MyPkg/CMakeLists.txt, a text file which tells ROS which elements (executable files, message types, ROS services, ...) it will have to create while building package MyPkg. CMakeLists.txt defines the compile behaviour of rosmake for package MyPkg.

• MyPkg/src/, where the source code for your ROS nodes reside (in the form of .cpp files, if you are using C++). (By the way: the executable files that rosmake creates are in MyPkg/bin.)

• MyPkg/launch/, where you put your launchfiles, if you use them (which is very likely when you build complex ROS systems).

• MyPkg/msg/, where you define your own types of ROS messages.

• MyPkg/srv/, where you define your own ROS services.

• MyPkg/manifest.xml, which (by being present) specifies that MyPkg is a ROS package directory, and which defines some properties of the package; usually you won't need to modify manifest.xml unless you need to add a dependency to your package.

Moving package directories

If you have to move the directory which contains a ROS package (say, directory MyPkg) to another place in the filesystem, the package ceases to work properly. To make the package functional again you have to recompile it while forcing the process to consider its modified location. In practice you have to:

1. delete file MyPkg/build/CMakeCache.txt;
2. recompile MyPkg in the usual way, by running rosmake.

Of course, you also have to make sure that the new location of MyPkg is one of the locations where ROS looks for packages.

Filenames and node names

[Note: this section is only valid if C++ is used to define nodes. TODO: expand to the Python case.]

The .cpp files that define ROS nodes can have any name, provided that such names are legal.

When a .cpp file is compiled using rosmake, the files that are generated by the compilation process (which include the executables in the /bin subdirectory) take the names that are specified by the CMakeLists.txt file. For instance, putting in CMakeLists.txt the line

rosbuild_add_executable(name_of_executable src/name_of.cpp)

instructs rosmake to compile file name_of.cpp and call name_of_executable the resulting binary file.

The name of the executable takes the role of the name of type of node. All ROS nodes which are run using such executable are of the same type (i.e., they work in the exact same way) but take different names depending on the way they are run.

If a single instance of such type of node is run with rosrun, it will take as its own name the name of its type; when, instead, one or more instances of such type of node are run with roslaunch, each of them can be given an arbitrary individual name.

When a ROS node is run using rosrun, the running ROS node takes the name specified in the associated .cpp file. Precisely, the .cpp file that defines the node always includes a statement like

ros::init(argc, argv, "name_of_the_node");

The string between quotes is the name given to the running node.

Usually (for complex ROS systems, at least) nodes are not run with rosrun. roslaunch is used instead, to perform several operations at the same time (including, but not limited to, running nodes). In this case, the names taken by the running nodes are specified by the .launch file passed to roslaunch. For instance, if file launchfile includes the line

<node pkg="name_of_package" type="name_of_executable" name="name_of_the_node" />

a node called name_of_the_node will be run using the executable name_of_the_executable contained in package name_of_package.

In a running ROS system, each node must have a unique name. If a new node with the same name of one that is already active is run, the older node is stopped by ROS (and a warning is generated). A consequence of this is that you can't run two or more nodes of the same type with rosrun, as only one of them (the last) would remain active. This is a case when running the nodes with roslaunch is a necessity, because you need to assign a different name to each instance of the node.

About specific components of ROS

The preceding part of the HOWTO is dedicated to general issues regarding ROS. On the contrary, what follows is concerned with individual elements of a ROS system, such as pieces of the ROS infrastructure (e.g., the parameter server), single stacks or packages, debugging tools...

Everything that is not related to all of ROS (and therefore is only of interest for people using a specific part of ROS) belongs to this part of the HOWTO.

ROS parameter server

ROS includes a parameter server that can be used to store in a centralized way all the configuration parameters of a robot system. As autonomous robots are generally a collection of hetereogeneous modules, each having its own parameters and its own methods for storing and retrieving them, this is a valuable step towards making robot software more easy to use, organized and reusable. Configuration parameters managed by the ROS parameter server are specified using the YAML language. They can be stored, modified and retrieved at runtime both from the command line and (more importantly) from ROS nodes.

The key element in using parameters is that by storing them outside of the software, you don't need to recompile it every time you change a value. Moreover (ideally, that is...) you have all the parameters at hand in the same place. The usual way to do this is to (manually) write configuration files, i.e. text files complying to a specified syntax. When the system is run, each software module parses its own config files and extracts the values of its parameters.

There are several problems with this approach:

• every software module has its own configuration files, usually located within its own directories: so you end up with config files scattered through the filesystem instead of in a single place;
• different programmers tend to use different syntaxes for their config files, so in the same robot system you often have to write configuration parameters using several different (though equivalent) ways, which leads to errors;
• worse still, the number, name, position and syntax of configuration files is not usually well documented (that's an euphemism :-) );
• finally, devising ways to let the system set or modify its own config parameters while it is running is difficult.

As previously said, the ROS parameter server is a good attempt to make the configuration mechanism standard and common to all software modules, and therefore less prone to errors and more easy to use.

The most common usage pattern for the parameters of a robot system is this:

1. parameter are defined and values are set by writing the relevant configuration files;
2. as soon as each module of the system is started, it parses its own configuration files and extracts parameter values.

For what concerns defining configuration parameters and setting their values, ROS offers several options:

• using rosparam from the command line, like this:

rosparam set parameter_name value

• putting a <param> statement into a launchfile:

<param name="my_param" value="my_value" />

• writing a text file with extension .yaml (say, my_file.yaml) including the parameter definition expressed in YAML syntax (my_param: "my_value"), then loading such file by including in a launchfile the following statement:

<rosparam command="load" file="$(find my_pkg)/path_within_pkg_directory/my_file.yaml" />

In the code above, my_pkg is the package that the .yaml file belongs to. Also note how $(find my_pkg) is used in place of the actual path to the package, so that the launchfile will work wherever the package is located within the filesystem. Such use of find is very handy when writing launchfiles, and is an example of substitution arguments in launchfiles.

For what concerns how nodes can retrieve parameter values from the parameter server, see AIRLab's general ROS node template.

As other elements of ROS systems, parameters have a scope. If the statement that defines a parameter (either directly or by loading a .yaml file) in a launchfile is included into a <node> block, the parameter is defined in the namespace of the node. This is the preferred way to define parameters, because it minimizes conflicts.

Finally, a word of warning. If you set a parameter and then remove the lines that set it from your configuration files, the parameter remains set until you restart roscore!. Not knowing this leads to much head-scratching as you try to figure out why your ROS system continues to behave in the wrong way even after you removed the parameter setting that led to such wrong behaviour.

Fortunately, there's an easy way to check, at any time, what parameters are set in your system: by using

rosparam list

If you want to know the current value of parameter named /full/name/of/the/param (this is the full name, starting from base namespace "/", as shown by rosparam list), you can use

rosparam get /full/name/of/the/param

rosbag

"Stale" transforms?

Some ROS tutorials make use of bagfiles containing sensor data and transforms. If you try to play a bagfile with rosbag play and do something with its contents (e.g., visualize the data using rviz), you can get nasty but obscure errors like this:

MessageFilter [target=/map ]: Dropped 100.00% of messages so far.

Such errors will prevent you from doing anything with the data being played (including visualizing it).

Depending on what ROS tools you are using, the error message can change; but the point is that data have been discarded because the transforms between reference frames in the bagfile are too old to be considered reliable. For instance in rviz you will get something like "ignoring data from the past for frame name_of_the_reference_frame".

The solution is to force ROS to use the time when the bagfile was prepared instead of the current time: i.e., to get the time from the bagfile instead of getting it from the "wall clock" (i.e., from your computer's clock). This is done by setting to true the ROS parameter called use_sim_time, stored by the parameter server. See | the section about the ROS parameter server to read how you can do this.

After you have set the parameter, you have to run rosbag like this:

rosbag play --clock <name_of_the_bagfile>

In this way, rosbag acts as a ROS clock server, publishing time readings (on the /clock topic) that are coherent with the timestamps of the data in the bagfile. Other ROS nodes will take time readings from the /clock topic, ignoring the wall clock... and the transforms will appear to be "fresh" instead of "stale". See the Clock page of the ROS wiki if you want more information about clock and time management in ROS.

Warning: setting use_sim_time to true is something that you will only have to do while testing or debugging your system: it should not be done when ROS is used on running robots.

tf

From the the ROS wiki: "tf is a package that lets the user keep track of multiple coordinate frames over time. tf maintains the relationship between coordinate frames in a tree structure buffered in time, and lets the user transform points, vectors, etc between any two coordinate frames at any desired point in time". tf is a key element of ROS and, if you work on mobile robotics, there's not much that you can do with ROS before you discover that you need tf.

Basically, every time you have a non-rigid coupling in your robot (including the non-fixed coupling between robot and floor!) it's a good idea to set up a new coordinate frame (i.e., a set of Cartesian xyz axes) on the movable element. Therefore, you will need to define and use the transforms that -given the coordinates in space of a point when measured in one of the frames you defined- produce the coordinates of the same point when measured in another frame. tf lets you define, manage and use such coordinate frames and transforms. Here is a nice tutorial about how to use tf.

Transform tree

Many ROS packages assume that in your ROS system a correct transform tree has been set up. This means that there are some coordinate systems, and some relations among them, that most ROS packages assume to exist. One of the things that are badly documented in ROS is precisely what these coordinate systems are, and how they relate to each other. Although it's well hidden in the documentation, ROS does define a quasi-standard transform tree for ROS, which looks like this:

map -> odom -> base_link -> sensor_link

In this transform tree (where each coordinate frame is the child of the one on its left):

• map is the fixed frame, sometimes also called "world". It is considered static in real space.

• odom is the frame where the robot localizes itself thanks to its own odometry system.

• base_link is a coordinate frame fixed to the base of the robot in a convenient place (dependent on the specific robot used);

• sensor_link is a frame fixed to one of the sensors mounted on the robot (a common example for this frame is base_laser_link): there will be one such frame for each sensor.

For what concerns axis orientation, ROS provides some guidelines.

Of course, the applicability of the transform tree described above to your own robot is not guaranteed, so be prepared to make alternative choices. However, this transform tree is more or less taken for granted by most of the ROS wiki (especially where the PR2 robot is concerned, although in that case odom is often called odom_combined).

The relation between coordinate frames map and odom is an especially critical one, so it's a good idea to discuss it in more detail.

Even before the robot starts moving, odom usually differs from map because its origin is defined by the robot's starting pose. That said, if odometry were perfect, the transform between map and odom would stay constant over time. In the real world, such transform is not fixed: it drifts over time due to odometry errors, and can even experience abrupt changes (e.g., the "jumps" that occur in case of wheel slippage, when the robot perceives a big displacement of its body while the actual displacement is very small).

In practice, the relation between base_link and odom assumes that odometry is perfect, i.e. that it never introduces errors. The transform between base_link and odom represents the change of pose of the robot from its initial pose to the current one, as estimated by the robot's odometry subsystem.

For this reason, a mobile robot needs a localization system with the task of continuously updating the transform between map and odom. The odometry system of the robot uses data from the odometers to update the transform from frame odom to frame base_link: this transform represents how the robot thinks to have moved with respect to the surrounding physical environment (such as the floor). The localization system uses sensor data to update the transform from frame map to frame odom in order to correct the errors in the above transform. Whenever the odom -> base_link transform imperfectly captures the movement of the robot in the real world, the localization system modifies the map -> odom transform so that the base_link frame is shifted to the correct pose with respect to the world. The presence of the odometry system is important to provide the localization subsystem with a good guess of how the robot has moved: in fact over short time intervals odometry does not introduce large errors.

You can also see the situation from the point of view of maps. ROS includes a navigation stack which includes an implementation of all the elements required to manage robot motion. Among these elements, there are a global map and a local map.

Generally a mobile robot is provided with (or builds by itself) a map of its environment, showing obstacles and other features. This is the global map, that by definition is considered fixed with respect to the map coordinate frame (hence the name of the latter). However, while the robot moves it also builds a local map, which includes the obstacles and features located in its immediate surroundings. The local map is considered fixed, by definition, with respect to the odom coordinate frame. The local map is a portion of the global map: so localization can be performed by comparing the two to find the correct alignment between them. Finding such alignment corresponds to finding the correct transform between coordinate frame map (to which the global map is affixed) and coordinate frame odom (to which is affixed the local map).

Finally, a practical note. In ROS, to establish a transform tree, you have to define and publish (on the /tf topic) the transforms from each of the component frames to its parent. Some ROS packages, like gmapping, specify in their page of the ROS wiki what transforms they require; most packages, unfortunately, do not.

Tip: to publish fixed transforms you can use the handy static_transform_publisher.

Who defines /world or /map?

One puzzling aspect of the ROS documentation is that it contains countless references to coordinate frames called /world or /map, which do not seem to be defined anywhere. The solution to this problem is simply that the /world' or /map coordinate frame is defined implicitly. In fact, in any ROS applications where tf is employed, a "default" coordinate frame is used as the starting point to define (through suitable transforms) all the coordinate frames used in the system. Such "default" frame, considered fixed, is called /map, or sometimes /world.

tf maintains a tree of coordinate frames, where each frame has one (and only one) parent and as many children as needed. The only exception to this rule is the frame that constitutes the root of the tree, which has no parent. This is accepted (and indeed necessary, given how coordinate frames are defined using tf), as long as in the system there is a single root frame: i.e., as long as every other frame in the tree has a parent. Which frame is the root, i.e. which coordinate frame acts as the "default" coordinate frame of the system, is defined implicitly. In fact, any frame F in the tf tree is there because a transform between another frame (parent) and F (child) has been specified. So, the one frame that has been used one or more times as a parent but has never been used as a child is the root of the tree: i.e., the "default" coordinate frame of the ROS application.

The name of the root coordinate frame is arbitrary; however, as ROS packages generally call it "/map", it is advisable to stick to this rule. By the way, if you used (for instance) "/map" and find out that some ROS package you are using requires instead that the name (for instance) /world is used for the fixed frame, it's easy to define a static transform that both defines the reference frame /world and makes frame /map coincident with it. This can be done by using a static_transform_publisher. The easiest way to define and run the static_transform_publisher is to insert in your launchfile (assuming your ROS application has one)

<node pkg="tf" type="static_transform_publisher" name="map_broadcaster" args="0 0 0 0 0 0 world map 100" />

The above statement creates a static_transform_publisher node that every 100ms broadcasts (on the /tf topic) a message specifying that the transform from /world to /map has zero translation and zero rotation. (By the way, that value of 100ms comes from the ROS wiki, which says it's a "good value".)

Useful ROS commands

ROS Official Cheat Sheet

ROS installation and package creation

Configure your environment

If you followed the ROS tutorial to configure your environment, the variable $ROS_PACKAGE_PATH should be set. This can be easily verified by check if the command echo $ROS_PACKAGE_PATH returns an output similar to:

/home/your_user_name/fuerte_workspace/sandbox:/opt/ros/fuerte/share:/opt/ros/fuerte/stacks

If you use a different path (e.g.: ~/eclipse_workspace) you should add it to the $ROS_PACKAGE_PATH variable. The simplest way to achieve this is to edit the .bashrc file located in your home directory and add the line

export ROS_PACKAGE_PATH=~/eclipse_workspace:${ROS_PACKAGE_PATH}

NOTE: Please be sure to add this command AFTER the following line (that you should have added to your .bashrc, according to the tutorial) or you will get an error running make eclipse-project:

source /opt/ros/[ros_distribution_name]/setup.bash

IDEs

If you use an IDE (in this example Eclipse will be used), in order to reuse your shell environment it is advisable to launch it with the following command:

bash -i -c /usr/lib/eclipse/eclipse

If you use Eclipse you can also use the following command to let ROS create the Eclipse project files.

make eclipse-project

Note that if you change anything to your manifest.xml, you will have to run this script again, which will overwrite your Eclipse project file and thereby reverting all manual changes to the project settings. Please refer to this page if you need further information.

Package management

ROS packages can be managed using your linux distribution package manager and/or with the built-in ROS package manager.

ROS package environment

• initialize the ROS package management environment:

(as root) rosdep init

• update the package list:

rosdep update

ROS package installation

• Find a package:

browse to this page to browse a list of available packages.

• Check if a ROS package or stack is installed with the following command:

rospack find package_name

rosstack find [stack_name]

• If you get an error, install the stack that contains the package with the package manager of your linux distribution (e.g.: sudo apt-get install ros-distribution_release_name-stack_name ), then check again if rospack can find the package and, if not, install it with the command:

(as root) rosdep install package_name

New package creation

This command creates a new package in the current directory:

roscreate-pkg package_name package_dependency_1 package_dependency_2 package_dependency_3 ...

Please note that package dependencies can be explicitly specified when the package is created, but they can also be manually added afterwards to the manifest.xml file or with the rospack command. Take a look at this page if you need further information.

CMakeLists.txt

cmake_minimum_required(VERSION 2.4.6)
include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)

# Set the build type.  Options are:
#  Coverage       : w/ debug symbols, w/o optimization, w/ code-coverage
#  Debug          : w/ debug symbols, w/o optimization
#  Release        : w/o debug symbols, w/ optimization
#  RelWithDebInfo : w/ debug symbols, w/ optimization
#  MinSizeRel     : w/o debug symbols, w/ optimization, stripped binaries
# Usage:
#     set(ROS_BUILD_TYPE build_type)
set(ROS_BUILD_TYPE Debug)

rosbuild_init()

# Set the default path for built executables to the "bin" directory
set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
# Set the default path for built libraries to the "lib" directory
set(LIBRARY_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/lib)

# Uncomment if you have defined messages
#rosbuild_genmsg()

# Uncomment if you have defined services
#rosbuild_gensrv()

# **** Common commands for building c++ executables and libraries ****

# To add an executable cpp file: 
# Usage:
#     rosbuild_add_executable(${PROJECT_NAME} executable_path)
rosbuild_add_executable(test_read_map src/test_read_map.cpp)

# To add a library:
# Usage:
#     rosbuild_add_library(${PROJECT_NAME} libraries_path)
rosbuild_add_library(map
                    src/map/map_cspace.cpp
                    src/map/map_draw.c)

# To link a library to an executable file:
# Usage:
#     target_link_libraries(${PROJECT_NAME} library_name)
target_link_libraries(test_read_map map)

# To add boost directories:
# rosbuild_add_boost_directories()

# To link boost:
# rosbuild_link_boost(${PROJECT_NAME} thread)

# To add the dynamic reconfigure api:
# rosbuild_find_ros_package(dynamic_reconfigure)
# include(${dynamic_reconfigure_PACKAGE_PATH}/cmake/cfgbuild.cmake)
# gencfg()
# rosbuild_add_executable(dynamic_reconfigure_node src/dynamic_reconfigure_node.cpp)
# rosbuild_add_executable(FIRST_dynamic_reconfigure_node src/FIRST_dynamic_reconfigure_node.cpp)

Makefile

Be sure that the following line is present in the Makefile in order for the command make eclipse-project to work:

include $(shell rospack find mk)/cmake.mk

Manifest.xml

<package>
  <description brief="brief description of your package">

     [write here your package name]

  </description>
  <author>Your name</author>
  <license>BSD</license>
  <review status="unreviewed" notes=""/>
  <url>http://ros.org/wiki/package_name</url>
  <depend package="package dependance 1"/>
  <depend package="package dependance 2"/>
  ....
</package>

ROS filesystem commands

• To change directory directly to a package or stack directory:

roscd package/stack_name

ROS visualization system - rviz

• To open rviz you will need roscore running in background (execute roscore in a different shell) and then run the following command:

rosrun rviz rviz

The rviz interface will pop up, to visualize something published by a node you will have to

• Add a type by clicking Add and selecting a display type (e.g.: poing cloud)
• Set the topic that you want to listen (the one specified in the node that is publishing)
• Set in the Global Options menu the desired Fixed Frame (typically /map )