roby 0.7.3 → 0.8.0

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

@@ -0,0 +1,33 @@
+---
+title: Code Examples
+sort_info: 10
+--- pipeline:tags,markdown
+Notations
+---------
+In the following pages, the example code is meant to be run either in a Ruby
+shell or in a normal Unix shell. The following notations are used for these code
+samples:
+
+* "$" represents the prompt of the Unix shell. Code that is after it is
+  therefore supposed to be written by you.
+* ">>" represents the Ruby shell prompt. Code that is after ">>" is therefore
+  supposed to be written by you
+* '#' is a comment marker we use to display some information about the example
+  code
+* '=>' is the result of the previously entered command. It is omitted in the
+  examples if that information is not useful for the purpose of the example
+  itself.
+* lines that start with nothing are lines that are displayed by the Ruby code
+
+Setting up the Ruby shell
+-------------------------
+Moreover, before typing in the Roby shell, you will need to prepare it a bit. Do
+the following:
+
+     $ irb
+{coderay:: ruby}
+ >> require 'roby/standalone'
+ >> include Roby
+ >> plan = Roby.plan
+{coderay}
+

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

@@ -0,0 +1,69 @@
+---
+title: Don't repeat yourself !
+sort_info: 800
+--- pipeline:tags,markdown,blocks
+
+Unlike most (all ?) other supervision system, Roby is *not* a domain-specific
+language (DSL). Instead, it uses the facilities offered by the Ruby programming
+language to _look like_ a DSL.
+
+The main consequence, and the reason why this design decision has been made, is
+that in part of the Roby applications one can use programmatic ways to avoid
+**repeating oneself**.
+
+Let's take one simple example: in [the tasks page](tasks.html), we defined the
+MyTask task model that way:
+
+{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}
+
+Full of repetitions ... Now, one could have written, instead:
+
+{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 :finished, :terminal => true
+
+  each_event do |ev|
+    on(ev.symbol) { puts "#{ev.symbol} event emitted" }
+  end
+end
+{coderay}
+
+This way:
+* if we want to display more information, changing one line does the trick
+* if a new event is added, it gets displayed automatically
+
+
+
+**Don't forget !**: every piece of text you write in a Roby application is Ruby
+code, so you have the means to avoid ugly repetitions.
+{.warning}
+

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

@@ -0,0 +1,443 @@
+---
+title: Error handling
+sort_info: 700
+--- pipeline:tags,markdown,blocks
+
+One thing about robotics, and in particular plan execution, is that Murphy's
+rule applies quite well. This is due to a few things. Among them, the first is
+that the models planning uses (and therefore the plans it builds) are (i) too
+simple to completely reflect the reality, (ii) badly parametrized and (iii)
+represent dynamic agents, which can themselves be able to take decisions. So, in
+essence, the rule of thumb is that a plan will fail during its execution.
+
+Because Roby represents and executes all the activities of a given system, the
+representation of errors becomes a very powerful thing: it is quite easy, when
+an error appears somewhere to actually determine what are its consequences.
+
+What this tutorial will show is:
+* how parts of the error conditions are encoded in the task structure.
+* how exceptions that come from the code itself (like NoMethodError ...) are
+  handled.
+
+Failed dependencies
+-------------------
+The hierarchy relation, because it defines a dependency, also obviously defines
+the situations where that dependency has failed. To describe this, the relation
+options allow to define a set of _desirable_ and a set of _forbidden_ events.
+The first category defines what the parent needs (task A desires the success
+event of task B to be emitted). The second category defines what the parent is
+incompatible with (task A will fail if task's B failed event is emitted).
+Obviously, there is a problem if:
+* none of the desirable events can be emitted ever
+* one of the forbidden events is emitted
+
+In both cases, a specific {rdoc_class: ChildFailedError} is produced. This error
+describes what happened ("the dependency relation between tasks A and B failed
+because the event 'failed' was emitted) and who is the culprit (in the
+ChildFailedError, the child).
+
+Let's see an example of such an error. We'll cheat a bit and make our
+ComputePath task fail. Edit tasks/compute\_path.rb and add an error at the beginning of the implementation block. Make it so that it looks like the following:
+
+{coderay:: ruby}
+implementation do
+  raise "implementation failed !"
+  path      = [start_point]
+{coderay}
+
+Now, start the controller in one console and the roby shell in another and:
+
+    localhost:48902 > planned_move! :x => 10, :y => 20
+    !Roby::ChildFailedError
+    !at [345013:53:51.812/109] in the failed event of ComputePath:0x7f6ff6a8f0a8
+    !implementation failed ! (RuntimeError)
+    !  ./tasks/compute_path.rb:19,
+    !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in `value',
+    !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in the polling handler,
+    !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require',
+    !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `require',
+    !    scripts/run:3
+    !
+    !The failed relation is
+    !  MoveTo:0x7f6ff6a8f198
+    !    owners: Roby::Distributed
+    !    arguments: {:goal=>Vector3D(x=10.000000,y=20.000000,z=0.000000)}
+    !  depends_on ComputePath:0x7f6ff6a8f0a8
+    !    owners: Roby::Distributed
+    !    arguments: {:path_task=>
+    !      MoveTo:0x7f6ff6a8f198
+    !        owners: Roby::Distributed
+    !        arguments: {:goal=>Vector3D(x=10.000000,y=20.000000,z=0.000000)},
+    !     :goal=>Vector3D(x=10.000000,y=20.000000,z=0.000000)}
+    !
+    !The following tasks have been killed:
+    !  ComputePath:0x7f6ff6a8f0a8
+    !  MoveTo:0x7f6ff6a8f198
+    !
+    !task MoveTo{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}:0x7f6ff6a8f198[] failed
+
+What information is there ?
+* we do have a ChildFailedError
+* the source is the emission at 345013:53:51.812/109 of the 'failed' event of
+  ComputePath. Roby::ThreadTask will automatically emit _failed_ if the
+  implementation block raises an exception (what we did). In that case, the
+  context of _failed_ is the exception object itself.
+* because the exception object is available, it is displayed, including
+  its backtrace.
+
+        !implementation failed ! (RuntimeError)
+        !  ./tasks/compute_path.rb:19,
+        !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in `value',
+        !    /home/joyeux/dev/roby/lib/roby/thread_task.rb:63:in the polling handler,
+        !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require',
+        !    /usr/lib/ruby/1.8/rubygems/custom_require.rb:31:in `require',
+        !    scripts/run:3
+
+* the two tasks involved in the failed relation are displayed as well. MoveTo is the parent, ComputePath is the child.
+* finally, because nothing was done to repair the error, both the failed task
+  _and its parents_ are **killed and removed from the plan**. This is because
+  the parent tasks may not behave correctly given that one of their dependencies
+  is not behaving properly. So, as a safety measure, we kill them. This is done by
+  the garbage collection mechanism we presented along with the plan display.    
+* the last line, announcing that the MoveTo task failed is not part of the
+  exception message, but of the interactive shell that tells us that one of our
+  missions has failed.
+
+Coding mistakes
+---------------
+Roby tries very hard to separate the _framework_ code from the _user_
+code, so that coding mistakes in user code can be dealt with in a safe manner.
+
+The _user code_ is the part of the code which is tied to events and tasks:
+event commands, event handlers, polling blocks. For those, it is actually
+possible to generate a plan error, as for instance for the child failed error,
+and to handle the error at the plan level.
+
+The _framework code_ is the more problematic part: if an error appears here, it
+means that there is really a bug in the execution engine itself (and therefore
+that we can't rely on it). In that case, Roby tries to hang up as cleanly as
+possible by killing all tasks that are being executed.
+
+Let's try one code error. Add the following event handler in the definition of
+MoveTo in tasks/move\_to.rb
+
+{coderay:: ruby}
+on :start do
+  raise "the start handler failed !"
+end
+{coderay}
+
+Start (or restart) the controller and launch a planned\_move! action in
+the shell. The following should happen:
+
+    !Roby::EventHandlerError: user code raised an exception at [336641:28:04.607/23] in the start event of MoveTo:0x2b4330b4fae8
+    !
+    !
+    !the start handler failed ! (RuntimeError)
+    !./tasks/move_to.rb:10:in event handler for 'start',
+    !  /home/joyeux/system/rubygems/lib/rubygems/custom_require.rb:27:in `gem_original_require',
+    !  /home/joyeux/system/rubygems/lib/rubygems/custom_require.rb:27:in `require',
+    !  scripts/run:3
+    !
+    !The following tasks have been killed:
+    !  MoveTo:0x2b4330b4fae8
+
+Now, what happens during execution: how Roby does react to that error ? What we
+can see in the relation display is the following three successive steps. **Don't
+forget to uncheck _View/Hide finalized_**.
+
+![](log_replay/hierarchy_error_1.png)
+{.fullfigure}
+
+**Starting point**: the MoveTo is started and so is the ComputePath task, as it
+is an event handler that fails (i.e. the error appears _after_ the event is
+emitted).
+{.figurecaption}
+
+![](log_replay/hierarchy_error_2.png)
+{.fullfigure}
+
+**Next cycle**: MoveTo is killed because of the error in the previous cycle.
+ComputePath took only one cycle to complete, so ExecutePath is started as well.
+{.figurecaption}
+
+![](log_replay/hierarchy_error_3.png)
+{.fullfigure}
+
+**Killing useless tasks**: the now useless ExecutePath is killed as well.
+{.figurecaption}
+
+From Roby's point of view, the event has already happened when the event
+handlers get called. Therefore, the event propagation should go on even though
+one of the event handlers failed, and therefore ComputePath is started.
+
+However, since an error occured and has not been handled, the MoveTo task cannot
+keep running and is stopped at the next cycle. The tasks that are now useless
+are also stopped (in this particular execution, ComputePath took only one cycle
+to execute and therefore only ExecutePath is stopped).
+
+For event commands, all depends on where the exception actually appears. If
+'emit' has already been called, then the event will be emitted and propagated.
+Otherwise, it counts as a cancelling of the event command -- which is an error
+itself.
+
+Handling errors
+---------------
+This is more an advanced subject, but we'll give you an overview of the means
+for error handling that Roby offers anyway. The basic principles are as follows:
+* the plan structure should be sane. We saw what it means in the case of the
+  hierarchy relation, but other relations also define what is a "nominal" plan
+  structure. An error is raised if the current plan does not match that nominal
+  structure.
+* tasks for which coding errors have been detected must be terminated.
+* anything that depends on a failed task must be terminated.
+
+During the application's execution, the event propagation, error detection and
+garbage detection are three distinct steps:
+
+![](roby_cycle_overview.png)
+
+So, if a broken plan structure is repaired in the event propagation stage, then
+no errors will ever be emitted. Indeed, the error detection and handling stage
+will not see the problem. **Repairing errors in event handlers** is a first mean of
+error handling.
+
+The error handling stage is actually split into two sub-stages:
+
+* first, specific code blocks are called for each error found in the plan (these
+  code blocks are called _exception handlers_)
+* then, the structure is checked again and the errors that remain lead to
+  garbage collection.
+
+**Exception handlers** are the second mean of error handling.
+
+Finally, sometime, recovering from an error requires complex actions (or
+decision-making) that do not fit in one execution cycle. For those situations,
+Roby allows to mark some tasks as being _plan repairs_: these tasks' job is to
+repair specific errors. **Plan repairs** are the third mean of error handling.
+
+Repairing during events propagation
+-----------------------------------
+
+If a child fails, for instance because of a spurious problem, it would have been
+possible to actually restart the failing child directly in the event handler of
+_failed_ and replace the failed task through this new one. This is as simple as:
+
+{coderay:: ruby}
+on(:failed) do
+    plan.respawn(self)
+end
+{coderay}
+
+Let's try it. Add the following to the definition of ExecutePath to simulate an
+error:
+
+{coderay:: ruby}
+attr_accessor :should_pass
+event :start do
+  if !should_pass
+    forward :start, self, :failed, :delay => 0.2
+  end
+  emit :start
+end
+
+on :failed do
+  if !should_pass
+    Robot.info "respawning ..."
+    new_task = plan.respawn(self)
+    new_task.should_pass = true
+  end
+end
+{coderay}
+
+In the first pass, #should\_pass is false and therefore the _delayed forwarding
+relation_ is set up between start and failed. It means that _failed_ will be
+emitted 0.2 seconds after _start_ (thus simulating a failing task).
+
+In the _failed_ handler, a new ExecutePath task is re-created with the same
+arguments using Plan#respawn. On this task, #should\_pass is set to true so that
+the execution continues normally.
+
+Note that doing such a thing on the failed event is a bad idea, as failed is
+emitted when the task gets interrupted. You would, in general, do that on a more
+specific error event (i.e. an event that is forwarded to _failed_).
+
+TODO: figure.
+
+Asynchronous repairs
+--------------------
+
+In Roby's plans, asynchronous repairs are represented as _plan repairs_. Plan
+repairs are tasks which are associated with a task's event. When the task's
+event is the source of a failure, the task is activated and should repair that
+particular error.
+
+To define plan repairs, a ErrorHandling relation exists. This relation defines
+the set of possible plan repairs for a given task and event. To define a
+specific repair, one uses something like:
+
+{coderay:: ruby}
+task.event(error_event_name).handle_with(my_repair_task)
+{coderay}
+
+Let's try it in our application. What we will do is the following:
+* add a _blocked_ fault event to the model of ExecutePath, and make the poll
+  block of ExecutePath emit _blocked_ randomly.
+* have a repair task wait 2 seconds and either (randomly) respawn the path
+  execution after those two seconds, or emit _failed_.
+
+The first point is straightforward: just change tasks/execute\_path.rb so that
+the bottom of it looks like the following code. Changed lines are 4, 5, 10 and
+11.
+
+{coderay:: {lang: ruby, line_numbers: true}}
+    if @waypoint_index == path_task.path.size
+      emit :success
+    elsif rand < 0.05
+        emit :blocked
+    end
+    Robot.info "moved to #{current_waypoint}"
+  end
+
+  event :blocked
+  forward :blocked => :failed
+end
+{coderay}
+
+A new RepairTask model has to be added. Open tasks/repair\_task.rb and add the
+following:
+
+{coderay:: ruby}
+class RepairTask < Roby::Task
+  terminates
+
+  event :start do
+    Robot.info "repair will succeed in 2 seconds"
+    forward_to :start, self, :success, :delay => 2
+    emit :start
+  end
+
+  on :success do
+    current   = failed_task.current_waypoint
+    execute   = plan.respawn(failed_task)
+    repair    = plan.recreate(self)
+
+    # Get the path object, and remove from the points that have already been
+    # done
+    path = execute.path_task.path
+    while !path.empty? && path[0] != current
+        path.shift
+    end
+  end
+end
+{coderay}
+
+Finally, the repair handler must be defined added to the plan. Edit the
+planned\_move method in <tt>planners/goForward/main.rb</tt> and add the
+following line to it:
+
+{coderay:: ruby}
+execute.event(:blocked).handle_with(RepairTask.new)
+{coderay}
+
+Let's run it as usual and see what happens ... In the Roby shell, do
+
+    >> planned_move! :x => 10, :y => 20
+
+Then, take a look at the application output
+
+    24 points between Vector3D(x=0.000000,y=0.000000,z=0.000000) and Vector3D(x=10.000000,y=20.000000,z=0.000000)
+    moved to Vector3D(x=0.447214,y=0.894427,z=0.000000)
+    moved to Vector3D(x=0.894427,y=1.788854,z=0.000000)
+    repair will succeed in 2 seconds
+    moved to Vector3D(x=1.341641,y=2.683282,z=0.000000)
+    moved to Vector3D(x=1.788854,y=3.577709,z=0.000000)
+    moved to Vector3D(x=2.236068,y=4.472136,z=0.000000)
+    moved to Vector3D(x=2.683282,y=5.366563,z=0.000000)
+    moved to Vector3D(x=3.130495,y=6.260990,z=0.000000)
+    moved to Vector3D(x=3.577709,y=7.155418,z=0.000000)
+    moved to Vector3D(x=4.024922,y=8.049845,z=0.000000)
+    moved to Vector3D(x=4.472136,y=8.944272,z=0.000000)
+    moved to Vector3D(x=4.919350,y=9.838699,z=0.000000)
+    moved to Vector3D(x=5.366563,y=10.733126,z=0.000000)
+    moved to Vector3D(x=5.813777,y=11.627553,z=0.000000)
+    moved to Vector3D(x=6.260990,y=12.521981,z=0.000000)
+    moved to Vector3D(x=6.708204,y=13.416408,z=0.000000)
+    moved to Vector3D(x=7.155418,y=14.310835,z=0.000000)
+    moved to Vector3D(x=7.602631,y=15.205262,z=0.000000)
+    moved to Vector3D(x=8.049845,y=16.099689,z=0.000000)
+    repair will succeed in 2 seconds
+    moved to Vector3D(x=8.497058,y=16.994117,z=0.000000)
+    moved to Vector3D(x=8.944272,y=17.888544,z=0.000000)
+    moved to Vector3D(x=9.391486,y=18.782971,z=0.000000)
+    repair will succeed in 2 seconds
+    moved to Vector3D(x=9.838699,y=19.677398,z=0.000000)
+    moved to Vector3D(x=10.000000,y=20.000000,z=0.000000)
+    moved to
+
+Each time the task failed, the repair task was started and repaired the plan.
+Note that the task also adds a copy of itself to the plan. Let's look at it in
+more details in the plan display (note that this time, you need to display the
+ErrorHandling relation as well).
+
+![](log_replay/plan_repair_1.png)
+{.fullfigure}
+
+**Nominal execution**: the plan repair (in blue) is not executed yet and the ExecutePath is running
+{.figurecaption}
+
+![](log_replay/plan_repair_2.png)
+{.fullfigure}
+
+**ExecutePath fails**: the plan repair is queued for starting, and will actually start in the next cycle
+{.figurecaption}
+
+![](log_replay/plan_repair_3.png)
+{.fullfigure}
+
+**Repair started**
+{.figurecaption}
+
+![](log_replay/plan_repair_4.png)
+{.fullfigure}
+
+**Repair successful**: a new ExecutePath task is added with a new repair. The
+new task's start event is queued, and will therefore start at the beginning of
+the next cycle.
+{.figurecaption}
+
+A simple real-world example is
+[here](http://roby.rubyforge.org/videos/rflex_repaired.avi) In this video, the
+microcontroller which drives the robot's motors sometime gives spurious
+<tt>BRAKES_ON</tt> messages. Our problem is that the Roby controller must
+determine if the message is spurious, or if brakes are actually set by the means
+of an emergency switch for instance. To do that, the plan waits a few seconds
+and tests the <tt>BRAKES_ON</tt> state of the robot. If the brakes are reported
+as off, then the robot can start moving again. Otherwise, the error was a
+rightful one and should be handled by other means.
+
+Another, more complex example is the "P3d repaired" video presented
+[here](http://roby.rubyforge.org/videos/p3d_repaired.avi)
+
+Exception propagation
+---------------------
+This is the third error handling paradigm available in Roby. It is akin to
+classical exception propagation. This mean of error handling is more advanced,
+and therefore is not presented in detail here.
+
+Unhandled errors
+----------------
+Once the exception propagation phase is finished, the plan analysis (i.e.
+constraint verification) is re-ran once to verify that exception handlers do
+have repaired the errors. If errors are still found, they cannot be handled
+anymore.
+
+This set of errors, and the errors that have not been handled before, determine
+a set of tasks that can be dangerous for the whole system. The garbage
+collection kicks in and will take the necessary actions to remove these tasks
+from the plan. Indeed, it is necessary to kill all tasks which were actually
+depending on the faulty activities: all tasks that are parents of the faulty
+tasks in any relation are forcefully garbage collected. In the exception
+propagation example above, all tasks which have a number will be killed and
+remove from the plan.
+