diff --git a/articles/151_roslaunch_xml.md b/articles/151_roslaunch_xml.md new file mode 100644 index 000000000..ffcfae976 --- /dev/null +++ b/articles/151_roslaunch_xml.md @@ -0,0 +1,255 @@ +--- +layout: default +title: ROS 2 Launch XML Format +permalink: articles/roslaunch_xml.html +abstract: + The XML format for declarative launch descriptions in the ROS 2 launch system. +author: '[Michel Hidalgo](https://github.com/hidmic)' +published: false +--- + +- This will become a table of contents (this text will be scraped). +{:toc} + +# {{ page.title }} + +
+{{ page.abstract }} +
+ +Authors: {{ page.author }} + + +# ROS 2 Launch XML Format v0.1.0 + +## Rationale + +As an alternative to a programmatic approach to the ROS 2 launch system's API, a declarative description features a WYSIWYG approach, easier to read, audit and maintain. +This is the preferred approach for ROS 1 `roslaunch` launch files, thus some degree of familiarity is expected (and relied upon). + +The body of such a description is mainly comprised of statically declared launch actions with a prescribed configuration. +To that, runtime value substitution is added in order to fullfill common dynamic (re)configuration needs like conditional execution, resource lookups, etc. +It is intended for these entities to map to those of the underlying implementation, reducing support to file parsing. + +This article describes XML aiming to ease the bridge between ROS and ROS 2 launch files. +YAML is currently supported too, and other markup languages could be added. + +## Static Description + +### Schema Definition + +```xml +{% include_relative specs/launch.0.1.0.xsd %} +``` + +### Tags Semantics + +#### All Tags + +Every tag's execution can be conditioned on a boolean predicate via `if` or `unless` attributes. + +#### `` Tag + +Root tag of any launch file. +There must only be one `` tag on a given launch file. + +#### `` Tag + +##### Description + +The `` tag allows for bringing a launch file description into another, enabling re-use of hierarchical launch layouts. +The included launch file description has its own scope for launch configurations. +The included launch file description is not necessarily written in this format nor a declarative one (i.e. a programmatic description). + +##### Examples + +```xml + + + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for launch actions' grouping as well as optional launch file configuration scoping. + +##### Examples + +```xml + + + + +``` + +#### `` Tag + +##### Description + +The `` tags allows for definition of scoped launch file configuration variables. + +##### Examples + +``` + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for launch file configuration via the command-line or when including it via an `` tag. +Arguments are launch configuration variables just like the ones defined by `` tags. +Arguments are limited to the scope of their definition and thus have to be explictly passed to included files if any. + +##### Examples + +```xml + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for executing a ROS node in the form of local OS process. + +##### Examples + +```xml + + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for setting ROS parameters of a ROS node. +These can be scalar values or sequences of scalar values, defined directly or +either nested or brought from a YAML file to make a map. + +##### Examples + +```xml + + + + + + + + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for ROS name remapping of a `` instance. + +##### Examples + +```xml + + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for modifying an OS process environment. +It can be used nested in `node` or `executable` tags. +It doesn't allow conditional execution. + +##### Examples + +```xml + + + + + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for modifying an OS process environment. +It can be used nested in `launch` or `group` tags. +It allows conditional execution. + +##### Examples + +```xml + + + +``` + +#### `` Tag + +##### Description + +The `` tag allows for deleting an OS process environment variable. +It can be used nested in `launch` or `group` tags. +It allows conditional execution. + +##### Examples + +```xml + + + +``` + +## Dynamic Configuration + +### Substitution Syntax + +All substitutions are enclosed by `$(...)`. + +### Built-in Substitutions + +`$(find-package )` +: Substituted by the path to package installation directory in the local filesystem. + Forward and backwards slashes will be resolved to the local filesystem convention. + Substitution will fail if the package cannot be found. + +`$(find-exec )` +: Substituted by the path to the executable in the local filesystem. + Lookups make use of the PATH environment variable. + Forward and backwards slashes will be resolved to the local filesystem convention. + Substitution will fail if the executable cannot be found. + +`$(var )` +: Substituted by the value of the launch configuration variable. + Substitution will fail if the named argument does not exist. + +`$(env [default-value])` +: Substituted by the value of the given environment variable + Substitution will fail if the variable is not set, unless a default value is provided. + +`$(dirname)` +: Substituted by the current launch file directory name. + Substitution will always succeed. + +#### User-defined Substitutions + +TBD diff --git a/articles/specs/launch.0.1.0.xsd b/articles/specs/launch.0.1.0.xsd new file mode 100644 index 000000000..9c0a653b4 --- /dev/null +++ b/articles/specs/launch.0.1.0.xsd @@ -0,0 +1,612 @@ + + + + + ROS 2 launch XML schema v0.1.0 + + + + + + + The root element of a launch file. + + + + + + + A collection of actions to be launched in order of appearance, plus + launch arguments for callers to provide, either through a tool or + by inclusion. + + + + + + + Declares launch file-level arguments. + + + + + + + + Name of the launch argument. + + + + + + + Fixed value for the launch argument, disables overrides. + + + + + + + Default value for the launch argument, used if non is provided. + + + + + + + Brief description of the launch argument. + + + + + + + + + + + + + + + + + Launch XML schema version in use. + + + + + + + + + + + + + + Defines a launch configuration variable. + + + + + + + + Name of the launch configuration variable. + + + + + + + Value for the launch configuration variable. + + + + + + + + + + Includes another launch file, either descriptive or programmatic. + + + + + + + + Path to the launch file to be included. + + + + + + + A predicate to condition launch inclusion i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition launch inclusion i.e. do + so unless the predicate evaluates to a truthy value. + + + + + + + Arguments for the included launch file, if any. + + + + + + + An included launch file argument provision. + + + + + + + + Name of the launch argument. + + + + + + + Value for the launch argument. + + + + + + + + + + + + + Groups and optionally scopes a set of actions. + + + + + + + + The actions that make up the group. + + + + + + + + + + + + + + Whether the group is a scoping one launch configuration-wise or not. + + + + + + + A predicate to condition group launch i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition group launch i.e. do + so unless the predicate evaluates to a truthy value. + + + + + + + + + + Modifies an executable process environment. + + + + + + + + Name of the environment variable to be set. + + + + + + + Value to be set for the environment variable. + + + + + + + + + + Modifies an executable process environment. + + + + + + + + Name of the environment variable to be set. + + + + + + + Value to be set for the environment variable. + + + + + + + A predicate to condition executable launch i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition executable launch i.e. do so unless + the predicate evaluates to a truthy value. + + + + + + + + + + Modifies an executable process environment. + + + + + + + + Name of the environment variable to be set. + + + + + + + A predicate to condition executable launch i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition executable launch i.e. do so unless + the predicate evaluates to a truthy value. + + + + + + + + + + Executes an executable as a local OS process. + + + + + + + A collection of environment variable settings for the + launched executable. + + + + + + + + + Path to the executable or a command-line if a + shell is used to launch. + + + + + + + The working directory for the launched process. + + + + + + + A name or label for the launched executable. + + + + + + + Additional 'command-line' arguments for the executable. + + + + + + + Whether to use a shell to launch or not. + + + + + + + A prefix for the executable command-line if a shell is used to launch. + + + + + + + Output type for the launched executable. + + + + + + + + Executable output goes to a log file. + + + + + + + Executable output goes to stdout. + + + + + + + + + + A predicate to condition executable launch i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition executable launch i.e. do so unless + the predicate evaluates to a truthy value. + + + + + + + + + + Sets a ROS parameter for the enclosing node to a scalar + value, a sequence of scalar values delimited by a known + separator or a sequence of nested named parameters, either + defined in place or in a file to be loaded. + + + + + + + + A collection of nested ROS parameters to be set. + + + + + + + + + Name of the ROS parameter to be set. + + + + + + + Value or list of values to set the the ROS parameter with. + + + + + + + Value separator when dealing with list of values. + + + + + + + Path to the parameters file to be loaded. + + + + + + + + + + + Remaps ROS names for a node. + + + + + + + + Name matching expression to look for replacement candidates. + + + + + + + Name replacement expression to replace candidates found. + + + + + + + + + + Executes a ROS node executable in a local OS process. + + + + + + + + A collection of ROS parameters, ROS remappings and/or + environment variable settings for the launched ROS node. + + + + + + + + + + + + Name of the package where the node is to be found. + + + + + + + Name of the node executable. + + + + + + + A name for the launched ROS node. + + + + + + + Additional 'command-line' arguments for the ROS node. + + + + + + + A ROS namespace to scope the launched ROS node. + + + + + + + A prefix for the ROS node command-line used for launch. + + + + + + + Output type for the launched ROS node. + + + + + + + + ROS node output goes to a log file. + + + + + + + ROS node output goes to stdout. + + + + + + + + + + A predicate to condition ROS node launch i.e. only do + so if the predicate evaluates to a truthy value. + + + + + + + A predicate to condition ROS node launch i.e. do so unless + the predicate evaluates to a truthy value. + + + + +