From b5e3177db06424c1b13b7ac237d94badb4100413 Mon Sep 17 00:00:00 2001 From: ivanpauno Date: Tue, 27 Aug 2019 09:37:22 -0300 Subject: [PATCH] Launch file migration guide (#302) Signed-off-by: ivanpauno --- source/Tutorials.rst | 1 + .../Launch-files-migration-guide.rst | 403 ++++++++++++++++++ 2 files changed, 404 insertions(+) create mode 100644 source/Tutorials/Launch-files-migration-guide.rst diff --git a/source/Tutorials.rst b/source/Tutorials.rst index 7a73d90476..0122339ca0 100644 --- a/source/Tutorials.rst +++ b/source/Tutorials.rst @@ -19,6 +19,7 @@ Basic Tutorials/RQt-Port-Plugin-Windows Tutorials/Node-arguments Tutorials/Launch-system + Tutorials/Launch-files-migration-guide Tutorials/Working-with-multiple-RMW-implementations Tutorials/Composition Tutorials/Rosidl-Tutorial.rst diff --git a/source/Tutorials/Launch-files-migration-guide.rst b/source/Tutorials/Launch-files-migration-guide.rst new file mode 100644 index 0000000000..6a946bd0c9 --- /dev/null +++ b/source/Tutorials/Launch-files-migration-guide.rst @@ -0,0 +1,403 @@ +Migrating launch files from ROS 1 to ROS 2 +========================================== + +.. contents:: Table of Contents + :depth: 1 + :local: + +This tutorial describes how to write XML launch files for an easy migration from ROS 1. + +Background +---------- + +A description of the ROS 2 launch system and its Python API can be found in `Launch System tutorial `. + + +Migrating tags from ROS1 to ROS2 +-------------------------------- + +launch +^^^^^^ + +* `Available in ROS 1 `__. +* ``launch`` is the root element of any ROS 2 launch XML file. + +node +^^^^ + +* `Available in ROS1 `__. +* Launches a new node. +* Differences from ROS 1: + * ``type`` attribute is now ``executable``. + * The following attributes aren't available: ``machine``, ``respawn``, ``respawn_delay``, ``clear_params``. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + + +param +^^^^^ + +* `Available in ROS1 `__. +* Used for passing a parameter to a node. +* There's no global parameter concept in ROS 2. + For that reason, it can only be used nested in a ``node`` tag. + Some attributes aren't supported in ROS 2: ``type``, ``textfile``, ``binfile``, ``executable``, ``command``. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + + + +Type inference rules +~~~~~~~~~~~~~~~~~~~~ + +Here are some examples of how to write parameters: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + +Parameter grouping +~~~~~~~~~~~~~~~~~~ + +In ROS 2, ``param`` tags are allowed to be nested. +For example: + +.. code-block:: xml + + + + + + + + + + +That will create two parameters: + +* A ``group1.group2.my_param`` of value ``1``, hosted by node ``/an_absolute_ns/my_node``. +* A ``group1.another_param`` of value ``2`` hosted by node ``/an_absolute_ns/my_node``. + +It's also possible to use full parameter names: + +.. code-block:: xml + + + + + + +rosparam +^^^^^^^^ + +* `Available in ROS1 `__. +* Loads parameters from a yaml file. +* It has been replaced with a ``from`` atribute in ``param`` tags. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + +remap +^^^^^ + +* `Available in ROS 1 `__. +* Used to pass remapping rules to a node. +* It can only be used within ``node`` tags. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + + + + + + +include +^^^^^^^ + +* `Available in ROS 1 `__. +* Allows including another launch file. +* Differences from ROS 1: + * Available in ROS 1, included content was scoped. + In ROS 2, it's not. + Nest includes in ``group`` tags to scope them. + * ``ns`` attribute is not supported. + See example of ``push_ros_namespace`` tag for a workaround. + * ``arg`` tags nested in an ``include`` tag don't support conditionals (``if`` or ``unless``). + * There is no support for nested ``env`` tags. + ``set_env`` and ``unset_env`` can be used instead. + * Both ``clear_params`` and ``pass_all_args`` attributes aren't supported. + +Examples +~~~~~~~~ + +See `Replacing an include tag`_. + +arg +^^^ + +* `Available in ROS 1 `__. +* ``arg`` is used for declaring a launch argument, or to pass an argument when using ``include`` tags. +* Differences from ROS 1: + * ``value`` attribute is not allowed. + Use ``let`` tag for this. + * ``doc`` is now ``description``. + * When nested within an ``include`` tag, ``if`` and ``unless`` attributes aren't allowed. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + + + + + + + +Passing an argument via the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See `ROS 2 launch tutorial `__. + + +env +^^^ + +* `Available in ROS 1 `__. +* Sets an environment variable. +* It has been replaced with ``env``, ``set_env`` and ``unset_env``: + * ``env`` can only be used nested in a ``node`` or ``executable`` tag. + ``if`` and ``unless`` tags aren't supported. + * ``set_env`` can be nested within the root tag ``launch`` or in ``group`` tags. + It accepts the same attributes as ``env``, and also ``if`` and ``unless`` tags. + * ``unset_env`` unsets an environment variable. + It accepts a ``name`` attribute and conditionals. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + + + + + + + + + + + +group +^^^^^ + +* `Available in ROS 1 `__. +* Allows limiting the scope of launch configurations. + Usually used together with ``let``, ``include`` and ``push_ros_namespace`` tags. +* Differences from ROS 1: + * There is no ``ns`` attribute. + See the new ``push_ros_namespace`` tag as a workaround. + * ``clear_params`` attribute isn't available. + * It doesn't accept ``remap`` nor ``param`` tags as children. + +Example +~~~~~~~ + +``launch-prefix`` configuration affects both ``executable`` and ``node`` tags' actions. +This example will use ``time`` as a prefix if ``use_time_prefix_in_talker`` argument is ``1``, only for the talker. + +.. code-block:: xml + + + + + + + + + + +machine +^^^^^^^ + +It is not supported at the moment. + +test +^^^^ + +It is not supported at the moment. + +New tags in ROS 2 +----------------- + +set_env and unset_env +^^^^^^^^^^^^^^^^^^^^^ + +See `env`_ tag decription. + +push_ros_namespace +^^^^^^^^^^^^^^^^^^ + +``include`` and ``group`` tags don't accept an ``ns`` attribute. +This action can be used as a workaround: + +.. code-block:: xml + + + + + + + + + + + + + + + + + +let +^^^ + +It's a replacement of ``arg`` tag with a value attribute. + +.. code-block:: xml + + + +executable +^^^^^^^^^^ + +It allows running any executable. + +Example +~~~~~~~ + +.. code-block:: xml + + + + + +Replacing an include tag +------------------------ + +To have exactly the same behavior as Available in ROS 1, ``include`` tags must be nested in a ``group`` tag. + +.. code-block:: xml + + + + + +To replace the ``ns`` attribute, ``push_ros_namespace`` action must be used: + +.. code-block:: xml + + + + + + +Substitutions +------------- + +Documentation about ROS 1's substitutions can be found in `roslaunch XML wiki `__. +Substitutions syntax hasn't changed, i.e. it still follows the ``$(substitution-name arg1 arg2 ...)`` pattern. +There are, however, some changes w.r.t. ROS 1: + +* ``env`` and ``optenv`` tags have been replaced by the ``env`` tag. + ``$(env )`` will fail if the environment variable doesn't exist. + ``$(env '')`` does the same as ROS 1's ``$(optenv )``. + ``$(env )`` does the same as ROS 1's ``$(env )`` or ``$(optenv )``. +* ``find`` has been replaced with ``find-pkg``. +* There is a new ``exec-in-pkg`` substitution. + e.g.: ``$(exec-in-pkg )``. +* There is a new ``find-exec`` substitution. +* ``arg`` has been replaced with ``var``. + It looks at configurations defined either with ``arg`` or ``let`` tag. +* ``eval`` and ``dirname`` substitutions haven't changed. +* ``anon`` substitution is not supported. + +Type inference rules +-------------------- + +The rules that were shown in ``Type inference rules`` subsection of ``param`` tag applies to any attribute. +For example: + +.. code-block:: xml + + + + + + + + + + + + + + +Some attributes accept more than a single type, for example ``value`` attribute of ``param`` tag. +It's usual that parameters that are of type ``int`` (or ``float``) also accept an ``str``, that will be later substituted and tried to convert to an ``int`` (or ``float``) by the action.