Robotics Service Bus

h1. Configuration

The configuration mechanism is based on the following principles:

* The configuration mechanism works identically across implementation languages

* Configuration options are obtained from multiple configuration sources:

** Configuration files

** Environment variables

** _Commandline options (planned)_

* Configuration options are organized in a tree of name-value pairs

h2. Syntax and Semantics

Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.

Currently the following option tree is defined (uppercase option name components are placeholders):

<pre>

+ qualityofservice

+-- reliability                     { UNRELIABLE, RELIABLE }

+-- ordering                        { UNORDERED, ORDERED }

+ errorhandling

+-- onhandlererror                  { LOG, PRINT, EXIT }

+ transport

+-- NAME

+---- enabled                       bool

+---- TRANSPORT_SPECIFIC_OPTION     ?

+---- converter

+------ WIRE-SCHEMA                 string

+-- spread

+---- host                          string

+---- port                          uint

+-- inprocess

</pre>

h2. Processing Order

Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:

# Config file @${HOME}/.config/rsb.conf@

# Config file @$(pwd)/rsb.conf@

# Environment variables

h3. Example and test case

Consider the following situation:

* Contents of @${HOME}/.config/rsb.conf@:

<pre>

[transport.spread]

host = azurit

port = <uint>5301

</pre>

* Contents of @(pwd)/rsb.conf@

<pre>

[transport.spread]

host = localhost

</pre>

* Environment Variables

  @RSB_TRANSPORT_SPREAD_PORT='<unit>4444'@

This would result in the following effective option values:

* @transport.spread.host = localhost@

* @transport.spread.port = 4444@

h2. Sources

The following sections briefly explains the currently defined configuration sources.

h3. Configuration Files

Configuration files use the following syntax, which is similar to INI-files or desktop-files:

* Comments are initiated by the @#@ character and extend to the end of the current line

* After removing comments, all lines have to be of one of the following forms:

** empty

** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons 

** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters

Here is an example:

<pre>

[qualityofservice]

reliability = UNRELIABLE

ordering = UNORDERED

[errorhandling]

onhandlererror = LOG

[transport.spread]

host    = localhost

port    = <uint>4803

enabled = <bool>1 # this is the default

[transport.spread.converter]

image = IplImage # wireSchema = dataType

[transport.inprocess]

foo     = barbar

factor  = <double>1.5

enabled = <bool>1

</pre>

h3. Environment Variables

Environment variables are processed according to the following rules

# Variables whose names start with @RSB_@ are processed

# The @RSB_@ prefix is stripped form the name

# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters

Example:

@RSB_TRANSPORT_SPREAD_PORT -> transport.spread.port@