dynamic-graph Documentation


Introduction

The dynamic-graph package is used to connect computation nodes, "entities" together using a graph system, akin to what Simulink does. With the building blocks this package provides, you can easily create a full computation graph for a given problem. It is the basis for the stack of tasks operation.

entity.png

Functionality:

  • Built-in scripting language* for fast prototyping and testing
  • Support for extensions and modules using dynamic link libraries
  • Template-based signal definition, independant
  • Type-safe connection of input and output signals
  • On-demand signal computation as well as a caching system for signal values allow fast computation of signal values, which is a critical point for real-time systems
    See Notes about the scripting language

Code overview

This code implements the factory design pattern, making creation of entities (as C++ classes) available to packages depending on the dynamic-graph API. For more information on this package's code or how to develop your own entities, see How to use this package.

List of entities in this package

Since most of the functionality in projects using the dynamic-graph framework is exposed from entities, here is a short description of all the entities contained in this package. Note that most entities are contained in a binary file that closely matches the entities' names in the scripts; loading this file with the plugin loader will enable creation of this entity through the factory.

The entities will be placed in ${PREFIX}/lib/plugin (since this may change, it is advised to check the install log or the CMakeLists.txt file to check the installation path).

About signals

Entities can output different types of signals. All signals are templated by a Time tick type parameter (which is used in the caching of signals) - usually int. Signals are also templated after the type of data they accept or provide. For example: (example) For a more detailed programmer-oriented description of signals, please see Signals

Notes about the scripting language

The scripting language allows entities to define their own commands, and provides a basic framework for working with the dynamic-graph. At the time of writing, there is talk about replacing (or complementing) this limited language with a python interpreter.

A couple of functions are built-in in the interpreter and provides low-level features such as file sourcing or plug-in loading.
These functions are:

plug <obj1.sig1> <obj2.sig2>

plugs the signal sig1 of obj1 to the signal sig2 of obj2. sig1 and sig2 have to be of the same type. sig1 has to be an output signal and sig2 an input signal.

new <class> <object>

instantiates an object object of class class. object has to be a free identifier and class an existing entity.

destroy <object>

deletes an instance previously created.

run <script.txt>

sources (i.e. read and interpret) an external file.

loadPlugin <file.so> <directory>

loads a plugin called file.so and located in the directory directory.

unloadPlugin <path/file.so>

unloads a plugin.

help

lists available functions.

set <obj.signal> <value>

defines an input signal to a specific, constant, value.

get <obj.signal> <value>

prints out a signal value.

compute <obj.sig> <time>

computes an output signal and sets the associated time to time.

How to use this package

1) Programmatically
Objects, which are derived from Entities (base class dynamicgraph::Entity), can be declared within the code and compiled to shared libraries (.so/.dll files). These libraries can be loaded at run-time using the PluginLoader methods, and at the same time register their class names to the Factory (see the examples in the SOT documentation to learn how).

The Factory can then create instances of these objects and subsequently register them in the Pool, where they can be listed, accessed, and acted upon (see PoolStorage documentation). Basic commands defined by entities include signal connection graph file generation, help and name print, and signals.

Finally, a shell (command-line) interface is made available thanks to the Interpreter class (see the file test_shell.cpp for an example). Objects deriving from Entity can expose their own commands by overriding the Entity's default commandLine() method. It is possible to load a plugin to register custom shell commands; see shell-functions and shell-procedure for an example.

Some basic shell functions, and support for procedures, are also included. For a complete list of those, load the plugin shell-functions.so and type 'help' at the command line.

The (singletons made available by including the corresponding headers in this module are:

For an example of a program creating entities in C++, see the unit test test_pool.cpp (in your package source directory/unitTesting).

2) Through scripts
The program dg-shell executable can be used to have scripting access to the dynamic-graph library, where you can execute scripts and commands, load plugins, create entities and connect signals.

Here is a typical use case for programmers:

use-case.png

References

"Task sequencing for sensor-based control", N. Mansard, F. Chaumette, IEEE Trans. on Robotics, 23(1):60-72, February 2007