Orocos documentation

Submitted by snrkiwi on Mon, 2009-03-16 16:10

Orocos-users

[seems to have become a theme on the ML, so I'm sending this in now
rather than continuing to clean it up ...]

People having trouble learning a new tool like Orocos, or completely
daunted by the mountain they appear to have to climb, will drop it and
move elsewhere. I've already personally seen a couple of instances of
this with Orocos. It is a wonderful, extremely capable tool, with
great detail-level documentation, however, IMHO the 10,000 foot view
documentation is missing. This makes it incredibly difficult to learn
how to use it. This has been brought up several times on the list in
previous months (and again today).

I think 3 critical items are missing, at least the first two of which
you see on most/all other mature OSS websites
1) FAQ
2) Tutorials
3) System examples

The FAQ is obvious, and some entries immediately come to mind based on
recent ML activity
a) My shared libraries won't load
b) Can I use dynamic memory allocation, and where?
c) How do I run in real time? ie how do I configure my system to allow
Orocos to run in real-time
d) Why do I have periodic delays when attaching a remote deployer?
... pretty much any question that has popped up on the forum more than
once ... or twice ... or ...

Tutorials (non-complete list below)
a) Hello world as an application
b) Hello world with the deployer
c) Use of reporting component
d) CMake and non-standard install location for Orocos
e) Distributed deployment - ie how to use more than one deployer, and
setting up CORBA
f) Adding types to Orocos
g) Adding types to Orocos+Corba
h) Changing ReadDataPort/WriteDataPort to DataPort for CORBA-based
deployment
...

Some combination of Peter's rtt-examples and rtt-exercises would be
the basis for the above. I would, however, argue that they should not
rely on the Kuka components in OCL. Just create a standalone sample
robot that kinematically loops back desired to actual. Some portion of
the above should be documented on the website (Qt has done this every
well, IMHO), so that someone can browse through and see how things can
be done without having to download the exercises, load multiple source
files and then work through them.

Some of the tutorials can also be ordered by level of difficulty,
where you are basically building up a more and more capable system
(although this may fit in more with the system-level examples below).
The other tutorials are really standalone "how to" concepts.

System level examples should be complete, working, independant, and
graduated. They should be such that a new user could come in, replace
the "Robot" (or "Plant") component with their own component that
talks to their hardware, and be moving their robot in short order. For
some of the examples, I think providing a UML diagram or two would be
very useful to demonstrate one approach in getting from a model to an
implementation.

1. Robot + HMI
Demonstrate robot running in more than one mode using a state machine
(say SAFE and POSITION_CONTROL states).
User manipulates HMI to make robot move
Demonstrate deployment
Demonstrate runtime configuration
Demonstrate CMake including finding Orocos

2: Robot + multiple controllers + controller manager + HMI
Demonstrate cascading state machines (ie controller manager and robot
state machines affect each other)
Demonstrate multiple controllers, and the switch over between them

3: Add GUI + CORBA
Add one example GUI toolkit
Demonstrate correct connection direction for GUI components over CORBA
Demonstrate use of toolkits (and how to forcibly load them into a non-
deployed application)
Explain why you would bring all controller ports/events/methods back
to an HMI, instead of having GUI connect direct to real-time components.

The "motioncontrol" example in the rtt-exercises could form the basis
for some of the above, but it needs much more documentation to be
useful as a learning aid to a new user, or as a proof of concept for
an evaluator of how Orocos can be used.

I am willing to get the ball rolling on the FAQ and system level
examples, but would like to get some preliminary consensus from the
community on what direction to take, etc.

Thoughts? Criticisms? Observations? Suggestions?
Stephen

Re: Orocos documentation

Submitted by phamelin on Tue, 2009-03-17 12:53.

As several speakers in this thread, I am relatively new to Orocos. By against, unlike the others, I enjoyed the learning curve of Orocos compared to other similar software that I used in the past. The only inconvenience I found is that the documentation is difficult to find. There should be a documentation page that contains links to all entry points of the documentation.

snrkiwi wrote:

I think 3 critical items are missing, at least the first two of which you see on most/all other mature OSS websites 1) FAQ 2) Tutorials 3) System examples

I agree on that. Orocos offers so many possibilities that it is often hard for new user to find what's the better way to do their own design. Therefore, I think that system examples that show the good design practices could certainly help the users, and provide at the same time a component repository. As an exemple, the controller-tutorial showed me a way to switch between many controllers using events.

snrkiwi wrote:

The "motioncontrol" example in the rtt-exercises could form the basis for some of the above, but it needs much more documentation to be useful as a learning aid to a new user, or as a proof of concept for an evaluator of how Orocos can be used.

I think that a typical Single-input/Single-output (SISO) first order system (i.e. DC motor) with speed/position controller with trajectory generation could be a good example after the Hello World, and before moving on the more complex case of the serial robot. This can allow to introduce plant model simulation, bumpless controller switching and trajectory generation.

Orocos documentation

Submitted by bruyninc on Tue, 2009-03-17 13:30.

