====================
Commandline Commands
====================

.. contents:: :local:

Commandline Variables
=====================

.. code-block:: bash

   echo $<variable_name>        # To display value

   ROS_DISTRO                   # Distro name e.g. melodic
   ROS_ETC_DIR                  #
   ROS_LISP_PACKAGE_DIRECTORIES # common-lisp folder e.g. ~/catkin_ws/devel/share/common-lisp
   ROS_HOSTNAME                 # ros hostname e.g. localhost
   ROS_MASTER_URI               # ros master url e.g. http://localhost:11311
   ROS_PACKAGE_PATH             # package path's e.g. ~/catkin_ws/src:/opt/ros/$(ROS_DISTRO)/share
   ROS_PYTHON_VERSION           # python version 2 or 3 e.g. 2
   ROS_ROOT                     # ros installation e.g. /opt/ros/$(ROS_DISTRO)/share/ros
   ROS_VERSION                  # ros version 1 or 2 e.g. 1

Useful commands
===============

ROS tools
-------------

``roscore``
^^^^^^^^^^^^

Launch ROS ``master`` core

.. code-block:: bash

   roscore


``rosversion``
^^^^^^^^^^^^^^

.. code-block:: bash

   rosversion -d                             # Print ROS distro name
   rosversion <package_name>                 # Print package vrosnode


``rosparam``
^^^^^^^^^^^^

Nodes use the parameter server to store and retrieve parameters at runtime.

http://wiki.ros.org/rosparam

.. code-block:: bash

   rosparam list                             # list parameter names
   rosparam set /<parameter_name> <value>    # set parameter
   rosparam get /<parameter_name>            # get parameter
   rosparam delete /<parameter_name>         # delete parameter
   rosparam dump <file>                      # dump parameter to file
   rosparam load                             # load parameter from file

``rosnode``
^^^^^^^^^^^^

Work with ``nodes``

.. code-block:: bash

   rosnode list                              # list all nodes
   rosnode ping /<node_name>                 # check node connectivity
   rosnode info /<node_node>                 # print information about node
   rosnode machine                           # list nodes running on a particular machine
   rosnode kill /<node_name>                 # kill a running node


``rostopic``
^^^^^^^^^^^^

Work with ``topics``

.. code-block:: bash

   rostopic list                             # list all topics
   rostopic info /<topic_name>               # print information about active topic
   rostopic echo /<topic_name>               # print messages to screen
   rostopic pub /<topic_name> msg/MessageType "data:value" # pubish data to topic

   rostopic type /<topic_name>               # print topic or field type
   rostopic find <type>                      # find topics by type
   rostopic bw /<topic_name>                 # display bandwidth used by topic
   rostopic hz /<topic_name>                 # display publishing rate of topic

``roslaunch``
^^^^^^^^^^^^^^

To start a launch file which can contain multiple ``nodes``.

.. code-block:: bash

   roslaunch <ros_pkg_name> <launch_file_name> # Launch ros launch file

``rosrun``
^^^^^^^^^^

To run a ``node``

.. code-block:: bash

   rosrun <ros_pkg_name> <node_name>         # Start a ros node
   rosrun <PACKAGE_NAME><NODE_NAME> __name:=<INSTANCE_NAME> # Start another instance of a node, the parameter *INSTANCE_NAME* can be whatever you want, but it must be unique.

``rosservice``
^^^^^^^^^^^^^^^^

Work with ``services``

.. code-block:: bash

   rosservice list                           # list active services
   rosservice info <service_name>            # print information about service
   rosservice uri <service_name>             # print service ROSRPC

``rosbag``
^^^^^^^^^^

ROS offers the possibility to record the data published on topics into ``bag`` files :

#. create a directory to store the bag files:

   .. code-block:: bash

      ~/ mkdir ros_bag_files && cd ros_bag_files

#. run the *record* command :

   .. code-block:: bash

      rosbag record -O <bag_name>.bag <topic_name> <topic_name>

#. play the bag file :

   .. code-block:: bash

      rosbag play <bag_name>.bag

#. Compress a bag file :

   .. code-block:: bash

      # Option 1 : use BZ2 compression -> slow but bigger compression rate
      rosbag compress <bag_name>.bag

      # Option 2 : use LZ4 compression -> much faster, but smaller compression rate
      rosbag compress --lz4 <bag_name>.bag

#. Decompress a compressed bag file :

   .. code-block:: bash

      rosbag decompress <bag_name>.bag

#. Repair a broken bag file (happens when there is a *.bag.active* file instead of a *.bag* file):

   .. code-block:: bash

      rosbag reindex <bag_name>.bag.active
      rosbag fix <bag_name>.bag.active <fixed_bag_name>.bag

#. Shorten a bag file :

   .. code-block:: bash

      rosbag filter <input>.bag <output>.bag "t.secs >= <timestamp>"

Many options are available for the *rosbag* command, see `this page <http://wiki.ros.org/rosbag/Commandline>`_ for more details.

.. note::
   To play a bag with several pointclouds at different position, it is better to have the following topics recorded:

   * ``/cloud``
   * ``/tf_static``

   The `/tf_static` is helpful to visualize in RViz

   .. code-block:: bash

      rosbag record -O cloud.bag /cloud /tf_static

``rosmsg``
^^^^^^^^^^

Display information about ros ``messages``.

.. code-block:: bash

   rosmsg list                     # List all messages
   rosmsg info <message_name>      # Show message description
   rosmsg package <package_name>   # List messages in a package
   rosmsg packages <package_name>  # List packages that contain messages

Other Commands
^^^^^^^^^^^^^^

.. code-block:: bash

   roscd <PKG_NAME>                 # move to the folder of the package

   rosinstall <PKG_NAME>            # install a ROS package

   rosdep <PKG_NAME                 # install all the dependencies of a package

   rqt                              # tool with many plug-ins available such as topic publisher, service caller, …

   rqt_graph                        # display the connections between nodes

   rviz                             # launch the graphical tool to visualize robots, point clouds, …

   view_frames                      # create a PDFcalled ``frames.pdf`` with the TF frames that are active
   evince frames.pdf                # show with evince the generated frames.pdf

Catkin
-------

More info:

* http://wiki.ros.org/catkin/Tutorials

Create Package
^^^^^^^^^^^^^^

#.  new terminal
#.  navigate to the source folder of the catkin workspace : ``.../catkin_ws/src``
#.  run : ``catkin_create_pkg <PACKAGE_NAME> <DEPENDENCIES>``
#.  update both CMakeLists.txt and package.xml
    note : *run_depend* has to be replaced by the *exec_depend*
#.  write source code in the source folder of the package :
#.  build the catkin workspace with the alias command : ``cm``
#.  launch the master as explained [here](ros-commands.md#roscore).
#.  now launch the node as explained [here](#roslaunch) and [here](rosrun).

.. code-block:: bash

   catkin_create_pkg <PKG_NAME> <PKG_DEPENDENCIES> # create a package, must be called inside a catkin workspace

Build
^^^^^^

.. code-block:: bash

   cm
   catkin_make                                     # build the whole workspace
   catkin_make <PKG_NAME>                          # build a single package

Install
^^^^^^^^

.. code-block:: bash

   catkin_make install                             # installs all executables
   catkin_make install <PKG_NAME>                  # installs single executables

Python modules
^^^^^^^^^^^^^^

Tips :

* put the script in a folder called *scripts*
* make sure to run ``chmod +x <script_name>.py`` so that the script is recognized as an executable by ROS


Update services with RQT
=========================

#.  launch *RQT* from a new terminal : run ``rqt``
#.  Search for the plugin *Service Caller*
#.  Choose the service that you want to update
#.  Fill the *expression* field with an expected parameter of this service
#.  Call the service and the response is displayed

:tag:`ROS`