Orca Configuration Files

Note:: Reviewed for release 2.9.0.

This page describes everything you need to know about writing and using Orca config files.

Sources, Priorities, and Order of Loading

Configuration parameters can come from 5 different sources, in any combination. The possible sources are listed here in the order of decreasing generality and increasing priority (i.e. the later more specific sources overwrite the earlier more general ones). At runtime, the properties are loaded in reverse order so that the property values from more specific sources (e.g. from the command line) can specify the address of the more general sources (e.g. the location of the global config file). Despite the reverse loading order, the priorities are of course preserved.

Built-in ("factory") defaults
- These are hard-wired into the code of commonly-used libraries and the individual components. The library and component documentation should specify default values. (See for example configuration parameters for libOrcaIce)
Over the network, from a remote interface. Only properties beginning with the component tag can be set using this method. The remote interface proxy (direct or indirect) is specified in one of 2 ways:
1. The contents of Orca.NetworkConfig parameter (supplied by any of the sources below), e.g.
```
Orca.NetworkConfig=properties@local/propertyserver
```
2. Default value: none. Network configuration properties are not used if the proxy is not specified explicitely.
From a global configuration file. The path to the file (absolute or relative) is specified in one of 3 ways (we use the first one we find):
1. The contents of Orca.GlobalConfig parameter (supplied by any of the sources below), e.g.
```
$ ls *.cfg
global.cfg
$ mycomponent --Orca.GlobalConfig=global.cfg
```
2. The contents of ORCA_GLOBAL_CONFIG environment variable
```
$ ls *.cfg
global.cfg
$ export ORCA_GLOBAL_CONFIG=global.cfg
$ mycomponent
```
3. Default value, platform-dependent:
  - Linux: File $HOME/.orcarc
```
$ ls $HOME/.orcarc
/home/myname/.orcarc
$ mycomponent
```
  - Win32: File C:\orca.ini
From a component configuration file. The path to the file (absolute or relative) is specified in one of 4 ways (we use the first one we find):
1. The contents of Orca.Config parameter (supplied by any of the sources below), e.g.
```
$ ls *.cfg
local.cfg
$ mycomponent --Orca.Config=local.cfg
```
2. The contents of Ice.Config parameter (supplied by any of the sources below), e.g.
```
$ ls *.cfg
local.cfg
$ mycomponent --Ice.Config=local.cfg
```
  We parse Ice.Config for compatibility with IceGrid. In manually-written files this option should not be used to avoid confusion.
3. The command line argument, when there is only 1 argument.
```
$ ls *.cfg
local.cfg
$ mycomponent local.cfg
```
4. File ./mycomponent.cfg when the component mycomponent is executed with no command line arguments.
```
$ ls *.cfg
mycomponent.cfg
$ mycomponent
```
Command-line arguments. Any property can be specified on the command line by prepending "--" to it. For example, your component's config file has the following property MyComponent.Config.MaxSpeed=50. You can change the effective value with a command-line option. (Note that we have to specify the config file name explicitely because the special cases of 4b and 4c no longer apply.)
```
$ mycomponent --Orca.Config=local.cfg --MyComponent.Config.MaxSpeed=500 
```

Note:: To avoid unexpected interactions between Ice runtime and Orca libraries, do not define ICE_CONFIG environment variable.

File Format

Orca uses Ice utilities to parse configuration files. Therefore, we use the same format as the Ice configuration files.

Config files are text files which list properties as key/value pairs. Each key/value pair is placed on a new line. Keys and values are strings which are separated by an equal sign ('='). The key strings are optionally devided into subfields with periods (aka dots, '.'). The value strings can represent strings, integers, or floats. Boolean variables are by convention stored as {0,1}. Comments are marked with '#'. For example:

Parameter=1
Parameter.Subfield="orca"
# This line is ignored
Parameter.Subfield.Whatever=123.4

For more information on Ice properties and configuration files, see chapter "Ice Properties and Configuration" of the Ice manual.

Writing Configuration Files

The configuration files are viewed slightly differently by the component user and the component developer.

From the User's Perspective

Typically, an Orca component has a definition file (file extention def) in the source tree and the configuration file (file extention cfg) is generated from it during compilation. The automatically generated cfg file is installed into [ORCA-INSTALL-DIR]/cfg/ directory.

To use a cfg file in your system, make a copy of the auto-generated mycomponent.cfg file and customize it to fit the needs of your system.

$ mkdir -p ~/sys/mysystem; cd ~/sys/mysystem
$ cp [ORCA-INSTALL-DIR]/cfg/somecomponent.cfg .
$ vi somecomponent.cfg
$ somecomponent somecomponent.cfg

From the Developer's Perspective

Orca configuration files (file extention cfg) are typically generated from component definition files (file extention def). This is the recommended method becauses it reduces workload and minimizes chances of error. The format for definition files is documented within a dedicated library libOrcaDef.

The configuration file mycomponent.cfg file can be generated from the corresponding def file in two ways:

manually at any time, using the generatecfg utility:
```
$ generatecfg component.def mycomponent.cfg
```
automatically during compilation, by including the following line in the component's CMakeLists.txt file
```
GENERATE_CONFIG_FILE( mycomponent.def )
```

The hand-written def file is installed into [ORCA-INSTALL-DIR]/def/ directory. The auto-generated cfg file is installed into [ORCA-INSTALL-DIR]/cfg/ directory.