On Tue, 17 Mar 2009, philippe [dot] hamelin [..] ... wrote:

> As several speakers in this thread, I am relatively new to Orocos. By
> against, unlike the others, I enjoyed the learning curve of Orocos
> compared to other similar software that I used in the past. The only
> inconvenience I found is that the documentation is difficult to find.
> There should be a documentation page that contains links to all entry
> points of the documentation.

Ok, this feedback could be turned into a constructive "patch" rather
quickly: what kind of stucture would be most convenient to you?

snrkiwi wrote:

> I think 3 critical items are missing, at least the first two of which
> you see on most/all other mature OSS websites
> 1) FAQ
> 2) Tutorials
> 3) System examples
>
>

> I agree on that. Orocos offers so many possibilities that it is often
> hard for new user to find what's the better way to do their own design.
> Therefore, I think that system examples that show the good design
> practices could certainly help the users, and provide at the same time a
> component repository. As an exemple, the controller-tutorial showed me a
> way to switch between many controllers using events.
>
>

snrkiwi wrote:

>
> The "motioncontrol" example in the rtt-exercises could form the basis
> for some of the above, but it needs much more documentation to be
> useful as a learning aid to a new user, or as a proof of concept for
> an evaluator of how Orocos can be used.
>
>

>
> I think that a typical Single-input/Single-output (SISO) first order
> system (i.e. DC motor) with speed/position controller with trajectory
> generation could be a good example after the Hello World, and before
> moving on the more complex case of the serial robot. This can allow to
> introduce plant model simulation, bumpless controller switching and
> trajectory generation.

This is the "N-axis" controller example in OCL...?

Herman

Orocos documentation

Submitted by snrkiwi on Tue, 2009-03-17 14:20.

On Mar 17, 2009, at 09:05 , Herman Bruyninckx wrote:

> On Tue, 17 Mar 2009, philippe [dot] hamelin [..] ... wrote:
>
>> As several speakers in this thread, I am relatively new to Orocos. By
>> against, unlike the others, I enjoyed the learning curve of Orocos
>> compared to other similar software that I used in the past. The only
>> inconvenience I found is that the documentation is difficult to find.
>> There should be a documentation page that contains links to all entry
>> points of the documentation.
>
> Ok, this feedback could be turned into a constructive "patch" rather
> quickly: what kind of stucture would be most convenient to you?
>
>>

snrkiwi wrote:

>> I think 3 critical items are missing, at least the first two of which
>> you see on most/all other mature OSS websites
>> 1) FAQ
>> 2) Tutorials
>> 3) System examples
>>
>>

>
>> I agree on that. Orocos offers so many possibilities that it is often
>> hard for new user to find what's the better way to do their own
>> design.
>> Therefore, I think that system examples that show the good design
>> practices could certainly help the users, and provide at the same
>> time a
>> component repository. As an exemple, the controller-tutorial showed
>> me a
>> way to switch between many controllers using events.

That last sentence is a perfect reason for a particular tutorial or
exercise. Again, Peter has already done something like this, it just
appears from the new user comments that either we need to make the
existing exercises/tutorials more available, or modify them slightly
to be easier to learn from.

snrkiwi wrote:

>>
>> The "motioncontrol" example in the rtt-exercises could form the basis
>> for some of the above, but it needs much more documentation to be
>> useful as a learning aid to a new user, or as a proof of concept for
>> an evaluator of how Orocos can be used.
>>
>>

>>
>> I think that a typical Single-input/Single-output (SISO) first order
>> system (i.e. DC motor) with speed/position controller with trajectory
>> generation could be a good example after the Hello World, and before
>> moving on the more complex case of the serial robot. This can allow
>> to
>> introduce plant model simulation, bumpless controller switching and
>> trajectory generation.
>
> This is the "N-axis" controller example in OCL...?

Other users have warned against using most (all?) of the examples in
OCL. This has come up a couple of times on the ML in recent months. I
personally found that the examples in OCL were just broken enough to
be difficult, though they did provide some usefulness. Hence my
suggestion of a complete separate, working, independant set of system
examples.

I think that straight away there is a semantic distinction above,
between Phillipe's request and Herman's answer. I know, as Herman
does, that the N-axis controller will do what Phillipe requested.
However, Phillipe may not. The example cited is actually SISO *or*
MIMO capable, which without further description is lost on a new user.
Personally, I didn't think of the SISO example as I was prepared to
jump straight to a "simple MIMO" example early on, though without the
trajectory generation component in the middle. Again, a new user
versus someone with more experience. Where do we compromise here?

Orocos documentation

Submitted by sspr on Wed, 2009-03-18 09:05.

