roby 0.7.3 → 0.8.0

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

@@ -0,0 +1,11 @@
+---
+title: Introduction
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+This section will present the basics of plan management using Roby. You will
+learn the following things:
+* 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/basics/plan_objects.page

@@ -0,0 +1,71 @@
+---
+title: Overview of Plan Objects
+sort_info: 50
+--- pipeline:tags,rdoc
+There are two basic objects in Roby plans, both objects being equally important.
+* *events*. They are both the basic command interface and the way to follow what
+  happens in and outside of the robot.
+* *tasks*. They represent the multiple processes that run on the robot: both the
+  robot physical actions and the robot's internal processing.
+
+== Events
+The first use of events is the representation of milestones in the robot's
+execution. For instance, a +reached_waypoint+ event would be _emitted_ when the
+robot reaches its assigned waypoint. Accordingly, a +detected_object+ event
+would be emitted when a visual object detection algorithm finds something.
+
+The second use of events is that, some of them (the "controllable ones") allow
+to _make_ things happen. I.e. they allow to make a specific event happen. The
+set of controllable events therefore represents the basic commands that can be
+sent to the robot's software.
+
+The event command is then the mean to make a specific event happen <i>with
+certainty</i>. For instance, +reached_waypoint+ cannot have a command, as
+navigation is not a certain endeavour. Same thing for an hypothetical
++detected_object+ of a searching robot. But a +stop_moving+ event could have a
+command. Then, by calling the command, the Roby controller would require the
+robot to "stop moving !". When the robot actually performed that action, it will
+inform the rest of the system that it stopped moving by emitting the event.
+
+== Tasks
+To represent more complex actions, that cannot be represented by the simple
+event command/emission scheme, Roby has a concept of <b>task</b>. A task
+represents a long-standing process, which can be supervised along its execution.
+One important "feature" of the task concept is that <i>a task can fail</i>.
+
+For instance, the basic task ({rdoc_class: Task}) has four default events:
+* a +start+ event
+* a +stop+ event
+* a +success+ event
+* and finally a +failed+ event
+
+On the one hand, a nominal execution of this task would be:
+* the +start+ event is emitted
+* the +success+ event is emitted
+* the +stop+ event is emitted
+
+On the other hand, a failed execution would be:
+* the +start+ event is emitted
+* the +failed+ event is emitted
+* the +stop+ event is emitted
+
+Then, a bit more complex task could be allow interruption. For this new task, we
+would need a new event (+interrupt+) and a command. One way to do it would be
+to have a _controllable_ +interrupt+ _event_ in the task. Its (interrupted)
+execution would then be
+* the +start+ event is emitted
+* the command of the +interrupt+ event is called
+* the +interrupt+ event is emitted
+* the +stop+ event is emitted
+
+Another way to see it would be that an interruption command is a way to require
+that the task stops. Therefore, one could want the following execution instead:
+* the +start+ event is emitted
+* the command of the +stop+ event is called
+* the +interrupt+ event is emitted
+* the +stop+ event is emitted
+
+The second way is the actual convention for interruptible tasks in Roby. It is
+important, as -- as we will see later -- an important feature is that Roby stops
+tasks for you.
+

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

@@ -0,0 +1,203 @@
+---
+title: Using Plan Display
+sort_info: 600
+--- pipeline:tags,markdown
+
+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
+------------------
+
+Plan execution logs are expensive from a CPU point of view, so they are disabled
+by default. Enable them back by editing config/app.yml and uncomment
+"events: true" around line 23. 
+
+Now, run again the controller
+
+    # scripts/run goForward
+
+and in the shell, do
+
+    >> planned_move! :x => 10, :y => 10
+    => MoveTo{goal => Vector3D(x=10.000000,y=10.000000,z=0.000000)}:0x4840c8d8[]
+    >>
+    !task MoveTo{goal => Vector3D(x=10.000000,y=10.000000,z=0.000000)}:0x4840c8d8[] finished successfully
+
+Finally, let's save the log files for further analysis (otherwise, one could
+destroy them by restarting the controller).
+
+    # scripts/results planned_move
+    moving /home/doudou/dev/first_app/log to /home/doudou/dev/roby-tutorials/results/20080502-planned_move
+
+"scripts/results" copies all files in "log/" into a subdirectory
+of the result dir (by default APP\_DIR/results, but can be changed in
+"config/app.yml"). The target directory name is generated following a pattern of
+"current\_date-name\_provided\_on\_command\_line".
+
+Displaying the log file
+-----------------------
+Go in the directory where the results are (see <tt>scripts/results</tt> output).
+On my machine, the command would look like this:
+
+    $ cd /home/doudou/dev/roby-tutorials/results/20080502-planned_move
+    $ ls
+    goForward-events.log
+    goForward-index.log
+
+If you look into it, two PathPlan files are present: <tt>PathPlan-events.log</tt> and
+"PathPlan-index.log".  The first one includes a trace of everything that
+happens in the Roby controller which has been traced. 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.
+
+To start it, simply do the following in the directory of the log files:
+
+    $ roby-log replay goForward
+
+The following window should appear:
+
+![](log_replay/roby_log_main_window.png)
+
+This window is separated in three:
+
+* the toplevel part ("Data sources") is the list of data sources defined for
+  this project. It is for instance possible to have a synchronized display of
+  the logs of two different Roby controllers -- for multi-robot setup.
+* the second part ("Displays") is the set of displays defined. More about that later.
+* the third part ("Play") is the replay controls: play, fast forward, position, ...
+
+Right now, we will be looking at the plan structure and execution trace. The
+"Relations" display is designed for that. Let's add one by clicking on the
+"Add" button just next to the display type combo. The configuration options
+appear (including the data source associated with the display), and a new
+window:
+
+![](log_replay/roby_log_relation_window.png)
+
+This display will show two things: the task structure (i.e. how tasks are
+related to each other) and the event propagation (i.e. how events call and/or
+emit each other). The set of task relations to display has to be selected on
+the configuration part of the relation display, including the colors for each
+displayed relation. For our purposes, we only need the "Hierarchy" and the
+"PlannedBy" relations, so check them in the display configuration, as it is done
+one the image above.
+
+Moreover,
+* go in the "View" menu of the relation display and uncheck "Hide
+  finalized", that will be useful for later.
+* go in the "Task labels" and uncheck "Ownership". Ownership is only useful for
+  multi-robot plans.
+
+**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
+---------------------------------------
+
+Let's get to the first task-related events. Click on the 'Step' button until
+something appears on the display. It should look like the next image:
+
+![](log_replay/goForward_1.png)
+
+The displays shows two plans (black boxes). The left one is the plan as it is
+being executed. The right one is called a _transaction_ and allows to build a
+new plan without interfering with the execution. You don't really need to know
+how it works, only that it does the job. The task description includes the task
+model and the task owners (which is only useful in multi-robot setup). The
+_Task labels_ menu allows to customize that.
+
+The left part 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
+_since the last display point_. It means that, if you go forward 10
+seconds, it will display 10 seconds worth of propagation. In our case, we
+displayed only the first execution cycle and we see that, in this cycle, the
+planning task "start" event has been called and emitted.
+
+The MoveTo plan
+---------------
+
+Advance again using 'Step' until the display looks like this:
+
+![](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 steps further, until something more happens. You should see
+something like this:
+
+![](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 are now in a dark grey instead than a light one. 
+
+The mission of the robot, MoveTo, is therefore finished. From the plan
+management point of view, it makes keeping a reference to it useless. In the
+same way, the tasks that were in the plan for the purpose of fullfilling that
+mission are rendered useless as well and can also be removed. The process which
+removes those tasks is called the <i>garbage collection process</i> and runs at
+the end of the execution cycle.
+
+The general idea is to kill and remove from the plan the tasks that are not
+useful for the achievement of the robot's missions. The "important" tasks for
+the robot is defined by the set of its missions.  These are added by calling
+Plan#add\_mission instead of the Plan#add that we were using until now. Note
+that, by calling the action through the shell, #add\_mission has been called
+automatically by the framework.
+
+Then, the task relations are used to determine what are the tasks, in the plan,
+which are actually useful for those "important" tasks. This is based on the
+convention that if a <tt>a=>b</tt> relation exists, then "b" is useful for "a".
+
+The remaining tasks, i.e. the tasks that are not useful, are killed (if possible)
+and removed from the plan. When it is done, the task is said to be finalized and
+are displayed in dark grey (if they are not hidden in the View menu).
+

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

@@ -0,0 +1,102 @@
+---
+title: Interactive Shell
+sort_info: 400
+--- pipeline:tags,markdown,blocks
+
+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.
+
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+Planners
+--------
+Right now, we saw two different places where code is stored:
+1. the tasks/ files, where task models are defined
+2. the controllers/ files, which is the startup code for the application
+
+What we will see in this section is a third component: the **planners**. These
+planners define the aggregate actions that the robot knows about. As we will see
+later, they also are the user interface of the robot.
+
+Exporting actions to the user's shell
+-------------------------------------
+
+Edit planners/goForward/main.rb and edit so that it looks like this:
+
+{coderay:: ruby}
+ require 'planners/main'
+ class MainPlanner
+   method(:move) do
+       GoForward.new :speed => arguments[:speed]
+   end
+ end
+{coderay}
+
+That exports a very simple action to the user's shell. Now, we can try out the
+Roby shell. First, remove the last three lines in 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}
+
+Now, start the roby application in one console:
+
+    $ scripts/run goForward
+    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:
+
+    $ scripts/shell
+    localhost:48902 >
+
+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:
+
+{coderay:: ruby}
+ > actions
+ => [move]
+{coderay}
+
+The 'action' command lists the available planning methods that are exported
+through the MainPlanner class. Let's try it (**notice the '!' at the end of
+move!**):
+
+{coderay:: ruby}
+ > task = move! :speed => 1
+ => GoForward{speed => 1}:0x48410aa8[]
+ > task.running?
+ => true
+ > task.stop!
+ => []
+ !task GoForward{speed => 1}:0x4850ddb0[] failed
+ !task GoForward{speed => 1}:0x4850ddb0[] stopped by user request
+ > task.running?
+ => false
+{coderay}
+
+The new task is running just after it has been added ! In Roby, a new task, when
+added in the main plan, becomes eligible for _scheduling_, i.e. a special
+component tries to find the best time to start it (which, in our case, is
+"now"). We'll see more about this later.
+{: .warning}
+
+You can see that the action method returns the task that the planning method has
+returned. Even though we are on a remote shell, the returned task object
+supports sending commands, checking its status, emitting events, ...
+

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

