the Robot Construction Kit

Configuration Files

Instead of writing configuration values in a Ruby script, one can also write down the configuration of a whole task in a YAML file, that then gets loaded through the Ruby API.

The benefits of doing it this way is twofold:

  • one can store multiple parallel configurations in the same file and select them by their name (as e.g. the “static” and “sweeping” configurations for a pan-tilt unit)
  • this is the way configuration is handled in Rock’s system management layer, so – if you use these files – you will be able to share these configurations between the system management and pure ruby scripts.

Configuration files are YAML files with a specific format. These files specify values for task ‘'’properties’’’ (which are supposed to describe the configuration interface of a component).

This page will cover the configuration file format and how these files can be used in Ruby scripts.

Configuration file format

  • configuration files are YAML sections separated by some section declarations
  • a file contains multiple configurations for a single type of tasks (i.e. configurations for the hokuyo::Task tasks)

It looks like:

--- name:default
port: /dev/ttyS1
--- name:with_remission
remission_values: true

The above example defines two possible configurations for the hokuyo::Task task context. The two configurations have names (default and with_remission).

Using single configuration files

Store configuration(s) in a single file of the format described above. Then, use orocos.apply_conf_file with the file name and the configurations that should be applied.

For instance,

task = Orocos.name_service.get 'hokuyo'
Orocos.apply_conf_file(task, 'hokuyo.yml', ['default', 'with_remission'])

In the list of configuration names, later values will override newer ones. So, if hokuyo.yml contains

--- name:default
port: /dev/ttyS1
remission_values: false
--- name:with_remission
remission_values: true

Then the resulting configuration, above, will be

port: /dev/ttyS1
remission_values: true

Configuration directories

A “configuration database” can be created in a directory by creating files whose name is the task model name. For instance, the hokuyo configuration file would be named ‘'’hokuyo::Task.yml’’’

Given such a directory, one can load all the configurations at once and apply them more easily:


task = Orocos.name_service.get 'hokuyo'
Orocos.conf.apply(task, ['default', 'with_remission'])

Multiple directories can be loaded. When loading a new directory, if a configuration is found with the same name than an existing configuration, the new one takes precedence.

The main advantage of this method over the simple script method above is that it is compatible with the system management system: one can share configurations between ruby scripts and the supervision system this way

Generating configuration files from the tasks

The easiest way to start a new configuration file is to create one from the default values of a task:

oroconf extract model_name

For instance, to get a fresh configuration file for a hokuyo::Task task, one does

oroconf extract hokuyo::Task

You can also specify a file to save it into

oroconf extract hokuyo::Task --save=hokuyo.yml

Or, if you use the directory configuration storage described above, give the directory directly

oroconf extract hokuyo::Task --save=config/orogen/

Generating configuration files from property logs

Since you are using Orocos.log_all in your Ruby scripts, a properties.0.log file is being generated by the script, in which the changes to the task’s configurations are saved. This data can be transformed into a proper configuration file using oroconf as well:

oroconf logextract properties.0.log task_name timespec

where timespec can either be a number of seconds since epoch (as reported by pocolog properties.0.log -s stream_name --time) or the keyword @last. If @last is given, the last sample in each relevant configuration streams is taken.