On Tuesday 17 March 2009 14:15:34 S Roderick wrote:
> Other users have warned against using most (all?) of the examples in
> OCL. This has come up a couple of times on the ML in recent months. I
> personally found that the examples in OCL were just broken enough to
> be difficult, though they did provide some usefulness. Hence my
> suggestion of a complete separate, working, independant set of system
> examples.
>
> I think that straight away there is a semantic distinction above,
> between Phillipe's request and Herman's answer. I know, as Herman
> does, that the N-axis controller will do what Phillipe requested.
> However, Phillipe may not. The example cited is actually SISO *or*
> MIMO capable, which without further description is lost on a new user.
> Personally, I didn't think of the SISO example as I was prepared to
> jump straight to a "simple MIMO" example early on, though without the
> trajectory generation component in the middle. Again, a new user
> versus someone with more experience. Where do we compromise here?

The RTT framework is domain specific (creating Controllers) but application
independent. People end up with the RTT because they want to control a machine
or robot (their domain) but have very different application backgrounds
(kinematics or not, PLC-like, distributed control etc...) Orocos tries to
provide an answer for all these applications. Maybe we should partition it
like this:

* General
- 'hello world' like examples, much like we have already in the tutorial.
Disadvantage: a bit abstract
Advantage: easy reference implementation for playing and copy/pasting
* Robotics
- Examples like Stephen proposed earlier
Focus on : Kinematics, path planning, HMI/interfacing
* Machine control
- Similar to Robotics with without kinematics or path planning
Master controller that controls slave devices through a state machine
Focus on : state machines & events
* Distributed
- Sensor data processing using various distributed components
Focus on : Data flow

We can start by setting up a wiki structure like this.

Peter

Orocos documentation

Submitted by bruyninc on Tue, 2009-03-17 16:10.

On Tue, 17 Mar 2009, S Roderick wrote:

[...]
>>> I think that a typical Single-input/Single-output (SISO) first order
>>> system (i.e. DC motor) with speed/position controller with trajectory
>>> generation could be a good example after the Hello World, and before
>>> moving on the more complex case of the serial robot. This can allow
>>> to
>>> introduce plant model simulation, bumpless controller switching and
>>> trajectory generation.
>>
>> This is the "N-axis" controller example in OCL...?
>
> Other users have warned against using most (all?) of the examples in
> OCL. This has come up a couple of times on the ML in recent months. I
> personally found that the examples in OCL were just broken enough to
> be difficult, though they did provide some usefulness. Hence my
> suggestion of a complete separate, working, independant set of system
> examples.
>
> I think that straight away there is a semantic distinction above,
> between Phillipe's request and Herman's answer. I know, as Herman
> does, that the N-axis controller will do what Phillipe requested.
> However, Phillipe may not. The example cited is actually SISO *or*
> MIMO capable, which without further description is lost on a new user.
> Personally, I didn't think of the SISO example as I was prepared to
> jump straight to a "simple MIMO" example early on, though without the
> trajectory generation component in the middle. Again, a new user
> versus someone with more experience. Where do we compromise here?

This is _the_ question we should try to find an answer to in this
discussion... As I said before, it is so difficult to get it "right" for
all users because of their different background, and the last thing that
Orocos can do is to provide the "ontology" of robotics in order to make
everything semantically clear and unambiguous... But we should try to do
_something_ decent anyway!

Herman

Orocos documentation

Submitted by phamelin on Tue, 2009-03-17 17:00.

>
> This is _the_ question we should try to find an answer to in this
> discussion... As I said before, it is so difficult to get it "right" for
> all users because of their different background, and the last thing that
> Orocos can do is to provide the "ontology" of robotics in order to make
> everything semantically clear and unambiguous... But we should try to do
> _something_ decent anyway!
>

To this end, I think that incremental examples should be sufficient. Thus, a
user can spare more or less time on each level according to his background.
Current examples only partially cover this type of incremental learning: it
goes directly from the basic theory (what's a Method/Command/Property ?) to
complex examples (how to control a serial robot?).

Orocos documentation

Submitted by snrkiwi on Tue, 2009-03-17 18:15.

On Mar 17, 2009, at 12:57 , Philippe Hamelin wrote:

> This is _the_ question we should try to find an answer to in this
> discussion... As I said before, it is so difficult to get it "right"
> for
> all users because of their different background, and the last thing
> that
> Orocos can do is to provide the "ontology" of robotics in order to
> make
> everything semantically clear and unambiguous... But we should try
> to do
> _something_ decent anyway!
>
> To this end, I think that incremental examples should be sufficient.
> Thus, a user can spare more or less time on each level according to
> his background. Current examples only partially cover this type of
> incremental learning: it goes directly from the basic theory (what's
> a Method/Command/Property ?) to complex examples (how to control a
> serial robot?).

This is partly what lead me to propose both tutorials (ie how to use
class A, class B, ...) as well as complete system examples. People
learn differently - some from the bottom up from details, and some
from the top down from complete systems - we should try to cope with
both (where possible with limited resources). When I was starting with
Orocos I found that the lack of a complete working example meant that
even if I knew how to use individual classes/concepts, I still had
little concept of how to tie them all together. System examples (and
it need only be one or two) will provide new users with a hug leg up,
by embodying "good design practices" (as Philippe called them earlier).

I agree completely with Heman's last statement above - we should aim
for something that is decent or "good enough". This is an incremental,
evolutionary process ...

Cheers
S

Orocos documentation

Submitted by phamelin on Tue, 2009-03-17 13:30.

2009/3/17 Herman Bruyninckx <Herman [dot] Bruyninckx [..] ...>

> On Tue, 17 Mar 2009, philippe [dot] hamelin [..] ... wrote:
>
> > As several speakers in this thread, I am relatively new to Orocos. By
> > against, unlike the others, I enjoyed the learning curve of Orocos
> > compared to other similar software that I used in the past. The only
> > inconvenience I found is that the documentation is difficult to find.
> > There should be a documentation page that contains links to all entry
> > points of the documentation.
>
> Ok, this feedback could be turned into a constructive "patch" rather
> quickly: what kind of stucture would be most convenient to you?
>

What looks like what I'm looking for is the RTT Manuals page. A list of
documentation with a short description. I think that everythings standing in
:

http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v1.8...

should be part of a documentation page. The presentations and Wiki should
also have a link in this page. The same pattern can apply to OCL. Finally,
it's just a matter of regrouping and briefly describing all the
documentation available.

>
> >

snrkiwi wrote:

> > I think 3 critical items are missing, at least the first two of which
> > you see on most/all other mature OSS websites
> > 1) FAQ
> > 2) Tutorials
> > 3) System examples
> >
> >

