This is an old revision of the document!


Tutorial for the C++ Beliefstate Client Library

What it can do

The Beliefstate Client library allows easy, lightweight access to the Beliefstate infracstructure for semantic event logging. Its main tasks consist of opening a new semantic context in which actions take place, and ending that context again, annotating it with success or failure. Such contexts can be nested at will.

Besides recording such events from a live running system (such as a robotic agent performing tasks in the real world, or a simulated machine working out given tasks), the recorded events can be exported as well-structured OWL files, allowing symbolic reasoning about the available information.

What is needed

In order to equip a program with logging functionality, it needs to be linked against the client library. The library is currently only available in C++, but the functionality is available to all programming languages that have access to the ROS messaging (and service) bus.

To get the necessary libraries, you must check out the following repositories into your catkin ROS workspace:

wstool set designator_integration --git https://github.com/code-iai/designator_integration
wstool set iai_common_msgs --git https://github.com/code-iai/iai_common_msgs
wstool set beliefstate_client --git https://github.com/fairlight1337/beliefstate_client

After doing a wstool update to make sure all library checkouts are up to date, make sure that everything compiles just fine:

catkin_make --pkg beliefstate_client

If no problems come up, you are set to connect your own applications to the logging infrastructure.

Using the client library

To clarify how to implement a logging infrastructure interface into your own ROS application, a basic ROS node template will be used. We first create this node's package by running:

catkin_create_pkg logging_node_client roscpp beliefstate_client

The package's node will be linked against the ROS C++ framework (roscpp) and the Beliefstate Client library (beliefstate_client).

This package's main code consists of a simple skeleton .cpp file including:

#include <cstdlib>
#include <ros/ros.h>
#include <beliefstate_client/beliefstate_client.h>
 
int main(int argc, char** argv) {
    ros::init(argc, argv, "logging_client");
 
    // Begin main code here.
    // ...
    // Main code ends here.
 
    return EXIT_SUCCESS;
}

We now add an instance of the Beliefstate Client class that takes advantage of the already present ROS connection:

    // Begin main code here.
 
    BeliefstateClient* bscl = new BeliefstateClient("logging_client");
 
    // Begin actual logging here.
    // ...
    // Actual logging ends here.
 
    delete bscl;
 
    // Main code ends here.

To log semantic events, we create some sample nested contexts:

    // Begin actual logging here.
 
    // Open a top-level context (level 0)
    int nContextID_1 = bscl->startContext("top-level-context");
 
    // Open a sub-context (level 1)
    int nContextID_2 = bscl->startContext("sub-context-1");
    // End the sub-context from level 1
    bscl->endContext(nContextID_2);
 
    // Open another sub-context (level 1)
    nContextID_2 = bscl->startContext("another-sub-context");
 
    // Open yet another sub-context (level 2)
    int nContextID_3 = bscl->startContext("a-sub-sub-context");
    // End the sub-context from level 2
    bscl->endContext(nContextID_3);
 
    // End the sub-context from level 1
    bscl->endContext(nContextID_2);
 
    // End the top-level context
    bscl->endContext(nContextID_1);
 
    // Actual logging ends here.

The logging result of this program is a nested tree with two branches from the top-level node, one with depth 1, and one with depth 2.

To export the logged tree now, we add another call from inside the library:

    // ...
 
    // Export files
    bscl->exportFiles("logged_data");    
 
    // Actual logging ends here.

The Beliefstate system (if properly configured with exporter plugins) now exports a .owl-file, including well-structured OWL code describing the tree semantics, and a .dot-file, in graphviz format for PDF generation.