Commit d4bd7415 authored by florent's avatar florent
Browse files

Added documentation page on development rules.

parent d5d40723
2007/10/01
3. Added documentation page on development rules.
2. Comment all dependences in configure.ac in order to be able to install the doc before the other packages.
2007/04/25
1. add the packages hppTutorialPlanner and kppTutorialPlanner
......
#
# Copyright
# Copyright 2007 LAAS-CNRS
#
Installation instructions for library hppDoc
......@@ -11,3 +11,4 @@ cd build
../configure [OPTIONS]
make
make install
See INSTALL for installation instruction.
#
# Copyright 2007 LAAS-CNRS
#
This package implements a documentation of most HPP software packages.
It includes:
-1. information about how to install HPP software,
-2. information about how to develop in HPP
-3. a front page with links to the packages constituting HPP.
Item 3 implies that this documentation depends on all the documented packages.
To make possible the installation of this documentation without primarily
installing all the necessary packages, all the dependencies have been
commented out in the configure.ac file:
dnl if PKG_CHECK_MODULES(XXX, xxx); then
dnl XXX_PREFIX=`$PKG_CONFIG xxx --variable=prefix`
dnl AC_SUBST(XXX_PREFIX)
dnl fi
It is recommended to do the following operations:
1. install documentation as such (see INSTALL)
2. install HPP packages you need (Related Pages->How to install HPP)
3. uncomment in configure.ac the packages you have installed and of
which you want to access the documentation (remove dnl
at the beginning of the selected lines
4. reinstall the documentation.
/**
\page hppDoc_development Developing in Hpp
This page explains some development rules applied in Hpp project.
This page explains some development rules applied in Hpp project. They are mostly common sense rules.
\section hppDoc_rules General rules to be followed in HPP developement
\subsection hppDoc_separate_algo_middleware Make clear distinction between algorithms, middleware and graphical interface
\image html archi.png "Architecture of HPP: the functionalities are distributed into separate software packages. The architecture is composed of Three types of packages: algorithms, CORBA interfaces and KPP-SDK interfaces."
\image latex archi.pdf "Architecture of HPP: the functionalities are distributed into separate software packages. The architecture is composed of Three types of packages: algorithms, CORBA interfaces and KPP-SDK interfaces."
HPP is composed of several software packages divided into three groups as explained in the above figure:
\li algorithms,
\li Corba server
\li KPP-interfaces
KPP-interface and Corba server should be considered as visualization and debugging-testing tools.
It is mostly important that packages implementing path planning algorithms for humanoid robots are
independent from a given middleware (CORBA) and from a given GUI (KineoPathPlanner). As a consequence,
no CORBA::xxx attribute should be in a class belonging to the algorithm part.
This simple principle will enable to easily insert the algorithmic software packages into different middlewares (GenoM, RT-middleware for instance).
\subsection hppDoc_small_packages Modularity
Try to avoid developing huge packages including many functions. Instead, build several small packages
with simple interfaces and easy to understand functionalities.
\subsubsection hppDoc_example1 Example
Let us assume that you are developing a path planning algorithm and you want to use quaternions to represent the orientations of rigid-bodies.
\li The first step consists in trying to find an existing implementation of quaternions that you can use.
\li Let us assume (this is very unlikeky) that you cannot find a good implementation of quaternions, then, instead of developing operations on quaternions in your path planning package, it is much more clever to create a package that will handle quaternion operations and to make your path planning package depend on it. Later, other users will be able to use your quaternion package.
\subsection hppDoc_level_generality Level of generality
When you implement an algorithm, always ask yourself the question: "Could my algorihtm be applied to applications more general than the one I am dealing with?"
If yes, try to make your algorithm take more general input than your practical problem of today.
\subsubsection hppDoc_example2 Example
Let us assume that you want to implement Newton algoritm to find a root of a polynomial function.
Your algorithm requires the derivative of the polynomial.
You can get an expression of a polynomial derivative using the polynomial coefficients.
However, it would be more clever to develop the same algorithm taking as input a function that might not be a polynomial.
For that you can define an abstract class
\code
class Cmapping {
public:
virtual double value(double inParamter) = 0;
virtual double derivative(double inParamter) = 0;
};
\endcode
make your Newton implementation take as input an object \c Cmapping and then derive this class into a concrete polynomial class.
Thus, your algorithm can be used by other people wanting to find the root of non-polynomial functions.
\subsubsection hppDoc_humanoid Humanoid robots
The algorithms we develop are mostly applied to one type of humanoid robot: HRP2.
It is therefore important to develop these algorithms in such a way that they can be
applied to any other humanoid robot. For that developers should avoid to make too strong asumptions
about the robot structure. The abstract CjrlHumanoidDynamicRobot interface for dynamic humanoid robots have been designed in this aim.
\section hppDoc_howto How to implement a new algorithm in HPP.
To implement a new algorithm in HPP, you need to create new software packages as described below.
To create new software packages, we advise developers to use perl script \c packageCreate.
\code
[~] cd devel/src
[src] cg-clone git+ssh://[git|softs].laas.fr/git/robots/scripts
\endcode
\subsection hppDoc_new_algo Create a new software package implementing your algorithm
To create a new package depending on \c hppCore, type the following commands.
\code
[~] cd devel/src
[src] perl ./scripts/packageCreate hppNewAlgo -d hppCore HPPCORE
\endcode
If you want your package to depend on other packages add -d package PACKAGE for each dependence.
This operation creates a template of software package with all necessary files to compile. There are four subdirectories in this package:
\li \c doc: contains necessary files to generate doxygen documentation,
\li \c include contains headers files
\li \c src contains source code files
\li \c unitTesting contains files used to test the algorithm developed in the package.
Define in <tt>include/hppNewAlgo.h</tt> a class that derives from ChppPlanner.
\code
#include "hppPlanner.h"
class ChppNewAlgo : public ChppPlanner {
public:
...
ktStatus solve();
};
\endcode
Class ChppPlanner proposes an interface function to insert a robot:
\code
ktStatus ChppPlanner::addHppProblem(CkppDeviceComponentShPtr robot);
\endcode
Independently from how the robot is inserted into the object, you can use
it as the input of your algorithm in your class ChppNewAlgo:
\code
CkppDeviceComponentShPtr robot = robotIthProblem(0);
\endcode
Write in <tt>src/hppNewAlgo.cpp</tt> function
\code
ktStatus ChppNewAlgo::solve()
{
CkwsPath path = resultOfNewAlgo();
ChppProblem& hppProblem = hppProblemVector[problemId];
hppProblem.addPath(kwsPath);
}
\endcode
that runs your algorithm. The two last lines insert the result of your path in KPP interface if the interface is running.
To compile and install your package do the following step:
\code
[~] cd devel/src/hppNewAlgo
[hppNewAlgo] aclocal
[hppNewAlgo] libtoolize -c
[hppNewAlgo] autoconf
[hppNewAlgo] automake -ac
[hppNewAlgo] mkdir build
[hppNewAlgo] cd build
[hppNewAlgo] ../configure --prefix=${HOME}/devel
[hppNewAlgo] make
[hppNewAlgo] make install
\endcode
\subsection hppDoc_new_interface Create a new KPP-interface for your package
To be able to see the result of your algorithm, you need to create a new KPP-interface deriving from CkppInterface
\code
[~] cd devel/src
[src] perl ./scripts/packageCreate kppInterfaceNewAlgo -d kppInterface KPPINTERFACE -d hppNewAlgo HPPNEWALGO
\endcode
and depending on your algorithm software package.
See package \c kppInterfaceTutorial for an example, and especially for managing Kineo license issue in <tt>src/Makefile.am</tt>
\code
[~] cd devel/src
[src] cg-clone git+ssh://[git|softs].laas.fr/git/jrl/hppTutorialPlanner
[src] cg-clone git+ssh://[git|softs].laas.fr/git/jrl/kppInterfaceTutorial
\endcode
To run your interface into KineoPathPlanner, do the following:
\code
[~] KineoPathPlanner -ModulePath ${HOME}/lib/modules/${HOST}/libkppInterfaceNewAlgo
\endcode
*/
- separer interfaces et algo
- utiliser kppInterface pour débugguer en s'assurant qu'on exécute les mêmes opérations.
......@@ -111,11 +111,11 @@ Compile and install the packages in your development directory
\subsection hppDoc_omniORB Configuring CORBA and using hppCorbaServer
\c hppCorbaServer is a package that enables developers to run their algorithms from external application like python scripts for instance.
This package instanciates a Corba server that can handle requests trigerring actions in HPP. The main actions consist in
\li defining robots,
\li defining obstacles,
\li defining and solving path planning problems.
The package also implements an OpenHRP client that enables the user to download HRP2 model by a Corba request.
This package instanciates a 3 CORBA objects that can handle requests trigerring actions in HPP. The CORBA objects correspond to the following interfaces:
\li <tt>ChppciRobot</tt> to define and build robots,
\li <tt>ChppciObstacle</tt> to define obstacles,
\li <tt>ChppciProblem</tt> to define and solve path planning problems.
The package also optionally implements an OpenHRP client (configuration option --with-openhrp) that enables the user to download HRP2 model by a Corba request.
\c hppCorbaServer is based on omniORB4 (installed by robotpkg), an implementation of Corba. We will explain now how to configure omniORB4 in order to be able
\li to load HRP2 model from OpenHRP
......@@ -159,6 +159,40 @@ setenv OMNIORB_CONFIG ${HOME}/omniORB/omniORB.cfg
setenv OMNINAMES_LOGDIR ${HOME}/omniORB/log
\endcode
\subsubsection hppDoc_python Controlling an application using python scripts
To send request to hppCorbaServer using python, you need to install packages
\li <tt>omniORBpy</tt> through robotpkg (<tt>cd ${HOME}/openrobots/robotpkg/devel/omniORBpy; make update</tt>) and
\li <tt>hppPython</tt> (either through <tt>robotpkg</tt> or through <tt>git</tt>).
Installation of \c hppPython is similar to other packages, except that command
\code
[package] libtoolize -c
\endcode
should be omitted.
<tt>hppPython</tt> installs a python script \c hppInit.py that initializes 3 CORBA clients, one to each the 3 CORBA objects instanciated by <tt>hppCorbaServer</tt> and described at the beginning of this section (\ref hppDoc_omniORB).
\c hppInit.py is installed in <tt>${HOME}/devel/share/script/python</tt>. Tu use this script, you need to set the following environment variables.
\code
setenv PYTHONPATH ${HOME}/devel/share/script/python:${HOME}/openrobots/lib/pythonx.y/site-packages:${PYTHONPATH}
setenv LD_LIBRARY_PATH ${HOME}/openrobots/lib:${LD_LIBRARY_PATH}
\endcode
where \c x.y is the version number of python installed by \c robotpkg.
Then open a python shell and call the initialization script
\code
[~] python
Python 2.4.3 (#1, Oct 23 2006, 14:19:47)
[GCC 4.1.1 20060525 (Red Hat 4.1.1-1)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from hppInit import *
>>>
\endcode
Three variables \c robotClient, \c obstacleClient and \c problemClient are defined and can be used to send requests to \c hppCorbaServer.
For an example, see <tt>hppPython/src/example.py</tt>.
\section hppDoc_install_example Example: Intalling and running walk planner package and corresponding kpp Interface
\subsection hppDoc_install_example_subsec Installing necessary packages
......@@ -201,6 +235,8 @@ ready
\image html "kppInterfaceWalk.png" KineoPathPlanner with module kppInterfaceWalk.
\subsubsection hppDoc_solve_GUI Defining and solving a problem using menu "HPP/WALK"
To solve a simple problem without obstacles, do the following step:
\li Click in menu "HPP/WALK -> Load HRP2"
......@@ -223,6 +259,24 @@ ready
\li Play the path in the path player that has appeared.
\subsubsection hppDoc_solve_python Defining and solving a problem using python scripts
\li Click in menu "HPP/WALK -> Start CORBA Server"
\li Open a python interpreter and type the commands below.
\code
[~] python
Python 2.4.3 (#1, Oct 23 2006, 14:19:47)
[GCC 4.1.1 20060525 (Red Hat 4.1.1-1)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from hppWalkInit import *
>>> initWalkPlanner(-8, -8, 0, 8, 8, 0)
>>> problemClient.solve()
\endcode
\li In the "Scene" tree, in the "Paths" node, select the last path
\li Play the path in the path player that has appeared.
You can of course add obstacles using Corba Client obstacleClient
*/
......@@ -48,7 +48,9 @@ The following packages implements a Corba communication functionalities
\htmlonly
<ul>
<li><a href="@HPPCORBASERVER_PREFIX@/share/doc/hppCorbaServer/main.html">hppCorbaServer</a>: Corba server to implementing a ChppPlanner object.</li>
<li><a href="@HPPPYTHON_PREFIX@/share/doc/hppPython/main.html">hppPython</a>: Script python to communicate with hppCorbaServer.</li>
<li><a href="@HPPOPENHRP_PREFIX@/share/doc/hppOpenHRP/main.html">hppOpenHRP</a>: Corba server that implements the model of HRP2.</li>
</ul>
\endhtmlonly
......@@ -66,7 +68,5 @@ These packages implement interfaces with Kineo Path Planner GUI.
</ul>
\endhtmlonly
\image html archi.png "Architecture of HPP: the functionalities are distributed into separate software packages. The architecture is composed of Three types of packages: algorithms, CORBA interfaces and KPP-SDK interfaces."
\image latex archi.pdf "Architecture of HPP: the functionalities are distributed into separate software packages. The architecture is composed of Three types of packages: algorithms, CORBA interfaces and KPP-SDK interfaces."
*/
......@@ -158,7 +158,9 @@ SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
TAGFILES = @HPPCORBASERVER_PREFIX@/share/doc/doxytag/hppCorbaServer.doxytag=@HPPCORBASERVER_PREFIX@/share/doc/hppCorbaServer \
@ABSTRACTROBOTDYNAMICS_PREFIX@/share/doc/doxytag/abstractRobotDynamics.doxytag=@ABSTRACTROBOTDYNAMICS_PREFIX@/share/doc/abstractRobotDynamics \
@HPPCORE_PREFIX@/share/doc/doxytag/hppCore.doxytag=@HPPCORE_PREFIX@/share/doc/hppCore
GENERATE_TAGFILE = hppDoc.doxytag
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
......
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