>
> > I agree on that. Orocos offers so many possibilities that it is often
> > hard for new user to find what's the better way to do their own design.
> > Therefore, I think that system examples that show the good design
> > practices could certainly help the users, and provide at the same time a
> > component repository. As an exemple, the controller-tutorial showed me a
> > way to switch between many controllers using events.
> >
> >

snrkiwi wrote:

> >
> > The "motioncontrol" example in the rtt-exercises could form the basis
> > for some of the above, but it needs much more documentation to be
> > useful as a learning aid to a new user, or as a proof of concept for
> > an evaluator of how Orocos can be used.
> >
> >

> >
> > I think that a typical Single-input/Single-output (SISO) first order
> > system (i.e. DC motor) with speed/position controller with trajectory
> > generation could be a good example after the Hello World, and before
> > moving on the more complex case of the serial robot. This can allow to
> > introduce plant model simulation, bumpless controller switching and
> > trajectory generation.
>
> This is the "N-axis" controller example in OCL...?
>

Yes I think so. However, It's unclear to me if this is dependant of the kuka
examples.

Philippe

Orocos documentation

Submitted by bruyninc on Tue, 2009-03-17 13:40.

On Tue, 17 Mar 2009, Philippe Hamelin wrote:

[...]
> This is the "N-axis" controller example in OCL...?
>
> Yes I think so. However, It's unclear to me if this is dependant of the kuka examples.

No, the other way around: a Cartesian control (e.g., the KUKAs) depends on
the joint ("axis") control.

Herman

Orocos documentation

Submitted by fosini on Mon, 2009-03-16 16:10.

I think this would be a most-greatly-appreciated work. Not only for
newcomers, but also for people that have worked with Orocos, but are not
expert developers (like myself). I, for one, find your proposal well
structured (FAQ, tutorials, system examples), and would personally benefit
from reading the answers to some of the topics you suggest in your post :).
I know it's a big job to get this up-and-running, but I think It would
definitely pay off in the long run.

Adolfo

On Mon, Mar 16, 2009 at 2:46 PM, S Roderick <kiwi [dot] net [..] ...> wrote:

> [seems to have become a theme on the ML, so I'm sending this in now
> rather than continuing to clean it up ...]
>
>
> People having trouble learning a new tool like Orocos, or completely
> daunted by the mountain they appear to have to climb, will drop it and
> move elsewhere. I've already personally seen a couple of instances of
> this with Orocos. It is a wonderful, extremely capable tool, with
> great detail-level documentation, however, IMHO the 10,000 foot view
> documentation is missing. This makes it incredibly difficult to learn
> how to use it. This has been brought up several times on the list in
> previous months (and again today).
>
>
> I think 3 critical items are missing, at least the first two of which
> you see on most/all other mature OSS websites
> 1) FAQ
> 2) Tutorials
> 3) System examples
>
>
> The FAQ is obvious, and some entries immediately come to mind based on
> recent ML activity
> a) My shared libraries won't load
> b) Can I use dynamic memory allocation, and where?
> c) How do I run in real time? ie how do I configure my system to allow
> Orocos to run in real-time
> d) Why do I have periodic delays when attaching a remote deployer?
> ... pretty much any question that has popped up on the forum more than
> once ... or twice ... or ...
>
>
> Tutorials (non-complete list below)
> a) Hello world as an application
> b) Hello world with the deployer
> c) Use of reporting component
> d) CMake and non-standard install location for Orocos
> e) Distributed deployment - ie how to use more than one deployer, and
> setting up CORBA
> f) Adding types to Orocos
> g) Adding types to Orocos+Corba
> h) Changing ReadDataPort/WriteDataPort to DataPort for CORBA-based
> deployment
> ...
>
> Some combination of Peter's rtt-examples and rtt-exercises would be
> the basis for the above. I would, however, argue that they should not
> rely on the Kuka components in OCL. Just create a standalone sample
> robot that kinematically loops back desired to actual. Some portion of
> the above should be documented on the website (Qt has done this every
> well, IMHO), so that someone can browse through and see how things can
> be done without having to download the exercises, load multiple source
> files and then work through them.
>
> Some of the tutorials can also be ordered by level of difficulty,
> where you are basically building up a more and more capable system
> (although this may fit in more with the system-level examples below).
> The other tutorials are really standalone "how to" concepts.
>
>
> System level examples should be complete, working, independant, and
> graduated. They should be such that a new user could come in, replace
> the "Robot" (or "Plant") component with their own component that
> talks to their hardware, and be moving their robot in short order. For
> some of the examples, I think providing a UML diagram or two would be
> very useful to demonstrate one approach in getting from a model to an
> implementation.
>
> 1. Robot + HMI
> Demonstrate robot running in more than one mode using a state machine
> (say SAFE and POSITION_CONTROL states).
> User manipulates HMI to make robot move
> Demonstrate deployment
> Demonstrate runtime configuration
> Demonstrate CMake including finding Orocos
>
> 2: Robot + multiple controllers + controller manager + HMI
> Demonstrate cascading state machines (ie controller manager and robot
> state machines affect each other)
> Demonstrate multiple controllers, and the switch over between them
>
> 3: Add GUI + CORBA
> Add one example GUI toolkit
> Demonstrate correct connection direction for GUI components over CORBA
> Demonstrate use of toolkits (and how to forcibly load them into a non-
> deployed application)
> Explain why you would bring all controller ports/events/methods back
> to an HMI, instead of having GUI connect direct to real-time components.
>
> The "motioncontrol" example in the rtt-exercises could form the basis
> for some of the above, but it needs much more documentation to be
> useful as a learning aid to a new user, or as a proof of concept for
> an evaluator of how Orocos can be used.
>
>
> I am willing to get the ball rolling on the FAQ and system level
> examples, but would like to get some preliminary consensus from the
> community on what direction to take, etc.
>
> Thoughts? Criticisms? Observations? Suggestions?
> Stephen
> --
> Orocos-Users mailing list
> Orocos-Users [..] ...
> http://lists.mech.kuleuven.be/mailman/listinfo/orocos-users
>
> Disclaimer: http://www.kuleuven.be/cwis/email_disclaimer.htm
>
>

Another vote here for

Submitted by markgillespie@d... on Mon, 2009-03-16 16:58.

Another vote here for enhanced documentation, we too are looking at Orocos, but having a real hard time getting to grips with it.

The problems seem to be inconsistency in the documentation, the docs go from a simple example, straight into very complex code. At times the examples are inconsistent.

Perhaps a more guided tutorial, where you create a very simple component, and then another and get them to exchange data, bit by bit, add further features like data ports later on, and finally adding some state machines and scripting. The examples MUST be simplistic, yet also be clear on how to extend them, no fancy stuff, and certainly no attempts at showing coding prowess. The current examples seem to require some complicated components to get working, and make some serious assumptions about what the end user knows about robotics.. (I have no idea what a CartesianController is, nor do I want to know...)

perhaps a 10 part exercise, starting at the very basics, and then ending at a medium level, rather than trying to cram every feature available into the examples.

Some things I am finding missing, as reasons WHY you would want to use a feature. For example, I am currently looking at the state machine scrips, and I see that I can optionally call program scripts. I have no idea if I need to or not, and what they would offer me that component class methods would not offer...

At the moment, I am failing to see the benefits of Orocos, because it's being clouded by the steep learning curve :-(

Another vote here for

Submitted by bruyninc on Mon, 2009-03-16 20:00.

On Mon, 16 Mar 2009, markgillespie [..] ... wrote:

> Another vote here for enhanced documentation, we too are looking at
> Orocos, but having a real hard time getting to grips with it.
>
It's nice to read that the poor documentation is Orocos' worst problem, and
not the code :-)

And while I perfectly understand your feedback, please remember that Orocos
is a real open source project: (i) it has very limited man power, (ii) you
can use everything without a fee, andd (iii) it can only prosper when all
users contribute to extent possible.

So, let's keep the momentum of this thread, and try to help Roderick's
laudible initiative to _do_ something about the documentation "gap" :-)

Since writing documentation is a hard job (not in the least because the
background of all readers is so different and unknown) we _need_ your help.
Maybe not directly with patches to the documentation, but with information
about your particular "use cases": why do _you_ want to use or to get to
learn Orocos? What is your context and background? What do _you_ find easy
or difficult? Etc.

The most effective short term actions everybody can possibly take are:
- to come to the Orocos workshop on the EURON Annual Meeting in Leuven on
6th of April and discuss these matters with other users and developers.
- to send short but concrete messages about what documentation exactly
you have problems with. Small step by small step.
- to try to find master thesis students to work on the problems.

