roby 0.8.0 → 3.0.0

data/doc/guide/src/{basics → tutorial}/hierarchy.page

@@ -1,7 +1,7 @@
 ---
 title: Task Hierarchies
 sort_info: 500
---- pipeline:tags,markdown
+---
 
 What building blocks do we have until now ?
 
@@ -21,8 +21,6 @@ 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.
@@ -46,11 +44,12 @@ 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}
+{: .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
+
+ * 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
@@ -64,9 +63,10 @@ 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.
+
+ * 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:
@@ -109,6 +109,7 @@ 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
@@ -131,7 +132,7 @@ 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:
+actually quite simple (add in models/tasks/move_to.rb)
 
 {coderay:: ruby}
 class MoveTo < Roby::Task
@@ -149,27 +150,25 @@ 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
+Tasks::Thread}. 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
+Tasks::Thread 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:
+models/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
+require 'roby/tasks/thread'
+class ComputePath < Roby::Tasks::Thread
   # 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
+  # Initialize start_point and call Tasks::Thread's start command
   event :start do |context|
     @start_point = State.pos.dup
     super
@@ -189,33 +188,25 @@ class ComputePath < Roby::ThreadTask
     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
+Finally, ExecutePath takes the path generated and follows it. It assumes that
+its path is stored on its parent task. Edit models/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
+  def current_waypoint; parent_task.path[@waypoint_index] end
 
   poll do
     @waypoint_index ||= 0
     State.pos = current_waypoint
     @waypoint_index += 1
-    if @waypoint_index == path_task.data.size
+    if @waypoint_index == parent_task.path.size
       emit :success
     end
 
@@ -225,51 +216,61 @@ 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
+the planning method. For the first point, we will use the Roby::Pos::Vector3D class
+that Roby provides (a simple x,y,z tuple). Edit scripts/controllers/goForward.rb and
 add:
 
-{coderay:: ruby}
-State.pos = Pos::Vector3D.new
-{coderay}
+~~~ ruby
+State.pos = Roby::Pos::Vector3D.new
+~~~
 
-Finally, edit planners/goForward/main.rb and add the following method:
+Finally, edit models/planners/goForward/main.rb and add the following method:
 
-{coderay:: ruby}
-method(:planned_move) do
- goal = Pos::Vector3D.new(*arguments.values_at(:x, :y))
+~~~ ruby
+describe("a movement that is using a planner").
+    required_arg('x', 'the X part of the position').
+    required_arg('y', 'the Y part of the position')
+def planned_move(arguments)
+ goal = Roby::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 = ComputePath.new :goal => goal
+ execute = ExecutePath.new
+ # ExecutePath expects its target path from its parent. Make sure that it
+ # happens
+ compute.on :success do |event|
+   move.path = compute.result
+ end
  (compute + execute).to_task(move)
  move
 end
-{coderay}
+~~~
 
 Trying it out 
 -------------
 
 In one Unix shell, do
 
-    $ scripts/run goForward
+    $ roby run -rgoForward -c
     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
+    $ roby 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}
+~~~ ruby
+localhost:48902 > planned_move! :x => 10, :y => 20
+=> #<service Roby::Task:0x7f34d6dce5f8{}[]>
+localhost:48902 > 
+[1] planned_move! started to plan
+[1] planned_move!: Roby::Task:0x7f34d6dce5f8{}[] has been replaced by MoveTo:0x7f34d6db7358{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[]
+[1] planned_move!: task MoveTo:0x7f34d6db7358{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] started
+[1] planned_move!: task MoveTo:0x7f34d6db7358{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] finished successfully
+[1] planned_move!: task MoveTo:0x7f34d6db7358{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] has been removed
+~~~
 

data/doc/guide/src/tutorial/index.page

@@ -0,0 +1,13 @@
+---
+title: Tutorials
+sort_info: 0
+---
+This section will present the basics of plan management using Roby, this time
+with concrete examples. It assumes that you already have read the
+[concepts](../concepts) section.
+
+ * the two core objects used in Roby to represent the robot's actions
+ * what is a Roby application and how create one
+ * how it is possible to interact with a running Roby application
+ * how to build complex actions from simple ones
+

data/doc/guide/src/tutorial/relations_display.page

@@ -0,0 +1,153 @@
+---
+title: Using Plan Display
+sort_info: 600
+---
+
+What we will see in this page is how to trace the execution flow (the flow of
+events), and understand a bit more how the plans you will build are actually
+executed by the system. We will re-use the planned\_move planning action we just
+built.
+
+Getting a log file
+------------------
+
+Using logging is the most common case, so it is enabled by default. However, it
+is can be expensive from a CPU point of view. To disable, edit config/app.yml
+and comment "events: false" around line 23. 
+{: .block}
+
+Run the controller again
+
+    # roby run -rgoForward -c
+
+and in the shell, do
+
+    localhost:48902 > planned_move! :x => 10, :y => 20 => #<service Roby::Task:0x7f48f073d6e8{}[]>
+    localhost:48902 > 
+    [1] planned_move! started to plan
+    [1] planned_move!: Roby::Task:0x7f48f073d6e8{}[] has been replaced by MoveTo:0x7f48f0726448{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[]
+    [1] planned_move!: task MoveTo:0x7f48f0726448{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] started
+    [1] planned_move!: task MoveTo:0x7f48f0726448{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] finished successfully
+    [1] planned_move!: task MoveTo:0x7f48f0726448{goal => Vector3D(x=10.000000,y=20.000000,z=0.000000)}[] has been removed
+
+The log files are saved in the logs/ folder with a name that represents the
+start time of the run (YYYYMMDD-HHMM). The last run (or the current run, if it
+is still running) is symlinked to logs/current. One can use
+
+    roby results plan_display_tutorial
+
+to rename the folder to YYYYMMDD-HHMM_plan_display_tutorial, so that finding
+this particular dataset later is easier.
+
+Displaying the log file
+-----------------------
+List the contents of the generated log directory:
+
+    $ cd /home/doudou/dev/roby-tutorials/
+    $ ls logs/current/
+    goForward-events.log
+    goForward-index.log
+
+If you look into it, two goForward files are present:
+<tt>goForward-events.log</tt> and "goForward-index.log".  The first one includes
+a trace of everything that happens in the Roby controller which has been traced
+(which virtually includes everything). The second one can actually be generated
+from data in the first one. It is simply used to speed up operations.
+
+The data in the event log can be used to display the plan operations in a GUI.
+For that, you need to have installed [Ruby/Qt4](http://korundum.rubyforge.org), as
+the GUI is written using Qt and Ruby. This can be done by installing the
+qtbindings rubygem.
+
+To start it, simply do the following in the directory of the log files:
+
+    $ roby display logs/current/goForward-events.log
+
+The following two windows should appear:
+
+![](log_replay/roby_log_main_window.png)
+
+The right window is the replay control. It displays the execution cycles in
+which something happened (an event has been emitted or the plan got modified).
+The left window represents the plan structure at the currently selected cycle,
+the events that got emitted during this cycle as well as the propagation between
+these events. The set of task relations that should be displayed can be selected
+by going into View/Configure.
+
+**Very important note** your own display may not look exactly like the ones
+displayed here. Some of the features showed here (like threaded planning) are
+asynchronous and as such the exact displays depend on the execution timing. Note
+that, even though it is the case, the robot _behaviour_ remains unchanged.
+{: .warning}
+
+Startup of the "planned\_move!" action {#planning}
+---------------------------------------
+
+Let's get to the first task-related events. Click on the first element in
+execution history (cycle @13 in the right window above). It should look like the
+next image:
+
+![](log_replay/goForward_1.png)
+
+What you see here is a representation of the plan built when the planned\_move!
+command is entered in the shell. It consists of a generic task (Roby::Task)
+which is planned\_by a Roby::PlanningTask. This is how Roby handles action
+requests from the shell: (i) it searches a planner defined for that robot with
+the specific action and (ii) generates the plan representing the planning
+process _in a separate thread_.
+
+Once that initial plan has been built, the Roby::PlanningTask task has been
+started. The various cases of event propagation are represented in different
+ways, based on whether or not the event is controlable or contingent, if it has been
+called and/or emitted. Finally, two different arrow representations are used for
+signalling (plain) and forwarding (dotted):
+
+![](log_replay/roby_replay_event_representation.png)
+
+A note about propagation representation: it would be useless to represent all
+the event propagation from the beginning of the execution to the current point.
+The display therefore represents only the propagations that have taken place
+_within the selected cycle_. In our case, we see that, in this cycle, the
+planning task "start" event has been called and emitted.
+
+The MoveTo plan
+---------------
+
+Advance one step (to the next cycle)
+
+![](log_replay/goForward_2.png)
+
+The MoveTo action has been planned and the executed plan is modified to reflect
+that. The MoveTo action itself is then started, and that is propagated to the
+ComputePath 'start' event through the signalling relation that was established
+in planned\_move.
+
+Next execution step gives us the following:
+
+![](log_replay/goForward_3.png)
+
+ComputePath emitted its "success" event. We see here that the emission of the
+"success" event of that task does not mean 'the plan modification has just took
+place' but instead that 'it has taken place some time earlier'.
+
+The ComputePath task has also finished generating the path, which is why
+ExecutePath is started. Here, the dotted lines between the events
+represent a forwarding relation between them, while the plain lines
+represent signal relations.
+
+Finally, light grey here represents tasks that have finished with the "success"
+event. Tasks whose "failed" event has been emitted are represented in red.
+
+To finish: the garbage collection process
+-----------------------------------------
+
+Advance a few more steps.
+
+![](log_replay/goForward_5.png)
+
+Here, ExecutePath has finished its execution with success and MoveTo is
+therefore finished as well -- per the forwarding relation between those two
+events. Note that the tasks have this thick dark grey contour. It means that the
+task got [garbage collected](../concepts/garbage_collection.html) in this cycle,
+i.e. removed from the plan because it was not useful anymore.
+

data/doc/guide/src/tutorial/shell.page

@@ -0,0 +1,121 @@
+---
+title: Interactive Shell
+sort_info: 400
+---
+
+As we saw earlier, the execution of Roby applications is done by an _event
+loop_. The reactivity of the supervision system obviously depend on the
+non-interruption of that event loop. Therefore, in a Roby application, the user
+runs a remote shell that is used to send specific commands to the Roby
+application itself.
+
+Actions
+--------
+Right now, we saw two different places where code is stored:
+
+1. the models/tasks/ files, where task models are defined
+2. the scripts/controllers/ files, which is the startup code for the application
+
+What we will see in this section is a third component: the **action
+interfaces**. They define what the robot can do, i.e. the overall actions that
+it is able to realize. What we will see here is that they also are the user
+interface of the robot.
+
+Exporting actions to the user's shell
+-------------------------------------
+
+Edit models/actions/goForward/main.rb and edit so that it looks like this:
+
+~~~ ruby
+require 'models/actions/main'
+class Main
+  describe('moves the robot in a forward direction').
+    required_arg('speed', 'the speed in m/s at which the robot should move')
+  def move(arguments)
+    GoForward.new :speed => arguments[:speed]
+  end
+end
+~~~
+
+That defines a very simple 'move' action. Now, we can try it out in the
+Roby shell. First, remove the last three lines in scripts/controllers/goForward.rb so
+that it looks like this:
+
+{coderay:: ruby}
+# Define the original value of x
+State.pos.x = 0
+
+# Will display the value of x every 1 second
+Roby.every(1) do
+  puts State.pos.x
+end
+{coderay}
+
+Start the roby application in one console:
+
+    $ roby run -rgoForward -c
+    44848:44:51.498 (Roby) GC.enable does not accept an argument. GC will not be controlled by Roby
+    344848:44:51.581 (goForward) loaded Roby 0.7.90 on ruby 1.8.7 (2008-08-11 patchlevel 72) [powerpc-linux]
+    344848:44:51.603 (goForward) loading controller file /home/doudou/dev/roby-tutorials/controllers/goForward.rb
+    344848:44:51.605 (goForward) done initialization
+    0
+    0
+
+Finally, start the shell in another console:
+
+    $ roby shell
+    localhost:48902 >
+
+Note that the shell does not have to be executed on the same machine than the controller.
+You can connect remotely with the --host option. Moreover, even though it
+requires a controller to be running when it starts, it will reconnect
+automatically afterwards.
+{: .note}
+
+The new prompt you get is a Ruby prompt (i.e. you should type Ruby code in it).
+Some special commands are available to interact with the Roby controller. For
+instance:
+
+~~~ ruby
+localhost:48902 > describe move
+~~~
+
+The 'help' command lists the available actions that are exported
+through the Main class. Let's try it (**notice the '!' at the end of
+move!**):
+
+~~~ ruby
+localhost:48902 > move! :speed => 1
+=> #<service Roby::Task:0x7f06da2ab308{}[]>
+localhost:48902 >
+[1] move! started to plan
+[1] move!: Roby::Task:0x7f06da2ab308{}[] has been replaced by GoForward:0x7f06da28f298{speed => 1}[]
+[1] move!: task GoForward:0x7f06da28f298{speed => 1}[] started
+> kill_job 1
+[1] move!: task GoForward:0x7f06da28f298{speed => 1}[] failed
+[1] move!: task GoForward:0x7f06da28f298{speed => 1}[] has been removed
+~~~
+
+The __intent__ to run the move is first added to the plan. Then, it gets
+developped by calling the action interface (the "started to plan" stanza), and
+the result replaces the placeholder task ("has been replaced by ..."). It then
+becomes eligible for [scheduling](../concepts/execution.html#scheduling) and is started.
+
+The value returned by the move! call can also be manipulated as if it was a task itself. For instance:
+
+~~~ ruby
+> t = move! :speed => 1
+=> #<service Roby::Task:0x7f06da2ab308{}[]>
+[1] move! started to plan                                                                                                                                        
+[1] move!: Roby::Task:0x7f06da2ab308{}[] has been replaced by GoForward:0x7f06da28f298{speed => 1}[]
+[1] move!: task GoForward:0x7f06da28f298{speed => 1}[] started
+> t.running?
+=> true
+> t.stop!
+[3] move!: task GoForward:0x7f06da215e20{speed => 1}[] failed
+[3] move!: task GoForward:0x7f06da215e20{speed => 1}[] has been removed
+~~~
+
+The action interface is described in details in the section about [Building Roby
+applications](../building). The shell in the section about [interacting with
+Roby applications](../interacting).