XML files

Starting with the idea of config repos a unified configuration file was needed. This new file type includes the old framework_conf.xml, loadConfig.xml and the various *.lconf files.

XML is a well-known extensible document format that's easy to parse and already used to configure different applications.

Example

framework_conf.xml

<framework>
  <execution>
    <clock sleep="true" unit="hz" value="100" />
  </execution>
  <modulesToEnable logLevel="INFO">
    <module logLevel="WARN">scheduler</module>
    <module>image_importer</module>
  </modulesToEnable>

  <module>
    <name>my_camera</name>
    <realName>image_importer</realName>
    <channelHint name="IMAGE" mapTo="RAW_CAMERA_IMAGE" priority="10" />
    <config src="my_camera.lconf" />
  </module>

  <include src="scheduler.xml" />
</framework>

scheduler.xml

<framework>
  <module>
    <name>scheduler</name>
    <config src="scheduler.lconf" />
    <config>
      <warn>true</warn>
      <maxExecTime>1000</maxExecTime>
    </config>
  </module>
</framework>

<execution>

<clock>

Has the same functionality as the deprecated scheduler module: Make sure a given cycle-rate is followed by sleeping the remaining time or warn if a cycle was too long. compensate tries to balance sleep time over several cycle if enabled, defaults to false. The watchDog warns if a module takes more time to execute then specified by this attribute.

Attribute	Value	Description
sleep	boolean, required	enable/disable sleeps
unit	enum (hz, ms, us), required	cycle rate's unit
value	positive integer, required	cycle rate's value
compensate	boolean, optional	enable/disable compensation
watchDog	positive integer, required	warning if module too slow

Available units

• hz - hertz, 1/s
• ms - milliseconds, 1/1,000 s
• us - microseconds, 1/1,000,000 s

Conversion example: 100 hz == 10 ms == 10000 us

Note: The given value will be converted to full microseconds.

<mainThread>

The runtime will be executed only on the main thread or in a thread. This is useful for runtimes using OGRE that should be executed only on main thread. If not given a runtime may be executed on any thread.

<paused>

By default runtimes start in running mode and will be executed after framework initialization. The empty <paused /> tag overrides this behavior and sets it to pause mode. Use resumeRuntime() inside modules to start a pausing runtime.

<modulesToEnable>

All modules that should be loaded and executed.

• optional attribute logLevel: default log level for all modules (See attribute logLevel of <module>)

<module>

• optional attribute logLevel: minimum log level for the module (defaults to attribute logLevel of <modulesToEnable>)
• content: module name

<module>

For each module that should be available there must be a module node.

<name>

• content: Name of the module (used inside <modulesToEnable>)

<realName>

• content: Real name of the module (If you instantiate modules multiple times you should use this tag to inform the framework where to look for the shared library.) On linux this will look for a shared library called lib${realName}.so.

<mainThread>

The module will be executed only on the main thread. This is useful for modules using OGRE that should be executed only on main thread. If not given a module may be executed on any thread.

<channelMapping> (deprecated)

If a module requests access to a datachannel then the request can be redirected to another channel with this tag.

Attribute	Value	Description
from	string, required	requested data channel
to	string, required	redirect to this data channel
priority	integer, optional	priority for the channel

• priority defaults to 0. Modules with higher priorities will be executed earlier in the cycle to access the data channel.

<channelHint>

If a module requests access to a datachannel then the request can be redirected to another channel with this tag.

Difference to <channelMapping>: The former to attribute was renamed to mapTo is now optional and defaults to the value of name.

Attribute	Value	Description
name	string, required	requested data channel
mapTo	string, optional	redirect to this data channel
priority	integer, optional	priority for the channel

• priority defaults to 0. Modules with higher priorities will be executed earlier in the cycle to access the data channel.

<config>

Attribute	Value	Description
name	string, optional	config's name, defaults to default
src	string, optional	path to config file to load
user	string list, optional	only load if current user is in this list
content	mixed, optional	XML module config, nestable tags

Note: The given src path is relatve to the current file. The given file will be read as an LCONF file. If the src attribute is given, the tag's content must be empty. The user attribute should be comma separated list of system usernames. If the tag's content is non empty the src attribute must not be set.

<service>

A referenced in XML will be installed in the framework during startup.

<name>

• content: Name of the service

<realName>

• content: Real name of the service (If you instantiate services multiple times you should use this tag to inform the framework where to look for the shared library.) On linux this will look for a shared library called lib${realName}.so.

<config>

See <module>/<config>.

<logLevel>

Set the logging threshold of this service. May be set to ALL, DEBUG, INFO, WARN, *ERROR or OFF.

<logging>

Use an instance of lms::logging::ThresholdFilter for all logging messages.

• required attribute logLevel: Default threshold level for all logging messages.

<filter>

For each logging message, it's tag is matched against each tagPrefix. If a match is found, the given logLevel is compared to the logging level of the log message.

Attribute	Value	Description
tagPrefix	string, required	check if the tag starts with this prefix
logLevel	string, required	log level to use

<include>

• required attribute src: Path relative to the current file. The given file will be read as a unified XML config file.

<runtime>

• required attribute name: Name of the runtime that will be created
• required attribute src: Path to another XML file that will be parsed for the newly created runtime

<if>

The if-tags get preprocessed before any other XML parsing. The content is conditionally included or excluded to the XML content depending on the flags given on startup (See the --flags command line argument).

Attribute	Value	Description
set	string, optional	flag must be set
notSet	string, optional	flag must not be set
anyOf	string list, optional	one of the flags must be set, logical OR
allOf	string list, optional	all of the flags must be set, logical AND
nothingOf	string list, optional	none of the flags must be set, logical NOR

NOTE: Only one of the conditional attributes is allowed on one if tag.