Herman

> The problems seem to be inconsistency in the documentation, the docs go
> from a simple example, straight into very complex code. At times the
> examples are inconsistent.
>
> Perhaps a more guided tutorial, where you create a very simple component, and then another and get them to exchange data, bit by bit, add further features like data ports later on, and finally adding some state machines and scripting. The examples MUST be simplistic, yet also be clear on how to extend them, no fancy stuff, and certainly no attempts at showing coding prowess. The current examples seem to require some complicated components to get working, and make some serious assumptions about what the end user knows about robotics.. (I have no idea what a CartesianController is, nor do I want to know...)
>
> perhaps a 10 part exercise, starting at the very basics, and then ending at a medium level, rather than trying to cram every feature available into the examples.
>
> Some things I am finding missing, as reasons WHY you would want to use a feature. For example, I am currently looking at the state machine scrips, and I see that I can optionally call program scripts. I have no idea if I need to or not, and what they would offer me that component class methods would not offer...
>
> At the moment, I am failing to see the benefits of Orocos, because it's being clouded by the steep learning curve :-(
>

>And while I perfectly

Submitted by markgillespie@d... on Tue, 2009-03-17 11:22.

>And while I perfectly understand your feedback, please >remember that Orocos is a real open source project: (i) it >has very limited man power, (ii) you can use everything >without a fee, andd (iii) it can only prosper when all >users contribute to extent possible.

I appreciate your points, but it's very difficult to contribute anything but feedback, when you are having problems getting to grips with the framework. Please don't take my comments as criticisms against the Orocos product itself, as i'm sure it's a very capable framework, that alot of people have spent alot of time on, however it's frustrating that it's very difficult to evaluate the product with such a steep learning curve, that you get to the "kill or continue" point long before you reach the point where you fully understand the product.

Another vote here for

Submitted by snrkiwi on Mon, 2009-03-16 18:45.

On Mar 16, 2009, at 12:58 , markgillespie [..] ... wrote:

> Another vote here for enhanced documentation, we too are looking at
> Orocos, but having a real hard time getting to grips with it.
>
> The problems seem to be inconsistency in the documentation, the docs
> go from a simple example, straight into very complex code. At times
> the examples are inconsistent.

I too found this exact problem when I started with Orocos. There is a
huge learning curve from the doc's to a working system, which lead me
to propose the tutorials and system examples. It isn't helped by
inconsistent examples and non-working code (particularly in OCL).

> Perhaps a more guided tutorial, where you create a very simple
> component, and then another and get them to exchange data, bit by
> bit, add further features like data ports later on, and finally
> adding some state machines and scripting. The examples MUST be
> simplistic, yet also be clear on how to extend them, no fancy stuff,
> and certainly no attempts at showing coding prowess. The current
> examples seem to require some complicated components to get working,
> and make some serious assumptions about what the end user knows
> about robotics.. (I have no idea what a CartesianController is, nor
> do I want to know...)

Peter has already done something like this with the rtt-exercises and
rtt-examples. Peronsally, I just don't think they're guided enough,
and they do jump rapidly in knowledge requirements, but I do think
that they are a great start for what you're asking for.

As a matter of curiousity, and with all due respect, if you don't know
what a Cartesian Controller is then what are you using Orocos for? A
non-robotic application?

> perhaps a 10 part exercise, starting at the very basics, and then
> ending at a medium level, rather than trying to cram every feature
> available into the examples.
>
> Some things I am finding missing, as reasons WHY you would want to
> use a feature. For example, I am currently looking at the state
> machine scrips, and I see that I can optionally call program
> scripts. I have no idea if I need to or not, and what they would
> offer me that component class methods would not offer...

This too I ran into. My 2c - scripts are useful but only in very small
quantities (we basically don't use them at all in any of the 3 or more
projects we use Orocos on). State machines, though, are phenomenally
useful ... we use them all over ...

> At the moment, I am failing to see the benefits of Orocos, because
> it's being clouded by the steep learning curve :-(

This is precisely what I'm afraid of. We have found the benefits to be
dramatic, but sticking with Orocos long enough to realise this
requires a really stubborn person right now .... kinda like me ... ;-)

I see we have opinions from the new users ... but nothing yet from the
more experienced members of the community ....? Anyone ....
Bueller ... Bueller ....?

Another vote here for

Submitted by snrkiwi on Mon, 2009-03-16 20:20.

> I see we have opinions from the new users ... but nothing yet from the
> more experienced members of the community ....? Anyone ....
> Bueller ... Bueller ....?

There is a FAQ already!?

http://people.mech.kuleuven.be/~orocos/pub/documentation/rtt/v1.8.x/doc-...

Am I completely blind in not knowing this was there? Or should I
presume since it was last updated for RTTv1.2 that this is a
discontinued effort?
S

Another vote here for

Submitted by sspr on Wed, 2009-03-18 09:05.

On Monday 16 March 2009 20:16:33 S Roderick wrote:
> > I see we have opinions from the new users ... but nothing yet from the
> > more experienced members of the community ....? Anyone ....
> > Bueller ... Bueller ....?
>
> There is a FAQ already!?
>
> http://people.mech.kuleuven.be/~orocos/pub/documentation/rtt/v1.8.x/doc-xml
>/orocos-faq.html
>
> Am I completely blind in not knowing this was there? Or should I
> presume since it was last updated for RTTv1.2 that this is a
> discontinued effort?

It's still useful for some users, but lacks the questions/answers you were
having.
The FAQ should be created as a wiki, not as an XML document in the sources.

Peter

Another vote here for

Submitted by snrkiwi on Thu, 2009-03-19 13:50.

On Mar 18, 2009, at 05:03 , Peter Soetens wrote:

> On Monday 16 March 2009 20:16:33 S Roderick wrote:
>>> I see we have opinions from the new users ... but nothing yet from
>>> the
>>> more experienced members of the community ....? Anyone ....
>>> Bueller ... Bueller ....?
>>
>> There is a FAQ already!?
>>
>> http://people.mech.kuleuven.be/~orocos/pub/documentation/rtt/v1.8.x/doc-xml
>> /orocos-faq.html
>>
>> Am I completely blind in not knowing this was there? Or should I
>> presume since it was last updated for RTTv1.2 that this is a
>> discontinued effort?
>
> It's still useful for some users, but lacks the questions/answers
> you were
> having.
> The FAQ should be created as a wiki, not as an XML document in the
> sources.

I started a wiki page to collect items that should end up as
documentation. Essentially I tried to summarize this thread's
discussion.

http://orocos.org/wiki/rtt/documentation-suggetsions

This is *not* intended to be the documentation itself - merely a
location to write down what we think needs to be done. We can then
slowly chip through the items on this page ...

Cheers
S

Another vote here for

Submitted by bruyninc on Mon, 2009-03-16 20:25.

On Mon, 16 Mar 2009, S Roderick wrote:

>> I see we have opinions from the new users ... but nothing yet from the
>> more experienced members of the community ....? Anyone ....
>> Bueller ... Bueller ....?
>
> There is a FAQ already!?
>
> http://people.mech.kuleuven.be/~orocos/pub/documentation/rtt/v1.8.x/doc-...
>
> Am I completely blind in not knowing this was there? Or should I
> presume since it was last updated for RTTv1.2 that this is a
> discontinued effort?

This is an example of an effort that was driven by Peter, but in which he
was (almost) not supported at all by the community... Maybe now the time is
more advantageous to such community contributions! :-) Let the
documentation patches stream!

Herman

orocos documentation

Submitted by Uwe Fechner on Sun, 2011-02-27 19:56.

Hello,

I am starting to use orocos for our kite-power control system.
(See: www.kitepower.eu )

I need the documentation of version 2.2.

On the internet I don't find it.

Google finds version 1.99:
http://people.mech.kuleuven.be/~orocos/pub/devel/rtt/rtt-2.0-mainline/do...

and version 1.85:
http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v1.8...

Here I find version 1.12.1:
http://www.orocos.org/rtt/manuals

I downloaded and installed the source code, using the boostrap.sh script.
In the orocos-toolchain/rtt/doc folder I find only .xml files.

The README.txt does say, that I can use "make docpdf" to create the pdf
documentation.
If I do it, I get the message:

> make: *** Keine Regel, um »docpdf« zu erstellen. Schluss.

Any hints, how to build the .pdf documentation are welcome.

Best regards:

----------------------------------------
Uwe Fechner, M.Sc.
Delft University of Technology
Faculty of Aerospace Engineering/ASSET
Kluyverweg 1,
2629 HS Delft, The Netherlands
Phone: +31-15-27-88902

orocos documentation

Submitted by willy on Sun, 2011-02-27 20:16.

You can find the most up to date of official 2.x documentation here
http://www.orocos.org/wiki/orocos/toolchain/toolchain-reference-manuals
or
here if you are looking precisely for the 2.2.x doc
http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v2.2...

I think the real documentation that interest you when you develop is the
"Component Builder Manual" :
http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v2.2...

a present time the latest doc is the 2.2 so both point to the same docs.

I can't help to generate the docs.

2011/2/27 Uwe Fechner <u [dot] fechner [..] ...>

> Hello,
>
> I am starting to use orocos for our kite-power control system.
> (See: www.kitepower.eu )
>
> I need the documentation of version 2.2.
>
> On the internet I don't find it.
>
> Google finds version 1.99:
>
> http://people.mech.kuleuven.be/~orocos/pub/devel/rtt/rtt-2.0-mainline/do...
>
> and version 1.85:
>
> http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v1.8...
>
> Here I find version 1.12.1:
> http://www.orocos.org/rtt/manuals
>
> I downloaded and installed the source code, using the boostrap.sh script.
> In the orocos-toolchain/rtt/doc folder I find only .xml files.
>
> The README.txt does say, that I can use "make docpdf" to create the pdf
> documentation.
> If I do it, I get the message:
>
> > make: *** Keine Regel, um »docpdf« zu erstellen. Schluss.
>
> Any hints, how to build the .pdf documentation are welcome.
>
> Best regards:
>
> ----------------------------------------
> Uwe Fechner, M.Sc.
> Delft University of Technology
> Faculty of Aerospace Engineering/ASSET
> Kluyverweg 1,
> 2629 HS Delft, The Netherlands
> Phone: +31-15-27-88902
>
>
> --
> Orocos-Users mailing list
> Orocos-Users [..] ...
> http://lists.mech.kuleuven.be/mailman/listinfo/orocos-users
>
>

