Commit 5530014d authored by Olivier Stasse's avatar Olivier Stasse
Browse files

[doc] Rewamping the documentation structure.

TODO: Homogeneous relationship between debugging information.
Giving more python examples.
parent 5ce8caa2
......@@ -4,3 +4,6 @@ IMAGE_PATH = @CMAKE_SOURCE_DIR@/doc/pictures \
@CMAKE_SOURCE_DIR@/doc/figures
FILE_PATTERNS = *.cc *.cpp *.h *.hh *.hxx
TAGFILES = \
"@CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python.doxytag = @CMAKE_INSTALL_PREFIX@/share/doc/dynamic-graph-python"
\ No newline at end of file
/**
\page debug Debugging
They are several ways to perform debugging in dynamic-graph.
You can do it:
- with entities inside the graph:\subpage tracerdoc
- programmatically inside the entity in C++ using member of the entities:
\subpage tracerrealtimedoc
- programmatically in C++ with macros
**/
/**
\page subpage_entities Entities
\section section_entities Entities
\subsection entity_definition General definition
\image html entity.png
Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
and should have a minimal computational time foot-print.
For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
to get the needed data.
It might be provided by the connection with remote computers through a middleware, or specific protocols,
but in general the external data is based upon the sensor values provided by a "Device" entity.
For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
or get information from the entity.
As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
executed in a \b none-real-time thread.
\subsection entity_classes Entity class
Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
It is therefore necessary to specify the location of their dynamical libraries.
However given the time it might take to load the library, it is not advised to do that during a control-law computation.
Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
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).
\subsection entities 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.
\li \ref tracerdoc
\li \ref tracerrealtimedoc
\subsection specific_semantics Specific semantics with entities
It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
*/
/**
\page subp_factory Factory
\section sec_factory Factory
The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
*/
/**
\page page_graph Graph
In this package, the graph considered are directed graphs.
In dynamic-graph a graph is build with:
- computational nodes which are entities \subpage subpage_entities.
- directed edges which are created by connecting input and output signals \subpage subp_signals.
- managing the nodes is done through a factory \subpage subp_factory providing classes and a way to create instances from this list of classes.
- the instances of node are handled through a pool \subpage subp_pool
We strongly recommend to use a scripting language such as Python to
manage the graph.
See <c>dynamic-graph-python</c> for more information on binding dynamic-graph with Python.
It is possible to display the graph of entities \subpage writegraphdoc
*/
......@@ -47,6 +47,8 @@ A scheme of the real-time control graph used for the humanoid robot HRP-2 is dep
\image html Concept-Software-Fig.png
You can find an example of a real example of control graph at \ref writegraphdoc.
<p>The device therefore has a specific input which should contain the control vector.
This control vector is the result of a computation solving a control problem.
The entity in charge of solving this control problem is called "Solver" in the previous
......@@ -84,73 +86,8 @@ create instances of entities.</p>
computation of signal values, which is a critical point for real-time systems\n
See \ref scriptingabout
\section entity Computational Entity
\image html entity.png
\subsection entity_definition General definition
Despite the fact that it looks very similar to a ROS node or a CORBA/OpenRTM server, an entity is simply a C++ object.
The main idea is that this entity is providing mostly a data-driven functionnality working at very high rate (\f$ 200 Hz\f$ or \f$ 1 kHz \f$)
and should have a minimal computational time foot-print.
For this signals (or ports to use a more classical terminology) are providing a time dependency between data.
To implement this, an output signal is linked with a method of the entity. The method calls input signals or use other means
to get the needed data.
It might be provided by the connection with remote computers through a middleware, or specific protocols,
but in general the external data is based upon the sensor values provided by a "Device" entity.
For this reason the signal evaluations are realized through the cascade of dependencies and start from the evaluation of an input
signal of a periodic node (in general the device). This is realized inside a \b real-time thread.
To add flexibility to a node, it is possible to add command with arguments to modify the internal behavior of the entity
or get information from the entity.
As a command is in general asynchronous and rare with respect to the data-flow scheme for the signals the command is in general
executed in a \b none-real-time thread.
\subsection entity_classes Entity class
Entities are implemented as C++ classes and compiled as dynamic libraries. They can be loaded and instancied dynamically.
It is therefore necessary to specify the location of their dynamical libraries.
However given the time it might take to load the library, it is not advised to do that during a control-law computation.
Entity instanciation also implies memory allocation which is also time consuming and thus not advised inside a real-time thread.
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).
\subsection entities 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.
\li \ref tracerdoc
\li \ref tracerrealtimedoc
\subsection specific_semantics Specific semantics with entities
It is possible to derive classes and apply specific semantic for the entities. In our case we are interested in specific control semantics:
\li Tasks (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00089.html">here</a>)
\li Features (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00030.html">here</a>)
\li Solver (more information <a href="http://stack-of-tasks.github.io/sot-core/doxygen/HEAD/a00078.html">here</a>)
\section sigintro 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 \c 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 \ref signals
\section graph Graph
In this package, the graph considered are directed graphs.
\subsection factory Factory
The class \ref dynamicgraph::FactoryStorage is a singleton which register the entity classes and which is allowing the instancation of such classes.
\subsection pool Pool
The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
from the entities. Signals are the directed edges of the graph.
The pool can write a file representing the graph of entities.
\section usecase How to use this package
\subsection use_programmtically Programmatically
......
/**
\page subp_pool Pool
\section pool Pool
The class \ref dynamicgraph::PoolStorage keeps track of the entities instanciated with the factory.
The entities are the graph nodes. Signals are constructed during the class instanciation, they do not live independently
from the entities. Signals are the directed edges of the graph.
The pool can write a file representing the graph of entities.
*/
/**
\page subp_signals Signals
\section sec_sigintro 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 \c 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 \ref signals
*/
/**
\page tracerrealtimedoc TracerRealTime
\section description Description
\section tracerrealtimedoc_description Description
The \b TracerRealTime entity monitors a set of signals with real-time constraints; its
function is very similar to the Tracer, except that all traces are recorded to a
memory buffer, which can be emptied at any time.
\section commands Commands
\section tracerrealtimedoc_commands Commands
The \b commands that this entity exposes are:
\code
empty (discards all buffers)
......@@ -16,13 +18,12 @@ Plus all the commands exposed by \ref tracerdoc
For more information on the signals exposed by this entity, please check the
code documentation of the dynamicgraph::Tracer class.
\section sample Sample usage
\section tracerrealtimedoc_sample Sample usage
See \ref tracerdoc for a code sample of using TracerRealTime.
\section addi Additional information
\section tracerrealtimedoc_addi Additional information
See doxygen documentation for the class dynamicgraph::TracerRealTime
\section generates Generated plugin file
\section tracerrealtimedoc_generates Generated plugin file
tracer-real-time.dll or tracer-real-time.so.
**/
*/
/**
\page tracerdoc Tracer
\section description Description
\section tracerdoc_description Description
The \b Tracer entity monitors a set of signals. With an input change on the entity's [trigger] signal,
the tracked signal values are recorded and traced to a file. The behavior of the trace-to-file
function can be changed, from printing to a file immediately after recording, to printing out
only when asked explicitly.
\section commands Commands
\section tracerdoc_commands Commands
The \b commands that this entity exposes are:
\code
open, close (a file);
......@@ -19,7 +20,8 @@ start, stop (traces)
For more information on the signals exposed by this entity, please check the
code documentation of the dynamicgraph::Tracer class.
\n\n
\section sample Sample usage
\section tracerdoc_sample Sample usage
The following code creates a TracerRealTime entity, then sets the tracing buffer
size to 10MB. It then tells the tracer to create files with names of the form:
jl_XXX.dat where XXX is the signal name, and adds a few signals after
......@@ -38,10 +40,9 @@ tr.add dyn.0
tr.add jgain.gain
\endcode
\section addi Additional information
\section tracerdoc_addi Additional information
See doxygen documentation for the class dynamicgraph::Tracer
\section generates Generated plugin file
\section tracerdoc_generates Generated plugin file
tracer.dll or tracer.so.
**/
*/
/**
\page writegraphdoc Displaying the graph of entities
\section description Description
It is possible to view the graph of entities currently instanciated.
The format used by dynamic-graph is dot.
Using the python interpreter the following command
\code
from dynamic_graph import *
writeGraph('/tmp/my_dynamic_graph.dot')
\endcode
is writing the <b>my_dynamic_graph.dot</b> in the <b>/tmp</b> directory
\section fromdottopdf Viewing as a PDF file
To view the dot file you can simply use:
\code
dot -Tpdf /tmp/my_dynamic_graph.dot > /tmp/my_dynamic_graph.pdf
\endcode
It provides the following output:
\image html my_dynamic_graph.png
*/
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment