wiki:Configuration

Version 2 (modified by tim, 2 years ago) (diff)

Added TOC and note on the Emacs YAML mode

Fawkes Configuration

The Fawkes configuration is stored in text files using the YAML syntax. It is represented as a structured tree where the actual configuration values are stored in the leafs and have explicit basic types. Values are accessed with path-like specifiers within the software, e.g. /fawkes/example-value.

The configuration has an immutable and a mutable part. The mutable part is called host-specific configuration and is stored in a specifically designated file, usually callled host.yaml. On issuing configuration setting operations the values are written to the hosts file. The other immutable configuration files might contain the same path, they are not updated. The value is overwritten on loading because the host-specific configuration is always loaded last.

An Example

%YAML 1.2
%TAG ! tag:fawkesrobotics.org,cfg/
---
# Configuration meta information document
include:
  # reads files ending in .yaml from modules.d config subdir
  - !ignore-missing modules.d/
  # Reads the host-specific configuration file, no failure if missing
  - !host-specific host.yaml
---
# Main configuration document
fawkes:
  example: value

YAML supports storing multiple documents within one file. For a Fawkes configuration, you can have one or two documents in the file separated by three dashes (---). The first document, if it exists, is used to store meta data for the configuration process. In the example, we specify files to be included that contain additional configuration. The second (or only document in the case there is only one) is the actual configuration. It consists of nested maps, which make up the tree. For now, sequences of values are not supported in the configuration, but they are used in the meta document. In the given example configuration there would be a single value accessible with the path /fawkes/example of inferred type string and with the value value.

The first two lines specify the used YAML version and a tag shortcut. The exclamation mark tag identifier is mapped to the Fawkes configuration tag space. In the meta document we use two such tags to define special behavior on the values.

A more complete example can be found in the repository.

Meta Configuration

The meta document is used by the configuration process for additional settings. For now, the following fields are supported:

include
Contains a sequence of strings which refer to files or directories to include. All files are loaded in the order they are specified one after another, overwriting previously defined data. A directory is denoted by a closing slash (/). It is searched for files with the suffix .yaml and added in alphabetical order.

Tags

Two tags are supported that can be specified (as in the example above).

ignore-missing
specifies that it is not an error if the file or directory is missing or if a directory contains no files. This is particularly useful for optional configuration.
host-specific
This tag can be used at most once across all and any configuration files. It specifies the file to which on-line configuration changes are written (note that comments in this file are not preserved during such operations). Independent of the time when it is specified it is always loaded last. The

Configuration

The configuration is specified as a tree, represented as YAML map. Values are accessed with path-like identifiers, i.e. a path from the root of the tree to a leaf containing a value is given by the names of the nodes concatenated by a slash. In the example document above, the only value can be accessed via /fawkes/example.

Types

The values are implicitly typed. They are checked in the following order if the given type can accomodate the value: unsigned int, int, float, bool, string.

Note that booleans are represented as the verbatim strings true and false. Numbers like 0 or 1 are not valid boolean values.

Strings can be added with or without quotes, e.g. "value" or just value are both valid. For readability it is recommended to omit the quotes. There are two exceptions where they are required. For one, to represent the strings "true" and "false" which would otherwise be read as strings, and for another for (pattern) strings starting with an asterisk (*), as they would otherwise be taken as anchor links in YAML.

Tags

Several tags are supported to provide additional validation of the configuration values to catch typical problems. The following tags can be used:

tcp-port or udp-port
Checked to be a number ranging from 1 to 65535
frame
Verified to be a valid coordinate frame identifier. It must start with a slash and then contain a path-like value.
url
Checked to be a valid URL string.

A small example of valid tag usage.

frame: !frame /base_link
port: !tcp-port 8088
url: !url http://www.fawkesrobotics.org

Emacs YAML mode

To make editing of the configuration easier and more comfortable we recommend to install the Emacs YAML major mode. It supports syntax highlighting of the configuration file and a few commands to support editing. The following procedure describes how to install the mode in your home directory.

git clone https://github.com/yoshiki/yaml-mode
mkdir -p ~/.emacs.d/lisp
cp yaml-mode/yaml-mode.el ~/.emacs.d/lisp

Then edit the file ~/.emacs and add the following (the first line is to add the just created directory as a path to look for Emacs LISP files):

(add-to-list 'load-path "~/.emacs.d/lisp/")
(require 'yaml-mode)
(add-to-list 'auto-mode-alist '("\\.yaml$" . yaml-mode))
(add-hook 'yaml-mode-hook
          '(lambda () (define-key yaml-mode-map "\C-m" 'newline-and-indent)))

After restarting Emacs the mode will be active.

Old Database Configuration

For the first couple of years the configuration used to be stored in a SQLite database. This was done to make access fast, to provide an overlay of the host-specific configuration over the default configuration, and to support full on-line modifyability and persistence from within the software. The new YAML configuration system revises some of these decisions based on the experience made with the system. In particular, the new focus is easy configuration by directly editing files. The anticipated benefit from using GUI or command line tools and overlayed configurations did not turn out to have the expected benefits. We still provided a simplified host-specific overlay configuration that can be modified from within the software at run-time, but we do not provide access to the default value anymore once overwritten.

From a plugin's perspective both configuration systems should behave the same way, only the developer and user will notice the differences when modifying the configuration.