motion-api.sgml

机器人开源项目orocos的源代码

<para>
A <parameter>Path</parameter> is an ordered list of 
<link linkend="via-point">via-points</link>, which (optionally) also
contains extra information:
<itemizedlist>

<listitem>
<para>
<emphasis role="strong">Blending policy</emphasis>: the path
can contain advice to the 
<ulink url="interpolation-api.html">interpolator</ulink> about how the
via-points should be approached: the motion can go through the via-point
<emphasis>exactly</emphasis> (<emphasis>i.e.</emphasis> guaranteeing the
timing or contact information at the via-points), or to take this
information only as a guideline from which can be deviated, in order to
&ldquo;smooth&rdquo; the path.
</para>
</listitem>

<listitem>
<para>
<emphasis role="strong">Events</emphasis>: in addition to the events
of each <parameter>ViaPoint</parameter> in a
<parameter>Path</parameter>, the <parameter>Path</parameter> itself
can have its own events.
</para>
</listitem>

</itemizedlist>
</para>

</section>

<section id="synchronized-path">
<title><parameter>SynchronizedPath</parameter></title>
<para>
A <parameter>SynchronizedPath</parameter> is an ordered list of 
<link linkend="path"><parameter>Path</parameter>s</link>.
The goal is to be able to specify a synchronized motion for more than one
end-effector on the device. For example, the two hands and the head of a
humanoid robot are required to move synchronously with the object that the
robot is carrying.
</para>
<para>
Extra information connected to a
<parameter>SynchronizedPath</parameter> is:
<itemizedlist>

<listitem>
<para>
<emphasis role="strong">Synchronization policy</emphasis>: 
a specification of how the motion through the
<parameter>ViaPoints</parameter> in the various
<parameter>Path</parameter>s must be synchronized.
</para>
</listitem>

<listitem>
<para>
<emphasis role="strong">Events</emphasis>, for example to signal a
violation of the synchronization requirements.
</para>
</listitem>

</itemizedlist>
</para>

</section>


<section id="motion-task">
<title><parameter>MotionTask</parameter></title>
<para>
A <parameter>MotionTask</parameter> is an ordered list of 
<link linkend="path"><parameter>Path</parameter>s</link>
and/or
<link linkend="synchronized-path"><parameter>SynchronizedPath</parameter>s</link>.
It contains the information for a whole sequence of motions of a
device.
</para>
<para>
Extra information connected to a
<parameter>MotionPath</parameter> is:
<itemizedlist>

<listitem>
<para>
<emphasis role="strong">Blending policy</emphasis>, that is, advice to the
interpolator about how to connect two motion segments together.
</para>
</listitem>

<listitem>
<para>
<emphasis role="strong">Events</emphasis>, for example to signal the
transition between paths in the task.
</para>
</listitem>

</itemizedlist>
</para>

</section>


</section>


<section id="motion-api">
<title>Motion API</title>

<para>
This Section explains the motion API designed for &orocos;.
The general trade-offs in an API design are explained in 
<ulink url="deep-shallow-api.html">this document</ulink>; in summary: (i)
it is worthwhile to separate the API of the data flow, the execution flow,
and the configuration flow, and (ii) APIs differ between
<emphasis>classes</emphasis> and <emphasis>components</emphasis>.
</para>


<section id="motion-api-data-flow">
<title>Data flow</title>
<para>
The data flow for motion consists of just one method call, with overloading
of the arguments for the different types of motion specifications:
<link linkend="via-point"><parameter>ViaPoint</parameter></link>,
<link linkend="path"><parameter>Path</parameter></link>, 
<link linkend="synchronized-path"><parameter>SynchronisedPath</parameter></link>
or 
<link linkend="motion-task"><parameter>MotionTask</parameter></link>. 
<variablelist>

 <varlistentry>
 <term>
  <anchor id="move-to">
  <parameter>Move</parameter>: 
 </term>
  <listitem>
   <para>
Start a motion according to the given motion specification, via-point, path,
synchronised path or motion task.
   </para>
   <para>
This method assumes the selected motion specification in its argument
is syntactically and semantically appropriate. Indeed, there is no time for
checking, since <parameter>Move</parameter> should also be usable in
realtime. 
   </para>
  </listitem>
 </varlistentry>

</variablelist>
</para>

</section>


<section id="motion-api-execution-flow">
<title>Execution flow</title>
<para>
The execution flow of a motion contains the methods that influence the
ongoing motion immediately, without reconfiguration of the components
involved in the motion. The logic state machine that implements the
execution flow is responsible that these execution flow commands are only
used in the appropriate moment and context; this check cannot be done
<emphasis>inside</emphasis> of the execution flow methods, because they
lack the context information.
</para>
<para>
Here is a list of possible execution flow methods:
<variablelist>

 <varlistentry>
 <term>
  <anchor id="freeze-motion">
  <parameter>FreezeMotion</parameter>: 
 </term>
  <listitem>
   <para>
Pause the ongoing motion, in a safe and controlled way (this
means using an <emphasis>interpolator</emphasis> for &ldquo;braking&rdquo;
the motion), and with the possibility to restart again.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="stop-motion">
  <parameter>StopMotion</parameter>: 
 </term>
  <listitem>
   <para>
Stop the ongoing motion, in a safe and controlled way (this
means using an <emphasis>interpolator</emphasis> for &ldquo;braking&rdquo;
the motion), without the need to restart again.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="abort-motion">
  <parameter>AbortMotion</parameter>: 
 </term>
  <listitem>
   <para>
Stop the ongoing motion, as quickly as possible. This is
only to be done in real emergencies, as it doesn't involve an
<emphasis>interpolator</emphasis> to smooth the braking motion.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="scale-motion-speed">
  <parameter>SetMotionSpeed</parameter>: 
 </term>
  <listitem>
   <para>
Set the desired speed for the (ongoing) motion. The argument can be a
<emphasis>percentage</emphasis> of a nominally configured speed.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="select-tcp">
  <parameter>SelectTCP</parameter>: 
 </term>
  <listitem>
   <para>
Define which Tool Centre Point on the device is to be used as the reference
for the motion specifications.
   </para>
   <para>
For devices with multiple TCPs, the argument of this method is a
<emphasis>list</emphasis> of TCPs.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="select-interpolator">
  <parameter>SelectInterpolator</parameter>: 
 </term>
  <listitem>
   <para>
Define which 
<ulink url="interpolation-api.html">motion interpolation</ulink>
algorithm to use to transform motion specifications into setpoints for the
device's motors.
   </para>
  </listitem>
 </varlistentry>

</variablelist>
</para>

</section>


<section id="motion-api-configuration-flow">
<title>Configuration flow</title>
<para>
The configuration flow of motion consists of: (i) the non-realtime classes
that prepare motion objects to be used in data and execution flow (in other
words, the <emphasis role="strong">class factory</emphasis> methods), and
(ii) the configuration of a
<link linkend="motion-application">motion application</link>.
</para>

<section id="motion-class-factory">
<title>Class factory</title>
<para>
In the first place, these are the <emphasis>constructors</emphasis> and
<emphasis>destructors</emphasis> of a
<link linkend="via-point"><parameter>ViaPoint</parameter></link>,
a <link linkend="path"><parameter>Path</parameter></link>, 
a <link linkend="synchronized-path"><parameter>SynchronisedPath</parameter></link>
or 
a <link linkend="motion-task"><parameter>MotionTask</parameter></link>. 
Secondly, one can construct composite motion primitives from more
elementary ones. This is done via <parameter>Add</parameter> methods; for
example:
<variablelist>

 <varlistentry>
 <term>
  <anchor id="add-via-point">
  <parameter>Path.Add(ViaPoint)</parameter>: 
 </term>
  <listitem>
   <para>
Adds the <parameter>ViaPoint</parameter> to the end of the
<parameter>Path</parameter>.
   </para>
  </listitem>
 </varlistentry>

