The result of this tutorial can be found in bundles/tutorials_scripts if you followed the instructions at the bottom of this page
Abstract
This tutorial will show you how to use configuration files within bundles and how to apply configurations to compositions and components.
Presentation
Configuration files are YAML files in which the properties are listed and some values are assigned to them. For instance, when looking at the interface of the random motion generator:
[...er/bundles/tutorial]% rock-inspect --show-tasks tut_brownian
==========================================================
Task name: tut_brownian::Task
defined in tut_brownian
----------------------------------------------------------
------- tut_brownian::Task ------
no documentation defined for this task context model
subclass of RTT::TaskContext (the superclass elements are displayed below)
Ports
[out]cmd:/base/MotionCommand2D
[out]state:/int32_t
No dynamic ports
Properties
max_angular_speed:/double, default: 0.314159265358979
max_speed:/double, default: 1.5
min_speed:/double, default: 0.5
straight_duration:/double, default: 5
turn_duration:/double, default: 5
No attributes
No operations
We have 5 properties that configure our component. Let’s use a non-default value for the max_speed.
First, let’s use a tool to generate a file filled with default values. To do this, we first create configuration directory for our oroGen components in bundles/tutorials and then use the tool oroconf to generate default configuration files with the option:
oroconf extract tut_brownian::Task
The new template file is generated in the config/orogen subfolder of the bundle, with a file name that matches the oroGen model name (here, config/orogen/tut_brownian::Task.yml)
The YAML files in config/orogen/ must follow the modelname.yml template to be picked up by the system. In this case, the generated file has automatically be called tut_brownian::Task.yml
Have a look at the freshly created config/orogen/tut_brownian::Task.yml, and compare it to the values reported by rock-inspect.
Let’s now start a controller and start the ‘random’ definition. And have a look at the configuration values using rock-display. They should match the values in the configuration file.
syskit run scripts/03_defines.rb random_def!
As you see here, it is possible to specify definitions on the command line of
syskit run
, to avoid having to go through the shell for simple cases.
Multiple Component Configurations
The configuration files can contain multiple blocks separated by three dashes (—) and a name. Let’s add two new configurations. Change config/orogen/tut_brownian::Task.yml to look like:
--- name:default
# no documentation available for this property
max_angular_speed: 0.314159265358979
# no documentation available for this property
max_speed: 1.5
# no documentation available for this property
min_speed: 0.5
# no documentation available for this property
straight_duration: 5.0
# no documentation available for this property
turn_duration: 5.0
--- name:slow
max_speed: 0.5
min_speed: 0
--- name:fast
max_speed: 4
min_speed: 2
If nothing else is specified, the ‘default’ configuration is applied to newly configured components. If it does not exist, then no properties are written. When a different configuration is needed, configuration overlays can be selected: the parameters defined by some sections are overriden by other(s). For instance, the ‘default,slow’ configuration contains all values from default except for max_speed and min_speed that are set to the values in the ‘slow’ configuration.
In a definition, the requested configuration is selected with
define 'random_slow', Tutorials::RockControl.use(TutBrownian::Task.use_conf('default', 'slow'))
Which configuration is actually applied can be visualized in syskit
instanciate
(the conf: flag) and in roby-display (simply double-click on the
task you are interested in to see its arguments). Finally, you can see it in the
console output of syskit run
(only the relevant output lines are shown below).
# syskit run 03_defines.rb random_slow_def!
Bundles[INFO]: Active bundles: tutorial
/media/Data/dev/rock/master-full/tools/syskit/lib/syskit/models/deployment.rb:83: warning: already initialized constant Joystick
20:19:20.540 (Robot) applied configuration [default, slow] to /brownian
20:19:20.540 (Robot) setting up TutBrownian::Task:0x2d69690{orocos_name => brownian, conf => [default, slow]}[]
Multiple Composition Configurations
The information in the previous section covered the components. One can also define configurations on compositions. Since compositions do not actually have properties, they are defined differently though. Indeed, a composition configuration specify how the composition’s children should be configured (i.e. it “forwards” some configuration selection). For instance, the following declaration announces that Tutorials::RockControl has a ‘slow’ configuration, in which the ‘cmd’ child (the Tutorials::CommandGeneratorSrv) should be configured with ‘default,slow’. The configuration of the RockTutorialControl task is left open.
module Tutorials
class RockControl < Syskit::Composition
# Any command generator
add CommandGeneratorSrv, :as => "cmd"
# And one rock
add RockTutorial::RockTutorialControl, :as => "rock"
# Create any unique connection possible, by matching
# input and output ports of the same data type. If
# ambiguities exist, an error is generated
cmd_child.connect_to rock_child
conf 'slow', cmd_child => ['default', 'slow']
end
end
These configurations are selected in the same way. Note, however, that they cannot be overlaid.
define 'random_slow2',
Tutorials::RockControl.use(TutBrownian::Task).use_conf('slow')
Advanced The configurations are part of the deployment constraints. This means, in practice that if two deployments request a task to be deployed with two different configurations, the deployment will fail.
There is, for now, no ways to select configurations from the shell.
Summary
In this tutorial you learned:
- how to generate configuration files
- how to make them part of your definitions, at both the component and composition levels
The next tutorial will introduce you to handling some more complex setups.