roby 0.8.0 → 3.0.0

data/doc/guide/src/advanced_concepts/scheduling.page

@@ -0,0 +1,87 @@
+---
+title: Scheduling
+sort_info: 5
+---
+
+Roby plans are encoding a lot of things. One thing they do not encode in general
+is __exactly__ which tasks should be started at every point in the execution.
+
+It would in principle be possible: one could use the signal relation to
+completely define the execution flow. However, this is both not very practical,
+and would break one of the main ideas behind Roby: that one should encode as
+much information as possible to represent the _context_ of running activities,
+and enough constraints to verify that the execution goes well. Based on that
+information, global reasoning can then be used to maintain the system in a "good
+state".
+
+In this scheme, the scheduling object is the object that decides which tasks
+should be started in the plan. This page will tell about the two existing
+scheduling objects (the basic and temporal schedulers), and will then talk about
+the generic scheduler interface in Roby.
+
+The basic scheduler
+-------------------
+The basic scheduler will start any task that is needed and for which the start
+event has no explicit mean of synchronization. It means that it will start a
+task that:
+ 
+ * is either toplevel or has a parent running in [the dependency
+   relation](../task_relations/dependency.html) (is needed by a running task).
+ * has a start event that is not the target of an edge in either the signal and
+   forward relations (won't be started explicitly because of one of these
+   relations).
+
+The temporal scheduler
+-------------------
+The temporal scheduler adds on top of the basic scheduler the ability to specify
+temporal constraints between any event and the task's start event. Moreover, it
+allows to tie the ability to schedule a task to the ability to schedule another.
+
+More specifically, the temporal scheduler will start a task if:
+
+ * it is either toplevel or has a parent running in [the dependency
+   relation](../task_relations/dependency.html) (is needed by a running task).
+   This is so unless there is a temporal constraint between the child and the
+   parent (in which case the child will be started before its parent).
+ * has a start event that is not the target of an edge in either the signal and
+   forward relations (won't be started explicitly because of one of these
+   relations).
+ * emitting the start event would not violate [temporal
+   constraints](../event_relations/temporal_constraints.html)
+ * if child in the [scheduling constraint
+   relation](../event_relations/scheduling_constraints.html), the parent has to
+   be schedulable.
+
+A simple example of the usage of temporal constraints is to specify a sequence:
+
+~~~ ruby
+t2.should_start_after t1
+~~~
+
+__How is this different from using the signal relation ?__ A sequence of tasks
+T1 and T2 for which there is a signal between T1.stop_event and t2.start_event
+means "t2.start MUST be called JUST AFTER t1.stop has been emitted". Adding a
+temporal constraint means that t2.start MAY be called as long as t1.stop has
+been emitted. The scheduler can decide to call it anytime after.
+{: .block}
+
+A simple example of the usage of both temporal constraints and scheduling
+constraints is to add a plan pattern to a sequence, requiring that the planner
+should only run when the task should be started (and not before).
+
+~~~ ruby
+t2.should_start_after t1
+t2.should_start_after t2.planning_task
+t2.planning_task.schedule_as(t2)
+~~~
+
+Choosing the scheduler
+----------------------
+The scheduler is in general chosen globally by setting Roby.scheduler. For
+instance:
+
+~~~ ruby
+require 'roby/schedulers/temporal'
+Roby.scheduler = Roby::Schedulers::Temporal.new
+~~~
+

data/doc/guide/src/advanced_concepts/transactions.page

@@ -0,0 +1,5 @@
+---
+title: Transactions
+sort_info: 50
+draft: true
+---

data/doc/guide/src/advanced_concepts/unreachability.page

@@ -0,0 +1,42 @@
+---
+title: Event Unreachability
+sort_info: 10
+---
+
+What we saw about events, so far, is the ability to listen to their emission
+(event handlers) and to trigger this emission (event commands).
+
+Now, let's think a pretty common situation: something is waiting for event A to
+be emitted. In other words, the follow-up execution of the system depends on
+having an event be emitted. But, for whatever reason, this event is __not__
+going to happen.
+
+This is covered by another event-related triggering mechanism: the event
+unreachability. An event generator is marked as unreachable when it is known
+that it cannot be emitted anymore.
+
+By default, this happens for all the generators of a task when the task
+finishes. Other conditions can apply (it can even be done by the tasks
+themselves to provide more information to the rest of the system).
+
+A generator is declared as unreachable by calling unreachable! on it:
+
+{coderay:: ruby}
+task.success_event.unreachable!
+{coderay}
+
+The fact that event becomes unreachable can be listened to with
+EventGenerator#when_unreachable
+
+{coderay:: ruby}
+task.success_event.when_unreachable do |reason|
+end
+{coderay}
+
+Additionally, one can use #when_unreachable without a block. Then, an event
+generator is returned that is emitted when the event becomes unreachable.
+
+A reason can be given, which is then stored in the #unreachability_reason
+attribute of the generator. The reason can be any object but is traditionally
+either an instance of Roby::Event or an instance of Exception.
+

data/doc/guide/src/base.template

@@ -0,0 +1,96 @@
+---
+template: ~
+--- pipeline:erb,tags,blocks,head
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+
+<!-- Recommended XHTML-Editor: HTML-Kit 292 (Freeware) -->
+<!-- http://www.chami.com/html-kit/download/ -->
+
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+  <meta name="description" content="The Robot Construction Kit - a robot software development environment" />
+  <meta name="keywords" content="robotics,toolchain,components,field robotics,underwater robotics" />
+  <meta name="author" content="The Rock core team" />
+  <meta name="google-site-verification" content="xipSGJiBKGluvNX8Y3Wr4zVMDSDJz5HIutUhfQSmXl8" />
+<!--  <link rel="stylesheet" type="text/css" media="screen,projection" href="" />-->
+<!--  <link rel="stylesheet" type="text/css" media="print" href="css/style_print.css" />-->
+   <title>Roby - Plan Management for Robotic Systems</title>
+   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
+</head>
+
+<body>
+  <div class="page-container-2">
+      <div class="nav1-container">
+          <div class="nav1">
+              <webgen:block name="navbar" notfound="ignore"/>
+          </div>
+      </div>
+
+      <div class="site-name" onclick="location.href='{relocatable: /}';" style="cursor: pointer; z-index: 10;">
+          <p class="title">Roby</p>
+          <p class="subtitle">Plan Management for Robotic Systems</p>
+      </div>
+
+      <div class="title_buffer"></div>
+
+      <div class="nav2">			
+          <ul>
+	      <li>{breadcrumb_trail: { separator: '' }}<span class="empty">&nbsp;</span></li>
+          </ul>
+      </div>
+    
+      <div class="buffer"></div>
+
+      <div class="leftnav">
+          <webgen:block name="leftbar" notfound="ignore"/>
+      </div>
+
+    
+      <div class="content2" <%= 'style="margin-left: 110px;"' if context.node.meta_info['rock_page_style'] == 'centered' %>>
+          <% if context.node.node_info[:page].meta_info.has_key?('page_title') %>
+          <div class="content2-pagetitle"><%= context.node.node_info[:page].meta_info['page_title'] %></div>
+          <% else %>
+          <div class="content2-pagetitle">{title: }</div>
+          <% end %>
+          <div class="content2-container line-box">
+              <div class="content2-container-1col">
+                  <% if false %>
+                  <% if context.node.node_info[:page].blocks.has_key?('localtoc') %>
+                  <div markdown="1" class="localtoc">
+                      <webgen:block name="localtoc" />
+                  </div>
+                  <% end %>
+                  <% if context.node.node_info[:page].blocks.has_key?('biglocaltoc') %>
+                  <div markdown="1" class="biglocaltoc localtoc">
+                      <webgen:block name="biglocaltoc" />
+                  </div>
+                  <% end %>
+                  <% end %>
+                  <% if flavors = context.node.node_info[:page].meta_info['only_on'] %>
+                  <div class="warning">
+                  The information present on this page is only valid on the <b><%= flavors %></b> flavors of Rock
+                  </div>
+                  <% end %>
+                  <%= context.node.node_info[:page].meta_info['page_title'] %>
+                  <webgen:block name="content" />
+              </div>
+          </div>
+      </div>
+
+      <!-- FOOTER -->
+      <div class="footer">
+          <div class="nav1">
+              <ul>
+                  <li><a href="http://rock-robotics.org/stable/documentation/about/index.html">About Rock</a></li>
+              </ul>
+          </div>
+      </div>
+  </div>
+</body>
+</html>
+
+<!--
+vim:set ts=2:
+-->
+

