Table of Contents

Lab 01

During this lab, you should learn how to use the Apptainer, the tmux, the terminal commands of Robot Operating System (ROS), and how to program a simple python subscriber/publisher node.

Slides used in this lab are available here: https://docs.google.com/presentation/d/1rLQQllG8z78JBPfMsZ-KJiQbpIWFphqULLs1VxF0gbQ/edit?usp=sharing (they are not standalone, they only make sense with the live lab program; use Faculty google account to access them).

Apptainer

Apptainer is software for virtualization via containers that allows you to program and test ARO homeworks and semestral work without installing all ROS dependencies on your computer.

You can learn how to use Apptainer on Lab PCs and/or details how to install/build it on your computer here. 

git clone https://gitlab.fel.cvut.cz/robolab/deploy.git
./deploy/scripts/install_apptainer
./deploy/scripts/download_apptainer_image
./deploy/scripts/start_apptainer_aro

The start_apptainer_aro script not only starts the Apptainer container, but also creates appropriate ROS workspace, clones the student packages to the workspace, builds the workspace, and sources the workspace. Details of this process are described here.

After starting the Apptainer container, try to run the simulation which will be part of your first homework using command: 

# in 1st terminal window:
ros2 run rmw_zenoh_cpp rmw_zenohd
# keep zenohd running and call this in the 2nd terminal:
ros2 launch aro_reactive_control hw01_sim.launch.xml

Terminal

You will need to be able to use terminal in Linux. Here are a few tips for what you will need:

The following key shortcuts are super cool quality-of-life helpers, give them a try!
  • Arrow keys up/down go through command history.
  • <Tab> (one or two presses) shows you autocompletion options (filenames, packages, topics…)
  • Ctrl-R allows you to search through command history (first press Ctrl-R, then type a substring from the command you search for, then press either Tab if you found it, Enter to directly execute it, or Ctrl-R again to search backwards in history with the same substring)
We've noticed some setups in which Tab completion doesn't work. If you think this problem affects you, please tell us on the forum a little bit more about your setup.

Terminal multiplexer (tmux)

Tmux allows you to switch easily between several windows in one terminal., detach them (they keep running in the background) and reattach them to a different terminal. To start Tmux use:

Inside tmux session, press $prefix (ctrl+b) followed by any of the keys below to control the session:

Robot Operating System (ROS)

Robot Operating System (ROS) https://www.ros.org/ is a set of software libraries that allows you to build a complex robotic system. It is not an operating system but rather a very convenient middleware for sharing data (messages) between different parts of the robot's software (nodes). When using ROS you can leverage the work of others and use an already very large code base of implemented packages for, e.g., mapping, localization, control, planning, and sensor interfacing.

We teach ROS 2 (version Kilted Kaiju). You can still find many links and references to ROS 1 on the web (versions e.g. Melodic Morenia or Noetic Ninjemys). ROS 1 and 2 are not compatible at all, although the core concepts are similar. When searching the web for resources, always check if you found a ROS 2 or ROS 1 answer (ROS 2 started being used around year 2020, so anything older is probably ROS 1).

Key aspects/buzzwords to know are:

The code for your projects with ROS is stored in a workspace.

Your workspace is created, built, and sourced automagically using the deploy/scripts/start_apptainer_aro script. So no need to create your workspace manually.

In case you would like to create your own workspace in some folder, you can do it by running the following commands in the started Apptainer container:

You do not need to run these commands to use the default ARO workspace because we have already created it for you. 

cd <where_you_want_the_workspace>
mkdir -p new_ws/src
cd new_ws
# Now source the "base workspace" that your workspace extends
source /opt/ros/aro/setup.bash
colcon build --symlink-install
source install/setup.bash
This code initializes your workspace as an extension of the default ARO workspace. Then it calls the colcon tool to build the workspace. Finally, it sources the workspace to load information about all built packages. Now you can place any of your packages into the src folder and after repeating colcon build and sourcing parts you can use them.