orocos documentation

Submitted by Uwe Fechner on Sun, 2011-02-27 22:24.

Hello,

thanks a lot, that was, what I was looking for.

Actually the links are not the same, the most up-to-date documentation,
that you find here
(http://www.orocos.org/wiki/orocos/toolchain/toolchain-reference-manuals) is
the 2.3 documentation,
but I think, 2.3 is not released yet.

Nevertheless it might be a good idea, to update this wiki page:
http://www.orocos.org/rtt/manuals

(I can't do it.)

Regards:

Uwe Fechner

On 27.02.2011 21:15, Willy Lambert wrote:
> You can find the most up to date of official 2.x documentation here
> http://www.orocos.org/wiki/orocos/toolchain/toolchain-reference-manuals
> or
> here if you are looking precisely for the 2.2.x doc
> http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v2.2...
> <http://people.mech.kuleuven.be/%7Eorocos/pub/stable/documentation/rtt/v2.2.x/doc-xml />
>
> I think the real documentation that interest you when you develop is
> the "Component Builder Manual" :
> http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v2.2...
> <http://people.mech.kuleuven.be/%7Eorocos/pub/stable/documentation/rtt/v2.2.x/doc-xml/orocos-components-manual.html>
>
>
> a present time the latest doc is the 2.2 so both point to the same docs.
>
> I can't help to generate the docs.
>
>
>
> 2011/2/27 Uwe Fechner <u [dot] fechner [..] ... u [dot] fechner [..] ...>>
>
> Hello,
>
> I am starting to use orocos for our kite-power control system.
> (See: www.kitepower.eu <http://www.kitepower.eu> )
>
> I need the documentation of version 2.2.
>
> On the internet I don't find it.
>
> Google finds version 1.99:
> http://people.mech.kuleuven.be/~orocos/pub/devel/rtt/rtt-2.0-mainline/do...
> <http://people.mech.kuleuven.be/%7Eorocos/pub/devel/rtt/rtt-2.0-mainline/doc/doc-xml/orocos-components-manual.html>
>
> and version 1.85:
> http://people.mech.kuleuven.be/~orocos/pub/stable/documentation/rtt/v1.8...
> <http://people.mech.kuleuven.be/%7Eorocos/pub/stable/documentation/rtt/v1.8.x/doc-xml/orocos-components-manual.html>
>
> Here I find version 1.12.1:
> http://www.orocos.org/rtt/manuals
>
> I downloaded and installed the source code, using the boostrap.sh
> script.
> In the orocos-toolchain/rtt/doc folder I find only .xml files.
>
> The README.txt does say, that I can use "make docpdf" to create
> the pdf documentation.
> If I do it, I get the message:
>
> > make: *** Keine Regel, um »docpdf« zu erstellen. Schluss.
>
> Any hints, how to build the .pdf documentation are welcome.
>
> Best regards:
>
> ----------------------------------------
> Uwe Fechner, M.Sc.
> Delft University of Technology
> Faculty of Aerospace Engineering/ASSET
> Kluyverweg 1,
> 2629 HS Delft, The Netherlands
> Phone: +31-15-27-88902
>
>
> --
> Orocos-Users mailing list
> Orocos-Users [..] ...
> <mailto:Orocos-Users [..] ...>
> http://lists.mech.kuleuven.be/mailman/listinfo/orocos-users
>
>

Another vote here for

Submitted by facontidavide on Mon, 2009-03-16 17:45.

> Some things I am finding missing, as reasons WHY you would want to use a feature.

About this, I can tell you that few days ago we had a discussion of
about 2 hours to decide if we should use DataPorts, Methods or
Commands to set the position of a motor...
At the end there was just 1 robust way to do it, but it took a lot of
time to figure it out.
I think that one of the goal of the new documentation should be to
make clear the advantages and disadvantages of any communication
method offered by Orocos.

Orocos documentation

Submitted by guoliang liu on Mon, 2009-03-16 16:10.

Really good comment...!!! Almost like what I thought..(-:
For newbie, like me, really need hard work on Orcos to know how it works in
real time way...
I think it should be better introduce something like what's the real time
before to introduce Orocos RTT..
"Real-Time and Embedded Guided" by Herman Bruyninckx is a pretty good
tutorial on Real-Time stuff..

2009/3/16 S Roderick <kiwi [dot] net [..] ...>