</variablelist>
Similar operations exist for <emphasis role="strong">removing</emphasis>
motion primitives; <emphasis>e.g.</emphasis>
<parameter>Path.Remove(ViaPoint);</parameter>.
And <emphasis>iterators</emphasis> are useful for
<emphasis role="strong">traversing</emphasis> a list of
composite motion primitives (<parameter>Path</parameter>,
<parameter>SynchronisedPath</parameter> and
<parameter>MotionTask</parameter>),
<emphasis>e.g.</emphasis> <parameter>MotionTask.GetNext(Path);</parameter>. 
</para>

</section>


<section id="motion-application">
<title>Motion application</title>
<para>
A generic motion application is a component that has a much larger
interface than just the above-mentioned data flow or execution flow
specification, and the class factory configuration. Indeed, the
<emphasis>executed</emphasis> motion also depends on the actual contents of
the Generator and the Controller components in the 
<ulink url="orocos-control-kernel.html">Control Kernel</ulink> that
implements the application. Hence, the configuration for a motion
application also provide methods for configuring Generator and Controller:
<variablelist>

 <varlistentry>
 <term>
  <anchor id="configure-interpolator">
  <parameter>ConfigureInterpolator</parameter>:
 </term>
  <listitem>
   <para>
this method takes care of
the non-realtime configuration of the Generator component (which contains
an <ulink url="interpolation-api.html">interpolator</ulink> in this case).
This configuration can consist of many things: setting property parameters,
loading code, etc.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
 <term>
  <anchor id="configure-controller">
  <parameter>ConfigureController</parameter>:
 </term>
  <listitem>
   <para>
this method takes care of the non-realtime configuration of the Controller
component: setting property parameters, loading code, etc.
   </para>
  </listitem>
 </varlistentry>

</variablelist>
</para>
<para>
In addition, a motion application can service multiple clients and
encompass multiple devices. So, configuration of devices and client
connections also belong to the interface.
Basically, this is a minimal API of the application:
<anchor id="motion-command-simple">
<programlisting>
 Device.Tool.Move(Path);
</programlisting>
The method call prototype above shows the different
&ldquo;sources of information&rdquo; needed to execute a motion:
<itemizedlist>

<listitem>
<para>
The <parameter>Device</parameter> provides the information about: the
dimension of the space in which the device moves; the kinematics chain
with which to execute the motion; the possible cost functions for
redundancy or constraint; etc.
</para>
</listitem>

<listitem>
<para>
The <parameter>Tool</parameter> provides the information about the
spatial object or reference frame for which the motion is specified.
</para>
</listitem>

<listitem>
<para>
<parameter>Path</parameter> (as well as the 
<link linkend="motion-classes">other motion primitives</link>): the
geometry, timing and events of the motion; the mathematical representation
of position, velocity, acceleration, etc.; how sensor-based input is to be
used in the motion generation; what kinematic optimizations are possible;
what controller-dependent optimizations are possible; etc.
</para>
</listitem>

</itemizedlist>
The API may be shortened to:
<programlisting>
 Tool.Move(Path);
</programlisting>
or
<programlisting>
 Device.Move(Path);
</programlisting>
<anchor id="motion-command-simple-short">
because the <parameter>Device</parameter> object is implicit in the
<parameter>Tool</parameter>, and vice versa if the
<parameter>Device</parameter> has only one single
<parameter>Tool</parameter>.
</para>
<para>
The motion API above satisfies the requirement for a
<emphasis>small</emphasis> API, but not that of a
<emphasis>complete</emphasis> API, or of a
<emphasis>decoupled</emphasis> API: in the method calls above, the
<parameter>Motion</parameter> object
contains the information about all the factors than can influence a
particular motion, so, a finer &ldquo;granularity&rdquo; in the
argument list could result in something like this:
<programlisting>
 Device.Move(Tools, Paths, KinematicChains, Sensors, Controllers);
</programlisting>
<anchor id="motion-command-extended">
Note the use of the <emphasis>plural</emphasis> in all arguments: 
complex devices can consist of several sub-devices, tools, etc., and
it should be possible to specify a coordinated motion for all of them
together.
</para>

</section>

</section>

</section>


</article>