Usage

Configuration files have two uses:

Connecting Components

First, we look at a component with provided interfaces (acting as a server).

COMP_TAG.Platform=p1
COMP_TAG.Component=c1
COMP_TAG.Endpoints=e1

# Provided interfaces
COMP_TAG.Provides.IFACE_TAG1.Name=i1
COMP_TAG.Provides.IFACE_TAG2.Name=i2
...

The fragment above contains two kinds of tags:

COMP_TAG (string)

All component settings are prefixed with a string which we call here 'COMP_TAG'. This is done to distinguish one component's setting from the other's and from other possible settings, e.g. Ice runtime parameters which start with 'Ice', 'IceStorm', etc.
Valid values:
- all characters, except '.'
- must be unique within one config file
- has to match the string hard-wired into the component's source code.

IFACE_TAG (string)

Settings for different interfaces are distinguished by using tags.
Valid values:
- all characters, except '.'
- must be unique within one component's settings
- has to match the string hard-wired into the component's source code.

Now we go through the keys of the fragment (the text on the left of the "=" sign):

COMP_TAG.Platform (string)

Platform name. Used for registering with the registry.
Valid values:
- all characters, except '@' and '/'
- combination with component name must be unique within the system
Default: "local"

COMP_TAG.Component (string)

Component name. Used for registering with the registry.
Valid values:
- all characters, except '@' and '/'
- combination with platform name must be unique within the system
Default: the value of COMP_TAG converted to lower case.

COMP_TAG.Endpoints (string)

The communication endpoints at which the component will accept connections.
Valid values:
- standard Ice endpoint specification.
- to allow direct connections, host name and port number must be specified.
Default: "tcp -t 5000"

COMP_TAG.Provides.IFACE_TAG.Name (string)

The interface name. Used for registering with the registry.
Valid values:
- all characters, except '@' and '/'
- must be unique within an Orca component

Orca defines the following naming rules:

fully-qualified component name

formed from platform and component names as follows: Platform/Component
Example: "p1/c1".
Must be unique within the system. (If the same registry is used by multiple system, the combination must be unique across all systems involved.)

fully-qualified interface name

formed from platform, component, and interface names as follows: Interface@Platform/Component
Example: "i1\@p1/c1" and "i2\@p1/c1".

fully-qualified interface address

formed from interface name and the component endpoint as follows: Interface:Endpoint
Example: "i1:e1" and "i2:e1"
am: does it work with multiple endpoints?

Now lets look at configuring the second component which will connect to the first.

COMP_TAG.Platform=p2
COMP_TAG.Component=c2

# Required interfaces

# Direct binding by specifying the address (endpoint)
COMP_TAG.Requires.IFACE_TAG1.Proxy=i1:e1

# Indirect binding by looking up the address through the Registry
COMP_TAG.Requires.IFACE_TAG2.Proxy=i2@p1/c1
...

As you can see, there are two options for connecting interfaces:

direct connection
- Must specify a fully-qualified interface address.
- Example: "i1:e1"
- (The Registry is not used)

indirect connection
- Must specify a fully-qualified interface name.
- Example: "i2@p1/c1"
- When the component is initialized, it contacts the Registry with the name of the required interface. The Registry returns the address of the 2nd provided interface of the component above.

Of course, the same component may have provided and required interfaces. The order of declaring interfaces is not important. Here's a complete example for a component which has provided and required interfaces.

LocalNav.Platform=local
LocalNav.Component=localnav

# Provided Interfaces
LocalNav.Provides.PathFollower2d.Name=pathfollower2d

# Required Interfaces
LocalNav.Requires.Localisation.Proxy=localise2d@local/faithlocaliser
LocalNav.Requires.Odometry2d.Proxy=odometry2d@local/robot2d

With COMP_TAG=LocalNav and component endpoints set to default. Provided interfaces: IFACE_TAG=PathFollower2d. Required interfaces: IFACE_TAG1=Localisation, IFACE_TAG2=Odometry2d.

Specifying Component's Internal Configuration Parameters

Components' internal behaviour usually needs to be configured at run time by setting certain parameters. The following syntax is used:

COMP_TAG.Config.SET_TAG1.PARAM_TAG1=0.1
COMP_TAG.Config.SET_TAG1.PARAM_TAG2=1
...
COMP_TAG.Config.SET_TAG2.PARAM_TAG3=left
...

The code looks up the value of the parameter by its full key, e.g. COMP_TAG.Config.SET_TAG1.PARAM_TAG1. Repeated keys are allowed, the later values replacing earlier ones.

String used for set and parameter tags are arbitrary. Parameter sets and the depth of the hierarchy are completely optional.

The code can contain hard-coded default values in case the config file omits them or leaves the value empty. The auto-generated config files should contain all parameters listed with the corresponding default values. The defaults should also be specified in component's documentation.

Example:

LocalNav.Config.TestMode=0
LocalNav.Config.Test.BatchMode=0
LocalNav.Config.Test.NumWaypoints=10
LocalNav.Config.Vfh.AbsoluteMaxTurnrate=60
LocalNav.Config.Vfh.CellSize=0.1

For More Information.

Follow the steps of Quick-Start Guide. After you get the two components to communicate, you can examine the configuration files to see how connections are specified.