@@ -0,0 +1,32 @@
+---
+title: Summary
+sort_info: 900
+--- pipeline:tags,rdoc,blocks
+
+
+* *events* allow you to represent the robot's situations and the commands that the
+  robot accepts
+  * the _Signal_ relation represents reactions: it calls the command of the
+    target when the source is emitted.
+  * the _Forwarding_ relation represents generalization: it emits the target
+    event when the source is emitted, and therefore the _situation_ of the
+    target is a superset of the _situation_ of the source.
+  * event handlers allow to call arbitrary code blocks when an event is emitted.
+* *tasks* allow you to represent the processes that run on the robot.
+  * the _Hierarchy_ relation represents dependencies between tasks.
+* <b>a Roby application</b> allows you to build a controller for a robot
+  * the task models are put in the tasks/ subdirectory
+  * the startup code is put in the robot's controllers/ file
+  * a Roby shell allows to interact with a running application
+  * planning methods can be defined in planners/ROBOT_NAME/main.rb. Those
+    methods define the set of actions that is exported to the Roby shell
+  * it is possible to log execution traces and replay them using
+    <tt>roby-log</tt>
+* <b>error handling</b>
+  * errors in user code are harmless to the Roby application as a whole
+  * the hierarchy relation allows to automatically detect failed dependencies
+  * three means exist to repair errors:
+    - in event handlers
+    - using plan repairs
+    - using exception handlers
+