Orocos RTT 1.0 Release Series Changes, New Features, and Fixes
<!--Couldn't selectively extract content, Imported Full Body :(-->
<div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div></div><div><h3 class="subtitle"><i><span class="emphasis"><em>Open RObot COntrol Software</em></span>
</i></h3></div></div><hr></hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#caveats">1. Caveats</a></span></dt><dd><dl><dt><span class="section"><a href="#id2505370">1.1. Overall Changes</a></span></dt><dt><span class="section"><a href="#id2483074">1.2. OS Changes</a></span></dt><dt><span class="section"><a href="#id2483180">1.3. CoreLib Changes</a></span></dt><dt><span class="section"><a href="#id2481972">1.4. Scripting Changes</a></span></dt><dt><span class="section"><a href="#id2482042">1.5. Component TaskContext Changes</a></span></dt><dt><span class="section"><a href="#id2482137">1.6. Corba IDL Changes</a></span></dt></dl></dd><dt><span class="section"><a href="#id2482202">2. Improvements</a></span></dt><dd><dl><dt><span class="section"><a href="#id2482208">2.1. Orocos C++ Interface</a></span></dt><dt><span class="section"><a href="#id2482304">2.2. Component XML Configuration</a></span></dt><dt><span class="section"><a href="#id2482366">2.3. TaskBrowser Component</a></span></dt></dl></dd><dt><span class="appendix"><a href="#id2482410">A. About Orocos</a></span></dt></dl></div><p>
This document provides a quick overview of what changed between <span class="acronym">Orocos</span> <span class="acronym">RTT</span> versions 0.24 and
1.0. Hence, this release includes all bugfixes of the 0.24
branch. If your application does not work, look here for
possible causes and solutions. Also feature additions and improvements
are documented.
</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="caveats"></a>1. Caveats</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2505370"></a>1.1. Overall Changes</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The make targets and make results have changed. One has now 'make rtt'
(equivalent to 'make all'), 'make rtt-embedded' or 'make rtt-corba'.
The resulting library and .pc file have the names 'liborocos-rtt.a'
and 'orocos-rtt.pc' respectively. All standard headers are installed in the
'rtt' directory. The device interface headers reside in 'rtt/dev'. The
OS headers reside in 'rtt/os'. The Corba headers are in 'rtt/corba'.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=265" target="_top">
Clean up the build system</a> and
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=168" target="_top">
for all details.
</a>
</p></li><li><p>
The 'ORO_...' namespaces of Orocos have been renamed to 'RTT', 'RTT::OS', etc.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=65" target="_top">
Project new Orocos namespace</a> for all details.
</p></li><li><p>
The <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Event.html">Event</a>,
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Method.html">Method</a>,
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Command.html">Command</a>,
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Property.html">Property</a>,
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Attribute.html">Attribute</a> and
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1DataPort.html">DataPort</a> classes have changed in usage
semantics. All these classes require a "name" as a
constructor parameter in order to be initialised. When no
"name" is given (the default constructor) the objects are
empty boxes which will refuse to operate. In order to
check for this condition, all these classes have a
<code class="function">ready()</code> method which returns true if
the object is correctly setup. These new semantics allow
far-going abstraction and network distribution of these
primitives. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=104" target="_top">
Commands and Methods : Away with the Template* classes</a>,
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=119" target="_top">
API Improve Attribute/Property usage</a> and
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=111" target="_top">
API Change event 'add' methods</a> for all details.
</p></li><li><p>
The <code class="function">addEvent</code>,
<code class="function">addMethod</code>,
<code class="function">addCommand</code>,
<code class="function">addProperty</code>,
<code class="function">addAttribute</code> and
<code class="function">addPort</code> functions
have been added to replace the 'TemplateFactory'
classes of prior Orocos versions.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=104" target="_top">
Commands and Methods : Away with the Template* classes</a>,
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=119" target="_top">
API Improve Attribute/Property usage</a> and
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=111" target="_top">
API Change event 'add' methods</a> for all details and a script
which converts 0.24.0 application code to the new syntax.
</p></li><li><p>
The device drivers have been removed from the RealTime Toolkit.
Their new home is the Orocos Components Library (OCL). This makes building
the RTT more simple and gives each device driver an easier to find place.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=115" target="_top">
Project Move device drivers to orocos-components </a> for all details.
</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2483074"></a>1.2. OS Changes</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The ORO_OS namespace has been renamed to RTT::OS.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=65" target="_top">
Project new Orocos namespace</a> for all details.
The headers are installed in 'rtt/os'.
</p></li><li><p>
The RTT::OS::PeriodicThread <code class="function">setToStop()</code> function
now executes finalize() as well and no longer uses Events nor the
Completion Processor.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=165" target="_top">
OS::PeriodicThread depends on RTT::Event, CompletionProcessor</a> for all details.
</p></li><li><p>
The RTT::OS::ThreadInterface functions
<code class="function">makeHardRealTime()</code>,
<code class="function">makeSoftRealTime()</code> and
<code class="function">isHardRealTime()</code> have been replaced
with <code class="function">bool
ThreadInterface::setScheduler(int)</code> and
<code class="function">int
ThreadInterface::getScheduler() const</code>. By default,
all threads (except the main thread) are created as 'hard
realtime' (if available). Use setScheduler to change the
default with an OS defined parameter. The rationale of
this decision has been discussed on
<a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=210" target="_top">
Remove ZTT and friends</a>. This also lead to a renaming
of the equivalent functions in the <code class="filename">fosi_internal.h</code>
file.
</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2483180"></a>1.3. CoreLib Changes</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The <code xmlns:str="http://xsltsl.org/string" class="classname">Event</code> object has changed 'constructor'
semantics. An Event requires a "name" upon construction in order
to be usable. Nameless events are 'empty' and require initialisation.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=111" target="_top">
API Change event 'add' methods</a> for all details.
</p></li><li><p>
The Activity classes can no longer react to Events. Use an <code xmlns:str="http://xsltsl.org/string" class="classname">EventProcessor</code>
or the <code xmlns:str="http://xsltsl.org/string" class="classname">ExecutionEngine</code> to react to events.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=129" target="_top">
Project Removing Events out of activities</a> for all details.
</p></li><li><p>
The NonPreemptibleActivity, PreemptibleActivity,
NonRealTimeActivity classes and their Thread classes no
longer exist. Use (or subclass) the
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1PeriodicActivity.html">PeriodicActivity</a> instead and
add a priority level in the constructor. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=210" target="_top">
Remove ZTT and friends</a> for all details.
</p></li><li><p>
The property reading and writing functions
of the <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1PropertyLoader.html">PropertyLoader</a> have changed
semantics. It is now possible to specify if all properties, some
properties or one property must be written to or read from a file.
The global 'find' function has been renamed to 'findProperty'.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=204" target="_top">
reading properties does not fail</a> for all details.
</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2481972"></a>1.4. Scripting Changes</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The <span><strong class="command">emit</strong></span> statement for emitting events has
been replaced by the <span><strong class="command">do</strong></span> statement in both
program scripts and state machine scripts.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=154" target="_top">
Using events in TaskBrowser</a> for all details.
</p></li><li><p>
The <code class="function">task.varname</code> prefix, required in programs
and statemachines in order to access TaskContext variables has been
dropped. One can now address a TaskContext variable by just writing
<code class="function">varname</code> in a script. The parser will not allow
name clashes between program script variables and TaskContext
variables in which the scripts are loaded.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=140" target="_top">
Using properties from a state machine</a> for all details.
</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2482042"></a>1.5. Component TaskContext Changes</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The RTT::<code xmlns:str="http://xsltsl.org/string" class="classname">GenericTaskContext</code> has been removed.
All its functionality is now available from the 'TaskContext' class,
although through a slightly different API.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=205" target="_top">
Deprecate GenericTaskContext, upgrade TaskContext</a> for all details.
</p></li><li><p>
The RTT::<code xmlns:str="http://xsltsl.org/string" class="classname">TaskBrowser</code> has been
removed. All its functionality is now available from the
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../../../ocl/v0.2.x/api/html/classOCL_1_1TaskBrowser.html">TaskBrowser</a> component in
the Orocos Component Library. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=262" target="_top">
Remove RTT::TaskBrowser, use OCL::TaskBrowser</a>
for all details.
</p></li><li><p>
The <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1WriteDataPort.html">WriteDataPort</a> has been renamed to
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1DataPort.html">DataPort</a> and a 'new' <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1WriteDataPort.html">WriteDataPort</a>
implementation with only a <code class="function">Get()</code> function has been
added. This means that applications that did 'Get()' on a 'WriteDataPort'
will no longer compile and need to rename to 'DataPort'.
This was done to improve naming consistency with the
<a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1BufferPort.html">BufferPort</a> class.
See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=201" target="_top">
API Rename WriteDataPort class to DataPort</a> for all details.
</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2482137"></a>1.6. Corba IDL Changes</h3></div></div></div><p>
These changes only apply if you directly used the IDL interface
of Orocos.
</p><div class="itemizedlist"><ul type="disc"><li><p>
The <span class="type">RTT::Corba::ControlTask</span> class
and related classes have been revised to map better to the
TaskContext interface. <span class="type">MethodFactory</span>
has been renamed to <span class="type">RTT::Corba::MethodInterface</span>,
<span class="type">CommandFactory</span>
has been renamed to <span class="type">RTT::Corba::CommandInterface</span>.
The <span class="type">RTT::Corba::TaskObject</span> has been added
and getting a command or method from the interface is now
similar to plain C++ usage.
</p></li><li><p>
All created objects now have a <code class="function">destroy_X</code>
IDL method which you must call to free the serverside object.
</p></li></ul></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2482202"></a>2. Improvements</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2482208"></a>2.1. Orocos C++ Interface</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
The classes and functions required to setup or access a component
have been greatly simplified and are more uniform in naming.
For example, adding a command is done by writing
commands()->addCommand(...), properties by properties()->addProperty(...)
etc and such for each primitive. Retrieving a 'pointer' to
a primitive from another TaskContext is then done by
peer->getCommand("name"), peer->getProperty("name") etc.
See <a href="orocos-components-manual" target="_top">The Component Builder's Manual</a> for all details.
</p></li><li><p>
All Orocos primitives are to be used as 'objects' and not as 'pointers'.
For example, one does no longer write
</p><pre class="programlisting">Property<int>* myProp = peer->properties()->getProperty<int>("Prop");
assert( myProp != 0 );</pre><p>
but instead:
</p><pre class="programlisting">Property<int> myProp = peer->properties()->getProperty<int>("Prop");
assert( myProp.ready() );</pre><p>
The ready() method checks if "Prop" could be found and had the correct value. This aproach must be taken for every Orocos primitive: Commands, Events, etc. See <a href="orocos-components-manual" target="_top">The Component Builder's Manual</a> for all details. </p></li><li><p> The <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../api/html/classRTT_1_1Command.html">Command</a>'s <code class="function">evaluate()</code> function has been renamed to <code class="function">done()</code>. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=188" target="_top">API Commands: evaluate() deprecated, use done()</a> for all details. </p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2482304"></a>2.2. Component XML Configuration</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> Orocos no longer has a hard dependency on Xerces, nor on 'cpf.dtd' for XML parsing. If Xerces is not detected on your system, an internal (TinyXML) implementation is used. Furthermore, the 'cpf.dtd' file is no longer required to parse Orocos XML files. Orocos has this file built-in and uses it to validate your document when the XML parser supports it (i.e. Xerces). See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=234" target="_top"> XML Parsing: DTD's and Parsers.</a> for all details. </p></li><li><p> The <code class="function">readProperties</code> and <code class="function">writeProperties</code> functions have become more strict. All properties must be read or written or they will refuse to change any values. To have more flexible behaviour, alternative functions have been added to fill the gap. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=204" target="_top"> reading properties does not fail</a> for all details. </p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2482366"></a>2.3. TaskBrowser Component</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p> One can emit events from the TaskBrowser by calling the event by name and providing the arguments. See <a href="https://proj.fmtc.be/orocos-bugzilla/show_bug.cgi?id=154" target="_top"> Using events in TaskBrowser</a> for all details. </p></li><li><p> An <a xmlns="http://www.w3.org/TR/xhtml1/transitional" href="../../../ocl/v0.2.x/api/html/classOCL_1_1TaskBrowser.html">TaskBrowser</a> 'Component' has been created which is more powerful than the classical RTT::<code xmlns:str="http://xsltsl.org/string" class="classname">TaskBrowser</code>. It dynamically connects to Data Flow Ports and allows better testing of unconnected components. </p></li></ul></div></div></div><div class="appendix" lang="en" xml:lang="en"><h2 class="title" style="clear: both"><a id="id2482410"></a>A. About Orocos</h2><p> Please send general, non technical, Orocos questions to <a href="mailto: orocos at lists.mech.kuleuven.be" target="_top"> orocos at lists.mech.kuleuven.be </a>. </p><p> These pages are maintained by <a href="http://www.orocos.org/orocos/whatis" target="_top">the Orocos team</a>. </p><p> For questions related to the use of the Orocos Software, please consult these web pages and the <a href="http://www.orocos.org/documentation.php" target="_top">Orocos manuals</a>. If that fails, the <a href="orocos-dev at lists.mech.kuleuven.be" target="_top"> orocos-dev at lists.mech.kuleuven.be </a> mailing list might help. Please send comments on these web pages and the development of Orocos to our developer mailing list at <a href="orocos-dev at lists.mech.kuleuven.be" target="_top"> orocos-dev at lists.mech.kuleuven.be </a>. All of our lists have <a href="http://lists.mech.kuleuven.be/mailman/listinfo/orocos" target="_top">public archives</a> ( <a href="http://lists.mech.kuleuven.be/mailman/listinfo/orocos-dev" target="_top"> dev public archive</a> ) . </p><p> Copyright (C) FMTC </p><p> Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. </p></div></div>