data/doc/guide/src/basics_shell_header.txt

@@ -1,16 +1,14 @@
 Code examples
 -------------
 This page includes code samples that you can try out in Ruby or Unix shells. See
-[this page](code_examples.html) for explanations on the notation.
-{.warning}
+[this page]({relocatable: /tutorial/code_examples.html}) for explanations on the notation.
+{: .warning}
 
 Moreover, to run the examples on this page, you must first set up your ruby
 shell:
 
-     $ irb
+     $ irb -rroby/standalone
+
 {coderay:: ruby}
- >> require 'roby/standalone'
- >> include Roby
- >> plan = Roby.plan
+>> plan = Roby.plan
 {coderay}
-

data/doc/guide/src/building/action_coordination.page

@@ -0,0 +1,96 @@
+---
+title: Action Coordination
+sort_info: 210
+---
+
+This page will present the high-level means of coordinating different actions to
+create a high-level system behaviour (i.e. "a mission").
+
+Action State Machines
+---------------------
+The easiest way to create an action is to define a state machine that calls
+other actions and/or some Roby tasks.
+
+~~~ ruby
+class Main
+  describe("move").
+    required_arg('speed', 'the speed it should move at in m/s').
+    optional_arg('time', 'how long it should move in seconds')
+  action_state_machine 'move' do
+    ... state machine definition ...
+  end
+end
+~~~
+
+The string argument to #action_state_machine being the action name. At runtime, the
+state machine will be represented by a toplevel task of the type given in the
+description, or if none is given by the automatically created task type
+mentioned earlier (here: Main::Move).
+
+Within the state machine, states are represented by __single Roby tasks__. These
+tasks are generated by calling #state with an argument which is either
+another action or a Roby task model, and some arguments. Note that the same
+action can be used to define multiple states (even with the same arguments).
+The starting state is defined with the start(state) statement and transitions
+with transition(event, next_state).
+
+~~~ ruby
+state_machine 'move' do
+  # Call other actions to get our states
+  planning  = state path_planning(:target => [10, 10, 0])
+  execution = state path_execution
+
+  start(planning)
+  transition(planning.success_event, execution)
+end
+~~~
+
+Defining a state from an action or task model basically tells Roby to start such
+an action / task each time the state is entered. Moreover, if the task that
+represents the current state terminates through an event for which no
+transitions is defined, this is going to generate a [dependency
+error](../task_relations/dependency.html) (ChildFailedError)
+
+If the action has arguments, they can be referred to as local variables:
+
+~~~ ruby
+describe("move to a given target point").
+  required_arg('target', 'the speed it should move at in m/s')
+state_machine 'move' do
+  planning  = state path_planning(:target => target)
+  execution = state path_execution
+
+  start(planning)
+  transition(planning.success_event, execution)
+end
+~~~
+
+Finally, one needs to tell the system when the toplevel task is terminated. This
+is done, as usual in Roby, by [forwarding](../event_relations/forward.html) a
+state event to a terminal event on the toplevel task:
+
+~~~ ruby
+describe("move to a given target point").
+  required_arg('target', 'the speed it should move at in m/s')
+state_machine 'move_to' do
+  planning  = state path_planning(:target => target)
+  execution = state path_execution
+
+  start(path_planning)
+  transition(path_planning.success_event, path_execution)
+  forward path_execution.reached_the_end_event, success_event
+end
+~~~
+
+As an example, a retry-until-it-works action can be specified with:
+
+~~~ ruby
+state_machine 'wait_until_it_works' do
+  act = state my_action
+  start(act)
+  transition(act.failed_event, act)
+  forward act.success_event, success_event
+end
+~~~
+
+

data/doc/guide/src/building/actions.page

