====== Lab 01 ======

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

===== Singularity =====

The Singularity 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 the singularity on Lab PCs and/or details how to install/build it on your computer [[courses:aro:tutorials:ros|here]].
  * To use the Lab computers remotely using ssh or remote desktop refer to [[courses:aro:tutorials:remote_access|this]] page.
  * **For now with your notebook with Linux OS, you can install singularity, download the image, and run the image using: **
 
 <code>
 git clone https://gitlab.fel.cvut.cz/robolab/deploy.git
 ./deploy/scripts/install_singularity
 ./deploy/scripts/download_singularity_image
 ./deploy/scripts/start_singularity_aro
 </code>

**The start_singularity_aro script not only starts the singularity, 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 [[courses:aro:tutorials:ros#behind_the_scenes|here]].

After starting the singularity container, try to run the simulation which will be part of your first homework using command:
<code>roslaunch aro_reactive_control hw01_sim.launch</code>

===== 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:
  * ''tmux'' - starts a new tmux session
  * ''tmux a'' - attaches to an existing session

Inside tmux session, press //$prefix// (''ctrl+b'') followed by any of the keys below to controll the session:
  * //$prefix//''+ d'' - detach from the session while it keeps running
  * //$prefix//''+ c'' - create new window
  * //$prefix//''+ w'' - list windows with option to select one to see
  * //$prefix//''+ n'' - next window
  * //$prefix//''+ p'' - previous window
  * //$prefix//''+ ,'' - name window
  * //$prefix//''+ %'' - split vertically
  * //$prefix//''+ "''  split horizontally


===== Robot Operating System (ROS) =====


Robot Operating System (ROS) [[https://www.ros.org/|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. 

Key aspects/buzzwords to know are:
  * **ROS architecture** - ROS uses a central node called **master** that registers all software modules (nodes) that want to communicate. The modules then communicate directly with each other using assigned ports. 
  * **master** - Can be started by calling ''roscore'' and needs to be always started first before other nodes. Its address is stored in the environment variable $ROS_MASTER_URI. 
  * **programming** - We will use //python 3//, but ROS also supports programming in //c%%++%%//.
  * **version** - We will use //ROS noetic// inside Ubuntu 20.04 inside singularity image.
  * **package** - Software in ROS is organized in packages. Usually, they contain individual nodes with different purposes.
  * **node** -  Executable program that runs some part of the robot's software and uses ROS to communicate with other nodes. Multiple instances with different name can run simultaneously.
  * **message** - ROS data type used to send information between //nodes//.
  * **topic** - Named communication channel for particular message types, e.g., camera image topic "/camera/image", that the nodes use to send/receive data from.
  * **publisher** - Part of a node that sends a //messages// of some type to a particular //topic//. There can be multiple publishers on the same topic.
  * **subscriber** - Part of a node that receives all //messages// of a particular //topic//. There can be multiple subscribers on the same topic.
  * **launch file** - Recipe that can start multiple nodes with given params simultaneously. 
  * **workspace** - Place for your project with multiple ROS packages.
  * **catkin** - CMake-based build system for ROS that builds your workspace packages. Also, auto-generates specified messages based on their definition.
  * **bag file** - File format in ROS for storing ROS message data allowing to log all transmitted messages within the robotic system.
  * **rosbag** - A command line tool for recording and playing back the recorded bag files.

The code for your projects with ROS is stored in a workspace.
<note important> Your workspace is created, built, and sourced automagically using the deploy/scripts/start_singularity_aro script. So no need to create your workspace manually.</note>

**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 singularity image:**
<code>
cd <where_you_want_the_workspace>
mkdir -p catkin_ws/src
cd catkin_ws
catkin init
catkin config --extend /opt/ros/aro
catkin build
source devel/setup.bash
</code>
This code initializes your workspace as an extension of the default ARO workspace. 
Then it calls the catkin 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 catkin 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.**

==== ROS in terminal ====
ROS has many handy command line programs that you can learn.

  * ''roscore'' - starts the ros master
  * ''rosnode list/info <node_name>/ping <node_name>/kill <node_name>'' - //list// shows all running nodes, //info// gives you information about a specified node, //ping// checks if you can contact the node, //kill// terminates the node
  * ''rostopic list/info <topic_name>/hz <topic_name>/echo <topic_name>/type <topic_name>/pub <topic_name> <topic_type> <data>'' - //list// shows all currently available topic names, //info// shows information about a given topic, //hz// shows frequency of messages published on a topic, //echo// prints all messages on a given topic, //type// shows message type of the topic, //pub// publishes a message to a topic
  * ''rosmsg list/show <message_type>/package'' - //list// shows all available messages, //show// displays the definition of a given message type, //package// lists messages of a certain package
  * ''roslaunch <package_name> <launch_filename>'' - launches the <launch_filename> of a given <package_name>
  * ''rosbag record/play/info'' - //record// a rosbag, //play// existing rosbag, //info// gives you information what is inside a rosbag
  * ''roscd <package_name>'' - goes into directory of a given package
  * ''rosrun <package_name> <node_name>'' - starts node <node_name> from package <package_name>
  * ''catkin build/clean/init/config'' - //build// workspace you are in, //clean// workspace you are in, //init// creates a new workspace in current folder, //config// - shows configuration of a workspace you are in


**Test the following individual commands. Use the tab for suggestions of node names, topic names, message types, etc.**
  - Start tmux and run the ''roscore''.
  - Create new tmux window and test all ''rosnode'' commands on default **/rosout** node.
  - Publish //std_msgs/String// message on topic ///new// with rate 10Hz using command ''rostopic pub /new std_msgs/String %%"%%data: 'whaaat'%%"%% -r 10''. Test other rostopic commands on this topic in new tmux window.
  - Test listing all available messages using ''rosmsg list'' and find out what messages are in std_msgs package. Show the definition of one of the message type.

==== ROS for python ====

In ROS noetic we will use python 3. The most important library that enables interfacing with ROS is //rospy//.
The typical content of a package folder in, e.g., catkin_ws/src/my_package/ is:

  * launch/ - folder with launch files
  * msg/ - folder with message definitions
  * src/ - folder with source codes where you can put your nodes
  * CMakeLists.txt - CMake build file
  * package.xml - file with information about the package used by the catkin

** Always make sure the python node is a runnable script ''chmod u+x <filename>.py'', otherwise you can not start it with rosrun or roslaunch.**
** Always make sure to ''source devel/setup.bash'' in your workspace after you build your workspace with ''catkin build''**. You need to build the workspace if you have new package, if you change c++ code or, e.g., message definitions. Changing python code does not require rebuilding.


\\
=== Initializing a node and running it ===

At the beginning of a python script you need to initialize the node such that it is registered within the ROS with ''rospy.init_node('my_node')'' command. 
Afterwards you can initialize all your subscribers, publishers, threaded workers, etc. 
Finally you need to run ''rospy.spin()'' which internally runs the messaging system of the node (especially important for subscribers to run callbacks for new messages).

\\
=== Printing ===

You can print messages within your package with different severity levels using:
  * ''rospy.loginfo('your message')''
  * ''rospy.logwarn('your warning message')''
  * ''rospy.logerr('your error message')''

\\
=== 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 ''rosmsg package std_msgs'').
Complex data types are composed of simple ones or their arrays (see, e.g., ''rosmsg info std_msgs/Header '').
Custom message files can be defined in message files and their respective c++ headers and python objects are generated during build.

\\
=== 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 = rospy.Publisher('message', String, queue_size=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)''.

\\
=== 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 = rospy.Subscriber('message', String , callback)''
,where the callback is a custom function (''def callback(msg):'') that handles the received message.

===== Lab task =====

Implement a simple publisher and subscriber nodes as specified below. 
You can get inspiration on how to write such python nodes in the following [[http://wiki.ros.org/ROS/Tutorials/WritingPublisherSubscriber%28python%29 | ROS tutorial]].
Both can be placed inside the aro_reactive_control/scripts of the student-packages.
  - Implement publisher inside ''publisher.py'' that publish String message from std_msgs package on topic "message" every one second.
  - Launch the publisher using rosrun.
  - Implement subscriber inside ''subscriber.py'' that receives the messages and prints them in the terminal.
  - Launch the subscriber using rosrun.
===== Homework 01 assignment =====

Follow the assignment of the homework [[courses:aro:tutorials:homework01|HW01]] which requires only some additional work compared to the lab task above.