[prev in list] [next in list] [prev in thread] [next in thread] 

List:       orocos-dev
Subject:    [Orocos-Dev] Updated Component Lifecycle flowchart
From:       peter.soetens () mech ! kuleuven ! ac ! be (Peter Soetens)
Date:       2003-10-23 12:29:01
Message-ID: 200310231228.06560.peter.soetens () mech ! kuleuven ! ac ! be
[Download RAW message or body]

I have updated the component lifetime semantics. Two functions were 
'renamed' :  kernelStarted and kernelStopped. They are now events, because 
their meaning as a hook was a bit ambiguous, I introduced two new hooks : 
componentStartUp() and componentShutdown() where you'll normally put the code 
which was in the previous functions.

A nice png in attachment explains it 'all' (is in control_kernel/doc dir).

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
------------------------------------------------------------------------

["component_life_cycle.png" (image/png)]
>From Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be>  Thu Oct 23 14:11:00 2003
From: Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be> (Herman Bruyninckx)
Date: Thu Oct 23 13:11:00 2003
Subject: [Orocos-Dev] Documentation TODO
In-Reply-To: <200310171552.34858.peter.soetens@mech.kuleuven.ac.be>
Message-ID: <Pine.LNX.4.44.0310231309330.1940-100000@srv04.mech.kuleuven.ac.be>

This is some feedback on the orocos-control-kernel document.

Herman
==================================

I would not talk about robotics components in this document; only
about application-independent feedback control stuff.

"A last piece of advice" as the fourth sentence in a document looks
quite weird :-)

I would not talk about installation at all; _all_ installation issues
are probably better treated in one dedicated document?

"Depending on the application, other components will be used, together
with other types of data being exchanged." I agree with the latter,
but certainly not with the former! That's exactly what the control
Software Pattern is all about: _every_ control application needs
nothing more than the five mentioned components. (As far as the proper
real-time control actions are involved; I'm not speaking about higher levels
than the real-time.)

"The Default Control Kernel is an empty box. It just defines the basis
for..." This is not really true: it offers _structure_, supported by
implemented functionality. It's just that this functionality is not
related to the applications.

Refer to doxygen only once in the document (in the introduction).
(Same remark for the other documents.)

Don't refer to the journal paper in this documentation: this kind of
information (i.e., links to paper drafts) ages too quickly.

Define the term "control kernel" as early as possible in the document.

Typo: "help to [to] find the correct order".

"DefaultControlKernel <InputType,..."
In fact this doesn't define the control kernel, but only the _data
flow_ of the kernel. Maybe the naming should be adapted
("ControlKernelDataObjects"?), because the contents of the components
have to be defined also somewhere ("ControlKernelComponents"?). It's
only after that has been done that the control kernel is ready.

Typo: " What really happen[E]d..." 

The paragraph "DataObjects" should be re-structured I think, or
renamed:  it deals with the _protected access_ of the data (which
could/should preferably be discussed in one of the other documents?),
and the sentences about defining the Kernel belong to the discussion
on the same topic held in the subsection before this.

"A kernel based on CORBA components": this sentence suggests too much
we do _not_ want to suggest, i.e., that CORBA is (i) fundamental to
Orocos, and (ii) advisable for control.

"kernel running in a single threaded system will need no protection at
all": this is _not_ true _in general_? For example, an ISR/DSR could
interfere with the single thread by accessing shared data...
(And the term "single threaded system" is not very precise, I think:
it's better to talk about a "single-thread control architecture".)

"Choosing a Kernel means choosing DataObjects" -> "Defining a Kernel
requires (among other things) defining its DataObjects" (and also the
access protection?)

"Once the kernel is fixed, the DataObjects can no longer be changed."
This seems to suggest that no flexibility is possible... But what
about the possibility that different algorithms in the same components
(running in different states of the component state machine) can
exchange different data objects? They _all_ have to be defined at
compile time, but there _can_ be reconfiguration of the DataFlow...

"This might be a bit heavy for some applications, but fortunately,
nameserving can relief this (see DataServed)." ("relieve"?)
DataServed is nowhere discussed... And the DataObject concept only
_seems_ to be heavy in the current document, because it doesn't
mention that two components can exchange data in a finer granularity
than one single DataObject...  Maybe the configuration interface of
the Kernel should become finer grained than
"DefaultControlKernel <InputType, ModelType, CommandType,
                       SetPointType, OutputType>;":
(I think Peter already has a prototype of this running?)
I can imagine an interface that defines the data objects between a
function in one component and another function in another component,
as long as this interaction fits in the control Software Pattern. So,
the interface could become:
"
 AddComponent(Generator, &MyGenerator1);
 AddComponent(Generator, &MyGenerator2);
 AddComponent(Controller, &MyController);
 AddDataObject(MyGenerator1,MyController,MyGenConDataObject1);
 AddDataObject(MyGenerator2,MyController,MyGenConDataObject2);
