Draft of motion programming interface...

This text is a draft for the robot motion programming interface of
Orocos.

I invite you to try this out on the "use cases" that you (want to)
work with in your applications, and give feedback. Be aware that it is
still an _early_ draft, so be critical :-)

The goals of the motion specification interface are twofold:
- to offer a system that allows very advanced programming
  functionalities when needed.
- but also allows the rather simple programming interface of current
  commercial controllers.
- to be very structured and consistent, such that programmers always
  see a similar API in different parts of Orocos.

The targeted "Users" are the Application Builders and the End Users.
Basically, we describe the interface for the Application Builders; and
it is not discussed here what interface they want to offer to the End
User.  Anyway, advanced End Users could get the same interface as the
Application Builders. The major difference between both is that
Application Builder fills in most of the motion programming interface
with "defaults", such that their End Users need (can) only give a
limited amount of information in their task programming.

The programming interface for the Application Builder relies on the
fact that the robot controller is designed according to the Orocos
Software Pattern for control; i.e., it knows that the following
components exist, and that it has to plug-in their functionalities:
- Generator (generates motion setpoints),
- Scanner (collects sensor inputs),
- Observer (makes estimates),
- Actuator (puts the outputs on the motors),
- Reporter (collects data from all other components and returns
  them to the user), and
- Controller (reads in motion setpoints, sensor inputs and
  observer estimates, and sends out outputs).

Behind the screens of the controller, the infrastructure components
CommandInterpreter, ExecutionEngine and HeartBeat are also active, but
these are not directly programmed by the Application Programmer or the
End User. (This is the job of the Framework Builder and/or the
Component Builder.)

Programming a motion task consists of the following steps:
  1. Configuration of the plug-ins.
  2. Construction of the next motion command(s).
  3. Starting the motion.
These steps are described in some more details below.

1. Configuration
================
The configuration step is only meant for the Application Builder, or
the advanced End User. The API used for configuration is quite uniform
for all components. Or rather, "will be", because we have not decided
yet about an API. For a generic "Component" it could be something
like this:
- Component.setPlugin("pluginName", pluginObject).
- Component.setProperties("pluginName", parameters).
Each component can get more than one plug-in for one single motion.
For example, the Generator gets a first plug-in (called, for example,
"robotGen") that generates the setpoints for a robot, and a second
plug-in (called, for example, "toolGen") that generates the setpoints
for an actuated tool attached to the robot. Configuration commands for
both plug-ins are kept apart, thanks to the nameserving that is
available in the Orocos core.
If the motion generated by the two plug-ins above really have to be
synchronized, it could be better to have them generated by the same
plug-in function.

The different plug-ins are accessed by their registered names. For
example, the setpoints for the tool are generated by a call
"getSetpoints("toolGen", setpoints)".

During configuration, also the information for the user interfacing is
collected, and sent to the user at the moment the motion starts. All
this is the job of the configurator component, i.e., the
ExecutionEngine. The reason for this is that the user interface
should be a faithful representation of what is running in the
controller, so the data should be filled in by the same component that
decides on what is configured in the controller.

In this draft, we do not go into the details of how the
ExecutionEngine does the configuration. But in general it will be
impossible to do a full configuration in real-time, and in a way that
is guaranteed to be consistent. Therefore, a two-step procedure (with
corresponding two-phase commit) seems natural: first collect all
configuration commands, and configure a "shadow" controller (possibly
while the current controller is still working); only after the
configuration is complete, the shadow controller replaces the current
controller. The configuration is a low-priority job, the switching can
be done in real-time, because it basically not more than switching a
set of pointers.


2. Construction of the next motion
==================================
When the user sends a motion command to the control core, this
commands needs time to be parsed, interpreted and executed. Since a
full specification of a complex motion could require several commands,
and some motion commands must be executed back to back in a
controlled, smooth way, it is in general impossible to do this in
realtime. Therefore the construction of motion commands can be done in
two modes:
- "batch" : several commands are parsed and the corresponding motion
  objects are filled in, and only then the whole thing is started.
- "online": the new motion command is immediately given to the
  controller. With the risk of non-smooth execution.
Of course, it's the ExecutionEngine's task to decide when exactly the
prepared commands are executed.


3. Start the motion
===================
In the simplest case, only two motion commands are available after
configuration:

  move (motionObject)
  moveTo (motionObject, destinationObject)

Both commands provide the last data needed before a motion can start,
and they also start the motion.

The "motionObject" is the name of a motion whose configuration has
been done before (as default by the Application Builder, or explicitly
by the advanced End User), through commands that will be discussed later.
"motionObjects" can come in a large variety: the G-code of CNC machine
tools; the programming primitives of commercial robot controllers; a
force-controlled compliant motion specification; a visual tracking
specification; an "elastic strip" motion; etc. All these particular
motion types are encoded in objects that inherit from the parent class
"motionObject".

The "destinationObject" decribes a desired destination, which can be
much more than just a target frame: the end-effector frame of a robot
arm; the two hands and the head of a humanoid robot; a docking
position annex arm configuration for a mobile manipulator.
A "destinationObject" can also be more than position/orientation:
contains velocity, acceleration, ...
All these particular destination types are encoded in objects that
inherit from the parent class "destinationObject".

"move" starts the configured motion, which doesn't have a
pre-specified destination, but relies on on-line generation of
setpoints, based on sensor input (e.g., camera, or force sensor), or
interactive user input (e.g., joystick, mouse or keystrokes).

"moveTo" starts a point-to-point motion, towards the
"destinationObject". What the controller does with subsequent "moveTo"
commands depends on the Generator that has been configured: it can
decide to stop at each "destinationObject", or perform a particular
motion blending function.

Both types of motions offer some functionality in common:
- freeze the motion, or scale the motion speed (or any other scalable
  parameter in the motionObject).
- reporting interface, i.e., selection of what parameters of the
  motion must be reported to the user, at what frequency.
- motion events (interruption, synchronization signals, etc.).
- other things????


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