Belief State Logging

Belief State Logging

In order to create extensive logs of CRAM plan executions, a software package for symbolic logging was created. It records data based on symbolic contexts started and ended by external entities (such as CRAM).

Context-driven, synchronous log generation

The logs generated using the belief state log mechanism are represented by a tree of contexts and subcontexts. Each context can be annotated by additional data. Exemplary context annotation can take a form similar to the following (shown in pseudo-code):

begin context: fetch object
  annotation: start-time = 0
  annotation: object-description = ...
 
  begin context: perceive
    annotation: start-time = 0
    annotation: detected-object(s) = ...
    annotation: end-time = 2
    annotation: success = true
  end context
 
  begin context: navigate-to-object
    annotation: start-time = 2
    annotation: goal-position = ...
    annotation: end-time = 7
    annotation: success = true
  end context
 
  begin context: grasp
    annotation: start-time = 7
    annotation: gripper-side = left
    annotation: end-time = 10
    annotation: success = true
  end context
 
  annotation: end-time = 10
  annotation: success = true
end context

Installation

The logging mechanism consists of two parts:

The belief state logging software: A ROS node that records all symbolic events that are sent to a specific set of ROS services. This node keeps track of the symbolic event tree, all of its annotations, and is able to extract to data in various formats.
The CRAM belief state interface: A CRAM package that enables easy integration of the logging mechanism into the CRAM system. Through hooks in vital functions inside CRAM, the belief state interface automatically logs structural information during plan execution.

In order to install the belief state logging software, you need the following entries in your .rosinstall file:

 - git: {local-name: semrec, uri: 'https://github.com/code-iai/semrec.git'}
 - git: {local-name: designator_integration, uri: 'https://github.com/code-iai/designator_integration.git'}
 - git: {local-name: iai_common_msgs, uri: 'https://github.com/code-iai/iai_common_msgs.git'}

In order to install the belief state interface for CRAM, you need these entries in your .rosinstall file:

 - git: {local-name: iai_common_msgs, uri: 'https://github.com/code-iai/iai_common_msgs.git'}
 - git: {local-name: designator_integration_lisp, uri: 'https://github.com/code-iai/designator_integration.git'}
 - git: {local-name: cram_bridge, uri: 'https://github.com/cram-code/cram_bridge.git'}

For compiling the package beliefstate with catkin you need the package libconfig++8-dev installed.

 sudo apt-get install libconfig++8-dev

Running the belief state software

When installed and compiled through catkin_make, you should be able to run the belief state software using this command:

$ rosrun semrec semrec

The software automatically looks for plugins in your ${catkin_workspace}/devel/lib directory. The ${catkin_workspace} directory is resolved by either trying the environmental variable ${ROS_WORKSPACE} or parsing the first path in ${ROS_PACKAGE_PATH}, minus the src directory, or ${CMAKE_PREFIX_PATH}, minus the devel directory (in that order).

So, pratically, you don't need to configure anything. If you want a configuration different from the default one, look into the file config.cfg inside of the semrec directory. Besides extensive documentation, it holds options for most details you might want to change.

Log files are by default saved into the directory structure in ${HOME}/bs_experimental_data/, followed by an indexed experiment directory.

Typical startup messages look like this:

[ core ] Starting beliefstate system.
[ plugin-instance ] Loaded plugin 'symboliclog' (version: 0.9)
[ plugin-instance ] Initialized plugin 'symboliclog'
[ plugin-instance ] Loaded plugin 'ros' (version: 0.9)
[ros/1] Starting ROS node 'beliefstate_ros'.
[ros/1] ROS node started. Starting to spin (4 threads).
[ plugin-instance ] Initialized plugin 'ros'
[ plugin-instance ] Loaded plugin 'owlexporter' (version: 0.73b)
[ plugin-instance ] Initialized plugin 'owlexporter'
[ plugin-instance ] Loaded plugin 'dotexporter' (version: 0.2)
[ plugin-instance ] Initialized plugin 'dotexporter'
[ plugin-instance ] Loaded plugin 'imagecapturer' (version: 0.2)
[ plugin-instance ] Initialized plugin 'imagecapturer'
[ plugin-instance ] Loaded plugin 'supervisor' (version: 0.6)
[ plugin-instance ] Initialized plugin 'supervisor'
[ plugin-instance ] Loaded plugin 'knowrob' (version: 0.25b)
[ plugins ] Not loading development plugin: 'libbs_plugin_knowrob.so'
[ plugin-instance ] Unloaded plugin 'knowrob'
[ plugins ] Failed to load plugin 'libbs_plugin_knowrob.so'
[ plugin-instance ] Loaded plugin 'interactive' (version: 0.4)
[ plugin-instance ] Initialized plugin 'interactive'
[ plugin-instance ] Loaded plugin 'experiment_knowledge' (version: 0.1a)
[ plugins ] Not loading development plugin: 'libbs_plugin_experiment_knowledge.so'
[ plugin-instance ] Unloaded plugin 'experiment_knowledge'
[ plugins ] Failed to load plugin 'libbs_plugin_experiment_knowledge.so'
[ plugin-instance ] Loaded plugin 'experiment_context' (version: 0.3)
[ plugin-instance ] Initialized plugin 'experiment_context'
[supervisor/5] Created new experiment space: 'exp-454'.
[supervisor/5] Symlink set accordingly.

Messages like [ plugins ] Failed to load plugin 'libbs_plugin_experiment_knowledge.so' are due to the fact that in the config file, development plugins are by default deactivated.

After startup, the ros plugin offers ROS services for information injection through the node /beliefstate_ros. More details on the communication protocol can be found here.

Running the belief state CRAM interface

In order to get log support in your CRAM applications, simply load the package cram_beliefstate (contained in the stack cram_bridge), using the ASDF system cram-beliefstate. Once it is loaded, it automatically makes use of all CRAM-defined hooks concerning high-level plan execution.

To set metadata about the plan you are executing (to correctly identify your experiment), use this cram-beliefstate-supplied command:

> (beliefstate:set-metadata
    :robot "My robot's name"
    :creator "The experimenter"
    :experiment "Pick and Place"
    :description "It went well, this was a great experiment! The robot cleaned up the whole place.")

The data is then sent to the belief state software and will be extracted as metadata.xml file when extracting files.

If you want to extract the current state of the experiment (after collecting experiment data from plan execution), do this:

> (beliefstate:extract-files "pick-and-place")

This effectively extracts the collected information into files preceeded with pick-and-place. Choose the filename at will.

Capabilities

The belief state logging software itself has no abilities itself except for message transportation and plugin loading. The capabilities available for logging are introduced by plugins, described in more detail here.

Tutorials

In order to interface with the logging infrastructure, a set of tutorials is available:

C++ Beliefstate Client Library

Table of Contents