roby 0.7.3 → 0.8.0

data/doc/guide/src/basics/tasks.page

@@ -0,0 +1,357 @@
+---
+title: Tasks
+sort_info: 200
+--- pipeline:tags,markdown,blocks
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+Definition of Tasks
+-------------------
+
+Unlike with event objects, which are usually created and parametrized on-the-fly, tasks are mostly first _defined_ and then _used_. To define a task, one creates a subclass of Roby::Task. In our examples, we'll take "the mother of all tasks in robotic systems": the MoveTo task.
+
+{coderay:: ruby}
+ class MoveTo < Roby::Task
+     ...
+ end
+{coderay}
+
+Then, to use it, one would do:
+{coderay:: ruby}
+ plan.add(task = MoveTo.new)
+{coderay}
+
+As for events, the task must be included in a plan to be usable, which is done
+by calling plan.add(). Don't forget that !
+
+Parametrization
+---------------
+
+Obviously, a plain MoveTo task is nothing if the system does not know *where* to go to ... That is called parametrization and has to be declared in the task definition, using Task.argument
+{coderay:: ruby}
+ >> class MoveTo < Roby::Task
+ ?>    argument :x
+ ?>    argument :y
+ >> end
+{coderay}
+
+Then, the arguments are provided at instanciation through an argument hash:
+
+{coderay:: ruby}
+ >> task = MoveTo.new :x => 10, :y => 20
+ >> task.x
+ => 10
+ >> task.y
+ => 20
+{coderay}
+
+A task instance (i.e. the result of TaskClass.new) will *not* be usable unless
+you initialize all its arguments. Such a task is called _partially
+instanciated_:
+
+{coderay:: ruby}
+ >> task = MoveTo.new
+ >> task.partially_instanciated?
+ => true
+ >> task = MoveTo.new(:x => 10, :y => 10)
+ >> task.partially_instanciated?
+ => false
+{coderay}
+
+Of course, it is possible to set default arguments by defining a #initialize
+method (like with all Ruby classes)
+{coderay:: ruby}
+ >> class MoveTo
+ ?>   argument :max_speed
+ ?>   def initialize(arguments)
+ ?>     arguments[:max_speed] ||= 1
+ ?>     super(arguments)
+ ?>   end
+ ?> end
+ >> task = MoveTo.new(:x => 10, :y => 20)
+ >> task.max_speed
+ => 1
+ >> task.partially_instanciated?
+ => false
+{coderay}
+
+Task control and monitoring: defining events
+--------------------------------------------
+
+In Roby, tasks are a __collection of events__.  Now that  you know the basics
+about events, the purpose of those events should be clear:
+
+* the controllable events allow to change the process' behaviour (the obvious
+  one being "start" which allows to start the task)
+* both contingent and controllable events allow to monitor the task's execution.
+
+The basic task already defines four events:
+ * the *start* event
+ * the *stop* event
+ * the *success* event
+ * and finally the *failed* event
+
+In the class definition, events are defined using Task#event. To define a
+controllable event, simply associate a block. First, copy/paste the following code in a
+my\_task.rb file.
+
+{coderay:: ruby}
+ class MyTask < Roby::Task
+     event :start do
+        puts "start event called"
+        emit :start
+     end
+     event :controlable do
+        puts "controlable event called"
+        emit :controlable
+     end
+     event :contingent
+ 
+     on(:start) { puts "start event emitted" }
+     on(:controlable) { puts "controlable event emitted" }
+     on(:contingent) { puts "contingent event emitted" }
+     on(:failed) { puts "failed event emitted" }
+     on(:stop) { puts "stop event emitted" }
+
+     event :finished, :terminal => true
+     on(:finished) { puts "finished event emitted" }
+ end
+{coderay}
+
+Finally, an event can be *terminal*: its emission means the end of the task's
+execution. __failed__ and __success__ are examples of terminal events. To declare a
+terminal event, one does as for the "finished" event above.
+
+Now, read that code into the ruby shell with
+{coderay:: ruby}
+ >> source "my_task.rb"
+{coderay}
+
+Using task events
+-----------------
+The {rdoc_class: EventGenerator} class that defines the task event can be
+accessed with Task#event. Then, you can manipulate them as for normal events:
+{coderay:: ruby}
+ >> plan.add(task = MyTask.new)
+ >> ev = task.event(:start)
+ >> ev.call
+ start event called
+ start event emitted
+ >> task.running?
+ => true
+ >> ev = task.event(:contingent)
+ >> ev.controlable?
+ => false
+ >> ev.emit
+ contingent event emitted
+{coderay}
+
+Instead of calling #on, #signal, #emit and #call on the event object, one can use
+shortcuts that are defined on {rdoc_class: Task}:
+{coderay:: ruby}
+ # Same as task.event(:contingent).on { ... }
+ >> task.on(:contingent) { puts "contingent event emitted" } 
+ # Same as task.event(:contingent).emit
+ >> task.emit(:contingent)
+ # There's two handlers now, so we should have two lines displayed
+ contingent event emitted
+ contingent event emitted
+ # Same as task.event(:controlable).call
+ >> task.controlable!
+ controlable event called
+ controlable event emitted
+ # Same as task.event(:contingent).signals task.event(:controlable)
+ >> task.signals(:contingent, task, :controlable)
+ >> task.emit :contingent
+ contingent event emitted
+ contingent event emitted
+ controlable event called
+ controlable event emitted
+ >> task.emit :finished
+ finished event emitted
+ stop event emitted
+ >> task.running?
+ => false
+{coderay}
+
+Event classification: using the *forward* relation
+--------------------------------------------------
+As we in the above examples, it is possible to have terminal events, which are events
+that end the task. Obviously, the "stop" event should be emitted when they are
+emitted ("stop" represents the task end, does not it ?).
+
+In a more generic way, these terminal events are likely to be either special
+cases of the task success or of the task failure. Then, we actually need a way
+to *classify* events: to say "success is a special case of stop, or
+"wheel\_blocked is a special case of failed, which is a special case of
+stop".
+
+To represent this specific event relationship, Roby provides a *forward*
+relation between events, which can be added as follows:
+{coderay:: ruby}
+ >> class MyTask < Roby::Task
+ ?>     event :wheel_blocked
+ ?>     on(:wheel_blocked) { puts "wheel_blocked emitted" }
+ ?> end
+ >> plan.add(task = MyTask.new)
+ >> task.start!
+ start event called
+ start event emitted
+ >> blocked = task.event(:wheel_blocked)
+ >> failed = task.event(:failed)
+ >> blocked.forward_to failed
+ >> task.emit :wheel_blocked
+ wheel_blocked emitted
+ stop event emitted
+{coderay}
+
+In practice, a _forward_ relation between two events a and b says "b should be
+emitted when a is". Or "b is a superset of the situations that a represents".
+
+This relation is also available on "plain" events (i.e. EventGenerator.new). 
+
+Task model and event relations
+------------------------------
+Until now, we only saw how to add relations between events of task instances.
+Sometime (especially with forwarding relations), some relations should be
+defined on _all_ the task instances of a given task class. To do that, use the
+class methods <tt>signal</tt> and <tt>forward</tt> defined on {rdoc_class:
+Task}:
+
+{coderay:: ruby}
+ >> class MyTask < Roby::Task
+ ?>     signal :start => :controlable
+ ?>     forward :wheel_blocked => :failed
+ ?> end
+ >> plan.add(task = MyTask.new)
+ >> task.start!
+ start event called
+ start event emitted
+ controlable event called
+ controlable event emitted
+ >> task.emit :wheel_blocked
+ wheel_blocked emitted
+ failed event emitted
+ stop event emitted
+{coderay}
+
+Tasks that terminates
+---------------------
+A very important characteristic of tasks is their ability to be _interrupted_
+(or lack of). What is meant by that is that Roby should be able to stop some
+(actually, most) tasks. In Roby, that ability is represented by giving a command
+to the 'stop' event.
+
+For most of the tasks, there is actually no need to perform specific actions.
+Simply having Roby mark the task as 'stopped' is enough. For those tasks, using
+the 'terminates' statement is enough:
+
+{coderay:: ruby}
+ >> class MyTask
+ ?>   terminates
+ ?> end
+ >> plan.add(task = MyTask.new)
+ >> task.start!
+ start event called
+ start event emitted
+ controlable event called
+ controlable event emitted
+ >> task.stop!
+ failed event emitted
+ stop event emitted
+{coderay}
+
+As you can see, 'terminates' is equivalent to
+{coderay:: ruby}
+ >> class MyTask
+ ?>   event(:failed) { emit :failed }
+ ?>   event(:stop) { failed! }
+ ?> end
+{coderay}
+
+Common errors when manipulating tasks
+-------------------------------------
+
+As for the event, a common error is to forget to include the task in a plan
+before calling events on it:
+
+{coderay:: ruby}
+ >> task = MyTask.new
+ >> task.start!
+ Roby::EventNotExecutable: start! called on MyTask{}:0x7f336c455af0[] but the task is in no plan
+{coderay}
+
+Another related error is to emit/call events other than "start" while the task is not yet running ...
+
+{coderay:: ruby}
+ >> plan.add(task = MyTask.new)
+ >> task.controllable!
+ Roby::CommandFailed: controlable!() called by [] but the task has never been started
+    from (irb):30
+ >> task.emit :contingent
+ Roby::EmissionFailed: emit(contingent, []) called by [] but the task has never been started
+    from (irb):31
+{coderay}
+
+... or when it has stopped
+
+{coderay:: ruby}
+ >> task.start!
+ >> task.stop!
+ >> task.controlable!
+ Roby::CommandFailed: controlable!() called by [] but the task has finished. Task has been terminated by [MyTask{}:0x7ff179064358[]/failed@7 [344917:00:42.215]:
+        from (irb):32
+ >> task.emit :contingent
+ Roby::EmissionFailed: emit(contingent, []) called by [] but the task has finished. Task has been terminated by [MyTask{}:0x7ff179064358[]/failed@7 [344917:00:42.215]: ].
+        from (irb):33
+{coderay}
+
+<div markdown="1" class="info">
+In these messages, the notation
+
+    MyTask{}:0x7ff179064358[]
+
+represents a task, the notation
+
+    MyTask{}:0x7ff179064358[]/failed
+
+represents the event "failed" of the same task and finally
+
+    MyTask{}:0x7ff179064358[]/failed@7 [344917:00:42.215]
+
+is an emitted event that has been generated by the "failed" event of the given
+task. The time on the right is the time of emission, and the "@x" notation is
+the propagation cycle (usually, you don't care about this but it is VERY useful
+for debugging Roby itself).
+</div>
+
+Of course, as we saw at the beginning of this page, a task must be fully
+instanciated to be started:
+
+{coderay:: ruby}
+ >> class Bla < Roby::Task
+ >>    argument :foo
+ >> end
+ >> plan.add(task = Bla.new)
+ >> task.start!
+ Roby::EventNotExecutable: start! called on Bar{}:0x7ff17901c1e8[] which is partially instanciated
+ The following arguments were not set:
+        foo
+{coderay}
+
+Summary
+-------
+
+What do we do know ?
+
+* we know how the robot's situation is represented: through the *emission
+  of events*
+* we know how the robot is controlled: through the call of *controlable
+  events*
+* we know how to sort events in tasks, in order to represent the different
+  processes that run on the robot.
+
+One important question is still left open: how all of this can be made into a
+whole that allows to control a robot ? Right now, we only have an overview of
+the basics of Roby plan. What follows will show what a *Roby application* is
+made of.
+

data/doc/guide/src/basics_shell_header.txt

@@ -0,0 +1,16 @@
+Code examples
+-------------
+This page includes code samples that you can try out in Ruby or Unix shells. See
+[this page](code_examples.html) for explanations on the notation.
+{.warning}
+
+Moreover, to run the examples on this page, you must first set up your ruby
+shell:
+
+     $ irb
+{coderay:: ruby}
+ >> require 'roby/standalone'
+ >> include Roby
+ >> plan = Roby.plan
+{coderay}
+

data/doc/guide/src/cycle/cycle-overview.svg

@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.45.1"
+   sodipodi:docbase="/home/doudou/laas/documents/production/thesis/figures/supervision"
+   sodipodi:docname="cycle-overview.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow1Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lend"
+       style="overflow:visible;">
+      <path
+         id="path3265"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
+         transform="scale(0.8) rotate(180) translate(12.5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.49497475"
+     inkscape:cx="818.39952"
+     inkscape:cy="483.78467"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     inkscape:window-width="1016"
+     inkscape:window-height="710"
+     inkscape:window-x="0"
+     inkscape:window-y="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <g
+       id="g3241"
+       transform="translate(96.232983,-246.65343)">
+      <path
+         transform="matrix(0.516129,0,0,0.516129,82.148213,214.40589)"
+         d="M 324.25896 525.56763 A 78.286819 78.286819 0 1 1  167.68532,525.56763 A 78.286819 78.286819 0 1 1  324.25896 525.56763 z"
+         sodipodi:ry="78.286819"
+         sodipodi:rx="78.286819"
+         sodipodi:cy="525.56763"
+         sodipodi:cx="245.97214"
+         id="path3185"
+         style="opacity:1;color:#000000;fill:#ffffff;fill-opacity:0.63598328;fill-rule:evenodd;stroke:#000000;stroke-width:2.71250033;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+         sodipodi:type="arc" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3187"
+         y="482.02158"
+         x="209.04053"
+         style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           y="482.02158"
+           x="209.04053"
+           id="tspan3189"
+           sodipodi:role="line">1. Event</tspan><tspan
+           id="tspan3191"
+           y="494.52158"
+           x="209.04053"
+           sodipodi:role="line">Propagation</tspan></text>
+    </g>
+    <g
+       id="g3247"
+       transform="translate(90.900118,-242.41612)">
+      <path
+         transform="matrix(0.516129,0,0,0.516129,210.51882,259.86277)"
+         d="M 324.25896 525.56763 A 78.286819 78.286819 0 1 1  167.68532,525.56763 A 78.286819 78.286819 0 1 1  324.25896 525.56763 z"
+         sodipodi:ry="78.286819"
+         sodipodi:rx="78.286819"
+         sodipodi:cy="525.56763"
+         sodipodi:cx="245.97214"
+         id="path3193"
+         style="opacity:1;color:#000000;fill:#ffffff;fill-opacity:0.63598328;fill-rule:evenodd;stroke:#000000;stroke-width:2.71250033;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+         sodipodi:type="arc" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3195"
+         y="527.47845"
+         x="337.41113"
+         style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           id="tspan3199"
+           y="527.47845"
+           x="337.41113"
+           sodipodi:role="line">2. Error</tspan><tspan
+           id="tspan3203"
+           y="539.97845"
+           x="337.41113"
+           sodipodi:role="line">Handling</tspan></text>
+    </g>
+    <g
+       id="g3253"
+       transform="translate(97.432971,-240.67052)">
+      <path
+         transform="matrix(0.516129,0,0,0.516129,99.320817,339.66483)"
+         d="M 324.25896 525.56763 A 78.286819 78.286819 0 1 1  167.68532,525.56763 A 78.286819 78.286819 0 1 1  324.25896 525.56763 z"
+         sodipodi:ry="78.286819"
+         sodipodi:rx="78.286819"
+         sodipodi:cy="525.56763"
+         sodipodi:cx="245.97214"
+         id="path3205"
+         style="opacity:1;color:#000000;fill:#ffffff;fill-opacity:0.63598328;fill-rule:evenodd;stroke:#000000;stroke-width:2.71250033;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+         sodipodi:type="arc" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text3207"
+         y="607.28052"
+         x="226.21313"
+         style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+         xml:space="preserve"><tspan
+           id="tspan3211"
+           y="607.28052"
+           x="226.21313"
+           sodipodi:role="line">3. Garbage</tspan><tspan
+           id="tspan3215"
+           y="619.78052"
+           x="226.21313"
+           sodipodi:role="line">Collection</tspan></text>
+    </g>
+    <path
+       style="opacity:1;color:#000000;fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:url(#Arrow1Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       d="M 341.12139,257.78591 L 387.27981,274.13091"
+       id="path3235"
+       inkscape:connector-type="polyline" />
+    <path
+       style="opacity:1;color:#000000;fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:url(#Arrow1Lend);stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       d="M 396.23341,313.66319 L 353.30654,347.3016"
+       id="path3237"
+       inkscape:connector-type="polyline" />
+    <path
+       style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-mid:none;marker-end:url(#Arrow1Lend);stroke-opacity:1"
+       d="M 311.55238,327.38282 L 305.65081,284.33607"
+       id="path3239"
+       inkscape:connector-type="polyline" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2185"
+       style="text-align:justify;text-anchor:start"
+       transform="translate(9.0913726,-136.3706)"><flowRegion
+         id="flowRegion2187"><rect
+           id="rect2189"
+           width="183.84776"
+           height="61.619305"
+           x="56.568542"
+           y="346.26556"
+           style="text-align:justify;text-anchor:start" /></flowRegion><flowPara
+         id="flowPara2195">determine what events should be emitted and/or called, and propagate the events in the event relation graphs.</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2201"
+       transform="translate(38.056586,-153.1509)"
+       style="text-align:end;text-anchor:end"><flowRegion
+         id="flowRegion2203"><rect
+           id="rect2205"
+           width="192.20023"
+           height="60.052284"
+           x="389.91888"
+           y="363.43814"
+           style="text-align:end;text-anchor:end" /></flowRegion><flowPara
+         id="flowPara2209">detect errors as violation of the constraints defined by the relation graphs, and try to recover from them.</flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2213"
+       style="text-align:justify;text-anchor:start"
+       transform="translate(-114.08627,-193.1509)"><flowRegion
+         id="flowRegion2215"><rect
+           id="rect2217"
+           width="272.14285"
+           height="47.142876"
+           x="318.57144"
+           y="606.64789"
+           style="text-align:justify;text-anchor:start" /></flowRegion><flowPara
+         id="flowPara2223">kill and remove the tasks that are either not useful for the completion of the robot goals, or for which errors have not been recovered.</flowPara></flowRoot>  </g>
+</svg>