[prev in list] [next in list] [prev in thread] [next in thread]
List: orocos-dev
Subject: [Orocos-Dev] draft manuals for upcomming release
From: peter.soetens () mech ! kuleuven ! ac ! be (Peter Soetens)
Date: 2003-10-15 18:38:00
Message-ID: 200310151823.06252.peter.soetens () mech ! kuleuven ! ac ! be
[Download RAW message or body]
I am still re-writing the manuals for the upcomming release. I have rewritten
the configuration/installation part and the motion-control part (which is now
mainly control-kernel).
I attach the resulting html files for your reference and comments.I still need
to work out the subversion repository with the system administrator for
public access.
Peter
--
------------------------------------------------------------------------
Peter Soetens http://www.orocos.org
Katholieke Universiteit Leuven
Division Production Engineering, tel. +32 16 322773
Machine Design and Automation fax. +32 16 322987
Celestijnenlaan 300B peter.soetens@mech.kuleuven.ac.be
B-3001 Leuven Belgium http://www.mech.kuleuven.ac.be/pma
------------------------------------------------------------------------
["orocos-control-kernel.html" (text/html)]
<html><head><meta http-equiv="Content-Type" content="text/html; \
charset=ISO-8859-1"><title> Orocos ControlKernel </title><meta name="generator" \
content="DocBook XSL Stylesheets V1.56.1"><meta name="description" content=" This \
document explains the design and implementation of the Control Kernel Framework.
"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" \
alink="#0000FF"><div class="book"><div class="titlepage"><div><h1 class="title"><a \
name="id2780236"></a> Orocos ControlKernel </h1></div><div><div \
class="authorgroup"><div class="author"><h3 class="author">Peter Soetens</h3><div \
class="affiliation"><span class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div><div class="author"><h3 \
class="author">Dr. ir. Herman Bruyninckx</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div><div class="author"><h3 \
class="author">Panagiotis Issaris</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div></div></div><div><p \
class="copyright">Copyright © 2002 <tt><<a \
href="mailto:Peter.Soetens@mech.kuleuven.ac.be">Peter.Soetens@mech.kuleuven.ac.be</a>></tt>, \
<tt><<a href="mailto:Herman.Bruyninckx@mech.kuleuven.ac.be">Herman.Bruyninckx@mech.kuleuven.ac.be</a>></tt></p></div><div><div \
class="legalnotice"><p> Permission is granted to copy, distribute and/or modify this \
document under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation, with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of this license can be found at
<a href="http://www.fsf.org/copyleft/fdl.html" \
target="_top">http://www.fsf.org/copyleft/fdl.html</a>. </p></div></div><div><div \
class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th \
align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td \
align="left">Revision 0.01</td><td align="left">22 Aug 2002</td><td \
align="left">hb</td></tr><tr><td align="left" colspan="3">Initial \
version</td></tr><tr><td align="left">Revision 0.02</td><td align="left">19 Sep \
2002</td><td align="left">hb</td></tr><tr><td align="left" colspan="3">Initial \
interface description</td></tr><tr><td align="left">Revision 0.9</td><td \
align="left">13 Nov 2002</td><td align="left">ps</td></tr><tr><td align="left" \
colspan="3">Updated for release</td></tr></table></div></div><div><div \
class="abstract"><p class="title"><b>Abstract</b></p><p> This document explains the \
design and implementation of the Control Kernel Framework.
</p></div></div><hr></div><div class="toc"><p><b>Table of \
Contents</b></p><dl><dt>1. <a href="#id2789386">Introduction</a></dt><dd><dl><dt><a \
href="#id2789399">Installation</a></dt><dt><a href="#id2789429">A last piece of \
advice</a></dt></dl></dd><dt>2. <a href="#id2789452">The Default Control \
Kernel</a></dt><dd><dl><dt><a href="#id2789457">Purpose</a></dt><dd><dl><dt><a \
href="#id2789478">Theoretic background</a></dt><dt><a href="#id2789537">Basic Kernel \
Interfaces ( Kernel, DataObjects, Components )</a></dt></dl></dd></dl></dd><dt>3. <a \
href="#id2790041">Extending the DefaultKernel</a></dt><dt>4. <a \
href="#id2786062">Available Extensions</a></dt><dd><dl><dt><a href="#id2786069">The \
Property Extension</a></dt><dd><dl><dt><a href="#id2786092">Configuring the Property \
Extension</a></dt><dt><a href="#id2786160">Hooks</a></dt></dl></dd><dt><a \
href="#id2786232">The Reporting Extension</a></dt><dd><dl><dt><a \
href="#id2786269">Configuring the Reporting Extension</a></dt><dt><a \
href="#id2786347">Hooks</a></dt></dl></dd></dl></dd><dt>5. <a href="#id2786418"> \
Motion Control Components </a></dt><dd><dl><dt><a href="#id2786425">Stuff to move to \
kernel_components documentation</a></dt><dd><dl><dt><a href="#id2786433">Trajectories \
and Interpolators</a></dt><dt><a href="#id2786491">Properties and the \
MotionMonitor</a></dt><dt><a href="#id2786568">Motion Commands and the \
RobotInterface</a></dt></dl></dd></dl></dd><dt>6. <a \
href="#id2786634">Kinematics</a></dt><dd><dl><dt><a \
href="#id2786642">Introduction</a></dt><dd><dl><dt><a href="#id2786688">The \
KinematicsInterface</a></dt><dt><a href="#id2786740">The \
KinematicsComponent</a></dt></dl></dd></dl></dd><dt>7. <a \
href="#chap-interface">Interfaces</a></dt><dd><dl><dt><a \
href="#interface-motivation">Motivation</a></dt><dt><a \
href="#interface-cart-motion">Cartesian motion</a></dt><dt><a \
href="#interface-axis-motion">Axis</a></dt><dt><a \
href="#interface-device">Device</a></dt><dt><a \
href="#interface-robot">Robot</a></dt><dt><a \
href="#interface-servo">Servo</a></dt><dt><a \
href="#interface-trajectory">Trajectory</a></dt><dt><a \
href="#interface-interpolation">Interpolation</a></dt></dl></dd></dl></div><div \
class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>3.1. <a \
href="#id2790241">Extension Method Hooks</a></dt></dl></div><div \
class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>3.1. <a \
href="#id2786046"></a></dt><dt>4.1. <a href="#id2786108">Example properties.cpf \
file</a></dt><dt>4.2. <a href="#id2786181">The PropertyExtension used in \
CartesianComponents.hpp</a></dt><dt>4.3. <a href="#id2786285">Example reporting.cpf \
file</a></dt><dt>4.4. <a href="#id2786385">Reporting in \
CartesianComponents.hpp</a></dt></dl></div><div class="chapter"><div \
class="titlepage"><div><h2 class="title"><a name="id2789386"></a>Chapter 1. \
Introduction</h2></div></div><div class="toc"><p><b>Table of \
Contents</b></p><dl><dt><a href="#id2789399">Installation</a></dt><dt><a \
href="#id2789429">A last piece of advice</a></dt></dl></div><p> This chapter \
explains installation, and gives an overview of the features and interface of the \
Orocos ControlKernel module. </p><div class="sect1"><div class="titlepage"><div><h2 \
class="title" style="clear: both"><a \
name="id2789399"></a>Installation</h2></div></div><p> Orocos uses the eCos tools for \
configuration and building. Therefore the configuration and building
process is pretty well standardised. We refer to the Orocos Base installation
instructions for the advised configuration and installation procedure.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2789429"></a>A last piece of \
advice</h2></div></div><div class="tip" style="margin-left: 0.5in; margin-right: \
0.5in;"><h3 class="title">Tip</h3> We highly advise you to read first the Orocos \
Core documentation before going on. Its nomenclature will be used extensively.
</div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Tip</h3> This document only covers some generic use cases. If you want \
detailed information about a class or function, read the Doxygen generated \
reference, you will find a lot of information in there not presented here.
</div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2789452"></a>Chapter 2. The Default Control \
Kernel</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#id2789457">Purpose</a></dt><dd><dl><dt><a href="#id2789478">Theoretic \
background</a></dt><dt><a href="#id2789537">Basic Kernel Interfaces ( Kernel, \
DataObjects, Components )</a></dt></dl></dd></dl></div><div class="sect1"><div \
class="titlepage"><div><h2 class="title" style="clear: both"><a \
name="id2789457"></a>Purpose</h2></div></div><p> Anyone wanting to write his own \
software (feedback) controller will need a control kernel to do the work. In this \
kernel, five basic responsabilities are identified and placed under the \
responsability of a Component. The responsabilities are : gathering sensor data \
(Sensor Component), estimating a model (Estimator Component), generating setpoints \
(Generator Component), taking a control action (Controller Component) and sending \
the outputs to the hardware (Effector Component). Depending on the application, \
other components will be used, together with other types of data being exchanged. The \
Default Control Kernel is an empty box. It just defines the basis for which data is \
exchanged between components and what functionality the components can use (more on \
this later). </p><p>
We refer to the source code documentation or the doxygen generated files for the \
most recent documentation about which functions exist and do what.
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2789478"></a>Theoretic background</h3></div></div><p> The implementation of \
the Control Kernel is based on the software pattern for control. A paper is to be \
published, which gives a high level explanation of its purpose. This paper is \
available on the Orocos website. </p><p>
<a href="http://www.orocos.org/documents/motconframe.pdf" target="_top">See the
Control Kernel paper.</a>
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2789537"></a>Basic Kernel Interfaces ( Kernel, DataObjects, Components \
)</h3></div></div><p> When you start thinking about a control application, you \
mostly have a control scheme at hand. This scheme identifies data flows from data \
sources (sensors) over algoriths to data sinks (effectors). In any application the \
following data must be passed around : Input data from sensors, Command data from a
higher level producer, Model data representing the current system state,
SetPoint data denoting the desired system state, Output data to send to the
system's effectors. Identifying what is exactly in these five data types is
the first step for creating a control kernel. In Orocos, these five types
must be given as a template parameter to the DefaultControlKernel. The
most simple invocation is when only a double is passed on (think one axis \
control): </p><pre class="programlisting">
typedef DefaultControlKernel <double, double, double, double, double> \
My1DKernel; </pre><p>
What is shown above is defining the type My1DKernel as being a \
DefaultControlKernel where only a double is exchanged between each component. The \
meaning of the template parameters is like this :
</p><pre class="programlisting">
DefaultControlKernel <InputType, ModelType, CommandType, SetPointType, \
OutputType>; </pre><p>
Which you can remember by the acronym IMCSO ;-). If that doesn't work, looking at \
the data flow (cfr the uni-directional graph) might help to to find the correct \
order. But do not worry, you only need to do this once for your application. Next \
you can create an instance of your new kernel :
</p><pre class="programlisting">
My1DKernel first_kernel;
</pre><p>
What really happend is that you created a kernel with five DataObjects for each \
DataType (being all doubles) and 5 default components which do just nothing. Other \
kernels may define other DataObjects and/or other default components. It is the \
programmers task to replace the default components with 'functional' components, \
actually doing something with the data. Each component can be set and get with the \
respective method calls on the kernel.
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2789624"></a>DataObjects</h4></div></div><p>
Data must be guarded agains concurrent (multi-threaded) access, or it may be \
needed
to fetch the data from a server or to instruct the data-producer to provide a \
new
sample. All these actions are the responsibility of the DataObjects. They shield
or extend data access as the kernel requires. A kernel based on CORBA components
will need DataObjects which understand CORBA, a kernel running in a single \
threaded
system will need no protection at all and thus can use an efficient DataObject. \
The
data guarded by the DataObjects can be any valid C++ type, so mostly people use
classes or structs (instead of double). The default constructor of the data is \
called on creation time.
</p><p>
Choosing a Kernel means choosing DataObjects. Once the kernel is fixed, the \
DataObjects
can no longer be changed. The type of the data they hold is determined and the \
means
of protection also. There are many possible kinds, the most common are listed \
below: </p><div class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789673"></a>DataObjectInterface</h5></div></div><p>This Interface describes \
the Get() and Set() methods each DataObject must have.
Set() and Get() retrieve all contents of the DataObject. This might be a bit \
heavy
for some applications, but fortunately, nameserving can relief this (see \
DataServed). </p></div><div class="sect4"><div class="titlepage"><div><h5 \
class="title"><a name="id2789690"></a>DataObject</h5></div></div><p>This is the most \
simple DataObject implementation. The Get() and Set() methods
directly map onto the contents and can always be inlined by the compiler. It \
offers no thread safety, but maximum efficiency for copying data.
</p></div><div class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789707"></a>DataObjectLocked</h5></div></div><p>This is a thread safe \
DataObject which Set() and Get() methods are guarded
by a single mutex. The second thread accessing this object will always block, \
which is not always wanted in a realtime system.
</p></div><div class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789723"></a>DataObjectPrioritySet</h5></div></div><p>This is a more complex \
DataObject which gives always priority to the thread
calling Set(), which will never block. The thread accessing Get() will block \
if the
Set() thread is accessing the contents.It is mainly used for sharing data \
between two kernels, running at different priorities.</p><div class="note" \
style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This \
DataObject will only work if the Set() thread has the highest priority. When the \
inverse is true, data corruption will occur. It is obvious that this DataObject can \
only be used if both threads have static priorities (which is the case for all \
threads in the Orocos framework)</p></div></div><div class="sect4"><div \
class="titlepage"><div><h5 class="title"><a \
name="id2789755"></a>DataObjectPriorityGet</h5></div></div><p>The inverse of \
DataObjectPrioritySet. The thread accessing Get() will never \
block.</p></div></div><div class="sect3"><div class="titlepage"><div><h4 \
class="title"><a name="id2789770"></a>Components</h4></div></div><div \
class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789777"></a>Defining your own Component</h5></div></div><p>As mentioned \
before, the Default Kernel will have made Default Components which do \
nothing.
The kernel is equiped with setController(), setGenerator(),.. methods which \
allow a clean insertion
of a new component and which guarantee a clean removal of the old component. \
Defining a Component of your own goes like this :
</p><pre class="screen">
#include <Kernel.hpp>
template < class _DefaultGenerator >
class MyGenerator
: public _DefaultGenerator
{
void pull() {
// ...
}
void calculate() {
// ...
}
void push() {
// ...
}
};
</pre><p>What you see is that the class MyGenerator has one template argument, \
_DefaultGenerator,
which must be supplied on object creation and this template argument is a base \
class of MyGenerator.
This might look a bit strange to people not familiar with templates, but the \
aim of this construct
is to allow the changing of the base class of a Component, without having to \
adjust the code each time.
As you can guess, the _DefaultGenerator type is supplied by the kernel. You \
can access it like this :</p><pre class="screen">
My1DKernel::DefaultGenerator</pre><p>These types exist for all components. Of \
course, the type is useless in that form, it must be supplied to your own written \
component : </p><pre class="screen">
MyGenerator< My1DKernel::DefaultGenerator > my_gen;</pre><p>The above \
line has created an instance of MyGenerator called my_gen and which \
now has the
DefaultGenerator as base class. Since MyGenerator is a subclass of \
DefaultGenerator, it can be
used with the setGenerator() method call of the DefaultKernel. The next line \
could then be :</p><pre class="screen"> first_kernel.setGenerator( &my_gen );
</pre><p>which would cause my_gen to be loaded into the kernel and the default \
generator unloaded. This is possible for all components of the kernel.</p></div><div \
class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789878"></a>Inserting Functionality and Algorithms</h5></div></div><p>As \
seen in the previous section, each component you write should have at \
least a
pull(), calculate(), push() method for data processing. The pull() method will \
Get() the
data objects and copy its contents to local variables, the calculate() method \
will perform
some algorithmic functionality on the data and the push() method must Set() \
the results in
the next DataObject. This division is done to isolate communication in \
different methods
so that a more intelligent interaction between kernel and component is \
possible. For example,
a certain kernel implementation could only call the pull() method if new data \
is effectively
available, but always calls the calculate/push() method. A practical example \
of this is the
Interpolator residing in a Generator component.</p><p>A DataObject can be \
accessed from within the component as such :</p><pre class="screen"> // ...
_DefaultGenerator::InputType localCopy;
_DefaultGenerator::SetPointType localResult;
// ...
void pull() {
localCopy = _DefaultGenerator::Inputs::dObj()->Get();
}
void calculate() {
// ... calculate the setpoint
}
void push() {
_DefaultGenerator::SetPoints::dObj()->Set( localResult );
}
</pre><p>
These methods are used for the Data-Flow of the kernel. You copy data from one
component to the other, purely for doing calculations, not doing \
configurations.
If you want to configure/modify a component, you must add a method call to it,
which does the action. An example is a method to turn off the D action of a \
PID
Controller Component. The wrong way to do this is to insert a 'bool' member in \
the
SetPointType to indicate if the D action should be enabled. The correct way is \
to
provide a method. If it must be switched off dynamically, an Event can be \
created
which is fired by the component (Generator, Estimator or even an external \
object)
which demands that the D action must be stopped. The Controller can locate \
this
Event and register the disable/enable-method as a handler. How this is \
practically done is described later.
</p><p>
Fortunately, a Template file is provided from which you can copy/paste to \
start
writing your own components. This file is called \
<tt>ComponentTemplates.hpp</tt>
and is provided with this package. You will see that for each component \
different DataObjects
can be accessed and different types will be defined to facilitate that access.
</p></div><div class="sect4"><div class="titlepage"><div><h5 class="title"><a \
name="id2789965"></a>Standard Kernel Events</h5></div></div><p>
A component might be interested in the fact if it is inserted in a kernel and \
if
this kernel is running or not. A kernel might possibly do an init- run of the
components so that the member variables can be initialised correctly, with \
sensor
readings for example. All these actions are quite standard for every component \
and
kernel. For each such action, an Event is created by the Kernel which will be \
fired
by the kernel when it occurs. In some cases, a method of the DefaultComponent \
can be overriden and act as an event handler for a specific action.
</p><p>
To summarize, each Kernel has some Events to which each component can \
subscribe.
As an alternative, some Events have a method counterpart which can be \
overriden.
This method is guaranteed to be called when the Event occurs (together with
all the registered handlers).
</p><p>Each DefaultComponent (and thus each component you will insert into the \
kernel) is a subclass of the <tt>ComponentBaseInterface</tt>, which is
defined in the file <tt>KernelInterfaces.hpp</tt>. This interface
allows each component to locate the kernel in which it is loaded by the \
kernel() method returns a pointer to the <tt>KernelBaseExtension</tt>, which
is the base class of each kernel. The <tt>ComponentBaseInterface</tt>
defines the methods you can override, the <tt>KernelBaseExtension</tt>
interface allows you to access the Standard Kernel Events. We refer to the \
Doxygen
API documentation for the full documentation of these interfaces. The Events \
document explains how Events work and how a handler can be added.
</p></div></div></div></div></div><div class="chapter"><div \
class="titlepage"><div><h2 class="title"><a name="id2790041"></a>Chapter 3. Extending \
the DefaultKernel</h2></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2790048"></a>Kernel Extensions</h3></div></div><p> \
Extending the Default Kernel, composing extensions </p><p>
The DefaultControlKernel has only little features. It can be used to write a closed
control cycle, but it offers no facilities to report data or configure it at run \
time. A kernel extension mechanism has been designed to extend the kernel, and all \
its components with additional features. A kernel can have as many extensions as \
possible, but each extension can only be added once. There are currently two \
extensions provided : the Property extension and the Reporting extension, which are \
both described below. Each kernel has also a <tt>KernelBaseExtension</tt>, which \
defines the basic features each kernel must have.
</p><p>
Each extension is accompanied by a piece of code, which is inserted in all \
components of the kernel. This allows the component to communicate information to \
the extension and back. This piece of code is called a Component Aspect. As the \
previous section explained, the <tt>KernelBaseExtension</tt> is coupled with
the <tt>ComponentBaseInterface</tt> Aspect. What the Aspect does is
providing extra method calls to each component, which are related to a particular
extension. The extension on the otherhand can access the component through the \
Aspect interface.
</p><p>
How does one add an extension to the Default Kernel ? It happens by adding an
extra template parameter on creation. To revisit the My1DKernel example :
</p><pre class="screen">
// equivalent typedef as before :
typedef DefaultControlKernel <double, double, double, double, double, \
KernelBaseExtension> My1DKernel; // adding a new extension to the \
KernelBaseExtension : typedef CompositeExtension< KernelBaseExtension, \
PropertyExtension> MyExtension; typedef DefaultControlKernel <double, double, \
double, double, double, MyExtension> My1DPropertyKernel; </pre><p>
As can be seen, Extensions are composed using the <tt>CompositeExtension</tt>
class, specifying the < First, Second > extension, where First and Second are \
allowed to be Composite Extensions themselves. The order First, Second determines \
which Extension is executed before the other. In the example above, the \
<tt>KernelBaseExtension</tt> is executed by the kernel before the \
<tt>PropertyExtension</tt>, as it should be. Adding the reporting extension is then \
analogouos : </p><pre class="screen">
// ...
// A kernel with two additional Extensions :
typedef CompositeExtension< MyFirstExtension, ReportingExtension> \
MySecondExtension; typedef DefaultControlKernel <double, double, double, double, \
double, MySecondExtension> My1DPropRepKernel; </pre><p>
The order in which the extensions are composed is important. If one extension fails
on startup, the other will not be initialised and the starting of the kernel will \
fail. Logically, you can read from left to right : If the first works, check then if \
the second works, then the third etc. A whole dependency tree can be built in that \
way, but each extension can occur only once.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2790182"></a>Component Aspects</h3></div></div><p> Extensions add Aspects to \
Components. </p><p>
Adding an Extension to the kernel does not (visibly) change the existing components.
So a component does not need to anticipate any possible extension (nor does the \
Kernel). The Aspect, which is added to the Component does however add a hook, into \
which the Component can place code which will be executed when the Extension \
accesses the Component. If a component wants to export some data when the kernel \
supports reporting, it will put some code into the <tt>exportReports()</tt> hook. If \
the reporting extension is not present in the kernel, the <tt>exportReports()</tt>
method will never be called. The Extension can know if a component has put code into
the hook by providing a default implementation which gets called if the component
does no want to use it. Each Aspect is defined as such that the Component has a \
passive role, meaning that the hook is always called by the Extension, and the \
component does not need to call the Extension (which would lead to locking the \
component into an Extension).
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2790225"></a>Extension Method Hooks</h4></div></div><p> Almost every \
Extension will provide a hook method that each component can override ( re-implement \
) to make use of the functionality. One hook might be used by different Extensions, \
as long as the semantical meaning remains the same for both Extensions. The \
following hooks are defined until now : </p><div class="table"><a \
name="id2790241"></a><p class="title"><b>Table 3.1. Extension Method \
Hooks</b></p><table summary="Extension Method Hooks" \
border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Used \
For</th><th>Used By Extension</th></tr></thead><tbody><tr><td> void exportReports( \
PropertyBag& bag ) </td><td>The component needs to fill the bag with its own \
Properties
which will be read after each kernel cycle. This is how the Extension
knows what the Component wants to report.
</td><td>ReportingExtension, CORBAExtension</td></tr><tr><td>bool \
updateProperties( const PropertyBag& bag )</td><td>The component can use the \
Properties found in the bag to update its own properties. The Extension got the \
Properties from
a .cdl xml file.</td><td>PropertyExtension</td></tr></tbody></table></div><p>
</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2790327"></a>Configuring a Kernel.</h3></div></div><p>This section explains \
how a ControlKernel can be configured in your program.</p><div class="sect3"><div \
class="titlepage"><div><h4 class="title"><a name="id2790340"></a>The \
KernelConfigurator</h4></div></div><p>Kernels ( and Components ) can be configured \
at runtime with an XML file in the CPF (Component Property Format) format, defined \
by the OMG group. The KernelConfigurator is a class which can read a given xml file \
and configure a kernel with that information. The KernelConfigurator parses the file \
and passes the result to the <tt>updateKernelProperties()</tt> method.
If you want to add your own configuration options to a Kernel subclass, you can
override this method, with your own which parses the extra properties
and then call the method of the base class with the rest of the bag.
</p><p>A kernel configuration file might look like this :</p><pre \
class="programlisting"> <?xml version="1.0" \
encoding="UTF-8"?> <properties>
<struct name="KernelProperties" type="type_less">
<description>The Basic characteristics of this kernel.</description>
<simple name="name" \
type="string"><description>The Name of this \
kernel</description><value>Default</value></simple> \
<simple name="frequency" \
type="double"><description>The periodic execution frequency in \
Hz</description><value>1000</value></simple> <simple \
name="priority" type="string"><description>The priority \
of the kernel.</description><value>NonPreemptible</value></simple>
</struct>
<struct name="Extensions" type="type_less">
<simple name="Interpreter" type="string">
<description>The property file of the interpreter</description>
<value>interpreter.cpf</value></simple>
<simple name="Reporter" type="string">
<description>The property file of the reporter</description>
<value>reporter.cpf</value></simple>
<simple name="Sequencer" type="string">
<description>The property file of the sequencer</description>
<value>sequencer.cpf</value></simple>
<simple name="Property" type="string">
<description>The property file of the property manager</description>
<value>property.cpf</value></simple>
</struct>
</properties>
</pre><p>
It has two major parts : KernelProperties and Extensions. The first contains \
general options which apply to any kernel. The second specifies the property file \
for each (possible) extension. If the file is not found, an error is raised by the \
KernelConfigurator. The XML format is further explained in the Property Extension \
section. It is allowed to define your own properties in this file and update them in \
your own <tt>updateKernelProperties</tt> method.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2790442"></a>Configuring the Kernel with XML files</h4></div></div><p> \
Runtime configuration of the Kernel and its Components can happen with XML files, so \
that you don't have to recompile your program each time you want to change an option. \
The CPF format is defined in the cpf.dtd file and is equal to the CORBA 3 standard's \
property file format. The Default Kernel and each extension have an own cpf file, \
which defines the values some (or all) properties should take. There may be more
properties than listed in the cpf file and vice versa. The parser will do its
best effort to configure each component with the given data.
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Tip</h3> Example cpf files can often be found in the doc directory of \
the packages. </div></div><div class="sect3"><div class="titlepage"><div><h4 \
class="title"><a name="id2790470"></a>Properties</h4></div></div><p> Properties are \
a way to represent configuration options in an abstract way. The property contains \
data or has a value, which is of one certain, immutable type. Any type can be \
encapsulated by a Property. A Property of a double is written as : </p><pre \
class="screen">Property<double> d_prop;</pre><p>. A Property of an arbitrary \
type A is equally written as </p><pre class="screen">Property< A > \
a_prop;</pre><p>. This however does not enable the marshallers or demarshallers to \
know how to convert a property to a text file and vice versa. For each unknown type,
the user has to write an composeProperty and decomposeProperty method.
How this must happen can be read in the
<tt>corelib/properties/base PropertyComposition.hpp</tt> and
<tt>corelib/properties/base PropertyDecomposition.hpp</tt> files.
</p><div class="example"><a name="id2786046"></a><p class="title"><b>Example 3.1. \
</b></p> The Geometry primitives have also such custom functions which can be found
in the file <tt>geometry MotionProperties.hpp</tt> file.
</div></div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2786062"></a>Chapter 4. Available \
Extensions</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#id2786069">The Property Extension</a></dt><dd><dl><dt><a \
href="#id2786092">Configuring the Property Extension</a></dt><dt><a \
href="#id2786160">Hooks</a></dt></dl></dd><dt><a href="#id2786232">The Reporting \
Extension</a></dt><dd><dl><dt><a href="#id2786269">Configuring the Reporting \
Extension</a></dt><dt><a href="#id2786347">Hooks</a></dt></dl></dd></dl></div><div \
class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a \
name="id2786069"></a>The Property Extension</h2></div></div><p> Extending your \
components with properties. </p><p>
By default, only the Kernel has a limited set of properties, Components have none.
The PropertyExtension adds properties also to the components. The properties.cpf
file lists the cpf file for each component type. The components present
in the kernel will get the properties updated on starting the kernel. An option
can be enabled to configure all components, even those not loaded in the kernel.
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786092"></a>Configuring the Property Extension</h3></div></div><p> The \
PropertyExtension can be configured through the cpf file given in the kernel \
configuration file. Not all configuration options are yet implemented and the layout \
may change in future releases. An example looks like this :
</p><div class="example"><a name="id2786108"></a><p class="title"><b>Example 4.1. \
Example properties.cpf file</b></p><pre class="programlisting"> <?xml \
version="1.0" encoding="UTF-8"?> <!DOCTYPE properties \
SYSTEM "cpf.dtd"> <properties>
<!--Possible future syntax : -->
<struct name="Generator" type="ComponentEntry">
<simple name="Type"><value>Generator</value></simple>
<simple name="Filename"><value>MotionGenerator.cpf</value></simple>
</struct>
<!--Current syntax : -->
<simple name="Generator" \
type="string"><description>The Generator Component Property \
File.</description><value>generator.cpf</value></simple> \
<simple name="Estimator" \
type="string"><description>The Estimator Component Property \
File.</description><value>estimator.cpf</value></simple> \
<simple name="Controller" \
type="string"><description>The Controller Component Property \
File.</description><value>controller.cpf</value></simple> \
<simple name="Sensor" \
type="string"><description>The Sensor Component Property \
File.</description><value>sensor.cpf</value></simple> \
<simple name="Effector" \
type="string"><description>The Effector Component Property \
File.</description><value>effector.cpf</value></simple>
<simple name="SaveProperties" type="boolean">
<description> True if properties of components need to be saved when \
stopping the kernel.</description> <value>1</value>
</simple>
<simple name="SaveFilePrefix" type="string">
<description>The suffix of the filename to store the components state \
into</description><value>saved_</value> </simple>
<simple name="SaveFileExtension" type="string">
<description>The extension of the filename to store the components \
state into</description><value>cpf</value> </simple>
</properties>
</pre></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786160"></a>Hooks</h3></div></div><p>The Property Extension \
has one hook : the <tt>updateProperties( const PropertyBag& bag )</tt>
method. The user must extract properties from the bag and assign
his own proper property with the value found. A helper function
can be written to facilitate this for any type.
</p><div class="example"><a name="id2786181"></a><p class="title"><b>Example 4.2. \
The PropertyExtension used in CartesianComponents.hpp</b></p><p> A simple component \
with only one property. If composeProperty can not find the gain property back, it \
will return false, and the kernel will not start.
</p><pre class="programlisting">
// In constructor, gain defaults to zero :
, gain("Gain","The gain of the controller",0)
// Hook In Controller Component :
virtual bool updateProperties( const PropertyBag& bag)
{
return composeProperty(bag, gain ); // returns true if successful.
}
// ... The gain of the Controller ...
Property<double> gain;
// ...
</pre><p>The cpf file looks like this :</p><pre class="programlisting">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "cpf.dtd">
<properties>
<simple name="Name" \
type="string"><description>The unique name of this \
component</description><value>CartesianController</value></simple>
<simple name="Gain" \
type="double"><description>The gain of the controller \
</description><value>2</value></simple> </properties>
</pre></div></div></div><div class="sect1"><div class="titlepage"><div><h2 \
class="title" style="clear: both"><a name="id2786232"></a>The Reporting \
Extension</h2></div></div><p> Reporting components and dataobjects values.
</p><p>
A second functional Extension is the Reporting Extension. It enables components
to report the status of internal variables to the screen or to a file, independent
of the kernel's execution period. It can be used for synchronous reporting of data
(every sample), but the design favoured determinism of execution time over
determinism of data acquisition.
This means that it is possible that a data sample is lost, but never possible that
the kernel stalls because of the reporting activity. Another extension does not need
to make the same choice however.
</p><p>
What happens is that after each kernel step, the Extension tries to make
a backup of the components data. If by accident the data is accessed by
the report writing task, the copy operation is cancelled. A better buffering
mechanism (swinging buffers) might solve this in a better way.
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786269"></a>Configuring the Reporting Extension</h3></div></div><p> The \
ReportingExtension can be configured through the cpf file given in the kernel \
configuration file. Not all configuration options are yet implemented and the layout \
may change in future releases. An example looks like this :
</p><div class="example"><a name="id2786285"></a><p class="title"><b>Example 4.3. \
Example reporting.cpf file</b></p><pre class="programlisting"> <?xml \
version="1.0" encoding="UTF-8"?> <!DOCTYPE properties \
SYSTEM "cpf.dtd"> <!-- Properties of the ReportingExtension -->
<properties>
<simple name="ReportPeriod" type="double">
<description>The period, in seconds, for making \
reports.</description> <value>0.1</value>
</simple>
<simple name="ReportFile" type="string">
<description>The file to write the reports to.</description>
<value>reports.txt</value>
</simple>
<simple name="ReportServer" type="string">
<description>The name of the report server to use.</description>
<value>MyReporter</value>
</simple>
<simple name="WriteToStdOut" type="boolean">
<description>True if the report needs to be written to standard \
output.</description> <value>1</value>
</simple>
<simple name="WriteToFile" type="boolean">
<description>True if the report needs to be written to a \
file.</description> <value>1</value>
</simple>
<struct name="Exporters" type="type_less">
<simple name="Component" \
type="string"><value>Sensor</value></simple>
<simple name="Component" \
type="string"><value>Effector</value></simple>
<simple name="Component" \
type="string"><value>Controller</value></simple>
<simple name="Component" \
type="string"><value>Estimator</value></simple>
<simple name="Component" \
type="string"><value>Generator</value></simple> \
</struct> </properties>
</pre></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786347"></a>Hooks</h3></div></div><p>The ReportingExtension \
has one hook : the <tt>void exportReports( PropertyBag& bag) </tt>
method. The user must put every value he wishes to report in a
Property of the according type. For example to report a 6D position,
one would create a Property </p><pre class="screen">Property< Double6D > \
q6;</pre><p> in the component class. The exportReports method will then insert this
property into the given bag. Of course, a component does not need to
report all its properties, depending on the configuration, other
types might be reported.
</p><p>
The Decomposition constraint of the
PropertyExtension also applies here.
</p><div class="example"><a name="id2786385"></a><p class="title"><b>Example 4.4. \
Reporting in CartesianComponents.hpp</b></p><p> A simple component with only one \
value to report. </p><pre class="programlisting">
// In constructor :
:end_pos("End Position","One of many variables which can be \
reported.")
// Hook in Generator Component:
virtual void exportReports(PropertyBag& bag)
{
bag.add(&end_pos);
}
// The property itself
Property< ORO_Geometry::Frame > end_pos;
// ...
</pre></div></div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2786418"></a>Chapter 5. Motion Control Components \
</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#id2786425">Stuff to move to kernel_components \
documentation</a></dt><dd><dl><dt><a href="#id2786433">Trajectories and \
Interpolators</a></dt><dt><a href="#id2786491">Properties and the \
MotionMonitor</a></dt><dt><a href="#id2786568">Motion Commands and the \
RobotInterface</a></dt></dl></dd></dl></div><div class="sect1"><div \
class="titlepage"><div><h2 class="title" style="clear: both"><a \
name="id2786425"></a>Stuff to move to kernel_components \
documentation</h2></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786433"></a>Trajectories and \
Interpolators</h3></div></div><p> We use the LRL (Leuvens Robotics Library) \
Trajectory planning software which can be found on the Orocos webpage. The library \
already provides Cartesian path planning and interpolation. We provided actuator \
(joint) level interpolators described by the <tt>TrajectoryInterpolatorInterface
</tt>. It is used to decouple two control loops which run with
different periodicities. Internally, a fifo buffer is used to make the
decoupling. The slower loop writes a new setpoint to the interpolator,
the interpolator reads new setpoints from its buffer when its needed.
A setpoint is always set in combination with a relative timeperiod
which indicates how long the interpolater must do between its current
value and the new setpoint. After this time, a new setpoint will be read.
When time zero is given, the interpolater will go as fast as possible
( obeying limits ) to the latest setpoint and will use the new one
as soon as it arrives. The interpolators buffer can thus be filled with
a series of setpoints in advance and then process them as desired.
</p><p>
Two implementations exist :
<tt>TrajectoryInterpolatorSimple</tt>, which is more for
testing since it does not interpolate, but does use the buffer,
timing and limiting infrastructure.
The <tt>TrajectoryInterpolatorParabolic</tt>provides
an integrater which allows variable period interpolations and parabolic
interpolation between two consecutive setpoints.
</p><p>
The interpolator is mostly placed at an end of the control loop,
generating reference signals.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786491"></a>Properties and the MotionMonitor</h3></div></div><p> \
ControlKernel provides some extentions to the LRL. We have written PropertySets \
which represent structures as Frame, Twist, etc from the LRL. The \
<tt>MotionMonitor</tt> extends the core <tt>ReportHandler</tt> to allow reporting
of these structures also.
The Properties exist in two kinds,
on one hand is the <tt>PropertyObject</tt>
(or <tt>PropXYZ</tt>), which extends the
existing structures with a property like interface. This means
that you can anywhere replace an existing structure with
a <tt>PropertyObject</tt>. On the other hand
are the predefined <tt>PropertySet</tt>
(or <tt>PropertySetXYZ</tt> objects
which extends the <tt>PropertySet</tt> class
to extract the represented structure (e.g. Frame, Twist,...).
</p><p>
These properties become handy for reporting to userspace and
setting parameters of the realtime system. The interfacing
package provides a way of changing properties in
an easy way. (all we need now is a GUI :-)
</p><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3> RTLinux users can not use this until they have a memory \
allocator. </div><p>
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786568"></a>Motion Commands and the RobotInterface</h3></div></div><p> The \
ControlKernel package extends the interfacing package with some ControlKernel \
specific extensions. Please read the interfacing package documentation for further \
explanations of the terms below
</p><p>
This package also defines a generic <tt>RobotInterface
</tt>, designed for a 6 degrees of freedom robot.
It is nameserved which means that we can control any
known robot in a generic way.
This interface is far from definate, but it should map on
most robots.
When the configure script detects that the interfacing package
is installed, it will also compile a series of
<tt>Command</tt> classes, designed for
calling the methods in the <tt>RobotInterface</tt>.
A <tt>Parser</tt> will create and relay all commands
for nameserved robots.
</p><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3> RTLinux users can not use this until they have a memory \
allocator. </div><p>
</p></div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2786634"></a>Chapter 6. Kinematics</h2></div></div><div \
class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#id2786642">Introduction</a></dt><dd><dl><dt><a href="#id2786688">The \
KinematicsInterface</a></dt><dt><a href="#id2786740">The \
KinematicsComponent</a></dt></dl></dd></dl></div><div class="sect1"><div \
class="titlepage"><div><h2 class="title" style="clear: both"><a \
name="id2786642"></a>Introduction</h2></div></div><p> Kinematics are used for \
converting postions, velocities,... expressed in one (orthogonal) frame, to another \
frame or another space. The two major spaces in Robotics are Cartesian space and \
Joint space. Cartesian space uses 3D coordinates for position and a kind of \
convention for orientation ( the homogeneous transformation matrix, Euler \
angles,...), while joint space is just the radial position of each joint, thus for \
a 6 degrees of freedom robot, this is a vector with 6 values, denoting
the six joint positions.
</p><p>
Forward kinematics is used to calculate from a given set of joint
positions the end effector position of the robot in a kind of
reference frame. Inverse kinematics is used to calculate from a
given end effector position, expressed in a certain frame,
the joint positions which lead to this position. The solutions
of the inverse kinematics can not always be found because :
The position might be impossible to reach by the robot, or,
the position might be reachable in many ways by the robot
(called different configurations), or,
the joint positions can not be calculated because the end
effectors position is singular, which means that it can be
reached in an infinite amount of ways by the joints.
</p><p>
Our kinematics algorithms keep track of all the above and
much more. This can clearly be seen from the used interfaces too.
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786688"></a>The KinematicsInterface</h3></div></div><p> This interface \
describes the library side of the kinematics algorithms. The interface allows you to \
calculate all forward and inverse jacobians, positions and velocities.
A desired <tt>Configuration</tt>
and a <tt>Singularity</tt>
class instance must be provide where approriate.
How the kinematics are calculated depends on the actual
implementation. We provide the Featherstone algorithms
for many kinds of robots. Only the ZXXDWH and ZYYDWH robots
are converted to the KinematicsInterface. You can take a
look at how we converted them to fit into the framework
if you have a different kind of robot.
</p><p>
The KinematicsInterface is completely stateless and returns
theoretical values, thus does not take into account any
geometry constraints or winding of joints (angles larger
than 360 degrees). All state information is kept in the
<tt>KinematicsComponent</tt>.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786740"></a>The KinematicsComponent</h3></div></div><p> As each robot only \
needs one instance of the <tt>KinematicsInterface</tt>, for doing
the calculations, many are needed to keep track of the current
path and configuration of the robot in different places of
your program. The KinematicsComponent makes sure that between
two consecutive calls, the robot stays in the same configuration
and the joints follow a continuous path. It will return in error
when an impossible jump is detected. It provides methods
for setting or extracting the desired robot configuration.
For example, your trajectory generator and
the actual robot might be using a different KinematicsComponent
to keep track of the state of the calculations.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="chap-interface"></a>Chapter 7. Interfaces</h2></div></div><div \
class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#interface-motivation">Motivation</a></dt><dt><a \
href="#interface-cart-motion">Cartesian motion</a></dt><dt><a \
href="#interface-axis-motion">Axis</a></dt><dt><a \
href="#interface-device">Device</a></dt><dt><a \
href="#interface-robot">Robot</a></dt><dt><a \
href="#interface-servo">Servo</a></dt><dt><a \
href="#interface-trajectory">Trajectory</a></dt><dt><a \
href="#interface-interpolation">Interpolation</a></dt></dl></div><p>
This chapter describes the <span class="emphasis"><em>interfaces</em></span> of \
the different components in the motion control part of Orocos.
</p><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-motivation"></a>Motivation</h2></div></div><p> \
A complex and feature-rich application such as motion control can be given various \
different interfaces. This Section explains and motivates the guidelines we follow \
in the Orocos project to define interfaces:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<span class="emphasis"><em>Loose coupling.</em></span>
Every object that implements an interface must implement the whole
interface. This means that interfaces are kept as small a possible,
and that every object usually implements several interfaces. The
reasons for this choice are: (i) it avoids the need to return
“method not implemented” error messages and the
corresponding error recovery; and (ii) it forces the developers to
classify functionality into parts with the least possible amount of
interdependencies.
</p></li><li><p>
<span class="emphasis"><em>Application independence.</em></span>
The words “robot” or “machine tool” are
avoided whenever possible, because most of the functionalities are
much more general than just for robots or machine tools.
</p></li><li><p>
<span class="emphasis"><em>Shallow inheritance hierarchies.</em></span>
We avoid inheritance hierarchies of more than two levels deep, because
deep hierarchies lead to ambiguous inheritance structure. For example,
one could suggest to have a hierarchy such as “robot”
↦ “6DOF robot” ↦ “6DOF velocity-controlled
robot” ↦ “6DOF hybrid velocity/force-controlled robot”
↦ … But the latter interface could originate equally well
from another hierarchy, such as “control law” ↦
“velocity control” ↦ “hybrid force/velocity
control” ↦ “6DOF hybrid force/velocity
control.”
</p></li><li><p>
<span class="emphasis"><em>Inheritance versus aggregation and \
composition.</em></span>
A particular interface can be a <span \
class="emphasis"><em>specialisation</em></span> of
an already existing interface, for which inheritance is an appropriate
formalism. But an interface can also the
<span class="emphasis"><em>composition</em></span> or <span \
class="emphasis"><em>aggregation</em></span> of other interfaces, i.e., the \
interface contains other interfaces, and possibly puts extra constraints on how to \
use the individual interfaces. The difference between aggregation and composition is
that, in the latter case, the object that implements the composed
interface cannot exist if one of its sub-interfaces is taken out.
</p></li></ul></div><p>
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-cart-motion"></a>Cartesian \
motion</h2></div></div><p> moveTo (Cartesian position); move (Cartesian velocity);
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-axis-motion"></a>Axis</h2></div></div><p> \
readId(); setId(); </p><p>
moveTo (joint position set); move (joint velocity set);
</p><p>
readPos (joint position set); readVel (joint position set);
</p><p>
applyForce (joint velocity set); readForce (joint velocity set);
</p><p>
home ();
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-device"></a>Device</h2></div></div><p> \
readId(); setId(); </p><p>
Activate(), deactivate().
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-robot"></a>Robot</h2></div></div><p> \
readId(); setId(); </p><p>
composite of Axis objects;
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-servo"></a>Servo</h2></div></div><p> \
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="interface-trajectory"></a>Trajectory</h2></div></div><p> \
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a \
name="interface-interpolation"></a>Interpolation</h2></div></div><p> \
</p></div></div></div></body></html>
["orocos-core.html" (text/html)]
<html><head><meta http-equiv="Content-Type" content="text/html; \
charset=ISO-8859-1"><title>Orocos Core</title><meta name="generator" content="DocBook \
XSL Stylesheets V1.56.1"><meta name="description" content=" This document explains \
the design and implementation of the Core component of Orocos, the Open
RObot COntrol Software project. The Core provides
infrastructural support for the functional and application components
of the Orocos framework. An overview of that Orocos framework
(including installation) is
given in the general Orocos overview document.
"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" \
alink="#0000FF"><div class="book"><div class="titlepage"><div><h1 class="title"><a \
name="id2783309"></a>Orocos Core</h1></div><div><div class="authorgroup"><div \
class="author"><h3 class="author">Peter Soetens</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div><div class="author"><h3 \
class="author">Herman Bruyninckx</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div><div class="author"><h3 \
class="author">Panagiotis Issaris</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div></div></div><div><p \
class="copyright">Copyright © 2002 Peter Soetens, Herman \
Bruyninckx</p></div><div><div class="legalnotice"><p> Permission is granted to copy, \
distribute and/or modify this document under the terms of the GNU Free Documentation \
License, Version 1.1 or any later version published by the Free Software Foundation, \
with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of this license can be found at
<a href="http://www.fsf.org/copyleft/fdl.html" \
target="_top">http://www.fsf.org/copyleft/fdl.html</a>. </p></div></div><div><div \
class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th \
align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td \
align="left">Revision 0.01</td><td align="left">22 Aug 2002</td><td \
align="left">hb</td></tr><tr><td align="left" colspan="3">Initial \
version</td></tr><tr><td align="left">Revision 0.9</td><td align="left">11 Nov \
2002</td><td align="left">ps</td></tr><tr><td align="left" colspan="3">lots of \
updates</td></tr></table></div></div><div><div class="abstract"><p \
class="title"><b>Abstract</b></p><p> This document explains the design and \
implementation of the <span class="emphasis"><em>Core</em></span> component of \
Orocos, the <span class="emphasis"><em>Open RObot COntrol Software</em></span> \
project. The Core provides infrastructural support for the functional and application \
components of the Orocos framework. An overview of that Orocos framework
(including installation) is
given in the general Orocos overview document.
</p></div></div><hr></div><div class="toc"><p><b>Table of \
Contents</b></p><dl><dt>1. <a href="#id2789381">The Realtime \
Core</a></dt><dd><dl><dt><a href="#id2789460">Beyond Realtime</a></dt><dt><a \
href="#id2789483">The Framework Operating System Interface (FOSI)</a></dt><dt><a \
href="#id2789825">The Framework Device Interface (FDI)</a></dt><dd><dl><dt><a \
href="#id2790032">Name Serving</a></dt></dl></dd><dt><a href="#id2790318">The Orocos \
Object Hierarchy</a></dt><dt><a href="#id2790346">Threads and Realtime execution of \
your program</a></dt><dd><dl><dt><a href="#id2790354">Starting your \
program</a></dt><dt><a href="#id2790502">The Orocos Thread System</a></dt><dt><a \
href="#id2786126">The Orocos Thread Philosophy</a></dt></dl></dd><dt><a \
href="#id2786355">Events</a></dt><dd><dl><dt><a href="#id2786592">Other Kinds of \
Events</a></dt><dt><a href="#id2786609">EventSimple</a></dt><dt><a \
href="#id2786631">EventMultiCast</a></dt><dt><a \
href="#id2786652">EventBarrier</a></dt><dt><a \
href="#id2786698">EventPeriodic</a></dt><dt><a \
href="#id2786734">EventDivider</a></dt></dl></dd><dt><a href="#id2786758">The \
HeartbeatGenerator</a></dt><dt><a href="#id2786785">The Completion \
Processor</a></dt><dt><a href="#id2786812">States and the \
StateContext</a></dt><dd><dl><dt><a href="#id2786879">The \
ConditionInterface</a></dt><dt><a href="#id2786926">Programming and Requesting State \
Transitions</a></dt></dl></dd><dt><a \
href="#id2787008">Properties</a></dt><dd><dl><dt><a href="#id2787076">How should I \
use PropertyBag ?</a></dt><dt><a href="#id2787130">Marshalling and \
demarshalling</a></dt></dl></dd><dt><a href="#id2787170">Reporting</a></dt><dt><a \
href="#id2787198">Fifos</a></dt></dl></dd><dt>2. <a \
href="#id2787286">Examples</a></dt><dt>3. <a \
href="#id2787308">Todo</a></dt></dl></div><div class="list-of-figures"><p><b>List of \
Figures</b></p><dl><dt>1.1. <a href="#id2789538">FOSI overview</a></dt><dt>1.2. <a \
href="#id2789908">FDI overview</a></dt><dt>1.3. <a href="#id2789992">(insert \
example-picture here)</a></dt><dt>1.4. <a href="#id2790432">(insert picture of \
loading+calling a kernel module) </a></dt><dt>1.5. <a href="#id2786187">Execution \
collaboration diagram</a></dt><dt>1.6. <a href="#id2786234">Execution sequence \
diagram</a></dt></dl></div><div class="list-of-tables"><p><b>List of \
Tables</b></p><dl><dt>1.1. <a href="#id2789606">Header files</a></dt></dl></div><div \
class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>1.1. <a \
href="#example_name_service">Using the name service</a></dt><dt>1.2. <a \
href="#id2786422">Using events</a></dt><dt>1.3. <a href="#id2787059">Using \
properties</a></dt></dl></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2789381"></a>Chapter 1. The Realtime \
Core</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a \
href="#id2789460">Beyond Realtime</a></dt><dt><a href="#id2789483">The Framework \
Operating System Interface (FOSI)</a></dt><dt><a href="#id2789825">The Framework \
Device Interface (FDI)</a></dt><dd><dl><dt><a href="#id2790032">Name \
Serving</a></dt></dl></dd><dt><a href="#id2790318">The Orocos Object \
Hierarchy</a></dt><dt><a href="#id2790346">Threads and Realtime execution of your \
program</a></dt><dd><dl><dt><a href="#id2790354">Starting your program</a></dt><dt><a \
href="#id2790502">The Orocos Thread System</a></dt><dt><a href="#id2786126">The \
Orocos Thread Philosophy</a></dt></dl></dd><dt><a \
href="#id2786355">Events</a></dt><dd><dl><dt><a href="#id2786592">Other Kinds of \
Events</a></dt><dt><a href="#id2786609">EventSimple</a></dt><dt><a \
href="#id2786631">EventMultiCast</a></dt><dt><a \
href="#id2786652">EventBarrier</a></dt><dt><a \
href="#id2786698">EventPeriodic</a></dt><dt><a \
href="#id2786734">EventDivider</a></dt></dl></dd><dt><a href="#id2786758">The \
HeartbeatGenerator</a></dt><dt><a href="#id2786785">The Completion \
Processor</a></dt><dt><a href="#id2786812">States and the \
StateContext</a></dt><dd><dl><dt><a href="#id2786879">The \
ConditionInterface</a></dt><dt><a href="#id2786926">Programming and Requesting State \
Transitions</a></dt></dl></dd><dt><a \
href="#id2787008">Properties</a></dt><dd><dl><dt><a href="#id2787076">How should I \
use PropertyBag ?</a></dt><dt><a href="#id2787130">Marshalling and \
demarshalling</a></dt></dl></dd><dt><a href="#id2787170">Reporting</a></dt><dt><a \
href="#id2787198">Fifos</a></dt></dl></div><p> This Section describes the semantics \
of the services available in the Orocos Core Package. Only Framework Builders,
Component Builders and Application Builders should use the Core
directly; End Users do not.
</p><p>
The Core makes an abstraction of the operating system on which it runs.
It provides C++ interfaces to only the <span class="emphasis"><em>minimal
set</em></span> of operating system
primitives that it needs: mutexes, condition variables and tasks.
This is in accordance with the general developers requirements of the
project: a minimalistic approach is much easier to scale, to maintain,
and to port.
The abstraction also allows Orocos users to build their software on all supported \
systems with only a recompilation step. But the Core goes further than restricting
the abstracted OS primitives: it also imposes a hard realtime
<span class="emphasis"><em>architecture</em></span>. This architecture is explained \
and motivated in a later Section.
The goal of this fixed architecture is to keep
applications deterministic, by avoiding the classical pitfalls of
letting application programmers freely choose the priorities of their
tasks, and their communication primitives. Practice has indeed showed
that most programmers do not succeed in strictly decoupling the
functional and algorithmic parts of their code from the OS-specific
primitives used to execute them.
</p><p>
Of course, the realtime performance depends not only on
the underlying operating system
<span class="emphasis"><em>but also on the hardware.</em></span> The Orocos Core
Package also provides an abstraction of the hardware, again in order
to facilitate maintenance and porting.
</p><p>
The abstractions cause (almost) no execution overhead, because the wrapping
is solved at compile or configuration time, i.e., before the hard
realtime tasks are running.
</p><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: \
both"><a name="id2789460"></a>Beyond Realtime</h2></div></div><p>Not everything must \
be executed in realtime in a control system, on the contrary. User
interaction,
some environment interaction, and system configuration can not
execute within deterministic time
limits. Orocos also provides this interaction and configuration
without disturbing the determinism
of the control task execution.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2789483"></a>The Framework Operating System Interface \
(FOSI)</h2></div></div><p> Keeping the Orocos core portable requires an extra \
abstraction of some operating system (OS) or kernel functionalities. For example, we
all know that a task can be created, started, paused, scheduled, etc.,
but each OS uses other function calls to do this. Orocos prefers
C++ interfaces, which led to the
<tt>ComponentActive</tt> class interface as the
abstraction of a task. Each OS implements in its
<tt>os/<OS-name-here></tt> directory the
specific system calls to get the desired effect. Other abstractions
are the <tt>HeartBeatGenerator</tt> class (to keep track
of (virtual network) time), and the
<tt>EventInterrupt</tt> class (to cover interrupt
handlers). So, using the Core header files, every application should
run on every supported OS.
</p><p>
</p><div class="figure"><a name="id2789538"></a><p class="title"><b>Figure 1.1. FOSI \
overview</b></p><div class="mediaobject"><img src="FDIvsFOSI.png" alt="FOSI \
overview"></div></div><p> </p><p>
When building kernel space applications, the realtime code does not
run in a C++ friendly environment and we had to wrap some libraries
with our own headers to guarantee
correct functioning. If you want to use the Standard C++ library
(without iostreams), you
have to include <tt>rtstl/rtstl.hpp</tt>. You can include
<tt>math.h</tt> without problems. The following table
contains the latest Orocos-approved header files:
</p><div class="table"><a name="id2789606"></a><p class="title"><b>Table 1.1. Header \
files</b></p><table summary="Header files" \
border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Library</th><th>Which \
file to include</th><th>Remarks</th></tr></thead><tbody><tr><td align="center" \
valign="middle">OS functionality</td><td align="center" \
valign="middle">os/fosi.h</td><td align="left" valign="middle">Include this file if \
you want to make system calls to the underlying operating system (RTLinux, RTAI, \
GNU/Linux,...) .</td></tr><tr><td align="center" valign="middle">C++ \
functionality</td><td align="center" valign="middle">os/cpp.hpp</td><td align="left" \
valign="middle">Include this file in every C++ program you make.</td></tr><tr><td \
align="center" valign="middle">Standard Template Library</td><td align="center" \
valign="middle">rtstl/rtstl.hpp</td><td align="left" valign="middle">No iostream \
support. RTLinux only supports string and vector.</td></tr><tr><td align="center" \
valign="middle">Streams</td><td align="center" \
valign="middle">rtstl/rtstreams.hpp</td><td align="left" valign="middle">Defines \
StoneHead::cout with limited functionality</td></tr><tr><td align="center" \
valign="middle">C Math Library</td><td align="center" valign="middle">math.h</td><td \
align="left" valign="middle">not all functions supported in \
RTLinux</td></tr></tbody></table></div><p>
OSs implementing the POSIX Threads API <span \
class="emphasis"><em>correctly</em></span> greatly
eases our efforts.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3>When using RTAI-LXRT, you can include any headerfile of any \
library, as long as you don't make system calls in hard realtime threads.</div><p>
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2789825"></a>The Framework Device Interface \
(FDI)</h2></div></div><p> Designing portable software which should interact with \
hardware is very hard.
Some efforts, like <a href="http://http://stm.lbl.gov/comedi/" target="_top">
Comedi</a> propose
a generic interface to communicate with a certain kind of hardware (mainly
analog/digital IO). This allows us to change hardware and still use the
same
code to communicate with it. Therefore, we aim at supporting every Comedi
supported card. We invite you to help us writing a C++ wrapper for this
API
and port comedilib (which adds more functionality) to the realtime
kernels.
</p><p>
We do not want to force people into using Comedi, and most of us have home
written device drivers. To allow total implementation independence, we
are writing a C++ device interface hierarchy (a part of the Orocos
Object Hierarchy) which just defines which functionalities a generic
device
driver should implement. It is up to the developers to wrap their C device
driver into a class which implements this interface. You can find an
example
of this in the devices package. The core only contains the interface
header files. Other packages should always point to these interface files
and never to the real drivers actually used. It is up to the
application
writer to decide which driver will actually be used.
</p><p> <span class="emphasis"><em>STRUCTURE</em></span> The FDI can be \
structured in two major parts : <span class="emphasis"><em>physical</em></span>
device interfaces and <span class="emphasis"><em>logical</em></span> device \
interfaces. Physical device
interfaces can be subdivided in four basic interfaces: Analog Input, Analog
Output, Digital Input, Digital Output. The major difference is that
analog devices are addressed with a channel as parameter and write a
ranged value, while digital devices are addressed with a bit number as
parameter and a true/false value.
Logical device interfaces represent the entities humans like to work
with: a drive, a sensor, an encoder, etc. They already make the
abstraction on how they are physically addressed. You just want to know
the position of a positional encoder in radians for example.
Often, the physical layer is device dependent
(and thus non-portable) while the logical layer is device independent.
</p><p>
</p><div class="figure"><a name="id2789908"></a><p class="title"><b>Figure 1.2. FDI \
overview</b></p><div class="mediaobject"><img src="fdi.png" alt="FDI \
overview"></div></div><p>
</p><p> <span class="emphasis"><em>EXAMPLE</em></span> An example of the \
interactions between the logical and the physical layer is the logical encoder with \
its physical counting card. An encoder is a physical device keeping track of the \
position of an axis of a robot or machine.
The programmer wishes to use the encoder as a sensor and just asks for
the current position. Thus a logical encoder might choose to
implement the <tt>SensorInterface</tt> which provides a
<tt>read(ReadType & )</tt> function. Upon construction of
the logical sensor, we supply the real device driver as a parameter.
This device driver implements for example
<tt>AnalogInInterface</tt> which provides
<tt>read(ReadType & data, unsigned int chan)</tt> and allows
to read the position of a certain encoder of that particular card.
Of course, we could also put a simulation of an encoder in place of
the device driver for testing purposes.
</p><p>
</p><div class="figure"><a name="id2789992"></a><p class="title"><b>Figure 1.3. \
(insert example-picture here)</b></p><div class="mediaobject"><img src="example.png" \
alt="(insert example-picture here)"></div></div><p>
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2790032"></a>Name Serving</h3></div></div><p> The FDI provides name serving \
on interface level. This means that one can ask a certain interface by which objects \
it is implemented and retrieve the desired instance. No casting whatsoever is needed \
for this operation. For now, only the physical device layer can be queried for \
entities, since logical device drivers are typically instantiated where needed, \
given an earlier loaded physical device driver.
</p><p>
<a href="#example_name_service" title="Example 1.1. Using the name \
service">Example 1.1</a> shows how one could query the <tt>AnalogOutInterface</tt>.
</p><div class="example"><a name="example_name_service"></a><p \
class="title"><b>Example 1.1. Using the name service</b></p><pre \
class="programlisting">
unsigned int pos;
new FancyCard("CardName"); // FancyCard implements \
AnalogOutInterface
AnalogOutInterface* card = \
AnalogOutInterface::nameserver.getObjectByName("CardName"); \
card->read(pos, 0); // Read some data delete card;
</pre></div><p>
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2790318"></a>The Orocos Object \
Hierarchy</h2></div></div><p> It is our aim to gradually build a common class \
hierarchy in the project describing the interfaces of data structures or devices. \
This will allow our applications to share the same data format and thus communicate
efficiently.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2790346"></a>Threads and Realtime execution of your \
program</h2></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2790354"></a>Starting your program</h3></div></div><p> All \
tasks in the realtime system have to be performed by some thread. In userspace, a \
normal <tt>main()</tt> function is already a thread. One can first construct all
components, initialize them and then start the task. After the task
has finished everything is cleaned up and the
<tt>main()</tt> function exits. You can use Orocos
perfectly this way, but it won't be realtime unless you are using
userspace realtime (LXRT,...)<span class="emphasis"><em>Things are
a bit more complex in the kernel (RTAI, RTLinux,...)</em></span>.
For a program to be executed in kernelspace-realtime,
it has to be compiled into a kernel module.
The Orocos build system does this automatically if you have chosen
a kernel based realtime system. Each kernel module has exactly one
<tt>init_module()</tt> and
<tt>cleanup_module()</tt> function call. The former
will be called when the module is loaded, the latter will be called
when the module is unloaded. Our policy is to put these functions
in a <tt>moduleXYZ.c</tt> file, which will call then
our real C++ functions, which reside in another file. The whole
procedure goes like this :
</p><p>
</p><div class="figure"><a name="id2790432"></a><p class="title"><b>Figure 1.4. \
(insert picture of loading+calling a kernel module) </b></p><div \
class="mediaobject"><img src="loading_calling.png" alt="(insert picture of \
loading+calling a kernel module)"></div></div><p> </p><p>
Once can see that first, a special function is called to initialize
all static variables your program might have. When this is done the real
initialisation function is called. There we instantiate all objects
we need, and finally start the services. Each service is now running
as a realtime thread, using the data you provided on instantiation.
Be warned that when this function exits, all local data is destroyed,
that is why we use global variables.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2790502"></a>The Orocos Thread System</h3></div></div><p> An Orocos \
component, which must execute a task periodically, is defined by the
<tt>ComponentActiveInterface</tt>.
The most common operations are <tt>start()</tt>,
<tt>stop()</tt> and setting the periodicity. What is
executed is defined in the <tt>
RunnableInterface</tt>. It contains three methods :
<tt>initialize()</tt>,
<tt>step()</tt> and
<tt>finalize()</tt>. You can inherit from this
interface to implement your own functionality. In
<tt>initialize()</tt>, you put the code that has to be
executed once when the component is
<tt>start()</tt>'ed. In
<tt>step()</tt>,
you put the instructions that must be executed periodically. In
<tt>finalize()</tt>, you put the instructions that must
be executed right after the last <tt>step()</tt> when
the component is <tt>stop()</tt>'ed.
</p><p>
Orocos delivers one implementation of the
<tt>ComponentActiveInterface</tt> :
<tt>
ComponentThreaded</tt>, which creates a thread according to
the operating system you are compiling for.
However, you are encouraged
<span class="emphasis"><em>NOT</em></span> to use it ! Other classes explained
in the next section will provide the functionality you really need.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786126"></a>The Orocos Thread Philosophy</h3></div></div><div \
class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2786132"></a></h4></div></div><p> Threads are the major cause of headaches \
in multithreaded systems programmers heads.
Synchronisation, data protection, priority tweaking and resource
locking must all be done very carefully and mostly lead to suboptimal
solutions. Even more, the predictability of the system highly decreases
with the introduction of more threads or interactions between threads.
Because of this, we propose the following:
</p><p>Only two realtime threads : A high priority thread and a low priority \
thread.
The high priority thread is used for all tasks that need to be executed
atomically. No action in this thread
will ever be pre-empted.
The low priority thread is used for all tasks which may be
interrupted but still have hard deadlines. It can always be preempted by the
high priority thread.
</p><p>The high priority thread is the <tt>ZeroTimeThread</tt>. It will
execute all <tt>TaskNonPreemptable</tt> Components synchronically.
You can create your own not preemtable task by inheriting from this
class. Its name is derived from the fact that some tasks need to be executed
in an infinite small amount of time to work correctly. Control loops
are an example of this. To come as close as possible to this (impossible)
constraint, we make sure that the task is never preempted by another task and
thus is executed 'atomically'.
</p><p>
</p><div class="figure"><a name="id2786187"></a><p class="title"><b>Figure 1.5. \
Execution collaboration diagram</b></p><div class="mediaobject"><img \
src="execution-collaboration.png" alt="Execution collaboration \
diagram"></div></div><p> </p><p>
</p><div class="figure"><a name="id2786234"></a><p class="title"><b>Figure 1.6. \
Execution sequence diagram</b></p><div class="mediaobject"><img \
src="execution-sequence.png" alt="Execution sequence diagram"></div></div><p> \
</p><p>The low priority tasks are executed by the <tt>ZeroLatencyThread</tt> \
Component. It will execute all <tt>TaskPreemptable</tt> Components
sequentially, when no non-preemptable tasks are
executed. Every <tt>TaskPreemptable</tt> can be preempted by a
<tt>TaskNonPreemptable</tt> but not by another <tt>TaskPreemptable</tt>.
The ZeroLatencyThread has this name because the zero time constraint is
dropped, but replaced by the constraint that no latency may occur and
thus, execution is still realtime. Again, to satisfy this constraint,
only deterministic time operations may be done in this thread.
</p><p> For not realtime executions, as there are userspace communication,
memory allocations,... we use the CompletionProcessor. Roughly put, you
can do <span class="emphasis"><em>anything</em></span> in this thread, as long \
as it
takes finite time. This is the lowest priority thread in the system and
it should never lock a resource of the realtime thread. Tasks being executed
in the CompletionProcessor are called <tt>TaskNonRealtime</tt>.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2786329"></a></h4></div></div><p>
<span class="emphasis"><em>This is true for each hardware unit of each Orocos \
based system.</em></span>
We will present an Event infrastructure which allows high priority tasks to \
postpone
partial execution of a task to a later period, when not deterministic actions \
have to be taken.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><h2 \
class="title" style="clear: both"><a name="id2786355"></a>Events</h2></div></div><p> \
Events are implemented using the <tt>Observer</tt> design pattern. An object or \
component which wants to be notified of events, has to implement the \
<tt>EventListenerInterface</tt>, in which the
<tt>handleEvent(CallbackInterface*)</tt> method will be called when
the event occurs. This is a subscription model (yeah, like the newsletters,
but we don't do SPAM), you only get notified when you registered for it.
</p><p>
The <tt>EventListener</tt> can decide to call the event completer (if \
available) by calling the <tt>complete()</tt>
function on the <tt>CallbackInterface</tt> object.
An example is when an EventListener is gathering data and enough data is available,
the Completer should finish the job, so the EventListener invokes the complete() \
method. <tt>EventListener</tt> and completer can be
different or the same objects. Let's look at an example :
</p><p>
</p><div class="example"><a name="id2786422"></a><p class="title"><b>Example 1.2. \
Using events</b></p><pre class="programlisting">
class Cat : public EventListenerInterface
{
public:
virtual void handleEvent(CallbackInterface *cb) {
// Handler code
std::cout << "Miau!" << std::endl;
// optional
cb->complete();
}
};
Class Pawn : public EventCompleterInterface
{
public:
virtual void completeEvent() {
//Completer code
std::cout << "Scratch!"<<std::endl;
}
};
...
Cat minou;
Pawn sharpy;
Event fullmoon(Event::SYNSYN);
std::cout << "Register minou to the fullmoon event\n";
fullmoon.addHandler(&minou, &sharpy);
std::cout << "Fire the event\n";
fullmoon.fire();
fullmoon.removeHandler(&minou,&sharpy); // automatically removes the \
completer too
fullmoon.addHandler(&minou, EventCompleterInterface::none ); // No \
completer will be called
std::cout << "Just making noise"<<std::endl;
fullmoon.fire();
...
</pre><pre class="screen">
Register minou to the fullmoon event
Fire the event
Miau!
Scratch!
Just making noise
Miau!
</pre></div><p>
</p><p>
We can categorise event handling and
completion in two categories: synchronous and asynchronous, both
possible for handling and completion. This leaves four types of events :
</p><div class="itemizedlist"><ul type="disc"><li><p>Synchronous event \
handling, synchronous completion (think separate \
components)</p></li><li><p>Synchronous event handling, asynchronous completion (think \
interrupts)</p></li><li><p>Asynchronous event handling, asynchronous completion \
(think mission to Mars)</p></li><li><p>Asynchronous event handling, \
synchronous
completion (think separate components on Mars)</p></li></ul></div><p>
One could argue that the first and last one have no practical applications, \
we're
busy thinking of some. All four types are nonetheless implemented in the \
framework. </p><p><span class="emphasis"><em>
The aim of this separation of listener and completer is decoupling: both
can be implemented in different objects and do not know about each other. Even
more, the completer should not count on the fact that it is called each time
the listener is called. It is possible that in some cases the listener asks for
completion, and in other cases does not require it (yet).</em></span>
</p><p>
Whether your <tt>handleEvent()</tt> and <tt>completeEvent()</tt>
methods contain deterministic code or not is up to you. It depends on the choice of \
the Event type and in which thread it is executed. A good rule of thumb is to make
all Synchronous handling/completing deterministic time and do all the rest in
the Asynchronous part, which will be executed by the <tt>CompletionProcessor</tt>.
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Tip</h3><p>You must choose the type of <tt>Event</tt> upon \
construction. This can no longer be changed once the <tt>Event</tt> is created (for \
obvious reasons). You must specify the type as the first constructor argument with \
one of the four following: \
Event::SYNSYN,Event::ASYNSYN,Event::SYNASYN,Event::ASYNASYN; with the first \
[SYN|ASYN] denoting the handling and the second the completion policy</p></div><div \
class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786592"></a>Other Kinds of Events</h3></div></div><p> Our subscription \
based Event is just an example of the many possibilities of Events in general. We \
provide four other Event primitives which you will need in your Event based \
applications. </p></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786609"></a>EventSimple</h3></div></div><p> \
<tt>EventSimple</tt> is a simplification of the general Event. It can have exactly \
one Listener and one Completer, which can be set or removed. You can use this Event \
in case you want to be sure that only one Listener and one Completer are notified \
when this event is fire()'d. </p></div><div class="sect2"><div \
class="titlepage"><div><h3 class="title"><a \
name="id2786631"></a>EventMultiCast</h3></div></div><p> <tt>EventMultiCast</tt> has \
one Listener and many Completers. When the event is fire()d and the Listener calls \
for complete()'ion, all subscribed Completers will be notified. In this sence, not \
the fire call is MultiCasted, but the complete call is MultiCasted to all \
Completers. </p></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786652"></a>EventBarrier</h3></div></div><p> \
<tt>EventBarrier</tt> has many Listeners and one Completer. When the event is \
fire()d and the Listener calls for complete()'ion, the Completer will only be \
notified if all Listeners called the complete() method. A new fire() method call \
will reset all complete() calls and wait again for all Listeners to call complete() \
before the Completer is notified.
</p><p>
An example is an EmergencyStop Event. Some program logic decides that the
EmergencyStop Event must be fired. All Listeners are called and perform
their emergency stop handling and call the complete() method. When
all Listeners called this, the Completer is called which now knows
that everyone stopped safely and can report this to the user or another
component. It is as if the Completer was on hold until all Listeners were
ready, hence the word barrier.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786698"></a>EventPeriodic</h3></div></div><p> <tt>EventPeriodic</tt> is a \
special case of the Event subscription model. That is, the Listener-Completer \
mapping is N to N, as with the normal Event, but the fireing of the event results in
periodically notifying of Listeners. For example, if the periodicity
is 10 to 1, each Listener will have been called exactly once after
the EventPeriodic was fired ten times. For each Listener, it is as
if the fire calls are done with longer periods in between.
</p><p>
This Event is used in the Orocos Threading classes for executing
tasks at a lower frequency than the thread is running.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786734"></a>EventDivider</h3></div></div><p> <tt>EventDivider</tt> is also \
a special case of the Event subscription model. That is, the Listener-Completer \
mapping is N to N, as with the normal Event, but the notifying of the Listeners of \
the event will only happen after X effective fire calls. It is as if
The Event divides the firing by factor X.
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2786758"></a>The \
HeartbeatGenerator</h2></div></div><p> The <tt>HeartbeatGenerator</tt> is \
implemented using the <tt>Singleton</tt> design pattern. You can query it for the \
current (virtual) time in clock ticks or in seconds. The idea here is that it is \
responsible for synchronising with other (distributed) cores, for doing, for example \
compliant motion with two robots. This functionality is not yet implemented though.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2786785"></a>The Completion \
Processor</h2></div></div><p> The Completion Processor is also implemented using the \
<tt>Singleton</tt> design pattern. It is the lowest priority, not realtime thread in \
the Orocos framework. It will execute all Events that have to be completed \
asynchronously. The only constraint it has is that all tasks it executes should \
require finite time to complete. </p></div><div class="sect1"><div \
class="titlepage"><div><h2 class="title" style="clear: both"><a \
name="id2786812"></a>States and the StateContext</h2></div></div><p> Any complex \
software component will sooner or later need a way to change state, depending on how \
it is used by the other components. The <tt>StateInterface</tt> describes how state \
changes are handled. When the current state is left, its <tt>onExit()</tt> method is \
called. Next, the <tt>onEntry()</tt> of the new state is called and right after that \
its <tt>handle()</tt> is called. Each time the current state is again requested, the \
<tt>handle()</tt> is called again.
</p><p>
So the <tt>StateInterface</tt> determines what has to be done, but
the decision to change state is made in the <tt>StateContext</tt>. The
StateContext keeps track of the current state and all valid state transitions.
One has to 'program' the StateContext so that it knows which transitions can be made
under which conditions
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786879"></a>The ConditionInterface</h3></div></div><p> The \
ConditionInterface is very basic : </p><pre class="programlisting">
class ConditionInterface
{
virtual bool evaluate() = 0;
};
</pre><p>
Conditions are classes that evaluate an expression and return the result. This \
expression must be defined by the user. Some examples are in the source tree, like \
<tt>
ConditionOnce</tt> (returns only true when it is the first time evaluated),
<tt>CondionTrue</tt> (always returns true), etc. The StateContext must have for
each state transition a Condition object which it will <tt>evaluate()</tt>
to determine if the transition is allowed.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786926"></a>Programming and Requesting State Transitions</h3></div></div><p> \
Now how does it all work together ? First, a StateContext object is created and all \
its possible States. </p><pre class="programlisting">
StateInit startState;
StateA aState;
StateB bState;
StateError errState;
ConditionTrue cTrue;
ConditionOnce cOnce;
StateContext context;
</pre><p>
Next, we will tell the <tt>context</tt> object which is the initial state which
state transitions are allowed :
</p><pre class="programlisting">
context.initState(&startState);
context.transitionSet(&startState, &aState, &cOnce);
context.transitionSet(&aState, &bState, &cTrue);
context.transitionSet(&bState, &aState, &cTrue);
context.transitionSet(&errState, &cTrue);
</pre><p>
As you can see, you can only go once from the startState to the aState, then you \
can always switch from aState to bState and back. All states are allowed to go to \
the errorstate, but in this example, it will be impossible to leave the errorstate:
</p><pre class="programlisting">
...
// we are in the startState
context.requestState(&bState); // will return false !
context.requestState(&aState); // ok, returns true.
context.requestState(&bState); // ok, returns true.
context.requestState(&errState); // returns true, but we are trapped in it.
// we are now in the errState
...
</pre><p>
Please take a look at the Doxygen API documentation for a precise description of
all the function calls.
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2787008"></a>Properties</h2></div></div><p> \
Properties are well known in object oriented programming languages. They are used \
to store primitive data (float, strings,...) in a 'PropertyBag', which can be \
changed by the user and has immediate effect on the behaviour of the program. \
Changing parameters of an algorithm is a good example where properties can be used. \
Each parameter has a value, a name and a description. The user can ask any \
PropertyBag for its contents and change the values as they see fit. Java for
example presents a Property API.
</p><p>
However, having Properties in a realtime system is a very hard task. Currently
RTLinux does not support it. RTAI, LXRT and GNU/Linux have been tested succesfully
with properties. An example of how to build a PropertyBag can be found in the
<tt>doc/examples/properties/simple_hibernate.cpp</tt> file.
The Doxygen Property API should
provide enough information for succesfully using them in your Software Component.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3><p>
Reading and writing a properties value can be done in realtime. Every other
transaction, like marshalling, demarshalling or building the property
is not a realtime operation.
</p><p>
</p><div class="example"><a name="id2787059"></a><p class="title"><b>Example \
1.3. Using properties</b></p><pre class="programlisting">
...
// a property, respresening a double of value 1.0:
Property<double> myProp("Parameter A","A demo parameter", \
1.0); // not realtime ! myProp = 10.9; // realtime
double a = myProp.get(); // realtime
...
</pre></div><p>
</p></div><p>
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2787076"></a>How should I use PropertyBag \
?</h3></div></div><p>
First of all, a PropertyBag is not the owner of the properties it owns,
it merely keeps track of them, it defines a logical group of properties
belonging together. Thus when you delete a bag, the properties in it are
not deleted, when you clone() a bag, the properties are not cloned
themselves. PropertyBag is thus a container of pointers to Property objects.
</p><p>
If you want to duplicate the contents of a PropertyBag or perform recursive
operations on a bag, you can use the helper functions we created and which
are defined in <tt>PropertyBag.hpp</tt> (see Doxygen documentation).
These operations are however, most likely not realtime.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3>When you want to put a PropertyBag into another PropertyBag, \
you need
to make a Property<PropertyBag> and insert that property into the
first bag.
</div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2787130"></a>Marshalling and \
demarshalling</h3></div></div><p>
Marshalling is converting an object from machine code to a code suitable
for transportation or storage. When an object is marshalled, a copy is made
so that it can be restored in its original state. Demarshalling instantiates
the object again from the marshalled copy. Common formats of marshalling are
writing out properties or efficient binary memory copies. So properties are
just an example of objects that can be marshalled. We wrote however specific
marshallers for properties and property bags. These are the
SimpleMarshaller, XMLMarshaller, XMLRPCMarshaller, INIMarshaller and
the CPFMarshaller (for CORBA). You will need the xerces library for the XML
related marshalling.
</p><p>
The marshaller uses the <tt>PropertyIntrospectionInterface</tt>
for inspecting the type of a Property. This mechanism is called
double dispatching.
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2787170"></a>Reporting</h2></div></div><p> Having a \
realtime process running is one thing, knowing what its internal status is is \
another. Reporting is made in such a way that existing components can be extended \
with a Reporting Stub, which creates reports of the internal state of variables and \
waits for client requests to update or export the data. A client can then ask each \
existing Stub to create and deliver a report. A timestamp is used to tag all data. \
When the client has collected all reports, it may transform it to another format, \
for example, in a log file or a display on screen. We call these clients often \
ReportWriters since they write out the gathered reports in one or another format.
An example of an application is a realtime robot component
which delivers every 10ms its position, velocity and sensor data
to a userspace map building application.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2787198"></a>Fifos</h2></div></div><p> Fifos are used \
to send data from one address space to another. For example from realtime to \
userspace or vice versa. We have four kind of fifos : </p><div \
class="itemizedlist"><ul type="disc"><li><p>FifoRTIn : Used to read data in realtime \
from a realtime fifo</p></li><li><p>FifoRTOut: Used to write data in realtime to a \
realtime fifo</p></li><li><p>FifoUSIn : Used to read data in userspace from a \
realtime fifo</p></li><li><p>FifoUSOut: Used to write data in userspace to a realtime \
fifo</p></li></ul></div><p>
Furthermore, one can still use the FifoRTIn/Out in userspace simulations.
They will act as if they get their data from real fifos. The API documentation \
should be clear about how to use them.
</p><p>
Fifos are very important means of communication between userspace and kernelspace.
Components requireing data communition will indicate this with a <tt> WriteInterface
</tt>,<tt>ReadInterface</tt> or <tt>ObservableReadInterface
</tt> in their constructors argument list.
All fifos implement one of these interfaces.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3><p> For examining which data would be sent through a fifo, \
one can always temporarily use a <tt>WriteCout</tt> object instead of a fifo, which \
will print the data to the screen instead of delivering it.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><h2 \
class="title"><a name="id2787286"></a>Chapter 2. \
Examples</h2></div></div><p>
We intend to write many example programs to demonstrate how easily complex \
components
can be built using the core and the existing interfaces. Only the test \
directory
contains some usage examples, but they might not always be clear. For example \
the
properties test file is a white box test and very inaccesable by non-insiders.
Please, feel free to post your example programs on the mailing list, we'll \
gratefully accept them.
</p></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a \
name="id2787308"></a>Chapter 3. Todo</h2></div></div><p> The core still misses a \
lot of functionality:
</p><div class="itemizedlist"><ul type="disc"><li><p>A HeartBeatGenerator that \
synchronises with other cores</p></li><li><p>A threadsafe C++ Allocator for embedded \
systems, RTAI provides one already, RTLinux does not</p></li></ul></div><p>
</p><p> Currently, the core can be extended with four packages : \
motioncontrol,
drivers, interfacing, lrl (Leuvens Robotics Library) and robots. They can be \
found on the Orocos website or in our CVS repository.
We'd like to add in the future:
</p><div class="itemizedlist"><ul type="disc"><li><p>Graphical configuration - \
generating components on
the fly with a GUI</p></li><li><p>Remote Access - a secure communication channel \
for accessing the framework over a network</p></li></ul></div><p>
</p></div></div></body></html>
["orocos-overview.html" (text/html)]
<html><head><meta http-equiv="Content-Type" content="text/html; \
charset=ISO-8859-1"><title> The OROCOS Project
</title><meta name="generator" content="DocBook XSL Stylesheets \
V1.56.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" \
alink="#0000FF"><div class="article"><div class="titlepage"><div><h1 class="title"><a \
name="id2780236"></a> The OROCOS Project
</h1></div><div><h3 class="subtitle"><i><span class="emphasis"><em>Open RObot \
COntrol Software</em></span> </i></h3></div><div><div class="authorgroup"><div \
class="author"><h3 class="author">Herman Bruyninckx</h3></div><div class="author"><h3 \
class="author">Peter Soetens</h3></div><div class="author"><h3 \
class="author">Panagiotis Issaris</h3><div class="affiliation"><span \
class="orgname">K.U.Leuven<br></span><div \
class="address"><p>Belgium</p></div></div></div></div></div><div><p \
class="copyright">Copyright © 2002 Herman Bruyninckx, Peter Soetens, Panagiotis \
Issaris</p></div><div><div class="legalnotice"><p> Permission is granted to copy, \
distribute and/or modify this document under the terms of the GNU Free Documentation \
License, Version 1.1 or any later version published by the Free Software Foundation, \
with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of this license can be found at
<a href="http://www.fsf.org/copyleft/fdl.html" \
target="_top">http://www.fsf.org/copyleft/fdl.html</a>. </p></div></div><div><div \
class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th \
align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td \
align="left">Revision 0.01</td><td align="left">05 Dec 2002</td><td \
align="left">hb</td></tr><tr><td align="left" colspan="3">Initial \
version</td></tr></table></div></div><div><div class="abstract"><p \
class="title"><b>Abstract</b></p><p> This document explains the goals, vision, \
design, implementation and packages of
<a href="http://www.orocos.org" target="_top">Orocos</a>,
the <span class="emphasis"><em>Open RObot COntrol Software</em></span> project.
</p></div></div><hr></div><div class="toc"><p><b>Table of \
Contents</b></p><dl><dt><a href="#intro">What is Orocos?</a></dt><dd><dl><dt><a \
href="#audience">Target audience</a></dt><dt><a href="#vision">Vision</a></dt><dt><a \
href="#components">Objects and Components</a></dt><dt><a href="#history">Project \
history</a></dt></dl></dd><dt><a href="#installation">Installation and \
configuration</a></dt><dd><dl><dt><a href="#id2786326">Supported platforms \
(targets)</a></dt><dt><a href="#id2786373">The versioning scheme</a></dt><dt><a \
href="#id2786424">Installing Orocos from CVS</a></dt><dt><a \
href="#id2786567">Installing Orocos from the epk packages</a></dt><dt><a \
href="#id2786946">Configuration</a></dt><dt><a href="#general_setup_rtai">Configuring \
for RTAI</a></dt><dt><a href="#id2850591">Configuring for \
RTLinux</a></dt></dl></dd><dt><a href="#started">Getting started with the \
code</a></dt><dd><dl><dt><a href="#id2850718">A quick test</a></dt><dt><a \
href="#id2850779"> Where's main() ?</a></dt><dt><a href="#id2850919"> How do I \
compile my program ? </a></dt></dl></dd><dt><a \
href="#id2851146">Examples</a></dt><dt><a href="#id2851165">Todo</a></dt><dt><a \
href="#id2851201">Bibliography</a></dt></dl></div><div class="sect1"><div \
class="titlepage"><div><h2 class="title" style="clear: both"><a name="intro"></a>What \
is Orocos?</h2></div></div><p> “Orocos” is the acronym of the
<span class="emphasis"><em><a href="http://www.orocos.org" target="_top">Open Robot \
Control Software</a></em></span> project. The project's aim is to develop
a general-purpose, free software, and modular <span \
class="emphasis"><em>framework</em></span> for <span class="emphasis"><em>robot \
control</em></span> (including extensive and high-quality documentation).
</p><p>
A framework is a set of source code from which applications in a
particular domain can be made [Johnson97]). So, the
framework is not an application
in itself, but it provides the infrastructure and the functionalities to
build applications. Usually, application builders must fill
in some “hot spots” that are specific to their
application, and hence, which cannot be provided by the framework.
</p><p>
Orocos works in a “bottom-up” fashion, so current
activities are currently more focused on developing
<span class="emphasis"><em>basic infrastructure</em></span> than on implementing
advanced control, planning or sensor processing algorithms.
</p><p>
Orocos is a free software project, hence its code and documentation
are released under Free Software licenses.
</p><p>
Your feedback and suggestions are greatly appreciated. Please, use the
project's
<a href="http://mail.mech.kuleuven.ac.be/mailman/listinfo/orocos" \
target="_top">mailinglist</a> for this purpose. </p><div class="sect2"><div \
class="titlepage"><div><h3 class="title"><a name="audience"></a>Target \
audience</h3></div></div><p> Robotics is a very broad field, and many roboticists are \
pursuing quite different goals, dealing with different levels of
complexity, real-time control constraints, application areas, user
interaction, etc. So, because the robotics community is not
homogeneous, Orocos targets
four different categories of “Users” (or, in the first
place, “Developers”):
</p><div class="orderedlist"><ol type="1"><li><p>
<span class="emphasis"><em>Framework Builders.</em></span>
</p><p>
These developers do not work on any specific robotics application, but
they provide the infrastructure code to support applications. This
level of supporting code is most often neglected in robot software
projects, because in the (rather limited) scope of each individual
project, putting a lot of effort in a generic support platform is
often considered to be “overkill”, or even not taken into
consideration at all. However, because of the large scope of the
Orocos project, the supporting code (the “Framework”)
gets a lot of attention. The hope is, of course, that this work will
pay of by facilitating the developments for the other
“Users”.
</p></li><li><p>
<span class="emphasis"><em>Component Builders.</em></span>
</p><p>
These developers implement basic robotics functionality, on top of the
generic Framework. The functionality is offered as a
“service”, in the form of a <span class="emphasis"><em>(Software)
Component</em></span>, [Szyperski98]. Such a
component is not (necessarily) a full application in itself, but the
Component Builders do their best to
provide high-quality functionality, in an application-independent way.
That is, the <span class="emphasis"><em>programming interface</em></span> to the \
robotics functionality is rich and well documented, and the component can be
used as a stand-alone part in various applications.
</p><p>
Components come in roughly three different types. The simplest is an
object-oriented <span class="emphasis"><em>class hierarchy</em></span>, offering \
direct access to the objects data and functionality. The medium-level
component provides <span class="emphasis"><em>monitored access</em></span> to the
objects' functionality, in the sense that it guarantees that different
accesses do not interfere with each other, and that the object always
remains in a consistent state. The highest-level Component has the
properties as described in the <span class="emphasis"><em>CORBA Component
Model</em></span>.
</p></li><li><p>
<span class="emphasis"><em>Application Builders.</em></span>
</p><p>
These developers use the Orocos' Framework and Components, and
integrate them into one particular application. That means that they
add a specific, application-dependent
<span class="emphasis"><em>architecture</em></span> and <span \
class="emphasis"><em>API</em></span> on top of the functionalities offered by the \
Framework and the Components. </p></li><li><p>
<span class="emphasis"><em>End Users.</em></span>
</p><p>
These people use the products of the Application Builders to program
and run their particular tasks.
</p></li></ol></div><p>
The focus in the Orocos project lies primarily with the Framework
Builders and the Component Builders. But, since all contributors
are motivated by their own particular applications, the needs of
the Application Builders are also taken into account, albeit
indirectly.
</p><p>
End Users do not directly belong to the target audience of
the Orocos project, because Orocos concentrates on the common
<span class="emphasis"><em>framework</em></span>, independent of any application
architecture. Serving the needs of the End Users is left to
(commercial and non-commercial) Application Builders.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="vision"></a>Vision</h3></div></div><p> </p><blockquote class="blockquote"><p>
<span class="emphasis"><em>
The long-term goal of Orocos is to provide
<span class="emphasis"><em>all possible</em></span> software, for
<span class="emphasis"><em>all possible</em></span> robots (manipulator arms, mobile
robots, humanoids, rehabilitation devices, etc.).
</em></span>
</p></blockquote><p>
This is a very ambitious goal, and will inevitably lead to a very
large code tree, various sub-projects, and contributors that are only
interested in one or two of these sub-projects. So, the danger of
arriving at a chaotic and incoherent project is real.
This danger will be fought by adhering to a clear
“roadmap”, or “vision” for both of the
following aspects (discussed in more detail in the following Sections):
</p><div class="orderedlist"><ol type="1"><li><p>
<span class="emphasis"><em>Software engineering requirements.</em></span>
</p><p>
What quality and approach are expected from contributions to the project?
</p></li><li><p>
<span class="emphasis"><em>Directory structure of the source code.</em></span>
</p><p>
How is the project structured into sub-projects?
</p></li></ol></div><p>
The project maintainers will <span class="emphasis"><em>strictly impose</em></span>
adherence to the project's vision and roadmap when considering
incorporation of contributions to the project. However, they always
welcome a motivated discussion about these topics on the project's
<a href="http://mail.mech.kuleuven.ac.be/mailman/listinfo/orocos" target="_top">
mailinglist.
</a>
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="proj-dev-req"></a>Software engineering requirements</h4></div></div><p> Orocos \
has a vision on <span class="emphasis"><em>how</em></span> developers should design, \
implement and present new functionality, in order to guarantee the project's \
coherence and scalability. These are the software engineering guidelines that support \
the implementation of the project's vision:
</p><div class="orderedlist"><ol type="1"><li><p>
<span class="emphasis"><em>Object-oriented design.</em></span>
</p><p>
This seems an obvious requirement for modern-day software development.
However, the experience within the project has learned that designing
an appropriate class hierarchy is a <span class="emphasis"><em>major</em></span>
challenge, mainly because of the diversity of the field.
</p></li><li><p>
<span class="emphasis"><em>Extreme decoupling and modularity.</em></span>
</p><p>
This is the fundamental criterium to keep in mind when designing
and/or refactoring the project's class hierarchy.
Object classes encapsulate data and activities, and the choice of
classes should be such that:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The implementation of one class should not rely on knowing something
about the internals of another class. Relying on such knowledge is
called <span class="emphasis"><em>coupling</em></span> between both classes, and this
must be avoided at all costs, because it prevents the independent
evolution or re-implementation of the classes.
</p></li><li><p>
Every class should have an interface that fits more or less on one
single page. Elaborate interfaces are a sign that the implemented
functionality may better be split into multiple objects.
</p></li></ul></div><p>
The strong desire to <span class="emphasis"><em>decouple</em></span> software parts
wherever possible is a key feature of the project; it may seem a bit
of an overkill for each individual application built with the Orocos
code (and hence a burden for the individual contributor), but for the
whole project it is expected to become its major competitive advantage.
</p></li><li><p>
<span class="emphasis"><em>Small and shallow interfaces.</em></span>
</p><p>
It is useful to separate the <span class="emphasis"><em>interface</em></span> of a
certain functionality from its <span class="emphasis"><em>implementation</em></span> \
(as a class or as a component). The interfaces are what Application
Builders and End Users need to construct their programs; the
class and component implementations are contructed by the Framework and
Component Builders.
</p><p>
Separated interfaces give more flexibility in changing
implementations, and in allowing “third-party” providers
of components. They also allow to discuss functionality without being
biased by possible implementations problems or opportunities.
</p><p>
Orocos prefers interfaces that are:
</p><div class="itemizedlist"><ul type="disc"><li><p><span \
class="emphasis"><em>Small.</em></span> This improves the focus of the interface, and \
hence (hopefully) its quality. In this sense, it corresponds to the minimality \
requirement discussed below. Another motivation is that Orocos wants to avoid
“exceptions” in implementations of the interfaces: when
the interface is large, the chance increases that a particular
developer will not be able to provide a <span \
class="emphasis"><em>complete</em></span> implementation. In that case, the \
implementation must return an exception “functionality not implemented”, \
and this complicates the execution logic of the component that uses the
interface, and reduces the real-time performance.
</p></li><li><p><span class="emphasis"><em>Shallow.</em></span>
In an object-oriented paradigm, much functionality is provided by
class <span class="emphasis"><em>hierarchies</em></span>. Every hierarchy may seem
natural in the context on one particular application, but it will most
certainly not be natural in other applications. For example, a
robotics engineer may find it normal to have a “robot”
object at the top of a large and deep hierarchy. But that same word
“robot” will not be well received by machine tool builders
that construct milling machines, or laser cutters. Although most of
the functionality of motion control and task execution will be the
same in both application areas. Therefore, class hierarchies should
not be deep.
</p></li></ul></div><p>
In addition to the technical reasons to use small and shallow
interfaces, they are a key feature for free software projects that
expect significant contributions from their community: the complexity
of the whole system can only be tackled by restricting the scope of
each individual piece of code. An <span class="emphasis"><em>increased
flexibility</em></span> is a derived property that comes for free.
</p></li><li><p>
<span class="emphasis"><em>Distributable.</em></span>
</p><p>
Future robot control systems will most certainly use multiple
processors, connected through a network with sensors and actuators
that most probably will have their own embedded intelligence.
Hence, the robot control software will have to be scalable and
distributable.
</p><p>
Having a design that is modular and maximally decoupled fulfills already
more than half of the requirements for such distributed control
systems. The other half will come from making software components
with an internal design that allows their different parts to cooperate
over a network.
</p><p>
Two software aspects are important in this respect: the ubiquitous use
of <span class="emphasis"><em>events</em></span> for synchronization, and of a
<span class="emphasis"><em>virtual (network) time</em></span> (instead of the time
delivered by the local processor). Both events and virtual time are
general <span class="emphasis"><em>abstractions</em></span>, that are easily mapped \
on corresponding primitives of the particular operating system the
component is running on. For example, a hardware interrupt is also an
event, and for the logic of a component it almost never matters
whether the event comes from the hardware or from a local
“stub” of remote hardware.
So, make sure that your components don't use system calls
that tie them to a particular operating system or a particular device.
</p><p>
Orocos provides <span class="emphasis"><em>abstraction layers</em></span> for both \
the operating system and the interfacing hardware. These abstractions
follow the principles of minimality and decoupling. Especially for the
operating system abstraction this is a big advantage, because typical
(real-time) OSs tend to have way too large and too primitive APIs,
that are easily abused.
</p></li><li><p>
<span class="emphasis"><em>Minimalistic .</em></span>
</p><p>
Developers should only offer features that are
<span class="emphasis"><em>absolutely</em></span> necessary: practical experience has
learned that the availability of superfluous APIs leads to
implementations with similar functionality but with different
implementations. And, worse, to implementations where the programmers
do not know very well what parts of the available functionality to
use. Both effects lead to <span class="emphasis"><em>sub-optimal</em></span> \
results, and applications that are more difficult to re-use and maintain.
</p><p>
</p></li><li><p>
<span class="emphasis"><em>Platform independent.</em></span>
</p><p>
Because of its Free Software nature, Linux is the normal environment
for both host development and target runtimes. This can in practice
lead very quickly to an unperceived bias towards Linux, that would
compromise the portability to other operating systems. Developers must
try to use only portable language constructs.
</p><p>
Of course, sooner or later, the project will be confronted with the
trade-off between portability and the choice for a particular desired
feature that can not be supported by all initially targeted platforms.
These trade-offs must be discussed on the mailinglist.
</p></li><li><p>
<span class="emphasis"><em>Thorough large-scale design.</em></span>
</p><p>
Developers must <span class="emphasis"><em>always</em></span> consider that their
designs will possibly be used in a very complex, distributed and hard
real-time implementation. Therefore, the design of such large-scale
robotics systems must be made clear before starting the implementation
of classes and components. And the implementators must provide
contributions that can safely and efficiently work in such
large-scale systems.
</p><p>
One particular item is <span class="emphasis"><em>real-time</em></span>: if an \
algorithm <span class="emphasis"><em>is</em></span> inherently real-time (i.e., it \
has a deterministic execution time), then its implementation
<span class="emphasis"><em>must</em></span> be implemented with constructs that are
real-time safe. For example, all variables and temporary objects must
be allocated before execution of the functionality proper, and no
exceptions or run-time type checking must be used. (So, Java
and C++ programmers need to be careful.)
</p></li></ol></div><p>
</p><p>
All these requirements illustrate the project's emphasis on
<span class="emphasis"><em>design</em></span>: most things in robotics have already \
been tried out in various ways, so the Orocos implementation should
<span class="emphasis"><em>at least</em></span> be as good as the best of these
tried-out predecessors. In addition, Orocos aims at a number of
extra features, such as “ultimate generality”.
This generality is the reason why the project follows a development
approach which is maybe a bit different from traditional free software
projects: the trade-off during the current development is towards
having a very well thought-out and very general design, and not in the
first place towards adding as many functionality features as possible.
This approach is motivated by the observation that all existing robot
control software packages are very difficult to use in applications
that are different from the first application they were built for. And
that sharing source or binary code is very hard in practice, because
of ill-defined interfaces, that are most often also strongly coupled
to one particular application.
</p><p>
The development approach of the project follows from the
above-mentioned vision: the project works in a “bottom-up”
fashion, on small interfaces at a time, <span class="emphasis"><em>but</em></span> \
while keeping the long-term goal in mind. So, it is currently building the
lowest levels of the framework, such as the hard real-time
“Core”, motion control functionality, primitives for
communication between Orocos components, robot kinematics, etc.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="proj-structure"></a>Code directory structure: the Packages</h4></div></div><p> \
The functionality available in Orocos is structured in a number of sub-projects; each \
of these is called an <span class="emphasis"><em>(Orocos) Package</em></span>.
A Package contains a coherent and related set of functionality, in the
form of documentation, and <span class="emphasis"><em>class libraries</em></span> and
<span class="emphasis"><em>components</em></span>, <a href="#components" \
title="Objects and Components">the section called “Objects and \
Components”</a>. In principle, each Package could be a separate, independent \
project in itself, and the couplings with Orocos are loose.
</p><p>
The following Packages exist, or will be created in the near future:
corelib, kinematics and dynamics, device interface, device drivers,
control kernel, applications, estimation, execution, kernel components,
operating system, robots, XY tables, pan-tilt units.
</p><p>
The directories of each Package contain a detailed documentation of
the Package in their local <tt>/doc</tt>
directories.
</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="components"></a>Objects and Components</h3></div></div><p> The basic \
functionality of Orocos is implemented in libraries of object classes. Objects are \
the building blocks for encapsulation and modularity; their functionality is accessed \
by directly calling the member and data functions on objects created by those \
libraries. But Orocos also want to offer “higher-level” objects:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<span class="emphasis"><em>Monitors.</em></span>
</p><p>
A Monitor, or “protected object” doesn't allow direct
calls on its member and data functions. Instead, it implements its own
internal <span class="emphasis"><em>serialization</em></span> mechanism to allow only
one calling client at a time to really access the object.
</p><p>
Monitors offer more protection, and are hence better suited to be used
in a “hostile” application environment, but they are much
less efficient than “naked” objects.
</p></li><li><p>
<span class="emphasis"><em>Components.</em></span>
</p><p>
A Component is also an encapsulation for the functionalities of one or
more objects, but it is more: it behaves as a full application in
itself, that can dynamically be created or deleted, possibly while
preserving its state during the period it is deactivated. A Component
also notifies a so-called <span class="emphasis"><em>broker agent</em></span> when it
comes on-line, what kind of services it offers, and how these services
must be accessed. This means that it allows other Components to
discover it on-line, and to “browse” its interface.
</p></li></ul></div><p>
Orocos is inspired by the <span class="emphasis"><em>CORBA</em></span>
specification for components (version 3.0 of the CORBA standard). This
doesn't mean at all that CORBA will be the default way to access
Orocos' functionalities (especially not at the real time level), but
it would be stupid not to use the experience, suggestions and tools
available in the CORBA world.
</p><p>
Orocos imposes a consistent framework interface for its components;
i.e., they use the same API to be activated/deactivated, configured
and accessed in an application that runs in the Orocos Core. Most
Orocos Packages will contain one or more Components in the idl
subdirectory.
</p><p>
The documentation of the Core Package contains more details.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="history"></a>Project history</h3></div></div><p> The idea for starting a Free \
Software project for robot control was born in December 2000, motivated by over two \
decades of rather disappointing experiences and failures in trying to use commercial
robot control software for advanced robotics research. The idea,
together with a draft of a possible project proposal, was launched on
the mailinglist of <a href="http://www.euron.org/" target="_top">EURON</a>,
the European Robotics Network. This email gave rise to a lot of
responses, even though it was sent during the Christmas period. Within
about two weeks, a proposal was made ready, and sent to the European
Union. Contacts with the responsible Officer made clear that the size
of the project had to be very modest, so that only three partners were
selected: K.U.Leuven in Belgium, LAAS Toulouse in France, and KTH
Stockholm in Sweden. Each of these three groups would later receive
only one full man-year of support. The EU-sponsored project started in
September 2001, and has a duration for two years.
</p><p>
The EU sponsoring also provides some travel grants to invite
non-sponsored people to the Orocos project meetings. This, together
with the classical attributes of a
<a href="http://www.orocos.org" target="_top">web page</a> and a
<a href="http://mail.mech.kuleuven.ac.be/mailman/listinfo/orocos" \
target="_top">mailinglist </a>,
stimulated quite some discussions and exchanges of ideas.
</p><p>
A first version of the hard real-time core was released in the Summer
of 2002, but it was very preliminary and hard to use. In November
2002, the first version was released with which simple position and
velocity control of a six degrees-of-freedom robot manipulator arm was
possible.
</p><p>
Two packages with support for distributed, CORBA-based communication
between robot systems were also released in 2002.
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="installation"></a>Installation and \
configuration</h2></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2786326"></a>Supported platforms \
(targets)</h3></div></div><p> Orocos was designed with portability in mind. \
Currently, we support RTAI and (NEW)LXRT (<a href="http://www.rtai.org" \
target="_top">http://www.rtai.org</a>), GNU/Linux userspace, and RTLinux (<a \
href="http://www.fsmlabs.com" target="_top">http://www.fsmlabs.com</a>). So, you can \
first write your software as a normal program, using the framework for testing and \
debugging purposes in plain userspace and recompile later to another target.
</p><p>
RTAI and LXRT is the best supported platform at this moment. RTLinux can
only partially use all Orocos features, because it lacks a decent
kernel space memory manager.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786373"></a>The versioning scheme</h3></div></div><p> Orocos uses the \
well-known even/stable uneven/unstable version numbering scheme, just as the Linux \
kernel and many other projects. A particular version is represented by three numbers \
separated by dots. An <span class="emphasis"><em>even</em></span> middle number \
indicates a <span class="emphasis"><em>stable</em></span> version. For example :
</p><div class="itemizedlist"><ul type="disc"><li><p>0.1.4 : Release 0, \
unstable (1), revision 4.</p></li><li><p>1.2.1 : Release 1, stable (2), revision \
1.</p></li></ul></div><p>
This numbering allows to develop and release two kinds of versions,
where the unstable version is mainly for testing new features and designs and
the stable version is for people wanting to run a reliable system.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786424"></a>Installing Orocos from CVS</h3></div></div><p> Installing \
Orocos from CVS gets you the latest and greatest, but requires some familiarity
with the tools we use. This section will do its best to help you through
the CVS installation
process.
</p><p>
The commands below show how to obtain the <span class="emphasis"><em>Core</em></span>
Package from the CVS tree; other parts of the Orocos code are
retrieved in a similar way.
</p><pre class="screen">
cvs -d:pserver:cvsread@cvs.mech.kuleuven.ac.be:/repos/pub login
cvs -d:pserver:cvsread@cvs.mech.kuleuven.ac.be:/repos/pub co orocos/core
cd orocos/core
</pre><p>
Make sure you have “cvs”
installed; enter “anon” as password when asked for.
</p><p>
The next step requires that you use
<a href="http://www.gnu.org/software/automake/" target="_top">automake</a>
version 1.6.3,
<a href="http://www.gnu.org/software/autoconf/" target="_top">autconf</a>
version 2.54, and libtool version 1.4 or higher. You can check your
versions with the <i><tt>--version</tt></i> option:
</p><pre class="screen">
$ automake --version
automake (GNU automake) 1.6.3
...
$ autoconf --version
autoconf (GNU Autoconf) 2.54
...
$ libtool --version
ltmain.sh (GNU libtool) 1.4.2 (1.922.2.53 2001/09/11 03:18:52)
</pre><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3>You need these programs if you intend to modify the \
makefiles</div><p> When you get something similar, proceed with calling the <b>
./autogen.sh </b> command, in order to initialize the
<tt>autoconf</tt> and <tt>automake</tt> files:
</p><pre class="screen">
./autogen.sh
</pre><p>
The next steps are exactly the same as when you install the system
starting from a so-called “epk” package, as explained in the
next section. Of course, you don't have to apply the
<b>ecosadmin.tcl</b> command when installing from CVS.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786567"></a>Installing Orocos from the epk packages</h3></div></div><p> \
Orocos has switched to a less common system for distribution and configuration. It \
it taken from the eCos operating system, but, apart from the name, has nothing to do \
with it when used with Orocos. The tools you will need are ecosconfig and \
configtool. In Debian, one can install them using :
</p><pre class="screen">
apt-get -t unstable install ecosconfig
</pre><p>
Other distributions might need to build ecosconfig themselves from
this tarball : <a href="http://people.mech.kuleuven.ac.be/psoetens/ecos/%20%20%20%20ecosconfig-2.0.tar.gz" \
target="_top">ecosconfig-2.0.tar.gz</a>. </p><div class="note" style="margin-left: \
0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The graphical configtool \
program uses the libwxgtk2.4 library</div><p> These tools both serve the
same purpose : to control package configuration and installation. Ecosconfig
is command-line based, configtool is a graphical tool. The eCos folks wrote an
(eCos-oriented) manual which explains them in great detail in <a \
href="http://sources.redhat.com/ecos/docs-latest/user-guide/ecos-user-guide.html" \
target="_top"> the user guide</a> and how packages work internally is written in the
<a href="http://sources.redhat.com/ecos/docs-latest/cdl-guide/cdl-guide.html" \
target="_top"> eCos Component Writer Guide</a>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3> In the eCos operating system, a target is a hardware \
platform, in Orocos, a target is RTAI, GNU/Linux, LXRT and so on, so you can skip \
all hardware specific sections in the eCos manuals.
</div><p>
When these tools are present, proceed as follows :
</p><div class="orderedlist"><ol type="1"><li><p>Download Orocos-Host.tar.gz \
from the Orocos webpage</p></li><li><p>Extract it using : tar -xvzf \
orocos-0.10.0.tar.gz</p></li><li><p>Setup the base environment :
<b>cd orocos-0.10.0; ./autogen.sh; </b></p></li><li><p>Setup the packages \
environment : <b>cd orocos-0.10.0/packages; \
./autogen.sh;</b></p></li><li><p>Download the required Orocos .epk \
packages</p></li><li><p>Install each of them in the orocos-0.10.0/packages subdir, \
using
<b>cd orocos-0.10.o/packages; tclsh ecosadmin.tcl add <filename.epk></b>
This action is also documented in the ecos manuals and equivalent to the \
installation of any eCos package, see
<a href="http://sources.redhat.com/ecos/docs-latest/user-guide/managing-package-repository.html" \
target="_top"> the ecos userguide</a> for the synopsis.
</p></li><li><p>When all packages are installed, generate the ecos.db file \
using: <b>cd orocos-0.10.0/packages; ./configure ; make db</b>
This command generates an index of all installed packages, the configure command
may detect installed software on your system and generate support packages
to reflect this. When you install new relevant software, you must rerun <b> \
configure </b>
and <b>make db</b>.</p></li><li><p>Finally, you can now choose between using the \
plain ecos tools or our supplied make targets which enhance convenience :
</p><pre class="screen">
mkdir orocos-0.10.0/build
cd orocos-0.10.0/build
../configure --with-<target>
make new_packages
make configure_packages
make build_packages
</pre><p>
Where <target> is one of listed in <b>../configure --help</b>.
</p></li><li><p></p></li><li><p></p></li></ol></div><p>
Each package will have been installed in a packages/package-name/version/ directory,
allowing multiple versions to be installed next to each other. The CVS version is
always called 'current', and considered as the most recent version.
</p><p>
The make build_packages command will have made a directory packages-<target>
where the building takes place. The results of the build are in the
packages-<target>/install directory. You will find the header files and a
library called libtarget.a (literally). These files allow you to build external
applications with Orocos. Of course a package itself can also be an application,
resulting in an executable in the packages-<target>/install/bin directory.
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2786834"></a>Using Orocos concurrently for multiple \
targets</h4></div></div><p> When you want to build for another target, simply \
re-invoke ../configure --with-<target> from the build directory and a new \
packages-<target> directory will be made. </p><p>
If this step fails, it means that you have not everyting installed
which is needed for a basic Orocos build. Most users don't have the
Boost library (<tt>libboost-dev</tt> or
<tt>libboost-devel</tt>) installed. Please install this
package from the binary or source package repository of your Linux
distribution, or download and install it from the <a href="http://www.boost.org" \
target="_top">Boost project.</a> As soon as the configure step succeeds, all the \
rest will succeed too. Please use the mailinglist at <tt><<a \
href="mailto:orocos@mail.mech.kuleuven.ac.be">orocos@mail.mech.kuleuven.ac.be</a>></tt> \
for technical support.
</p><p>
You can use the <b>make check_packages</b> command to start building
a test program in applications/testcase.
The <b>make docs</b> or
<b>doxygen</b> commands build API documentation.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2786926"></a>Installing an Orocos Package </h4></div></div><p> This step is \
hardly needed, since the build-directory is also the installation directory. The \
ecostools allow to define a separate installation directory, but this is documented \
in the eCos docs. Kernel modules can be found in the install/modules directory and
might need manual installation.
</p></div></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2786946"></a>Configuration</h3></div></div><div class="sect3"><div \
class="titlepage"><div><h4 class="title"><a name="id2786953"></a>Configuring an \
Orocos Package</h4></div></div><p> By default, Orocos will be built to install in
<tt>packages-<target>/install</tt>.
You can modify this by passing a --prefix= option to ecosconfig or
change it in the GUI.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3>ecosconfig and configtool both use a different namingscheme \
for installation and build directories. configtool uses the \
<config_name>-build, <config_name>-mlt, <config_name>-mlt \
subdirectories while ecosconfig uses the current dir to build and the install \
directory for installation. </div><p>
Just running <b>./configure</b> or <b>./configure
--with-gnulinux</b> selects the os/gnulinux target.</p><p>
When running <b>./configure --with-rtlinux</b> the configure
script will select the os/rtlinux target.
</p><p>
When running <b>./configure --with-rtai</b>, the
configure script will select the os/rtai target
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Tip</h3><p>
Read <a href="#general_setup_rtai" title="Configuring for RTAI">the section \
called “Configuring for RTAI”</a> about possible patches you should \
apply to RTAI before a run will compile. </p></div><p>
</p><p>
When running <b>./configure --with-lxrt</b> the configure
script will select the os/lxrt target.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2787074"></a>Compiler flags</h4></div></div><p> You must set the compiler \
flags in the configtool GUI. </p></div></div><div class="sect2"><div \
class="titlepage"><div><h3 class="title"><a name="general_setup_rtai"></a>Configuring \
for RTAI</h3></div></div><p> Read first the 'Getting Started' section from
<a href="http://people.mech.kuleuven.ac.be/~psoetens/portingtolxrt.html" \
target="_top">this page</a> if you are not familiar with RTAI instalation
</p><p>
We recommend using RTAI version 24.1.11 or later. You can obtain it from
<a href="http://www.aero.polimi.it/projects/rtai/" target="_top"> the RTAI home \
page</a> or as follows from CVS: </p><pre class="screen">
export CVSROOT=":pserver:guest@cvs.zentropix.com:/opt/cvsroot/rtai"
cvs login
password: anoncvs
cvs -z3 co etna
cvs -z3 up
</pre><p>
Read The README.* files in the
<tt>rtai</tt> directory for detailed
instructions. First, you need to patch your Linux kernel. A patch per
kernel version can be found in the rtai/patches directory. You should
apply the <tt>patch-X.Y.Z-adeos-rx</tt> patch to a clean
Linux kernel. We refer to the RTAI installation instructions for more
details.
</p><p>
There's an extra Orocos patch you need to apply to the stable RTAI branch.
You find this patch in <tt> core/doc/rtai-24.1.11.patch </tt>
and apply it to your RTAI tree:
</p><pre class="screen">
cp rtai-24.1.11.patch /usr/src/rtai/
cd /usr/src/rtai
patch -p0 < rtai-24.1.11.patch
</pre><p>
Next do <b>make menuconfig; make dep; make;</b>
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2787192"></a> RTAI settings </h4></div></div><p> RTAI comes with extensive \
documentation for configuration and installation.
In the configuration process, make sure that you enable the following
options:
</p><pre class="screen">
--- Code maturity level options
[*] Prompt for experimental code
--- Scheduler
<*> UP Scheduler
--- Features
[*] Enable floating point support
<*> RTAI Math library support
[*] Strange APIC support
--- Subsystems
<*> RT memory manager
[*] Use vmalloc() instead of kmalloc()
<M> FIFOs
<M> Shared Memory
<M> POSIX API
< > Watchdog
<M> LXRT - Realtime in User Space
<M> NEWLXRT - Native Linux Hard Realtime (NEW)
<M> C++ support
[*] New rtai_cpp interface (EXPERIMENTAL)
<M> Tasklets
<M> Bits
<M> Typed mailboxes
< > Real-Time serial driver (rt_com)
< > Real-Time serial driver (spdrv) (NEW)
< > Real-Time networking (rtnet) (EXPERIMENTAL)
</pre><p>
After configuring you can run 'make' in your RTAI directory
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2787244"></a> Loading RTAI without LXRT (not recommended)</h4></div></div><p> \
To enable RTAI without LXRT run in your rtai directory one of the programs </p><pre \
class="screen">
./setsched up # for uniprocessor systems OR
./setsched smp # for smp systems
</pre><p>
next you can 'make install'.
Make sure that the following RTAI kernel modules are loaded:
</p><div class="itemizedlist"><ul \
type="disc"><li><p>rtai_cpp</p></li><li><p>rtai_sched_ext</p></li><li><p>rtai_bits</p> \
</li><li><p>rtai_tbx</p></li><li><p>rtai_pthread</p></li><li><p>rtai_sched</p></li><li \
><p>rtai_fifos</p></li><li><p>rtai_utils</p></li><li><p>rt_mem_mgr</p></li><li><p>rtai</p></li><li><p>adeos</p></li></ul></div><p>
>
For example, by executing as root:
<b>modprobe rtai_cpp; modprobe rtai_pthread; modprobe rtai_fifos</b>.
</p></div><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2787349"></a> Loading RTAI with (NEW)LXRT (recommended)</h4></div></div><p> \
NEWLXRT is a all-in-one scheduler that works for kernel and userspace. So if you use \
this, you can still run kernel programs but have the ability to run realtime \
programs in userspace. Orocos provides you the libraries to build these programs. \
When we say LXRT, we mean NEWLXRT. To enable RTAI with NEWLXRT run in your rtai \
directory the program </p><pre class="screen">
./setsched newlxrt
</pre><p>
next you can 'make install'.
Make sure that the following RTAI kernel modules are loaded for using:
</p><div class="itemizedlist"><ul \
type="disc"><li><p>rtai_fifos_lxrt</p></li><li><p>rtai_lxrt</p></li><li><p>rtai_sched< \
/p></li><li><p>rtai_fifos</p></li><li><p>rt_mem_mgr</p></li><li><p>rtai</p></li><li><p>adeos</p></li></ul></div><p>
For example, by executing as root:
<b>modprobe rtai_lxrt; modprobe rtai_fifos_lxrt</b>.
</p><p>For a more detailed description of what (NEW)LXRT really is,
you can read the LXRT HOWTO
<a href="http://people.mech.kuleuven.ac.be/~psoetens/portingtolxrt.html" \
target="_top">here</a>
</p></div></div><div class="sect2"><div class="titlepage"><div><h3 \
class="title"><a name="id2850591"></a>Configuring for RTLinux</h3></div></div><p> The \
latest free release of RTLinux was 3.2. RTLinux has no memory management, and this \
puts a limit on our use of STL (Standard Template Library) vectors in realtime. (In \
fact, we need maps too.) For these reasons, RTLinux is less supported and might lead \
to unstability. </p><p>
For a recent kernel patch, look at <a \
href="http://bernia.disca.upv.es/rtportal/apps/upgrades/" target="_top">RTlinux \
patches to newer Linux kernels</a> webpage. The RTLinux
<a href="http://www.fsmlabs.com/" target="_top">Homepage</a> contains more
information.
</p><div class="sect3"><div class="titlepage"><div><h4 class="title"><a \
name="id2850629"></a>Loading RTLinux</h4></div></div><p> The following RTLinux \
kernel modules should be loaded in the specified order: </p><div \
class="orderedlist"><ol \
type="1"><li><p>rtl</p></li><li><p>rtl_time</p></li><li><p>rtl_posixio</p></li><li><p>rtl_fifo</p></li><li><p>rtl_sched</p></li></ol></div><p>
You can use the <b>modprobe</b> or <b>insmod</b> as root
to load these needed kernel modules.
</p></div></div></div><div class="sect1"><div class="titlepage"><div><h2 \
class="title" style="clear: both"><a name="started"></a>Getting started with the \
code</h2></div></div><p> This Section provides the semantics of the services \
available in the Orocos Packages.
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2850718"></a>A quick test</h3></div></div><p> To quickly test Orocos code, \
you can run <b>make check</b> in your build directory. You have to do this as root
when you are building for RTAI or RTLinux. You'll see a lot of text
scrolling over the screen, being the output of the programs in the
<tt>tests</tt> directory. You can start examining
<tt>test.cpp</tt> and work your way up to more complex
tests. We may provide, some time in the near future, a <b>make
examples</b> target and an examples subdirectory. But for now,
the tests are the example programs. The tests are called by the
<tt>UnitTest.hpp</tt> file. See the documentation in that
file for how it works.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2850779"></a> Where's main() ?</h3></div></div><p>
The first question asked by many users is : How do I write a test program \
to see how it works?
</p><p>
The short answer is: modify a program in the
<tt>tests</tt> directory. The even
shorter answer is: <span class="emphasis"><em>There is no main (Neo realized \
that too!). </em></span>
In the current implementation, realtime execution in the kernel
of your program is provided by inserting kernel modules into the
kernel using the commands <b>insmod</b> and
<b>rmmod</b> as the root user. <b>insmod</b>
will call a function <tt>init_module()</tt> and
<b>rmmod</b> will call a function
<tt>cleanup_module()</tt>. You must
provide them, so that when they are called, they start your realtime
program. You can see an example in <tt>src/module.c</tt>.
As you will see, <tt>module.c</tt> calls our real C++
function which then starts or stops our program.
<tt>src/moduleStartStop.c</tt> is another example we use
for starting and stopping the framework in kernel space.
</p><p>
When you want to run the framework in userspace or LXRT, you
<span class="emphasis"><em>can</em></span> write your own <tt>main()</tt>
function which includes the <tt>Framework.hpp</tt> file
and starts the framework manually. You can take a look at
<tt>tests/TestMain.cpp</tt> to see how that works.
For beginners, this is really the easiest way.
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a \
name="id2850919"></a> How do I compile my program ? </h3></div></div><p> First of \
all, you can download the orocos-template package which provides you with a \
documented template how to use it. You do need the automake and autoconf tools to \
use this. </p><p>
Take a look at the <tt>Makefile.am</tt> file in the
<tt>tests</tt> directory. You will see
first a list of all the header files and below that, some AutoMake
directives abou how to build a specific program.
</p><pre class="screen">
test_gnulinux_SOURCES = test.cpp module.c
test_gnulinux_LDADD = -L ../src -lorocos_core-gnulinux -lstdc++
</pre><p>
Above you see how the program <tt>test-gnulinux</tt> is
compiled from <tt>test.cpp</tt>. LXRT has a similar syntax.
We suggest you copy/paste
this line and fill in your own filenames. For a realtime kernel module
you need something like the following line:
</p><pre class="screen">
test-rt.sh:
$(top_srcdir)/tests/create_module_testscript.sh test-rt
test_rt_o_SOURCES = test.cpp module.c
test-rt.o: ${CRTBEGIN} $(test_rt_o_OBJECTS) ${CRTEND}
${LD} -r -o $@ ${CRTBEGIN} ${test_rt_o_OBJECTS} ${CRTEND} -lm -lc
</pre><p>
The first two lines are common for all tests and instruct how a
start/stop shell script must be made. The next line says that the
module <tt>test-rt.o</tt> consists of two source files.
The next two lines are standard for linking kernel modules in
Orocos. A copy paste of these five lines should do for making your
own kernel module. You are obliged to add the programs name to the
<tt>EXTRA_PROGRAMS</tt> line on top of your
<tt>Makefile.am</tt>.
</p><p>
If you happened to rename the <tt>test-rt.o</tt> or
<tt>test-gnulinux</tt> targets (or added your own), you
need to add the new name to the <tt>configure.ac</tt> file
in the packages root directory:
</p><pre class="screen">
OROCOS_PRODUCTS_RTLINUX(
[orocos_core-rtlinux.o orocos_core_run-rt.o],
[test-rt.o test_heartbeat-rt.o test_event-rt.o test_eventinterrupt-rt.o]
)
</pre><p>
You can see in the above example that RTLinux has two kernel modules
<tt>orocos_core-rtlinux.o</tt> and
<tt>orocos_core_run-rt.o</tt>
as main products. The test products are listed below. Every target operating
system has this macro for specifying what should be built. So you
can define your own kernel module or user program.
</p><p>
Once you modified the source files and the <tt>Makefile.am</tt>
and <tt>configure.ac</tt>, you can rerun make in your
build directory.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 \
class="title">Note</h3><p> Changing your <tt>Makefile.am</tt> in your <tt>src</tt> \
directory will result in a rebuilding of the Makefile in your build directory. You \
will need the automake and autoconf tools which are probably provided by your Linux
distribution. See the installation Section for more information.
</p></div><p>
</p><p>
Yes, we are thinking about providing a template package with everything
in it. However, once you understand the above concepts, you can apply
them in every Orocos package.
</p></div></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2851146"></a>Examples</h2></div></div><p> The project \
maintainers intend to write many example programs to demonstrate how to build \
components and applications. At this time, only the test directories contain some \
usage examples, but they may not always be sufficiently clear. Please, post your \
example programs on the mailing list, and the project will gratefully accept the good
ones.
</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" \
style="clear: both"><a name="id2851165"></a>Todo</h2></div></div><p> The current \
Orocos framework has the following Packages: core, motioncontrol, drivers, \
interfacing, lrl (Leuvens Robotics Library) and robots. Besides improving these \
Packages, some new Packages are needed: </p><div class="itemizedlist"><ul \
type="disc"><li><p>(Graphical) configuration: generating components
ineractively with a (G)UI</p></li><li><p>Remote Access: secure communication for
accessing the framework over a network</p></li></ul></div><p>
</p></div><div class="bibliography"><div class="titlepage"><div><h2 \
class="title"><a name="id2851201"></a>Bibliography</h2></div></div><div \
class="biblioentry"><p><span class="title"><i>Pattern-oriented software architecture: \
a system of patterns
</i>. </span><span class="authorgroup">Frank Buschmann, Regine Meunier, and Hans \
Rohnert. </span><span class="pubdate">1996. </span><span class="publisher"><span \
class="publishername">Wiley Chicester. </span></span></p></div><div \
class="biblioentry"><p><span class="title"><i>Design Patterns Elements of Reusable \
Object-Oriented Software </i>. </span><span class="authorgroup">Erich Gamma, Richard \
Helm, Ralph Johnson, and John Vlissides. </span><span class="pubdate">1994. \
</span><span class="publisher"><span class="publishername">Addison Wesley. \
</span></span></p></div><div class="biblioentry"><p><span \
class="biblioset">“Frameworks = (components + patterns)”. <span \
class="authorgroup">R. E. Johnson. </span><span class="pagenums">39–42. \
</span><span class="volumenum">40. </span><span class="issuenum">10. </span><span \
class="pubdate">1997. </span></span><span class="biblioset"><i>Communications of the \
ACM</i>. </span></p></div><div class="biblioentry"><p><span \
class="biblioset"><i>Component Software: Beyond Object-Oriented Programming</i>. \
<span class="authorgroup">C, Szyperski. </span><span class="publisher"><span \
class="publishername">Addison Wesley. </span></span><span class="pubdate">1998. \
</span></span></p></div></div></div></body></html>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic