roby 0.8.0 → 3.0.0

data/doc/guide/{src → attic}/abstraction/forwarding.page

@@ -1,7 +1,7 @@
 ---
 title: The forwarding relation
 sort_info: 300
---- name:content pipeline:tags,markdown,blocks
+---
 
 * we already saw its usefulness inside tasks
 * semantics of forwarding in-between tasks

data/doc/guide/{src → attic}/abstraction/hierarchy.page

@@ -1,7 +1,7 @@
 ---
 title: Abstraction as task dependencies
 sort_info: 200
---- name:content pipeline:tags,markdown,blocks
+---
 
 Dependency relations
 --------------------

data/doc/guide/{src → attic}/abstraction/index.page

@@ -2,7 +2,7 @@
 title: Representing Abstraction
 routed_title: Representing Abstraction
 sort_info: 0
---- name:content pipeline:tags,markdown,blocks
+---
 Being able to abstract away the little details of execution is crucial. Indeed,
 it allows to apply high-level reasoning algorithms, that are not able to take
 into account too much details.

data/doc/guide/{src → attic}/abstraction/task_models.page

@@ -1,7 +1,7 @@
 ---
 title: Task Models
 sort_info: 100
---- name:content pipeline:tags,markdown,blocks
+---
 
 * relationship between models
   - semantics of subclasses

data/doc/guide/{overview.rdoc → attic/cycle/api_overview.rdoc}

@@ -1,8 +1,13 @@
+---
+title: API Overview
+sort_info: 400
+---
+
 = Overview
 
 This page describes the various components that form a Roby application. It is
 meant to be an "entry point" for people to understand what classes are there
-for. This describes the software architecture of the upcoming v0.8.
+for.
 
 == Life and death of a Roby Controller
 

data/doc/guide/attic/cycle/error_handling.page

@@ -0,0 +1,98 @@
+---
+title: Error Handling
+sort_info: 200
+---
+
+Integration in the execution cycle
+----------------------------------
+As was just explained, errors take two forms in Roby:
+
+ * failure to meet the constraints set by the task/event relations
+ * exceptions that come from the Ruby code
+
+For language exceptions, we will actually have to distinguish between exceptions
+that come from task/event code (essentially event commands and handlers, polling
+blocks) and Roby code itself.
+
+The root of error handling is to be able to automatically compute what the
+consequences of an error are. In Roby, the plan has the role of showing these
+links (a task's failure impacts the tasks that depend on it, i.e. its parents in
+the hierarchy relation). Therefore, Roby is only able to handle these errors
+that can be associated with a task (this error impacts that task), namely: the
+exceptions that come from task/event code and the constraint violations. The
+other exceptions (that come from Roby code that is not assigned to a task/event)
+are not handled automatically by Roby. They lead by default to a shutdown of the
+whole system.
+
+In the execution cycle, Roby runs a constraint analysis on the whole plan _after
+the event propagation phase_. This is because that pass has to see the "big
+picture", i.e. the result of all the event propagation in the current cycle.
+See [this page](../relations/new_relations.html) for details on how to integrate
+a constraint analysis routine from a task/event relation.
+
+We will now see the three means of error handling that Roby offers, and then
+conclude with an overview of the whole error handling phase.
+
+Repairing the plan during the event propagation
+-----------------------------------------------
+As has just been noticed, Roby has to analyze the plan __after__ all events have
+been propagated. So, if a constraint gets both violated *and* repaired during
+the event propagation phase, that won't really count as an error.
+
+That mean of "error repair" is useful for simple cases. The most obvious case is
+when a task should simply be restarted when it fails, for instance because the
+failure is a spurious error.
+
+As an example, I had a robot where the control module, in the functional layer,
+was checking that its input data flow was updated often enough (timeout).
+This is a fine design decision given the security it adds. And was working fine
+on the realtime operating system the functional layer was originally running on.
+But when I came at this lab, the functional layer was running on a standard
+Linux kernel, and therefore there were outliers in the command update rate (i.e.
+latencies much higher than expected). They were rare, but they happened.
+
+Changing the timeout was not the right solution, as its effect would have to
+actually make it much less useful (we would have had to move it to more than one
+second). So, I had to handle this in the supervision layer.
+
+How it was done was the following: whenever that particular failure message was
+coming in (<tt>poster\_not\_updated</tt>), the control task was simply restarted
+_unless it had already been restarted in the last second_.
+
+It was implemented like this:
+
+{coderay:: ruby}
+on :poster_not_updated do |event|
+  if (TrackSpeedStart.last_error - Time.now) > 1
+    plan.respawn(self)
+    TrackSpeedStart.last_error = Time.now
+  end
+end
+{coderay}
+
+Where <tt>plan.respawn</tt> do the job of creating a new task of the same type
+and with the same arguments, replacing the current version with the new instance
+and start the new instance.
+
+The execution trace looks like the following, with the original plan in the left
+and the plan after the error on the right.
+
+![](error_instantaneous_repair.png)
+
+Plan repairs: asynchronous reparations
+--------------------------------------
+
+Roby's exception system: synchronous reparations
+------------------------------------------------
+
+What to do with non-repaired tasks ?
+------------------------------------
+
+Well, that's actually the subject of the next page. In summary: since they're
+not repaired, they count as being potentially harmful to the system and
+therefore are stopped automatically by the garbage collection mechanism.
+
+Summary
+-------
+
+