"
This finer-grained interface does require support to check whether the
interface is consistent and complete. And we don't have this yet...
(I have replaced the "SetGenerator()"... calls by "AddComponent()",
because it is more flexible (= allows more than one Generator etc).)

"...DataObject which gives always priority to the thread calling
Set(), which will never block": how is this possible if another
component is performing a Get()? (By the "switching buffers" concept,
I assume? Otherwise data corruption at the Get() component is
inevitable...)
I think this semantics has nothing to do with priorities! But with
correct locking (monitor/buffer-like)...

The method calls "pull()" and "push()" are maybe better replaced by
"input()" and "output()"? Because these are policy-neutral, while pull
and push suggest a particular data communication policy...
And why not "get()" and "set()", since the names of the actual data
transfer method calls are called like that...
(It's _much_ better to adapt names at this pre-release stage than
later on in the lifetime of the software...)

"The pull() method will Get() the data objects and copy its contents
to local variables": shouldn't we leave open the opportunity to have
"empty" Get and Set, if multiple components are "collocated"; in the
CORBA sense: two components that are collocated act in the same space
and thread and are guaranteed not to interfere in each other's data
access...

"These methods are used for the Data-Flow of the kernel." There
should be some more details about data flow vs configuration flow
earlier in the document.

"In some cases, a method of the DefaultComponent can be overrid[d]en and
act as an event handler for a specific action."
I do not understand this sentence...

"Kernel Extensions": this concept is _cery_ difficult to really
understand, probably because "extension" is such a vague and general
term...
What are the real needs to introduce extensions?  Are extensions only
meant for adding non-realtime functionality?  Is CommandInterpretion
also an Extension? When exactly does something classify as an
extension? When not? What are the required "features" that an
extension should have?

In fact, I don't see the need to introduce something with such a
generic and empty name as "extension" in the framework.  Especially
when I read "Each kernel has also a KernelBaseExtension, which defines
the basic features each kernel must have", I feel uncomfortable, since
how can something be called an "extension" if it covers the "basic
features"....?
So, I prefer to _incorporate_ the "extensions" into the framework and
give them a good name (Reporting and Properties are good examples and
good names), after deliberation whether or not they are really
fundamental and structural. (Both reporting and properties are
fundamental and structural :-)

"This piece of code is called a Component Aspect": what is the
motivation for the name "aspect"? Isn't the CORBA 3.0 name "facet"
equally suitable? Preferable? (Because using terminology from the
CORBA domain reduces documentation requirements from our part...)

What is the reason to have such emphasis on the _order_ of extensions?
I do not really like _implicitly_ specified effects depending on order...
Moreover, the document says the order is very important, but it
doesn't explain why?
The document says "A whole dependency tree can be built in that way".
How does one make a tree? How is the tree "serialized" for concrete
execution? Is this serialization important? What are the real-time
properties ("priorities") of extensions/aspects? ...

Typos: " if the component does noT want to use it"
"Each Aspect is defined [as] such that the Component has..."

What is a ".cdl xml file"?

Shouldn't any CORBA "extension" be built around a real kernel
extension? Everything CORBA is just wrappers... And I would not like
the Kernel to have CORBA dependencies, because many people will _not_
like that. The best we can do, I guess, is to make a CORBA directory,
which is the only one with CORBA dependencies, and that is not
compiled in by default.

"This section explains how a ControlKernel can be configured". The
rest of the document never uses the word "ControlKernel", only Kernel,
or in combined words such as DefaultControlKernel; so using
ControlKernel in this section is a bit confusing; please always use
the same word for the same thing.

"defined by the OMG group": make the link with CORBA clear.

To which component/object does the "updateKernelProperties()" method
belong?

"Properties are a way to represent configuration options in an
abstract [AND STRONGLY TYPED] way." BTW, what does "abstract" mean in
this context...?

"The property contains data or has a value": what's the difference
between data and values?

"a[N] composeProperty and decomposeProperty method". These do marshalling
and demarshalling, isn't it? So why not call them "marshalProperty"
and "demarshalProperty"? (Or is "marshalling" too much bound to one
particular context?)

"Chapter 4. Available Extensions": the word "available" lacks any real
meaning, doesn't it? Why not "supported extensions", or just leave out
the adjective completely?

"We use the LRL (Leuvens Robotics Library) Trajectory planning
software": I very much prefer not to see this name anymore, because it
(the name, that is) will be a tremendously annoying legacy in the very
near future...
Anyway this Chapter, and the Kinematics and interfaces chapters should
be moved to their own documentation files.

"The properties.cpf file lists the cpf file for each component type":
Are .cpf files something that Orocos has invented?
What would you call a user interface program that helps you do
configuration interactively, and not via a .cpf file? An extension?

