ROS Resources

The intention of this collection is to give you a very quick overview of ROS and act a 'cheatsheet'. For a more through analysis of ROS and its packages, refer to the ROS wiki.

External Resources

A Gentle Introduction to ROS : A good resource to get up and running on basic ROS concepts and abilities.
The ROS Tutorials : Offered by ROS wiki and it covers a wide range of tools. For the purposes of this class, we recommend that you go through the Beginner level tutorials (Python, not C++) if you want some extra help and practice getting familiar with ROS. The wiki itself is also a great resource if you want specific information about anything ROS related.

Basic Concepts

Nodes: An executable that communicates with other nodes through ROS.
Topics: Named communication channels over which nodes exchange messages. Nodes can publish or subscribe to a topic. Publishing is the act of sending messages over a topic and subscribing is the act of listening for messages in a topic.
Messages: Simple data structure used by topic publishers and subscribers.
roscore: roscore provide a number of pre-requisits to run any ROS-based system. Of debugging importance rosout logging node (equivalent of stdout/stderr) which is included in roscore.

Core commands

Note: Commands followed by a ✶ will take over an instance of your terminal. As a result, to run each instance of these commands, you will need a new terminal (having a terminal emulator that can be tabbed will go a long way in preventing clutter). Don't forget to pay attention to the output of these programs as they are used for warnings and errors. To end a program while keeping the terminal window open, press Ctrl-C . Additionally, be careful to not accidentally close these terminals as they will end the program they are running.

Nodes

$ roscore

✶ Does not take any additional arguments and needs to be running the entire time you are working with ROS (in other words, run this first always). Keep in mind that stopping roscore will prevent all running nodes from establishing new connections, even if you start a new instance of roscore.

$ rosrun package-name executable-name arg-name:=arg-value

✶ Starts a running instance of a program (i.e. a node). The first parameter is a package name and the second one is an executable in said package. After that, you can name and specify command-line arguments (as many as you like) using the := assignment. Keep in mind that rosrun starts only one node. For more nodes, you need more terminals and other instances of rosrun.

$ roslaunch package-name launch-file-name

✶ Launches a number of nodes. The first parameter is a package name and the second one is a launch file that details a group of nodes that should be started at the same time.

$ rosnode list

Lists currently running nodes. You should always see the /rosout node which is started by roscore at all times.

$ rosnode info node-name

Outputs information about a node. It includes a list of topics for which the node is a publisher or subscriber and a summary of the connections it has made to other nodes.

Topics

$ rostopic list

Provides a list of active topics.

$ rostopic echo topic-name

✶ Shows the actual messages getting published on a single topic. Only outputs messages that are published while the program is running. Can be performed on topics and sub-parts of topics.

$ rostopic info topic-name

Shows details about the message types of selected topic and publishers and subscribers to the the topic.

Messages

$ rosmsg show message-type-name

Shows details about a message type, including the fields and their names.

$ rostopic pub --rate=x topic-name message-type msg

Repeatedly publishes the given message on the given topic at the given rate in HZ. Once you get to typing msg, double tap tab and the terminal should fill out a stub message for you (based on message-type).

Record & Replay (rosbag)

rosbag is a ROS tool used for recording messages published on any number of topics in a file and replaying them later. For the purposes of this course, you will be asked to record your interactions with your robots in bag files so we can later replay them. rosbag is also a great development and debugging tool. For instance, you would not need to move your robot in a certain manner every time you update your scripts. You can just record it once and replay it as you wish.

$ rosbag record -O filename.bag topic-names

✶ Records the messages published to topics specified by topic-names in a file specified by filename.bag. It is important to note that rosbag will only record messages while it's running. So, start a recording before your desired messages are sent to the desired topics and end the recording once they are done.
Addtionally, rosbag has multiple useful flags.

-a records on every topic.
-j compresses the recording.
-x "regex" excludes a topic that matches the regex from the recording. Some topics (e.g. /camera/rgb/image_raw) will take a lot of space in a bag file. In such scenarios, this flag is handy.

$ rosbag info filename.bag

Inspects a bag file. In particular, it lists out message count, duration, and topic lists. Use this command to ensure your bag files meet submission requirements.

$ rosbag play filename.bag

Replays recorded messages in the same manner they were recorded. While replaying, make sure no other node's publishing is interfering with the recordings. Additionally, keep in mind that while a recording contains every message published, it has no information about initial conditions. Hence, replays might lead to different outcomes depending on your setup. Be sure to specify initial conditions if necessary somewhere else.

RViz

RViz is a tool that allows you to visualize robot's sensor data, i.e. what your robot sees. Such a data is usually a long list of numbers that are difficult to interpret. RViz helps reduce the burden on the developer by visualize this data.
Either run:

$ rosrun rviz rviz

✶ or simply run:

$ rviz

✶ Starts a GUI that allows you to observe what your robot sees (there will be a dark panel in the middle if you have yet to connect a robot to it). Keep in mind that RViz is just an observation tool. It is unable to actually control your robot.

$ roslaunch turtlebot3_gazebo turtlebot3_gazebo_rviz.launch

✶ Launches an RViz instance that automatically connects to the gazebo simulator and sets up the RViz based on the waffle_pi robots.

Hints, Tricks and Common Mistakes

Most ROS commands support tab completion. Pressing tab when appropriate should fill in
Always make sure your environment variables are up to date. You can do so by running source your-neotic-directory/devel/setup.bash .
If you are using your own scripts, make sure they are executable. You can make sure a scripy is executable by running chmod u+x script_name .