roby 0.7.3 → 0.8.0

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

@@ -0,0 +1,29 @@
+---
+title: What is Roby?
+routed_title: Introduction
+sort_info: 0
+--- pipeline:rdoc
+
+Roby is a plan manager: it allows to represent, execute and adapt a plan, which
+is a representation of the past, present and future activities of a robot along
+with the information needed to verify that their executin is going well, and to
+manage errors.
+
+Roby is:
+* a task/event model in which one can represent the activities (Roby::Task) and
+  the noticeable situations during execution (Roby::EventGenerator,
+  Roby::Task.event).
+* a set of task relations describing the interactions between the activities
+  (Roby::TaskStructure).
+* a set of event relations describing the reaction the system should have in
+  response to some situations (Roby::EventStructure).
+* error management tools which allow to catch errors during execution and
+  repair them (i.e. let the system manage the error).
+* a mean to modify the plan as it is being executed (Roby::Transaction)
+* (G)UI tools for interacting/controlling the living system.
+* all of that in a multi-robot context.
+
+Roby is the result of my PhD. As such, my PhD thesis can be considered as a
+design document for the system. If you want an overview of the principles, you
+can also refer to the publications I did.
+

data/doc/guide/src/introduction/install.page

@@ -0,0 +1,133 @@
+---
+title: Installation
+sort_info: 100
+--- pipeline:rdoc
+== External dependencies
+Roby requires ruby version 1.8.6 or 1.8.7. Ruby 1.9 is a work in progress, but
+will not work with this release
+
+* The Roby engine needs 
+  * +utilrb+, which is available on RubyForge[http://utilrb.rubyforge.org] as a gem
+  * Facets, available on RubyForge[http://rubyforge.org/projects/facets] or as a gem
+  * ActiveSupport, available on RubyForge[http://rubyforge.org/projects/activesupport] or as a gem
+  * the {Boost C++ library}[www.boost.org], including Boost/Graph
+
+* the documentation generation requires
+  * the RDoc gem (not the default RDoc) for the generation of the API
+  * the webgen gem with coderay and maruku for the generation of the user's
+    guide
+
+* the test suite needs also
+  * FlexMock, available on RubyForge[http://rubyforge.org/projects/flexmock]
+
+* finally, the GUI requires {QtRuby >= 1.4.9}[http://rubyforge.org/projects/korundum], SVG export requires QtRuby to
+  be built with Qt >= 4.3
+
+== Before installation
+
+Before doing anything else, you will need to have the C++ dependencies listed
+above installed on your system:
+* the boost C++ libraries with boost/graph
+* QtRuby >= 1.4.9, compiled with Qt >= 4.3
+
+See the next page for a step-by-step installation on Debian/Ubuntu.
+
+All the rest can be installed with RubyGems
+
+== Setting the environment
+
+As a first step, you should set you environment variables. This is done by
+the following commands.
+
+  export GEM_HOME=$HOME/gems/
+  export ROBYHOME=$HOME/roby
+  export RUBYOPT=-rubygems
+  export PATH=$PATH:$GEM_HOME/bin:$ROBYHOME/bin
+  export RUBYLIB=$RUBYLIB:$ROBYHOME/lib
+
+The +GEM_HOME+ and +ROBYHOME+ should be set to wherever you want these parts to
+be installed. It would be wise to append these lines to your ~/.bashrc so that
+they are executed each time you start a console.
+
+== Debian/Ubuntu: Installing binary dependencies with apt-get
+
+You can install those packages with the following line.
+
+  sudo apt-get install ruby1.8-dev rubygems ruby libopenssl-ruby1.8
+  sudo apt-get install libqt4-ruby1.8 g++ libboost-dev git-core
+
+If you don't have administrative rights on your local pc, contact your system 
+administrator.
+
+== Install using RubyGems
+
+This is as simple as
+
+ gem install roby
+
+RubyGems will then take care of installing Roby dependencies. If you want to run
+the unit tests and/or to generate the user's guide, you will need to do
+
+ gem install --development roby
+
+== Install the development code from GitHub
+
+To do this, you will need to install Roby's gems dependencies yourself. This is
+as simple as
+
+ gem install rake utilrb facets activesupport rdoc webgen maruku coderay flexmock
+
+All you have to do now is changing into your development folder and clone 
+the github repository for roby.
+
+ git clone git://github.com/doudou/roby.git roby
+
+The last parameter (+roby+) is the folder which should be created to put
+roby's files in. You can easily adjust this to your needs.
+
++cd+ into the newly created roby folder.
+
+To work on the development version of roby, check it out with
+
+ git checkout -b next origin/next
+
+Otherwise just stay on the default master branch.
+To finally have a running copy of roby, run
+
+ rake setup
+
+to compile roby on your workstation and you're done. Additionally, you can run
+
+ rake docs
+
+To generate HTML documentation of Roby and its core plugins. The documentation
+is generated in doc/html
+
+=== Staying up to date
+
+To grab the newest updates of roby just change into your robyfolder and run
+
+ git pull
+
+After you merged all possible conflicts between your work and the origin,
+you must run
+
+ rake setup
+
+again.
+
+== Generating the documentation
+
+To generate the documentation, you will need to install the following gems:
+
+ gem install webgen maruku rdoc coderay
+
+Then, the following commands allow to generate separate parts of the
+documentation:
+ rake doc:api   # Generates the API documentation using RDoc
+ rake doc:guide # Generates the user's guide
+ rake doc:plugin_docs # Generate the plugin documentation
+
+Alternatively, you can generate all of the above with
+ rake docs
+

data/doc/{papers.rdoc → guide/src/introduction/publications.page}

@@ -1,5 +1,7 @@
-= Papers
-
+---
+title: Publications
+sort_info: 300
+--- pipeline:tags,rdoc
 These are the papers which present Roby that I published the last years.
 
 * A Software Component for Plan Management in Robotics
@@ -9,3 +11,4 @@ These are the papers which present Roby that I published the last years.
 * A Plan Manager for Multi-Robot Systems - FSR2007
   ({paper}[http://roby.rubyforge.org/papers/roby-2007-fsr.pdf], {slides}[http://roby.rubyforge.org/papers/roby-2007-fsr-slides.pdf])
 
+

data/doc/{videos.rdoc → guide/src/introduction/videos.page}

@@ -1,5 +1,7 @@
-= Videos
-
+---
+title: Demonstration Videos
+sort_info: 400
+--- pipeline:tags,rdoc
 == Normal operations
 
 Those videos don't show what Roby itself does, only results showing

data/doc/guide/src/plugins/fault_tolerance.page

@@ -0,0 +1,44 @@
+---
+title: Fault Injection <a href="fault_injection/index.html">[API]</a>
+sort_info: 100
+--- name:content pipeline:tags,markdown,blocks
+
+This is a fault injection plugin for the Roby robotic control framework. It
+allows to test the management of rarely occuring events by simulating the
+emission of those events. This plugin relies only on the core Roby library.
+
+Usage
+-----
+
+The fault injection plugin can be used in a system to inject some spurious
+events randomly. To set it up, one must call Application#add\_fault\_model
+in the configuration files of the application. For instance,
+
+{coderay:: ruby}
+Roby.app.add_fault_model P3d::Track,
+      :no_path, :blocked,
+      Roby::FaultInjection::Rate.new(500, 0.3)
+{coderay}
+  
+Would inject events no\_path and blocked randomly on any task of the P3d:Track
+model. The probability distribution used is a rate distribution with MTTF of
+500s and base probability of 0.3. See Roby::FaultInjection in the plugin's API
+documentation for the description of the available probability distributions.
+
+Enabling the plugin
+-------------------
+
+The plugin must be enabled in the configuration files (i.e. either in
+<tt>config/init.rb</tt> or in one of the robot-specific files) through a call
+to Roby.app.using:
+
+{coderay:: ruby}
+Roby.app.using 'fault_injection'
+{coderay}
+
+License
+-------
+
+This work is licensed under the CeCiLL-B license, which is a free software
+license similar to the BSD license. See License.txt for details.
+

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

@@ -0,0 +1,11 @@
+---
+title: Standard Plugins
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+
+A few generally useful plugins are shipped with the standard Roby installation.
+The following pages describes them and tells you how to enable them in your Roby
+controller.
+
+
+

data/doc/guide/src/plugins/subsystems.page

@@ -0,0 +1,45 @@
+---
+title: Subsystems <a href="subsystems/index.html">[API]</a>
+routed_title: Subsystems
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+
+This is a plugin for the Roby robotic control framework. It allows to generate
+an initial plan in which a set of common subsystems (sensors, localization,
+...) are already initialized, easing later the writing and management of the
+planning methods for other, more dynamical actions.
+
+Usage
+-----
+
+A set of services can be defined on <tt>State.services</tt> in the configuration
+files like this:
+
+{coderay:: ruby}
+State.services.localization = 'pom'
+State.services.camera = 'cam'
+{coderay}
+
+Then, at controller initialization and before the controller file is actually
+loaded, the corresponding planning methods are called on MainPlanner to generate
+a plan in which those subsystems are present:
+
+{coderay:: ruby}
+planner.localization(:id => 'pom')
+planner.camera(:id => 'cam')
+{coderay}
+
+The returned tasks are also started, in order. The controller file gets loaded
+only when the subsystems are ready (i.e. their start events are emitted).
+
+Enabling the plugin
+-------------------
+
+The plugin must be enabled in the configuration files (i.e. either in
+<tt>config/init.rb</tt> or in one of the robot-specific files) through a call
+to Roby.app.using:
+
+{coderay:: ruby}
+Roby.app.using 'subsystems'
+{coderay}
+

data/doc/guide/src/relations/dependency.page

@@ -0,0 +1,89 @@
+---
+title: TaskStructure::Dependency
+sort_info: 100
+--- name:content pipeline:tags,rdoc,blocks
+
+== Semantics
+The dependency relation is is a <i>dependency</i> relation. If task t1 is a
+parent of task t2 in that relation, it means that the successful execution of
+t1 requires the successful execution of t2.
+
+To add a new dependency relation between two tasks +t1+ and +t2+, simply do
+  t1.depends_on t2
+
+More specifically, the dependency relation expresses that +t2+ must achieve a
+specific thing for +t1+. In Roby, such an achievement is of course defined by a
+set of events.
+
+So, in Roby terms, _depends\_on_ specifies that +t2+ should achieve a specific
+thing for +t1+. By default, that achievement is the _success_ of the child task.
+That can be changed through the +:success+ option of _depends\_on_. By default,
+that set is <tt>:success</tt> (i.e. +t1+ requires a successful execution of
++t2+). As another example, the following
+  t1.depends_on t2, :success => [:updated]
+
+specifies that +t1+ needs +t2+ to emit its _updated_ event at least once. The
+default is obviously equivalent to
+  t1.depends_on t2, :success => [:success]
+
+A different constraint that can be specified is that some events <b>should
+not</b> be emitted. That is specified through the +:failure+ option. For
+instance, if it is required that +t2+ does not stop while +t1+ is running, do
+  t1.depends_on t2, :success => [], :failure => [:stop]
+
+Note that it does _not_ specify that +t2+ should run as long as +t1+ runs: to do
+that, you would need to specify that +t2+ must be started when +t1+ is started
+with (for instance):
+  t1.on :start, t2, :start
+
+The relation constraint is one-shot: if any of the success events have already
+been emitted, then the failure events do not matter anymore. For instance, if
+the following relation is added:
+  t1.depends_on t2, :success => [:updated], :failure => [:success]
+
+Then as soon as +:updated+ is emitted, the emission of +:success+ is not a
+failure anymore. In a same way, as soon as +:success+ is emitted then the
+emission of +:updated+ will not be considered as a success anymore.
+
+== Manipulation
+A dependency relation is added with the #depends_on call. Apart from the
++:success+ and +:failure+ options described above, one other option is
+available: the +:remove_when_done+ option. If set to true, as for instance
+  t1.depends_on t2, :remove_when_done => true
+
+then the relation is automatically removed as soon as it is not useful anymore
+(i.e. one of the success events is emitted).
+
+A dependency relation is removed with #remove_child
+  t1.remove_child t2
+
+Children are enumerated with
+  t1.each_child { |t2, options| ... }
+  t1.children => enumerator
+
+and parents with
+  t2.each_parent { |t1| ... }
+  t2.parents => enumerator
+
+Moreover, dependency relationship between two tasks can be tested with the
+following predicates:
+  t2.depended_upon_by?(t1)
+returns true if t2 is a dependency of t1: t2 is a direct child of t1.
+  t1.depends_on?(t2)
+returns true if t1 depends on t2 in one way or the other, i.e. that t2 is a
+child or a grandchild or a grand-grandchild or ... of t1.
+  t1.depends_on?(t2, false)
+returns true if t1 directly depends on t2: t1 is a direct parent of t2.
+
+== Errors
+
+The two types of errors that can occur in the context of a dependency relation
+are:
+* no success event will ever be emitted (see event
+  unreachability:"/objects/events")
+* one of the failure events is emitted
+
+In both cases, a {rdoc_class: ChildFailedError} exception is generated. In the
+first case, the failure point is the success event generator that is
+unreachable. In the second case, it is the event that triggered the failure.
+

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

@@ -0,0 +1,12 @@
+---
+title: Task and Event Relations
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+
+This section is a reference for the task and event relations. As you should
+already know now, these relations are used to build the plans that are executed
+by Roby.
+
+Look at the main menu on the right, and pick the relation you more information
+on !
+

data/doc/misc/update_github

@@ -0,0 +1,24 @@
+#! /bin/sh
+
+PAGES_BRANCH=gh-pages
+DOC_DIR=doc/html
+
+set -e
+
+git reset -q HEAD
+
+# Create the tree object
+git add -f $DOC_DIR
+tree=$(git write-tree --prefix=$DOC_DIR)
+
+echo "resetting the $PAGES_BRANCH branch"
+commit=$(echo $msg | git commit-tree $tree)
+
+if test -n "$commit"; then
+    # And finally update the tip of the branch
+    git update-ref "refs/heads/$PAGES_BRANCH" "$commit"
+fi
+
+git reset -q HEAD
+git push github +$PAGES_BRANCH:$PAGES_BRANCH
+

data/doc/tutorials/02-GoForward.rdoc

@@ -160,16 +160,16 @@ the application and wait for the "done initialization" line.
   0
   0
 
-Now, start a shell and wait its prompt.
+Now, leave the controller running and start a shell in another console. Wait its prompt.
 
   $ scripts/shell
   >>
 
-Let's now check that the <tt>move</tt> action does exist
+The <tt>move</tt> action does exist
   >> actions
   => [move]
 
-... and start the move
+And can be started ...
   >> m = move! :speed => 0.2
   => GoForward{speed => 0.2}:0x4886b248[]
 

data/ext/graph/graph.cc

@@ -79,6 +79,26 @@ VALUE graph_each_vertex(VALUE self)
     return self;
 }
 
+/* call-seq:
+ *    graph.size => vertex_count
+ *
+ * Returns the number of vertices in +graph+
+ */
+static
+VALUE graph_size(VALUE self)
+{
+    RubyGraph& graph = graph_wrapped(self);
+
+    vertex_iterator begin, end;
+    tie(begin, end) = vertices(graph);
+
+    size_t count = 0;
+    for (vertex_iterator it = begin; it != end; ++it)
+	++count;
+    return UINT2NUM(count);
+}
+
+
 /*
  * call-seq:
  *  graph.insert(vertex)		    => graph
@@ -122,6 +142,30 @@ VALUE graph_remove(VALUE self, VALUE vertex)
     return self;
 }
 
+/*
+ * call-seq: graph.clear => graph
+ *
+ * Removes from graph all vertices that are in graph
+ */
+static
+VALUE graph_clear(VALUE self)
+{
+    RubyGraph&	graph = graph_wrapped(self);
+
+    vertex_iterator begin, end;
+    tie(begin, end) = vertices(graph);
+    for (vertex_iterator it = begin; it != end; ++it)
+    {
+        VALUE vertex_value = graph[*it];
+        graph_map&  vertex_graphs = vertex_descriptor_map(vertex_value);
+
+        graph_map::iterator it = vertex_graphs.find(self);
+        vertex_graphs.erase(it);
+    }
+    graph.clear();
+    return self;
+}
+
 /*
  * call-seq:
  *  graph.include?(vertex)		    => true of false
@@ -500,6 +544,7 @@ extern "C" void Init_roby_bgl()
     rb_define_alloc_func(bglGraph, graph_alloc);
 
     // Functions to manipulate BGL::Vertex objects in Graphs
+    rb_define_method(bglGraph, "size",    RUBY_METHOD_FUNC(graph_size), 0);
     rb_define_method(bglGraph, "insert",    RUBY_METHOD_FUNC(graph_insert), 1);
     rb_define_method(bglGraph, "remove",    RUBY_METHOD_FUNC(graph_remove), 1);
     rb_define_method(bglGraph, "include?",  RUBY_METHOD_FUNC(graph_include_p), 1);
@@ -508,6 +553,7 @@ extern "C" void Init_roby_bgl()
     rb_define_method(bglGraph, "linked?",   RUBY_METHOD_FUNC(graph_linked_p), 2);
     rb_define_method(bglGraph, "each_vertex",	RUBY_METHOD_FUNC(graph_each_vertex), 0);
     rb_define_method(bglGraph, "each_edge",	RUBY_METHOD_FUNC(graph_each_edge), 0);
+    rb_define_method(bglGraph, "clear",	RUBY_METHOD_FUNC(graph_clear), 0);
 
     bglVertex = rb_define_module_under(bglModule, "Vertex");
     rb_define_method(bglVertex, "related_vertex?",	RUBY_METHOD_FUNC(vertex_related_p), -1);