• Overview
• Installation
• Updates
• Usage
• User Manual
• The data model
• The update capabilities
• The query capabilities
• The distribution capabilities
• Launch options
• World model debugging techniques
• Changelog
• Licensing

RSG integration into Microblox (UBX). Provides system composition models for the SHERPA World Model.

In a nutshell, a SHERPA World Model as typically deployed on a robot has one so called World Model Agent plus a set of communication components like ZMQ or ROS. The components are realized with the Microblox (UBX) framework that allows to represent the SHERPA World Model in a single system composition model (.utc file).

The World Model Agent is written in C++ and can be queried and updated with its respective API. In order to use that C++ API in your own program a dedicated World Model Agent has to be spawned, the communication infrastructure (ZMQ or ROS) has to be added manually and it has to be connected to the other World Model Agent wihtin SHERPA World Model.

As an alternative, the SHERPA World Model provides a JSON API that allows to send graph operations via Zyre or ZMQ. Examples for using the JSON API can be found for a Task Specification Tree and here

This software can be installed as a Docker container. Further details can be found in the respective docker section.

In the below example we assume that all modules will be installed in the parent folder, where this repository (ubx_robotscenegraph) has been cloned to. Call the script with default parameters:

	./install.sh -i 

OR:

 ./install.sh --help

to retrieve the following usage information:

 Usage: ./install.sh -i [--no-sudo] [--no-ros] [--workspace-path=PATH] [--install-path=PATH] [-h|--help] [-j=VALUE] 
 E.g. : ./install.sh -i --workspace-path=../ 

    -i                     Mandatory! Perform actual installation.
    -h|--help              Display this help and exit
    --no-sudo              In case the system has no sudo command available. 
    --no-ros               In case the system has no ROS (Hydro/Indigo) installation.
    --workspace-path=PATH  Path to where libraries and bulild. Default is ../
    --install-path=PATH    Path to where libraries and modules are installed (make install) into.
                           (except for brics_3d). Default is /usr/local 
    -j=VALUE               used for make -jVAULE 

The script will automatically summarize which environment variable have to permanently saved. Please follow the instructions. E.g.

############################ATTENTION###############################
 ATTENTION: Please add the following environment variables:

export "HDF5_ROOT=/usr/local/" >> ~/.bashrc
export "UBX_ROOT=/workspace/microblx" >> ~/.bashrc
export "UBX_MODULES=/usr/local/lib/ubx" >> ~/.bashrc
export "BRICS_3D_DIR=/workspace/brics_3d" >> ~/.bashrc
export "FBX_MODULES=/workspace/brics_3d_function_blocks" >> ~/.bashrc
source ~/.bashrc .

####################################################################

All detailed steps on how to install the dependencies can be found in the install.sh script. The relevant environment variables for the installation procedure are listed in the section below.

• brics_3d_function_blocks Installation instructions can be found here: https://github.com/blumenthal/brics_3d_function_blocks
• BRICS_3D library. Installation instructions can be found here: http://www.best-of-robotics.org/brics_3d/installation.html
• microblx library. See: https://github.com/UbxTeam/microblx

Compile this project manually as follows:

 $ mkdir build
 $ cd build 
 $ cmake -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DEIGEN_INCLUDE_DIR=/usr/include/eigen3 -DHDF5_1_8_12_OR_HIGHER=true -DUSE_JSON=true ..
 $ make
 $ make install 

Please make sure the following environment variables are set. (They should be since the install script is putting them into your .bashrc. However, you need to source your .bashrc after the installation.)

Default variables for Microblox:

Dependencies to BRICS_3D and HDF5:

In order to update the system go to all relevant module folders. For each perform a git pull origin master and recompile with make clean followed by sudo make install

For convenience please use the following update.sh script:

	./update.sh

Similar to install script the following options are available:

	./update.sh --no-sudo

In case the system has no sudo command available. Useful for Docker based installations.

OR

	./update.sh --no-git

In case no git pull should be invoked.

The first steps on how to start a SHERPA World Model are described below. For a more detailed description including various options please see the manual section on launch options.

You can start the SHERPA World Model by invoking:

  roscore&
 ./swm_launch.sh 

In case the ROS communication modules are not available use instead:

  /swm_launch.sh --no-ros

Note, there are a set of environment variables the might need to be adopted.

The swm_launch.sh script already contains of a set of commands to s ins initialize the SHERPA World Model. Still it is possible, e.g. in order to debug th e system, to manually perform these steps.

  roscore&
  ./run_sherpa_world_model.sh

or

  ./run_sherpa_world_model.sh --no-ros

When the system is launched correctly the following prompt appears:

JIT: ON CMOV SSE2 SSE3 SSE4.1 fold cse dce fwd dse narrow loop abc sink fuse
> 

Then enter the following command and hit enter:

 scene_setup()
 start_all()

####Verify that it works

• The system state can be observed in a browser by entering http://localhost:8888/ as URL.

• Type p() into the interactive console of the SWM followed by pressing the return key. Then open a second terminal and call ./show.sg. Note, the graphiz package need to be installed first.

• Other examples on how to use it can be obtained from the examples section.

In general there are multiple possibilities to interact with the SHERPA World Model:

1. By using the JSON API. It allows to send graph operations encoded as JSON messages via Zyre or ZMQ.

2. By using the C client library that wraps (a subset) of the JSON API.

3. By embedding a new World Model Agent in a process. It allows to [querie] (http://www.best-of-robotics.org/brics_3d/classbrics__3d_1_1rsg_1_1ISceneGraphQuery.html) and update all data via the C++ API. In order to use it, a dedicated World Model Agent has to be spawned, the communication infrastructure (Zyre) has to be added manually and it has to be connected to the other World Model Agent of the SHERPA World Model.

4. By creation of a dedicated bridge as done for KnowRob trees. Please note, that the implementation of the KnowRob bridge embeds a World Model Agent as stated my method 3 and serves as a good reference example.

• Extended functions in C client library (#31).
• Fixed stability issues and memory leaks in C client library (#31).
• Fixed bug that can hang the zyre bridge (#33).
• Added more options on how to perform updates on attributes. (OVERWRITE, UPDATE, APPEND, #34).
• Added function block for aggregated pose queries (#29).
• Added option to query for subgraphs (#27).
• Added help and start functions for function blocks to terminals commands.
• Added convenience launch script swm_launch.sh without the necessity to type commands at start up.
• Fixed bugs of for JSON API including wrong updateResult replies or missing ids.
• Fixed issues with graphviz visualization including duplicated edges or missing attributes.

• Added Zyre client example in C and Python. The existing Python examples can seamlessly used with the new Zyre back-end
• Added Zyre with and optinally without SHERPA Mediator as communication back-end between SWMs and removed ZMQ PUB-SUB sockets
• Added function block query API, mechanism and examples for advanced queries
• Replaced semantic context and frequency filter by graph constraint mechanism
• Added simulated mission to be used to test the Knowrob-RSG bridge, including battery and ARTVA signals
• Added optional OSG visualizer (as function block)
• Added Docker generation to Travis-CI
• Added handling of areas

• Added support for automatic self synchronization
• Added reply status messages for updates and queries.
• Added one shot launch script
• Added semantic context and frequency filter
• Added Champoluc semantic map and scripts
• Added further Python examples
• Revised install script

• Initial version

This software is published under a dual-license: GNU Lesser General Public License LGPL 2.1 and Modified BSD license. The dual-license implies that users of this code may choose which terms they prefer. Please see the files called LGPL-2.1 and BSDlicense.

This work was supported by the European FP7 project SHERPA (FP7-600958).

Written by Sebastian Blumenthal (blumenthal@locomotec.com) Last update: 01.12.2016