Please note that even when you are using Python, which normally does not require a build step, ROS requires you to re-build and re-source the workspace in some cases - most notably when you add a new package, add a new file to a package, or change the setup.py or CMakeLists.txt.
It is very important to call colcon build in the correct folder. You have to call it in the workspace folder (i.e. the folder that contains src and install. We made a convenience script for you that handles this and a few other tricky parts: call ./build.sh instead of colcon build in your ARO workspace.

ROS in terminal

ROS has many handy command line programs that you can learn. You won't use them to create the actual ROS programs (nodes), but you will be using them routinely when inspecting and debugging running ROS systems.

Please note that due to the distributed architecture of ROS, some commands can output incomplete information - most notably when run for the first time.

Test the following individual commands. Use the tab for suggestions of node names, topic names, message types, etc.

  1. Start tmux and run ros2 run rmw_zenoh_cpp rmw_zenohd .
  2. Start turtlesim: ros2 run turtlesim turtlesim_node .
  3. Create new tmux window and test all ros2 node commands on /turtlesim node.
  4. Test ros2 topic (including echo) commands on the listed topics in /turtle1 namespace in the same tmux window.
  5. Test listing all available messages using ros2 interface list --only-msgs and find out what messages are in turtlesim_msgs package. Show the definition of one of the message types.
  6. Create a new tmux window (Ctrl+B+C) and run an example publisher: ros2 topic pub /turtle1/cmd_vel geometry_msgs/msg/Twist \' # Now press Tab key to complete the message body and use left/right arrow keys to navigate in it and change values.

ROS for Python

In ROS Kilted we will use Python 3.12. The most important library that enables interfacing with ROS is rclpy. The typical content of a package folder in, e.g., workspace/src/my_package/ is:

Always make sure the python node .py file starts with the 'shebang' line #!/usr/bin/env python3. Always make sure to source install/setup.bash in your workspace after you build your workspace with colcon build or ./build.sh. You need to build the workspace if you have new package, if you change c++ code or, e.g., message definitions. Changing Python code or YAML config contents does not require rebuilding.

You can code in your favorite IDE, but the IDE needs to be run from inside the Apptainer container. See Using IDEs with Apptainer.
Do not set up any kind of virtual environment when developing with ROS. No venv, no conda, no uv or poetry! The often installed conda autostart of the base env can interfere with ROS. Please, check ROS/Common Problems to see how to fix it.


Initializing a node and running it

At the beginning of a Python script (actually usually at the bottom of the file) you need to initialize ROS with rclpy.init() command. Afterwards you can initialize all your subscribers, publishers, threaded workers, etc. Finally you need to run rclpy.spin() which internally runs the messaging system of the node (especially important for subscribers to run callbacks for new messages).

The actual startup code looks like this: 

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node
 
class MyNode(Node):
    def __init__(self):
        super().__init__('my_node')
        # Continue with setting up publishers, subscribers etc.
 
def main():
    try:
        with rclpy.init(), MyNode() as node:
            rclpy.spin(node)
    except (KeyboardInterrupt, ExternalShutdownException):
        # exit nicely if the program is normally terminated
        pass
 
 
if __name__ == '__main__':
    main()


Printing

You can print messages to console and log within your package with different severity levels using:

Find more logging capabilities on https://docs.ros.org/en/kilted/Concepts/Intermediate/About-Logging.html#apis .


Messages

Messages are data structures used to send data over topics. They are composed of either simple or complex data types. Simple types are, e.g.: bool, int<N>, uint<N>, float<N> (with N being {8, 16, 32, 64}), String, Time, Duration (see standard messages ros2 interface package std_msgs). Complex data types are composed of simple ones or their arrays (see, e.g., ros2 interface info std_msgs/Header ). Custom messages can be defined in message files, and their respective C++ headers and Python objects are generated during build.

Available message definitions can also be found on the ROS Index, e.g. std_msgs package. Click API docs in the upper right corner to get a nice view of the message definitions.

All released message definitions can be found in the list on index.ros.org.


Publisher

Publisher is an object assigned to a specific topic and message type that you can use to send messages from your node to other nodes. You can create publisher object using: publisher = self.create_publisher(std_msgs.msg.String, 'message', 10). Then every time you want to send a message you create a new message object msg = String() , then fill it with your data (msg.data="ahoj") and publish it to ROS using publisher.publish(msg).

Also try to publish to topic /turtle1/cmd_vel and control the turtle in turtlesim!


Subscriber

Subscriber is an object that basically assigns a callback function to received messages of a given topic name and message type. You can create the subscriber using: subscriber = self.create_subscription(std_msgs.msg.String, 'message', callback, 10) , where the callback is a custom function (def callback(msg):) that handles the received message.

Also try to subscribe topic /turtle1/pose and print the pose of the turtle!

Lab task

Implement simple publisher and subscriber nodes as specified below. You can get inspiration on how to write such Python nodes in the following ROS tutorial. Both can be placed inside the aro_reactive_control/scripts of the student-packages.

  1. Run turtlesim using ros2 run turtlesim turtlesim_node
  2. Implement publisher inside workspace/src/student-packages/aro_reactive_control/aro_reactive_control/publisher.py that publishes String message from std_msgs package on topic “message” every one second and also publishes cmd_vel for the turtle.
  3. Add an entry for the publisher in workspace/src/student-packages/aro_reactive_control/setup.py .
  4. Build the workspace: workspace/build.sh (or ./build.sh if you are in the workspace directory).
  5. Source the workspace: source workspace/install/setup.bash
  6. Launch the publisher using ros2 run aro_reactive_control publisher.
  7. Implement subscriber inside subscriber.py that receives the String messages and prints them in the terminal. It should also listen to turtle1/pose and print the received values.
  8. Again, add subscriber.py to setup.py, rebuild and source the workspace.
  9. Launch the subscriber using ros2 run aro_reactive_control subscriber.py.

Homework 01 assignment

Follow the assignment of the homework HW01 which requires only some additional work compared to the lab task above.