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..a326598c74 --- /dev/null +++ b/source/Tutorials/Launch-files-migration-guide.rst @@ -0,0 +1,318 @@ +.. redirect-from:: + + Launch-filse-migration-guide + +Migrating ROS 1 launchfiles +=========================== + +Background +---------- + +A description of the ROS 2 launch system and its python api can be found in `this tutorial`. +In this tutorial, will be describe how to write XML launch files, which allow an easy migration from ROS 1. + + +Migrating tags from ROS1 to ROS2 +-------------------------------- + +In each subsection, we will describe how to get the same behavior in ros 2. + +launch +^^^^^^ + +`This tag `__ hasn't been changed. +It works as the root element of any ROS 2 XML launch file. +The deprecated attribute isn't available. + +node +^^^^ + +As in `ROS1 `__, it allows launching a new node. +This table summarize some attribute renaming needed when porting ROS 1 launchfiles to ROS 2. +If the attribute is not available, it's indicated with ATTNA. + +.. list-table:: + :header-rows: 1 + + * - Attribute + - ROS 2 equivalent + * - pkg + - package + * - type + - executable + * - machine + - ATTNA: No implementation in current ros 2 launch. + * - respawn + - ATTNA: Similar functionality will be available after adding event handlers to the XML format. + * - respawn_delay + - ATTNA + * - clear_params + - ATTNA: Global parameters are not allowed in ROS 2. + +param +^^^^^ + +ROS 2 doesn't allow global parameter. +This tag can only be used nested in a node tag. +`ROS 1 reference `__. + +.. list-table:: + :header-rows: 1 + + * - type + - ATTNA: See type deduction rules below. + * - textfile + - ATTNA + * - binfile + - executable + * - command + - ATTNA + +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: + - ``group1.group2.my_param`` of value ``1``, hosted by node ``/an_absolute_ns/my_node``. + - ``group1.another_param`` of value ``2`` hosted by node ``/an_absolute_ns/my_node``. + +rosparam +^^^^^^^^ + +`This tag `__ can be replaced using ``from`` attribute in ``param`` tag. +For example: + +.. code-block:: xml + + + + + +remap +^^^^^ + +Its usage is the same as in `ROS 1 `__. + +machine +^^^^^^^ + +There's not implementation of this feature in ROS 2 at the moment. +Contributions are welcomed. + +include +^^^^^^^ + +There is some difference from how it worked in ROS 1: + +* In ros1, includes were scoped. + In ROS 2, they should be nested inside a ``group`` tag for this. +* ``ns`` attribute is not supported. + See example of ``push_ros_namespace`` tag for a workaround. +* ``pass_all_args`` hasn't been implemented. + It will be added in the future. +* ``clear_params`` attribute won't be supported. +* ``arg`` tags nested in ``include`` tag doesn't support conditionals (``if`` or ``unless``). +* There is not support of ``env`` child tags. ``set_env`` and ``unset_env`` can be used as a workaround. + +arg +^^^ + +Similar behavior to `ROS 1 tag `__. +There are some minor changes: + +* ``value`` attribute is not allowed. + Use ``let`` tag for this. +* ``doc`` is now ``description``. +* When used nested in an include action, ``if`` and ``unless`` attributes aren't allowed. + +Passing an argument via the command line +"""""""""""""""""""""""""""""""""""""""" + +See `ROS 2 launch tutorial `__. + + +env +^^^ + +This has been replaced with ``env``, ``set_env`` and ``unset_env``. + +* ``env`` can be used nested in a ``node`` or ``executable`` tag. + It accepts the same attributes as the `ROS 1 version `__, except ``if`` and ``unless`` condition. +* ``set_env`` can be used in the root tag ``launch``. + It also accepts the same attributes, including conditionals. +* ``unset_env`` unsets an environment variable. + It accepts a ``name`` attribute, and conditionals. + +group +^^^^^ + +There is some differences with `ROS 1 tag `__. + +* There is not ``ns`` attribute. + See the new ``push_ros_namespace`` tag as a workaround. +* ``clear_params`` attribute won't be available. +* It doesn't accept ``remap`` and ``param`` tags as children. + +machine and test +^^^^^^^^^^^^^^^^ + +They aren't supported at the moment. + +New tags +^^^^^^^^ + +set_env and unset_env +""""""""""""""""""""" + +See ``env`` tag decription. + +push_ros_namespace +"""""""""""""""""" + +``include`` and ``group`` tags don't accept ``ns`` attribute. +This action can be used as a workaround: + +.. code-block:: xml + + + + + + + + + + + + + + + + + +let +""" + +It replaces ``arg`` tag with value attribute. + +.. code-block:: xml + + + +executable +"""""""""" + +Allows running any executable. +For example: + +.. code-block:: xml + + + + + +Replacing include tag +^^^^^^^^^^^^^^^^^^^^^ + +For having exactly the same behavior as ROS 1, they should be nested in a ``group`` tag. + +.. code-block:: xml + + + + + +For replacing the ``ns`` attribute usage: + +.. code-block:: xml + + + + + + +Substitutions +------------- + +Substitutions syntax haven't changed, it's still ``$(sub-name val1 val2 ...)``. +There are some changes with ROS 1: + +* There is not ``env`` alternative. + ``optenv`` has been renamed as ``env``. +* ``find`` has been replaced with ``find-package``. +* There is a new ``exec_in_package`` substitution. + e.g.: ``$(exec_in_package package_name exec_name)`` +* There is a new ``find-exec`` substitution. +* ``anon`` hasn't an alternative at the moment. +* ``arg`` has been replaced with ``var``. + It looks at configurations defined with ``arg`` or ``let`` tag. +* It has not alternative at the moment. +* ``dirname`` has the same behaviour as before. + +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.