Skip to main content

Launch files

Basis launch files are yaml files consisting of one or two documents (separated by ---). If there are two documents, the first is args, the second is content. If there is just one document, it's just content.

Args

args: 
camera_topic_namespace:
type: string
help: the prefix to use for this pipeline's topics
default: /camera
enable_perception:
type: bool
help: run object detection on this camera
default: True
additional_log_pattern:
type: string
help: an optional, additional log pattern to pass to the recorder
optional: True

The args document must always contain a map named args. Currently, no other keys are valid. This is a mapping from argument name to argument definition.

⚠️ Do not use inja templating in the args document - it will not be processed.

Argument Definition

A single argument used for this launch file, with type safety. May be optional or supply a default.

type

The type to use for this argument. Any arguments passed to the launch file will be converted to these types, with range checking.

  • bool - 0/1/true/false, case insensitive
  • string - any string (converted to std::string)

Floating point types, can use scientific notation:

  • float - any floating point number
  • double - any floating point number, double precision

Any cpp integer type, with range checking:

  • uint8_t
  • int8_t
  • uint16_t
  • int16_t
  • uint32_t
  • int32_t
  • uint64_t
  • int64_t

help

Default: ""

A string describing this argument. Used when displaying error messages about the arguments a launch file requires.

default

Mutually exclusive with optional

When no user supplied value is supplied, this will be used. Must be convertable to type. There is currently no syntax for defaulting to the value of another arg, but use of inja variables can avoid this.

optional

Mutually exclusive with default

Don't throw an error when this argument isn't supplied.

Launch content

The data containing units to be launched and other information about the launch. This document is first preprocessed using inja - https://github.com/pantor/inja. Please see inja's documentation for usage - if you're familiar with jinja2, it's nearly the same. Jinja itself isn't used due to python dependency. jinja2cpp was also considered, but not used for now due to boost dependency.

Using inja enables lifting out functionality such as filtering and argument handling from the launch system to an already written preprocessor.

When preprocessing, all values for args will be supplied in an inja variable named args. Future updates will add other variables.

Some other notes:

  • inja currently requires double quotes " for strings, single quotes ' are not allowed
  • inja doesn't use filter expressions like jinja - think lower("MY_STRING") instead of "MY_STRING" | lower.
  • Take care when using inja includes - they aren't well tested and are tricky to get correct with regular yaml syntax (consider using json style syntax in these cases)

Recording settings

recording:
directory: /tmp/
name: camera_pipeline
topics:
- /log
- */image/*

Settings used for recording. Currently only used for the top level launch file in a launch. Included recording settings are ignored Recording settings are applied to every process in the launch.

⚠️ Recording syntax is WIP - future updates will enable features such as the ability to record to multiple files, more customizable names, and per process recording settings

directory

The directory to write the records to.

name

The prefix of the record file. Generally, records will be named as ${name}_${process_name}_${timestamp}.mcap

topics

A list of topic globs to be used as a filter when recording.

Group Definition

# The root of the document is also a group named "/"!
groups:
parent:
groups:
child: # /parent/child
process: True
units:
foxglove: {} # named as /parent/child/foxglove
include:
- awesome.launch.yaml: # all units/processes with /parent
my_string_arg: foobar
my_int_arg: 33

A group is a collection of units. Groups may recursively define other groups. The root of the document is a group named / with some special properties.

groups

Defines child groups for this group. Will concatenate the names together with / as a separator.

include

Includes a child launch file. Arguments are passed as a simple map, with type checking. Recursive includes are allowed up to a depth of 32. Groups and units will be prefixed with the current group name.

⚠️ Clever use of includes can result in units or processes with the same name as others from different files. This is not allowed and will cause a launch error.

Both:

    include:
- camera.launch.yaml:
camera: front
- camera.launch.yaml:
camera: back

and

    include:
camera.launch.yaml:
camera: front
lidar.launch.yaml:
lidar: front

are valid: the second is more natural, but the first is required to include the same file twice.

process

Default: false

When set to true, will split this group into a separate process when launching. Not valid for the root group in a document (it's implicitly true for the main launch file, and implicitly false for any included launch files).

⚠️Process syntax is experimental and subject to change.

units

Units to launch in this group. See Unit Definition.

Unit Definition

  units:
foxglove:
args:
port: 3344
camera_driver_{{args.device}}:
type: v4l2_camera_driver
args:
device: {{args.device}} # Templated into the launch file args
topic_namespace: {{args.camera_topic_namespace}}

A unit to run with this launch. The key the unit has in the units field is the name, and by default also the type.

type

default: (the name of the unit)

The type of unit to be launched. If not specified, will be the name of the unit.

args:

The arguments to be passed to the unit. Has the exact same semantics as launch file args, with type checking - the only difference is that they are in the content section of the launch file, and thus can be filled with templated values (including launch argument values). See [Argument Definition](#Argument Definition)