"to configure all components, even those not loaded in the kernel":
How does _that_ work? Why is it needed/useful to configure something
that is not loaded?

"the design favoured determinism of execution time over determinism of
data acquisition." _The_ design? Which one are you referring to?
favoured -> favours?
I assume you mean that the real-time determinism of the feedback
control kernel is favoured over reporting?

"Another extension does not need to make the same choice however." I
beg you pardon?!?! The real-time determinism of the feedback
controller should _UNDER NO CONDITION_ be compromised, so certainly
not by an extension...

"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."
Aren't you using the protected Set/Get primitives yet in this context?
(BTW, how do you detect this "accident"?)

"The Decomposition constraint of the PropertyExtension also applies
here." Where is this constraint introduced/explained?

-- 
  K.U.Leuven, Mechanical Engineering, Robotics Research Group
<http://people.mech.kuleuven.ac.be/~bruyninc> Tel: +32 16 322480


>From Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be>  Thu Oct 23 14:12:01 2003
From: Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be> (Herman Bruyninckx)
Date: Thu Oct 23 13:12:01 2003
Subject: [Orocos-Dev] Documentation TODO
In-Reply-To: <200310171552.34858.peter.soetens@mech.kuleuven.ac.be>
Message-ID: <Pine.LNX.4.44.0310231310480.1940-100000@srv04.mech.kuleuven.ac.be>

This is some feedback on the orocos-core document.
                                                                                
Herman
==================================

Revision history: we should be able to put more useful comments than
just "lots of updates" :-)

The following paragraph could/should be emphasized:
"The goal of this fixed architecture is to keep applications
deterministic, by avoiding the classical pitfalls of letting
application programmers freely (and independently from each other)
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."
We could add that it's not at all _necessary_ to be able to give
direct OS priorities in a control system.

The terms "FOSI" and "FDI" should appear already in the introductory
section.

"Each OS _PORT_ implements in its os/<OS-name-here> directory..."
Do we have some documentation of what is needed to do a port; or is
this the only thing that has to be done? (Except for the "hot spots".)

"EventInterrupt class (to cover interrupt handlers)": for both
hardware and software events, I guess.

I think we need 1-2 sentences explaining the difference between
"kernel space" and "user space"; not all OSs do make such a separation
(VxWorks, QNX, ...).

We should also _strongly motivate_ the choice for C++ somewhere!

There is still some "StoneHead" mentioned in the document :-(

Is there some more information available (needed?) for the remark
"math.h	not all functions supported in RTLinux"?

" OSs implementing the POSIX Threads API correctly greatly eases our
efforts": what about our need for "completeness" of the API?

"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."
Can the normal user of Orocos recognize easily when he's using a
system calls? Or can we add some more information (link?) in this
paragraph?

" Designing portable software which should interact with hardware is
very hard." I think we should say that we cannot guarantee this
portability; hence the "hot spots" in the framework.

"...and port comedilib (which adds more functionality) to the realtime
kernels": what more functionality exactly do we need?

"we are writing a C++ device interface hierarchy": I guess our policy
in this respect is to follow Comedi at closely as possible, because
there is no need to do otherwise?
There is also an ongoing effort in this direction (but not using
Comedi) within the Player/Stage project! 

"Logical device interfaces represent the entities humans like to work
with: a drive, a sensor, an encoder, etc." They put _semantics_ on top
of the physical interfaces they use underneath.

I suggest to make the documentation of the Orocos Object Hierarchy a
separate document. Or at least, those objects that encode "robotics"
content; not the objects that are application-independent and hence
have nothing to do with robotics. And these latter are exactly the
ones that are in the current document. So, probably, we should add an
extra adjective to the "Orocos Object Hierarchy", designating the
application area (OS, devices, robot objects, ...). And the "Orocos
Robot Object Hierarchy" will also contain large sub-hierarchies that
deserve (eventually) their own documentation: Planning, Sensing,
Control, Modelling, Architectures, ...

"moduleXYZ.c file": what does the XYZ stand for?

"Be warned that when this function exits, all local data is destroyed,
that is why we use global variables."
This seems that variables that have once been created can never be
removed again? What about protection of these data?

"initialize(), step() and finalize()": is this API
sufficient/necessary for "hot plugging" of components?

I think it is useful to say a word about how the context is guaranteed
to be the same for all calls of these functions. 
(_Is_ the context indeed guaranteed to be the same?)

" ComponentThreaded...However, you are encouraged NOT to use it!"
So, please explain why we offer it, and why one shouldn't use it.

"The high priority thread is the ZeroTimeThread. It will execute all
TaskNonPreemptable Components synchronically."
These "TaskNonPreemptable Components" have not been described yet...

" For not realtime executions...  we use the CompletionProcessor."
This is quite confusing: the name "CompletionProcessor" seems to have
nothing to do with the subject of the threading section ... The link
with events is not clear at this moment.

Events: which guarantee about execution context can the programmer of
callbacks expect? I mean, what data can be shared between raiser,
listener and completer of an event? What should the programmer do when
he wants objects to be shared between them?

I would _much_ prefer to have a real robotics example, instead of the
cat.  Take an example that is already in the code.

"Synchronous event handling, synchronous completion. ... we're busy
thinking of some". Isn't the following an example of the
synchronous-synchronous policy: an estimator is analysing data during
a compliant motion, and as soon as it received enough data to decide
that a change in contact configuration has occured, its completor
takes action to change controllers,etc. I can imagine that the
application programmer wants this reaction to occur synchronously.
(The reaction _could_ be nothing more than raising events for the
other components to react to, but anyway...)

"You must choose the type of Event upon construction. This can no
longer be changed once the Event is created (for obvious reasons)."
Please do explicitize these obvious reasons :-)
Or motivate why on-line reconfiguration of the type of an event is not
necessary.

