====== 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):

<code pseudo>
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
</code>


===== 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:
<code>
 - 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'}
</code>

In order to install the belief state interface for CRAM, you need these entries in your ''.rosinstall'' file:
<code>
 - 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'}
</code>

For compiling the package beliefstate with catkin you need the package libconfig++8-dev installed.
<code>
 sudo apt-get install libconfig++8-dev
</code>


===== 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:
<code bash>
$ rosrun semrec semrec
</code>
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 ''[[doc:logging:beliefstate:config_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:
<code>
[ 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.
</code>

Messages like ''[ plugins ] Failed to load plugin 'libbs_plugin_experiment_knowledge.so' '' are due to the fact that in the config file, [[doc:logging:beliefstate:development_plugins|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 [[doc:logging:communication|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:
<code lisp>
> (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.")
</code>
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:
<code lisp>
> (beliefstate:extract-files "pick-and-place")
</code>
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 [[doc:logging:plugins|here]].

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

  * [[doc:logging:tutorials-cpp|C++ Beliefstate Client Library]]