@@ -0,0 +1,124 @@
+---
+title: Actions
+sort_info: 200
+---
+
+As explained in [the introduction of this section](index.html), the action
+interface presented on this page has two roles:
+
+ - to define actual behaviours, that can run on the robot, by coordinating sets
+   of smaller behaviours
+ - to present this set of behaviours to the rest of the Roby application as well
+   as to outside (for instance to a user or to an automated planner). This
+   aspect of the usage of the action interfaces is covered in [another
+   section](../interacting)
+
+This section will describe the capabilities of this interface to __build
+plans__. Modifying running plans is a bit of a harder problem, so we keep it
+for a different time.
+
+In general, an action interface is defined by creating a subclass of
+{rdoc_class: Roby::Actions::Interface}. Action interfaces are defined in
+a file in the models/actions/ subfolder of the Roby application. The file name is usually
+the snake_case version of the class name, as e.g. my_actions.rb for the MyAction
+class:
+
+~~~ ruby
+class MyAction < Roby::Actions::Interface
+end
+~~~
+
+Roby expects an action interface class called Main to exist per Roby
+application, and registers it automatically. The Roby app template creates such
+a class in models/actions/main.rb (or model/actions/myrobot/main.rb for
+per-robot action interfaces). There is generally no point of defining another
+one. To foster reuse of action definitions, one creates an action library:
+
+~~~ ruby
+module MyApp
+  module Movements
+    action_library
+  end
+end
+~~~
+
+Action libraries accept the same statements than the action interfaces, but can
+be added to action interfaces (or other action libraries):
+
+~~~ ruby
+class Main < Roby::Actions::Interface
+  use_library MyApp::Movements
+end
+~~~
+
+Defining actions
+----------------
+Generally speaking, an __action__ is simply "something" that returns a Roby
+task.  It is up to the action to create all the tasks required for the
+behaviour, bind them together using Roby's plan building API and return the
+toplevel task that will represent the action.
+
+This page will not dwelve too much into how to do this. Higher-level
+representations allow to define actions without having to dwelve too much into
+Roby's plan model and plan building API.
+
+In any case, an action definition always start with an action _description_.
+This is done by calling the "describe" statement in the context of the action
+interface class or action library module and then chaining description calls on
+the returned object (which is of type {rdoc_class: Actions::ActionModel}).
+
+~~~ ruby
+class Main
+  describe("move").
+    required_arg('speed', 'the speed it should move at in m/s').
+    optional_arg('time', 'how long it should move in seconds').
+    returns(MoveTo)
+  ... define the actual action ...
+end
+~~~
+
+The way the action name is retrieved depends on the action type. We will
+describe each action type later in this page and talk about this.
+
+One very important attribute is the 'returns' statement. It defines the type of
+task this action is going to return. If it is not provided, one is created by
+the action interface using the action's name but CamelCased. I.e. a move_to
+action would return, by default, a MoveTo task type that is defined in the
+action's namespace (e.g. Main::MoveTo)
+
+Raw Interface
+-------------
+"Raw" actions are the one that are building Roby plans using Roby's plan
+building interface. They are defined as plain methods on the action interface
+class or the action library module. The action name is the name of the method.
+This interface requires a deep understanding of the Roby plan model.
+Higher-level coordination models (presented [on the next
+page](action_coordination.html)) are most often than not enough.
+
+If the action description specifies arguments, then the method must accept to be
+called with an argument of type Hash that is going to get the arguments. If it
+accepts only optional arguments, it is best practice to make that argument
+optional.
+
+__Important__ only methods that are directly preceded by a #describe block are
+turned into actions. You can freely add "helper" methods to the interface.
+{: .block}
+
+~~~ ruby
+class Main
+  describe("move").
+    required_arg('speed', 'the speed it should move at in m/s').
+    optional_arg('time', 'how long it should move in seconds')
+  def move_to(arguments)
+    Main::MoveTo.new(:speed => arguments[:speed], :time => arguments[:time])
+  end
+end
+~~~
+
+One can always call another action from within a raw action method to integrate
+the toplevel task of that action. However, you should really see the returned
+value as an interface (as it should) and never assume anything about the
+subtasks of the returned task. In particular, some actions will return you a
+[planning pattern](runtime.html#planning-pattern) which, at the time the action
+is called, will have no children.
+