roby 0.7.3 → 0.8.0

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

@@ -0,0 +1,179 @@
+---
+title: Events
+sort_info: 100
+--- name:content pipeline:tags,markdown,blocks
+
+This page will present the basic tools that allow to define and manipulate
+events. In {link: {path: /basics/plan_objects.html, attr:
+{:link_text: the overview of plan objects}}}, we saw that
+events are two sided objects: one the one hand, they represent the
+situations the system is in (event _emission_). On the other hand, they
+represent the commands that the system accepts (event _commands_).
+ We'll see in this page how to associate a command with an event (event
+command), how to call code when an event is emitted (event handlers), how to
+call it and how to emit it.
+
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+The basics
+----------
+
+In the plan, events are represented through the {rdoc_class: EventGenerator}
+class. With the following code, you will create an event that has no command (it
+is called a _contingent_ event, or a _non-controllable_ event):
+
+{coderay:: ruby}
+ >> ev1 = Roby::EventGenerator.new
+{coderay}
+
+Then, before using it, you need to include it in a plan, so do
+{coderay:: ruby}
+ >> plan.add(ev1)
+{coderay}
+
+Finally, to be able to see the event's emission, we would display some text
+using an _event handler_: a piece of code that is executed when the event is
+emitted.
+
+{coderay:: ruby}
+ >> ev1.on { |e| puts "ev1 emitted with context=#{e.context.inspect}" }
+{coderay}
+
+Let's try to emit it. The event _emission_ says "the event happened just now".
+{coderay:: ruby}
+ >> ev1.emit
+ ev1 emitted with context=nil
+{coderay}
+
+And if you would like to associate data with the event (what is called the event
+context), you would do
+  
+{coderay:: ruby}
+ >> ev1.emit(10)
+ ev1 emitted with context=[10]
+{coderay}
+
+Let's now create a second event
+
+{coderay:: ruby}
+ >> ev2 = Roby::EventGenerator.new do |argument|
+ ?>   puts "ev2 called with argument=#{argument.inspect}"
+ ?>   ev2.emit(argument.first + 1)
+ >> end
+ >> plan.add(ev2)
+ >> ev2.on { |ev| puts "ev2 emitted with context=#{ev.context.inspect}" }
+{coderay}
+
+This second event is _controllable_. It has a block of code associated to it
+(the event command) whose purpose it to make sure that the event will _happen_
+(be emitted). As you can see above, a command accepts an argument. In this
+example, the emission is done by calling emit directly. More complex
+(asynchronous) schemes can also be built, but in general they would be
+represented by tasks (that we will see later on).
+
+Let's try our controllable event
+{coderay:: ruby}
+ >> ev2.call(10)
+ ev2 called with argument=[10]
+ ev2 emitted with context=[11]
+{coderay}
+
+Reacting to events
+------------------
+The whole point of having a *plan* is to be able to describe _reactions_: i.e.
+what the system should do when something happens. The basic tool to do that,
+is to create a _signal_ between two events:
+
+{coderay:: ruby}
+ >> ev1.signals ev2
+{coderay}
+
+Try it:
+
+{coderay:: ruby}
+ >> ev1.emit(10)
+ ev1 emitted with context=10
+ ev2 called with argument=10
+ ev2 emitted with context=11
+{coderay}
+
+You can therefore see that
+
+ * because of the signal, the _emission_ of the first event caused the second
+   event's command to be called. The signal therefore means "when ev1 happens,
+   call ev2"
+ * the signalling transforms the event's context into the target command's
+   argument.
+
+Composing events
+----------------
+
+Another important capability built around events is the ability to _compose_ them. Two
+basic operators exist.
+
+For instance, in the following snippet, "and\_ev" is emitted when _both_ ev1
+__and__ ev2 have been emitted and "or\_ev" is emitted as soon as _one of_ ev1
+__or__ ev2 have been emitted.
+
+{coderay:: ruby}
+ >> plan.add(ev1 = EventGenerator.new)
+ >> plan.add(ev2 = EventGenerator.new)
+ >> and_ev = ev1 & ev2
+ >> or_ev  = ev1 | ev2
+ >> and_ev.on { puts "AND" }
+ >> or_ev.on { puts "OR" }
+ >> ev1.emit
+ OR
+ >> ev2.emit
+ AND
+{coderay}
+
+You did not have to add the and\_ev and or\_ev events to the plan. This is because
+they are linked to ev1 and ev2, so Roby added them to the plan automatically.
+{.info}
+
+You can see that the "OR" event is emitted only once. If you want it to be
+emitted every time one of its sources are, you would do:
+{coderay:: ruby}
+ >> or_ev = ev1 | ev2
+ >> or_ev.on { puts "OR" }
+ >> or_ev.on { or_ev.reset }
+ >> ev2.emit
+ OR
+ >> ev2.emit
+ OR
+ >> ev1.emit
+ OR
+{coderay}
+
+In the same way, the "AND" event is emitted only once. You can also use #reset
+to make it emit again.
+
+Common errors when manipulating events
+---------------------------------------
+
+A common error is to try to manipulate an event which is not included in a
+plan (objects are included in plans through the #add call). In that case,
+the event is not executable and you will get the following error:
+
+{coderay:: ruby}
+ >> ev = EventGenerator.new { }
+ >> ev.call
+ Roby::EventNotExecutable: #call called on #<Roby::EventGenerator:0x484aa3c0> which is a non-executable event
+ >> ev.emit
+ Roby::EventNotExecutable: #emit called on #<Roby::EventGenerator:0x484aa3c0> which is a non-executable event
+{coderay}
+
+Another common error is to try to call (or signal) and event that is non
+controllable. In that case, Roby raises a {rdoc_class: EventNotControlable}
+exception.
+
+{coderay:: ruby}
+ >> plan.add(ev = EventGenerator.new)
+ >> ev.call
+ Roby::EventNotControlable: #call called on a non-controllable event
+ >> source = EventGenerator.new
+ >> source.signal(ev)
+ Roby::EventNotControlable: trying to establish a signal from #<Roby::EventGenerator:0x484a77f8> to #<Roby::EventGenerator:0x484aab88> which is not controllable
+{coderay}
+

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

@@ -0,0 +1,275 @@
+---
+title: Task Hierarchies
+sort_info: 500
+--- pipeline:tags,markdown
+
+What building blocks do we have until now ?
+
+* events, signals and forwarding: a way to represent how the execution should
+  proceed. This is **the execution flow**.
+* tasks: how events can be aggregated into a representation of long-running
+  processes
+
+The goal of a plan-based system such as Roby is to allow aggregating the tasks
+to represent both *what* the system is doing and *how* it is doing it. To do
+this, Roby offers different **task relations**: these relations are a
+representation of the purpose of each tasks.  For instance, the *hierarchy*
+relation represents a dependency, i.e. saying "a given task purpose is to allow
+the successful execution of another task".  Another example is the "planned\_by"
+relation. This other relation represents that a given task takes care of
+generating the plan needed to perform an action.
+
+This page presents the most important of them: the hierarchy relation.
+
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+Semantics of task hierarchies
+-----------------------------
+The goal of that relation is to represent the hard dependencies between tasks.
+I.e. to say "task A needs results from task B to perform its duty" or "task A
+needs task B to run to perform its duty". The idea behind such a relation is to
+be able to create a "library" of tasks that perform simple actions (usually
+implemented in a functional layer external to Roby itself), and then to be able
+**aggregate** them into more complex actions simply by building plans.
+
+What is the purpose of this ? Why not just run things "like this" ?
+
+The goal is to be able to detect errors in execution. What a dependency relation
+gives is not only a semantic (why things are what they are), but also that "if
+the child fails, then something is wrong". The support of error detection and
+reparation is the central issue in supervision, and Roby offers advanced tools
+for it.
+
+Adding dependencies between tasks
+---------------------------------
+
+The code in that section is not meant to be tried out, but to support the
+explanations. A proper controller, that uses these principles, is shown in the
+following sections.
+{.warning}
+
+Let's assume our robot's functional layer offers two services:
+* it has a way to compute a path from A to B (path planning)
+* it has a way to execute that path once its computed
+
+What we want here is to build the plan that represents a _movement_ from the
+current robot's position to a goal position.  That aggregate action will
+naturally be represented by a MoveTo task that takes one 'goal' argument. In
+Roby, it would look like this:
+
+{coderay:: ruby}
+class MoveTo < Roby::Task
+  argument :goal
+end
+{coderay}
+
+So, now, we would have two options:
+* either call the functional layer directly from the MoveTo task
+* or integrate both services independently (in two different tasks) and then
+  aggregate their functionality through the plan.
+
+In Roby, we would usually use the second method, as it promotes reusability. The
+plan would therefore have to represent the following:
+
+    To do a MoveTo from point A to point B
+      => first the robot must successfully compute its 
+         path between those two points
+      => then it must successfully execute that path
+
+Assuming that we have the ComputePath and ExecutePath task models to represent
+our functional layer's services, and that the target point is represented by the
+variable 'p', this can be translated as a plan into:
+
+    The successful execution of MoveTo(:goal => p) depends on
+      the successful execution of ComputePath(:goal => p)
+      followed by the successful execution of ExecutePath
+
+Finally, that plan would be generated with the following code.
+
+{coderay:: ruby}
+ move    = MoveTo.new :goal => a
+ compute = ComputePath.new :goal => a
+ execute = ExecutePath.new
+
+ # The movement depends on the successful execution of both the computation and
+ # execution of the path
+ move.depends_on compute
+ move.depends_on execute
+ # Execution should start when computation has finished successfully
+ compute.signal :success, execute, :start
+ # Computation should start when the movement starts
+ move.signal :start, compute, :start
+ # The movement has successfully finished when the execution has successfully
+ # finished
+ execute.forward :success, move, :success
+{coderay}
+
+Obviously, the ComputePath/ExecutePath combination is a **sequence**. Rephrasing
+again, we could describe this plan with:
+    The MoveTo task is a sequence of ComputePath followed by ExecutePath
+
+and could be written
+{coderay:: ruby}
+ move    = MoveTo.new :goal => a
+ compute = ComputePath.new :goal => a
+ execute = ExecutePath.new
+ (compute + execute).to_task(move)
+ move
+{coderay}
+ 
+
+A controller using task hierarchies
+-----------------------------------
+
+What do we need to get a proper controller implementing this ?
+* first we need to define the three task models described above
+* then we need to define the planning method that will create the necessary
+  plan.
+
+The only thing that still needs to be defined is how to transfer the path from
+the ComputePath task to the ExecutePath task. In general, such an endeavour is
+done in Roby through the attributes on task objects. Here, we will simply define
+a 'path' attribute on the MoveTo class.  Given that the actual actions are
+performed by ComputePath and ExecutePath, the definition of the MoveTo task is
+actually quite simple:
+
+{coderay:: ruby}
+class MoveTo < Roby::Task
+  terminates
+
+  # The movement goal
+  argument :goal
+  # The generated path
+  attr_accessor :path
+end
+{coderay}
+
+The implementation of the ComputePath task is a bit more complex. First, on a
+model point of view, it will require the 'goal' argument again, and also a
+'path\_task' argument which is the task holding the path data when computed.
+
+On the implementation side, we will use a standard task, the {rdoc_class:
+ThreadTask}. This task represents in Roby's plan a computation that is done in a
+separate thread. To use this task, one simply needs to define an
+"implementation" block (see below). This block is ran in a separate thread by
+ThreadTask and, upon successful execution of the thread, the result value is
+saved in the tasks's 'result' attribute (and success is emitted). The
+added value is that if the thread fails by raising an exception, the "failed"
+event is simply emitted with the exception as context. Now, open
+tasks/compute\_path.rb and add the following code to it:
+
+{coderay:: ruby}
+require 'roby/thread_task'
+class ComputePath < Roby::ThreadTask
+  # Where we should store the path when computed
+  argument :path_task
+  # The movement goal
+  argument :goal
+
+  # The robot position at which we started planning the path
+  attr_reader :start_point
+
+  # Initialize start_point and call ThreadTask's start command
+  event :start do |context|
+    @start_point = State.pos.dup
+    super
+  end
+
+  # Implementation of the computation thread
+  implementation do
+    path      = [start_point]
+    max_speed = 1
+    while goal.distance(path.last) > max_speed
+      u = goal - path.last
+      u /= u.length / max_speed
+      path << path.last + u
+    end
+    path << goal
+
+    Robot.info "#{path.size} points between #{start_point} and #{goal}"
+    path
+  end
+
+  on :success do |ev|
+    path_task.path = result
+  end
+end
+{coderay}
+
+Finally, ExecutePath takes the path generated and follows it. In the same way than
+done with ComputePath, a "path\_task" argument represents the task that holds the
+path (which is everything the task needs). So, edit tasks/execute\_path.rb and
+add the following:
+
+{coderay:: ruby}
+class ExecutePath < Roby::Task
+  terminates
+
+  # The task holding the path data
+  argument :path_task
+
+  # The current waypoint
+  def current_waypoint; path_task.task[@waypoint_index] end
+
+  poll do
+    @waypoint_index ||= 0
+    State.pos = current_waypoint
+    @waypoint_index += 1
+    if @waypoint_index == path_task.data.size
+      emit :success
+    end
+
+    Robot.info "moved to #{current_waypoint}"
+  end
+end
+{coderay}
+
+There are two things left to do: properly initializing the position and adding
+the planning method. For the first point, we will use the Pos::Vector3D class
+that Roby provides (a simple x,y,z tuple). Edit controllers/goForward.rb and
+add:
+
+{coderay:: ruby}
+State.pos = Pos::Vector3D.new
+{coderay}
+
+Finally, edit planners/goForward/main.rb and add the following method:
+
+{coderay:: ruby}
+method(:planned_move) do
+ goal = Pos::Vector3D.new(*arguments.values_at(:x, :y))
+ move    = MoveTo.new :goal => goal
+ compute = ComputePath.new :goal => goal, :path_task => move
+ execute = ExecutePath.new :path_task => move
+ (compute + execute).to_task(move)
+ move
+end
+{coderay}
+
+Trying it out 
+-------------
+
+In one Unix shell, do
+
+    $ scripts/run goForward
+    344919:32:59.172 (Roby) GC.enable does not accept an argument. GC will not be controlled by Roby
+    344919:32:59.204 (goForward) loaded Roby 0.7.90 on ruby 1.8.7 (2008-08-11 patchlevel 72) [x86_64-linux]
+    344919:32:59.272 (goForward) loading controller file /home/joyeux/dev/first_app/controllers/goForward.rb
+    344919:32:59.273 (goForward) done initialization                                                        
+    0                                                                                                       
+    0                                                                                                       
+
+Then, **in another one**, start the Roby shell
+
+    $ scripts/shell
+    localhost:48902 >
+
+And do
+
+{coderay:: ruby}
+localhost:48902 > task = planned_move! :x => 10, :y => 20
+=> MoveTo{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}:0x7fd0ec1b1a38[]
+localhost:48902 >
+!task MoveTo{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}:0x7fd0ec1b1a38[] finished successfully
+{coderay}
+