Configuration¶
The configuration mechanism in RSB is based on the following principles:
- The configuration mechanism works identically across implementation languages
- We cannot (and do not want to) handle configuration of individual
participants:
- The configuration mechanism is intended to provide process-wide defaults.
- Participants that require individual configurations have to be configured programmatically.
- Configuration options are obtained from multiple configuration sources:
- Configuration options are organized in a tree of name-value pairs
Configuration Debugging¶
In complex systems, it is sometimes not clear how the configuration in effect in a particular part of the system came about. RSB-based systems are no exception. To assist users in such situations, RSB provides a few configuration debugging tools.
The simplest and often most effective configuration debugging tool is
the __CONFIG_DEBUG
environment variable. When set to any
value, it causes RSB-based programs to print informative
messages during configuration processing:
$ __CONFIG_DEBUG=1 RSB_TRANSPORT_SPREAD_ENABLED=1 rsb-infocpp0.15
Starting processing RSC-based logging configuration
Configuring with sources (lowest priority first)
1. Configuration files
1. Prefix wide config file "/home/jmoringe/opt/rsx-0.15/etc/rsb.conf" does not exist
2. User config file "/home/jmoringe/.config/rsb.conf" exists
3. Current directory file "rsb.conf" does not exist
2. Environment variables with prefix RSC_
<none>
3. Commandline options
<none>
Finished processing RSC-based logging configuration
Starting processing plugin configuration
Configuring with sources (lowest priority first)
1. Configuration files
1. Prefix wide config file "/home/jmoringe/opt/rsx-0.15/etc/rsb.conf" does not exist
2. User config file "/home/jmoringe/.config/rsb.conf" exists
3. Current directory file "rsb.conf" does not exist
2. Environment variables with prefix RSB_
RSB_TRANSPORT_SPREAD_ENABLED -> 1
3. Commandline options
<none>
Finished processing plugin configuration
Starting processing default participant configuration
Configuring with sources (lowest priority first)
1. Configuration files
1. Prefix wide config file "/home/jmoringe/opt/rsx-0.15/etc/rsb.conf" does not exist
2. User config file "/home/jmoringe/.config/rsb.conf" exists
3. Current directory file "rsb.conf" does not exist
2. Environment variables with prefix RSB_
RSB_TRANSPORT_SPREAD_ENABLED -> 1
3. Commandline options
<none>
Finished processing default participant configuration
Default participant configuration
…
Name-value Pairs¶
See also
- Specification of inprocess Transport
- Options accepted by the inprocess transport.
- Specification of Spread-based Transport
- Options accepted by the Spread transport.
- Specification of TCP-socket-based Transport
- Options accepted by the TCP-socket-based transport.
- Specification of TCP+YARP Transport
- Options accepted by TCP+YARP transport.
- Specification of YARP Transport
- Options accepted by YARP transport.
- Specification of TCP+ROS Transport
- Options accepted by TCP+ROS transport.
- Specification of ROS Transport
- Options accepted by ROS transport.
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
is mapped to
transport.spread.port
.
Currently the following option tree is defined (uppercase option name
components are placeholders, LANGUAGE
refers to the
implementation language, e.g. cpp
, java
, etc.)
Name Type Comment ---- ---- ------- + qualityofservice +-- reliability { UNRELIABLE, RELIABLE } +-- ordering { UNORDERED, ORDERED } + errorhandling +-- onhandlererror { LOG, PRINT, EXIT } + introspection +-- enabled bool +-- displayname string + plugins +--LANGUAGE
+---- path list of strings +---- load list of strings + transport +--NAME
# +---- enabled bool # +----TRANSPORT_SPECIFIC_OPTION
? # Subtree is valid +---- converter # for all transports +------LANGUAGE
# +--------WIRE-SCHEMA
string #
Effective Configuration¶
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:
- Start with Global Defaults
- Merge with Config Files (“Merge 3”), being the result of:
- Start with System Config file
PREFIX/etc/rsb.conf
- Merge with User Config file
~/.config/rsb.conf
(“Merge 1”) - Merge with Current Directory Config file
$(pwd)/rsb.conf
(“Merge 2”)
- Start with System Config file
- Merge with options supplied via environment variables (“Merge 4”)
- Merge with programatically supplied options (“Merge 6”)
Note
On Windows the configuration file is located at %userprofile%\.config\rsb.conf
.
Sources¶
The following sections briefly explain the currently defined configuration sources.
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]
whereNAME
consists of alphanumeric characters and colonsNAME = VALUE
whereNAME
consists of alphanumeric characters- Double quotes (
"
) can be used inNAME
to avoid splitting at.
characters. E.g[transport."socket.new"]
would interpreted as the section name(transport, socket.new)
.
Here is an example:
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED
[errorhandling]
onhandlererror = LOG
[transport.spread]
host = localhost
port = 4803
enabled = 1 # this is the default
[spread.converter.cpp]
image = IplImage # wire-schema = data-type
[transport.inprocess]
foo = barbar
factor = 1.5
enabled = 1
[plugins.cpp]
path = /vol/vampire/lib:/vol/cor/lib
load = rsbspread:rsbvampire # no filetype suffix
Please note that only files with the platform’s respective line
endings are supported (i.e. \n
on Linux and \r\n
on Windows).
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
Examples:
RSB_PLUGINS_CPP_LOAD
->plugins.cpp.load
RSB_TRANSPORT_SPREAD_PORT
->transport.spread.port
Programmatic Options¶
Please have a look at the API documentation for ParticipantConfig (C++, Python) or Properties (Java). Links to the API documentation can be found in the left sidebar.
Example and Test Case¶
Consider the following situation:
Contents of
~/.config/rsb.conf
[transport.spread] host = azurit port = 5301
Contents of
$(pwd)/rsb.conf
[transport.spread] host = localhost
Environment Variables
RSB_TRANSPORT_SPREAD_PORT
=4444
This should result in the following effective option values:
transport.spread.host = localhost
transport.spread.port = 4444
Implementations¶
Language | File(s) |
---|---|
C++ | “0.14” branch of https://code.cor-lab.org/git/rsb.git.cpp at src/rsb/ |
Java | “0.14” branch of https://code.cor-lab.org/git/rsb.git.java at src/rsb/ |
Python | /../rsb-python/rsb/__init__.py |
Common Lisp | /../rsb-cl/src/configuration.lisp |