"Other kinds of Events": in fact, these are not "other kinds", but
the same kinds with a more specific policy?

"the Listener-Completer mapping is N to N": what does this mean
exactly?

"EventDivider": any example of the usefulness of this?

"States": doesn't this implement the "Strategy" pattern?
Can states be added/deleted on-line?
"StateContext": what is the motivation to choose the name "context"
here? Is it any different from the better known "state machine"?

" Please take a look at the Doxygen API documentation for a precise
description of all the function calls."
This comment is general, and is better moved to the introductory
paragraphs.

"having Properties in a realtime system is a very hard task": why?
(You answer this in the Note, but it's better not to put another
paragraph between the statement and the answer...)
(De)marshalling (and why one needs it in a distributed environment
only?) is explained only later in the section.
A short concrete example of how we use properties would be welcome.
What do the abbreviations INI and CPF in INIMarshaller and CPFMarshaller"
stand for?
"double dispatching" could need a word of explanation. For example,
"overloading" on the _arguments_ of a method call (in contrast to
overloading of the _name_ of the call).

"Reporting": does reporting use propertybags, or is it, in principle,
not dependent on them?

"FIFOs": used to get data between address spaces; I think we should
also talk about data transfer/synchronization within the same address
space. I.e., the protected Set/Get operations, and the concept of
synchronous/asynchronous access to data.

"We have four kindS of FIFOs"

"FifoRTIn" etc. I think the names "In" and "Out", and "RT" and "US"
will turn out to give problems at later ports, because they do not
represent properties that are invariant between OSs.
Chapter 2 is filled in by our applications by now :-)


>From Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be>  Thu Oct 23 14:12:02 2003
From: Herman Bruyninckx <herman.bruyninckx at mech.kuleuven.ac.be> (Herman Bruyninckx)
Date: Thu Oct 23 13:12:02 2003
Subject: [Orocos-Dev] Documentation TODO
In-Reply-To: <200310171552.34858.peter.soetens@mech.kuleuven.ac.be>
Message-ID: <Pine.LNX.4.44.0310231311150.1940-100000@srv04.mech.kuleuven.ac.be>

This is some feedback on the orocos-overview document.
                                                                                
Herman
==================================

Maybe it's better to separate the "overview" and the
"installation/configuration" and "Getting started" sections?

Where do we make clear the difference between the "Core" (= wrapper
API on hardware and OS) and the "(Control)Kernel" (= structure for
feedback control)? Maybe, for the sake of absolute clarity, this
distinction should be repeated in the documentation of the Core and
the ControlKernel?

The document talks about some Software Patterns; what about the
"Strategy Pattern"?

Update on "Project history" needed.

I suggest to leave the TODO section out, because it's easier to keep
this updated outside of the documentation files.

Objects and components section: 
- do we provide "monitors" at this moment? Should we?
- "the idl subdirectory": what is this?

Update on RTLinux support needed:
- only RTAI is _really_ supported
- RTAI and RTLinux have different APIs for "user space realtime"
- RTLinux has no user space realtime in its GPL branch?
- does the RTLinux memory manager issue still hold?


EPK package:
- is it _mandatory_ to use it?
- "It it taken" -> "It is taken"
- make "eCos" a clickable link in the document.
- "USERS OF other distributions might need to..."
- for the sake of clarity, place somewhere a very visible remark that
  building Orocos requires quite a lot of non-standard packages, and a
  lot of compilation. In addition, we have to motivate this _very_
  intensively:
  - final result is efficient and highly type-checked (using templates
    and the configuration tools, etc.)
  - user-friendliness for the configuration and building of _large
    scale_ control system. (Which Orocos is going to be.)
  - scalability and distributability require thorough discipline! (And
    hence the "overhead" we "impose" on the users of the Orocos
    software...)



[prev in list] [next in list] [prev in thread] [next in thread]