data/doc/guide/{src/cycle/error_handling.page → attic/cycle/error_sources.page}

@@ -1,7 +1,7 @@
 ---
-title: Error Handling
-sort_info: 200
---- name:content pipeline:tags,markdown,blocks
+title: Error Sources
+sort_info: 190
+---
 
 Where do errors come from ?
 ---------------------------
@@ -49,7 +49,7 @@ has two roles:
    process states by indirect means. A simple example is to verify that the
    output values of the module is within specified boundaries.
 
-The most useful strategy is to actually do _both_. Simple diagnostics can be
+The most robust strategy is to actually do _both_. Simple diagnostics can be
 implemented using the task's __poll__ block. More complex ones can use two
 different tasks (one task for the process, one task for the monitoring), and
 according task relations.
@@ -80,89 +80,46 @@ end
 and then {coderay:: {lang: ruby, wrap: span}}emit :hesitates{coderay} when
 applicable.
 
-Integration in the execution cycle
-----------------------------------
-As was just explained, errors take two forms in Roby:
-
- * failure to meet the constraints set by the task/event relations
- * exceptions that come from the Ruby code
-
-For language exceptions, we will actually have to distinguish between exceptions
-that come from task/event code (essentially event commands and handlers, polling
-blocks) and Roby code itself.
-
-The root of error handling is to be able to automatically compute what the
-consequences of an error are. In Roby, the plan has the role of showing these
-links (a task's failure impacts the tasks that depend on it, i.e. its parents in
-the hierarchy relation). Therefore, Roby is only able to handle these errors
-that can be associated with a task (this error impacts that task), namely: the
-exceptions that come from task/event code and the constraint violations. The
-other exceptions (that come from Roby code) are not handled automatically by
-Roby and they lead by default to a shutdown of the whole system.
-
-In the execution cycle, a constraint analysis is ran on the whole plan _after
-the event propagation phase_. This is because that pass has to see the "big
-picture", i.e. the result of all the event propagation in the current cycle.
-
-We will now see the three means of error handling that Roby offers, and then
-conclude with an overview of the whole error handling phase.
-
-Repairing the plan during the event propagation
------------------------------------------------
-As has just been noticed, Roby has to analyze the plan __after__ all events have
-been propagated. So, if a constraint gets both violated *and* repaired during
-the event propagation phase, that won't really count as an error.
-
-That mean of "error repair" is useful for simple cases. The most obvious case is
-when a task should simply be restarted when it fails, for instance because the
-failure is a spurious error.
-
-As an example, I had a robot where the control module, in the functional layer,
-was checking that its input data flow was updated often enough (timeout).
-This is a fine design decision given the security it adds. And was working fine
-on the realtime operating system the functional layer was originally running on.
-But when I came at this lab, the functional layer was running on a standard
-Linux kernel, and therefore there were outliers in the command update rate (i.e.
-latencies much higher than expected). They were rare, but they happened.
-
-Changing the timeout was not the right solution, as its effect would have to
-actually make it much less useful (we would have had to move it to more than one
-second). So, I had to handle this in the supervision layer.
-
-How it was done was the following: whenever that particular failure message was
-coming in (<tt>poster\_not\_updated</tt>), the control task was simply restarted
-_unless it had already been restarted in the last second_.
-
-It was implemented like this:
-
-{coderay:: ruby}
-on :poster_not_updated do |event|
-  if (TrackSpeedStart.last_error - Time.now) > 1
-    plan.respawn(self)
-    TrackSpeedStart.last_error = Time.now
-  end
-end
-{coderay}
-
-Where <tt>plan.respawn</tt> do the job of creating a new task of the same type
-and with the same arguments, replacing the current version with the new instance
-and start the new instance.
-
-The execution trace looks like the following, with the original plan in the left
-and the plan after the error on the right.
-
-![](error_instantaneous_repair.png)
-
-Roby's exception system: synchronous reparations
-------------------------------------------------
-
-Plan repairs: asynchronous reparations
---------------------------------------
-
-What to do with non-repaired tasks ?
-------------------------------------
-
-Summary
--------
-
+Using tasks as an error isolation mechanism
+-------------------------------------------
+
+As we mentionned earlier, Roby tries to as much as possible isolate exceptions
+that are coming from "user code", i.e. event commands and handlers, polling
+blocks. The "isolation mechanism" is to associate these exceptions to a
+particular operation on a task or event.
+
+In practice, the following things can happen in a task's lifetime:
+
+ 1. the 'start' command raises an exception. This exception is wrapped in a
+    {rdoc_class: CommandFailed} instance, the task is marked as failed (both
+     #failed\_to\_start? and #failed? return true) and all its events are marked as
+    unreachable. The failure reason (returned by Task#failure\_reason) and the
+    unreachability reason are both the CommandFailed instance.
+ 2. the command or handlers of an intermediate event, or the polling block raise
+    an exception. In that case, the <tt>internal_error</tt> event is emitted
+    with said exception as context. This event either signals the stop event if
+    the stop event is controlable, or forcefully emits <tt>failed</tt>.
+ 3. the command or handler of a terminal event raise an exception. If it was
+    during a normal termination, then it is handled in the same way than in 2.
+    (internal\_error is emitted). Otherwise, then a {rdoc_class:
+    TaskTerminationFailure} error is injected in the error handling and the 
+    [task is put into quarantine](garbage_collection.html).
+
+Error representation in the API
+-------------------------------
+
+In practice, error handling operates on {rdoc_class: LocalizedError} instances.
+This new instance refers to the original error (if there is one, see for
+instance {rdoc_class: CommandFailed}).
+The error source will be as specific as possible: either a specific event
+emission (returned by #failed\_event), an event generator (returned by
+ #failed\_generator, for instance if the error is due to an event that has become
+unreachable) and finally a task (returned by #failed\_task).
+
+On creation, LocalizedError will "fill in the blanks", i.e. it will for instance set
+failed\_generator and failed\_task if the error source is an emission that comes
+from a task.
+
+Once created, this error gets registered in the execution engine by
+calling <tt>ExecutionEngine#add_error</tt>.
 

data/doc/guide/{src → attic}/cycle/garbage_collection.page

@@ -1,7 +1,7 @@
 ---
 title: Garbage Collection
 sort_info: 300
---- name:content pipeline:tags,markdown,blocks
+---
 
 * generatl meaning of task relations => dependencies at different levels
 * stoppign tasks while respecting dependency relations

data/doc/guide/{src → attic}/cycle/index.page

@@ -2,7 +2,7 @@
 title: The Execution Cycle
 routed_title: Execution Cycle
 sort_info: 0
---- name:content pipeline:tags,markdown,blocks
+---
 
 Now that we saw [the basics](../basics/index.html), this section will present in
 greater details how execution works in Roby. First, we will see how a Roby

data/doc/guide/{src → attic}/cycle/propagation.page

@@ -1,7 +1,7 @@
 ---
 title: Event Propagation
 sort_info: 100
---- name:content pipeline:tags,markdown,blocks
+---
 
 The execution flow in Roby is basically:
 
@@ -152,3 +152,13 @@ simply do
 The block will then be called at the beginning of the next execution cycle, in
 the propagation phase.
 
+Unreachable events
+------------------
+
+There are means, in the engine to declare that an event will __never__ be
+emitted anymore (the principal one being EventGenerator#unreachable!). This is
+useful in general, as it allows to realize that something that is _needed_ by
+the good execution of the system will actually never happen. This is actually
+how a big part of the error detection mechanism works.
+
+

data/doc/guide/attic/plans/building_plans.page

@@ -0,0 +1,89 @@
+---
+title: Building Plans
+sort_info: 150
+---
+
+In a Roby application / Roby controller, the task of building plans, i.e. adding
+[tasks](tasks.html) and [events](events.html), and adding relations between them
+is given the __planning interface__.
+
+In effect, the planning interface is not an interface to a planner. It is just
+an interface that allows to, dynamically, ask "something" to build a plan to
+realize an action. This page will describe this planning interface, and how it
+can be accessed at runtime.
+
+The planning scripts that we are going to describe below are defined in files in
+the models/planners/* directory, and models/planners/ROBOT directories (i.e.
+models/planners/asguard/ is going to hold planners that should only be defined
+when the system has been started with the -rasguard option).
+
+Planning methods
+----------------
+Planning methods are code blocks (in effect, Ruby methods) that get a set of
+arguments and return an instance of Roby::Task. They are describing the __action
+interface__ of your robot. I.e. if one wants to make a robot move, he would do
+(in the relevant planner class, we'll talk about that later)
+
+{coderay:: ruby}
+method(:move_to) do
+  task = MoveTo.new(arguments[:target_point])
+  # Create other tasks, [add relations](../relations) between them tasks, create
+  # links between the tasks events, add [polling and scripting](code.html)
+  task
+end
+{coderay}
+
+The task returned by the planning method will be used to represent the required
+action.
+
+In general, building plans manually like this gives you the greatest
+flexibility, but also requires you to understand a lot about Roby. The
+recommended way to do this kind of behaviour aggregation is to create a toplevel
+task, such as the MoveTo task above, and define either a task script -- if that
+is enough -- or a task state machine to represent the more complex behaviour:
+
+{coderay:: ruby}
+method(:move_to) do
+  task = MoveTo.new(arguments[:target_point])
+  task.script do
+    # Use the script to define your behaviour. The start(:planning_method_name!)
+    # or start(task_model) instructions allow you to add subtasks
+  end
+  task
+end
+{coderay}
+
+MainPlanner and defining additional planners
+--------------------------------------------
+By default, Roby defines a planner class to hold all these planning methods.
+This class is called MainPlanner and is available globally. It is, by default,
+modified in planners/models/main.rb.
+
+When systems grow larger, or in order to allow for reusing the planner models,
+one can define its own planning classes. This can be done by subclassing
+Roby::Planning::Planner:
+
+{coderay:: ruby}
+class MyPlanner < Roby::Planning::Planner
+end
+{coderay}
+
+Moreover, in order for this planning model to be made available to the action
+interfaces that are described below, one has to add the planner to the list of
+planner models in Roby.app.planners. This is usually done in config/ROBOT.rb,
+but could also be done dynamically.
+
+Dynamically querying planning methods
+-------------------------------------
+Once planning methods are defined, they can be accessed through two principal
+means:
+
+__From within the Roby controller__, one can inject a new mission in the plan
+from the planning interface using the Robot singleton object:
+
+{coderay:: ruby}
+Robot.move_to!
+{coderay}
+
+__From the Roby shell__, one does the same by using typing move_to!.
+