API discussion...

On the EURON meeting  (<http://www.euron.org>) this last weekend, I
got several perfect opportunities to talk to potential users of
Orocos. They made to-the-point comments about why they are NOT using
Orocos: its lack of clear APIs.

Let's try and do something about that :-) I hope at least somebody
will react this time... Anyway, the interactions during the EURON
meeting seemed to converge to the commitment that "we" will organize a
real-life meeting towards the beginning of the summer, to thoroughly
discuss these API matters. To be continued...

Now back to the concrete API discussion.
I've posted API suggestions to this mailinglist a couple of times
before, but got no reaction whatsoever. Maybe I overdid it, so I will
try to be more concise and focused this time. Orocos has (will have)
many different APIs, for various goals and at various levels of
complexity. Let's start with the simplest and most basic one:

Instantaneous motion API
------------------------
The goal of this API is to give instantaneous motion setpoints to the
robot. In other words, the robot is abstracted as a device that can
move the "end effector ("tool centre point", "base reference frame",
...) in a specified way. I see two complementary motion commands at
this level:

1. Move(): starts the motion of the robot (or does nothing if the
robot is already moving). The instantaneous motion is determined by
the Generator algorithm that runs in the controller. (More about this
later.) This motion command will be used a lot for motions that are
driven by on-board sensors; e.g., visual servoing. So, in order for
this Move() command to have effect, the Estimator and Sensor
components must have functionality that can generate sensor-based
setpoints. The arguments of Move() could be: a scalar that indicates a
speed, or time; it could also be a desired spatial velocity vector.
(What else?)


2. MoveTo(): this initiates a motion to a desired target position,
given as argument. (The other arguments are as in the Move() command.)

The Move and MoveTo commands are complemented with:

3. Stop(): go from motion to stop, in a given time (= argument).

4. EmergencyStop(): stop as fast as physically possible.

Do we need other basic motion commands?

PS The API above is to be used at the level where the robot is
   considered as a motion device for a reference frame. The API to
   transform this frame motion to motor motions (i.e., the kinematics and
   dynamics of the machine) are not relevant at this level.

Data, execution and configuration flows
=======================================
Let me now elaborate a bit more about the other components that
influence the precise "motion behaviour" of a Move() or MoveTo():

1. Generator: this component does the interpolation: it receives the
   Move(), MoveTo() command and determines _how_ to realise the motion.
2. Sensor, Estimator: they sense the world, and provide a mathematical
   description of (moving) geometric features in the world. So, the
   application can plug in functionality in these components to do, for
   example, obstacle avoidance, visual tracking, force-controlled or
   distance-controlled compliant motion, etc. It's the Generator's
   responsibility to take the outputs of Sensor or Estimator into
   account in its generation of the next instantaneous setpoint.
3. Controller: this component takes the setpoints of the Generator,
   and runs them through a control algorithm.

So, the _behaviour_ of a motion is _not_ specified as an argument to
the Move or MoveTo commands, but by configuration commands: these fill
in functionality in the Generator, Controller, Sensor, Estimator, ...
This is a design features, because we want to keep interfaces _small_:
In other words, Orocos has three families of interfaces:
1. Data flow: such as Move, MoveTo: they provide setpoints.
2. Execution flow: these commands can be used to change the behaviour
   of Components (and hence of the motion);for example, by signaling to
   the Generator that it should switch to another algorithm (on line);
   or to signal the Estimator to start tracking a particular object and
   provide the motion estimates to the Generator; etc.
3. Configuration flow: these commands change the plug-ins of the
   controller, so they can only be used in non-realtime mode.

What should be the API for the execution and configuration commands?
Is the change of the reference frame in which the motion commands are
to be interpreted a data flow command, or an execution flow, or is it
configuration? I tend to think it's configuration...

Let's think some more about all those open questions, and keep it for
another posting :-)

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