roby 0.7.3 → 0.8.0

data/bin/roby

@@ -8,7 +8,7 @@ require 'fileutils'
 require 'yaml'
 require 'find'
 
-require 'roby/app'
+require 'roby'
 
 MODES = %w{init robot}
 config = OpenStruct.new

data/bin/roby-log

@@ -75,13 +75,24 @@ when "stats"
     filename = if ARGV[0] == "--csv"
 		   do_csv = true
 		   ARGV[1]
-	       else
+               elsif ARGV[0] == "--help"
+                   puts "roby-log stats [--csv]"
+                   puts "  displays statistics about the execution timings"
+                   puts "  if the --csv option is given, a table with all"
+                   puts "  the timings is output on stdout instead"
+                   exit(0)
+               else
 		   ARGV[0]
 	       end
     io = Roby::Log.open(filename)
 
     cycle_count = io.index_data.size
-    puts "#{cycle_count} cycles between #{io.range.first.to_hms} and #{io.range.last.to_hms}"
+    timespan    = io.range
+    puts "#{cycle_count} cycles between #{timespan.first.to_hms} and #{timespan.last.to_hms}"
+    cpu_time = io.index_data.inject(0) { |old, info| old + info[:cpu_time] } / 1000
+    real_time = timespan.last - timespan.first
+    ratio = cpu_time / real_time
+    puts "Time: %.2fs CPU / %.2fs real (%i%% CPU use)" % [cpu_time, real_time, ratio * 100]
 
     if io.index_data.first.has_key?(:event_count)
 	min, max = nil
@@ -116,13 +127,12 @@ when "replay"
 		    stream.open
 		    main.add_stream(stream)
 		end
-	    else
-		STDERR.puts parser
-		exit(0)
 	    end
 	else
 	    remaining.each do |file|
-		if streams = Roby.app.data_streams_of([file])
+                if !File.exists?(file)
+		    STDERR.puts "WARN: #{file} does not exist"
+		elsif streams = Roby.app.data_streams_of([file])
 		    streams.each do |s|
 			s.open
 			main.add_stream(s)

data/doc/guide/.gitignore

@@ -0,0 +1,2 @@
+out/
+webgen.cache

data/doc/guide/config.yaml

@@ -0,0 +1,34 @@
+# This is the YAML configuration file for webgen used to set configuration options.
+#
+# The general syntax is:
+#
+#   configuration.option.name: value
+#
+# For example, to set a different default language, you would do:
+#
+#   website.lang: de
+#
+# Have a look at the documentation of the individual configuration options to see
+# the allowed format of the values. Since this is a YAML file, you can easily set
+# configuration options to strings, integers, dates, arrays, hashes and more.
+#
+# The available configuration options can be listed using the `webgen config`
+# command, for example: `webgen config sourcehandler` will list all options starting
+# with sourcehandler.
+default_processing_pipeline:
+    Page: rdoc,tags,blocks
+
+
+default_meta_info:
+    Webgen::SourceHandler::Page:
+        in_menu: true
+
+tag.menu.nested: false
+
+tag.breadcrumbtrail.omit_index_path: true
+
+rdoclinks.base_url: /api
+rdoclinks.base_module: Roby
+
+tag.coderay.line_numbers: false
+tag.coderay.lang: ruby

data/doc/guide/ext/init.rb

@@ -0,0 +1,14 @@
+# = webgen extensions directory
+#
+# All init.rb files anywhere under this directory get automatically loaded on a webgen run. This
+# allows you to add your own extensions to webgen or to modify webgen's core!
+#
+# If you don't need this feature you can savely delete this file and the directory in which it is!
+#
+# The +config+ variable below can be used to access the Webgen::Configuration object for the current
+# website.
+config = Webgen::WebsiteAccess.website.config
+
+$LOAD_PATH.unshift File.expand_path('..', File.dirname(__FILE__))
+require 'ext/rdoc_links'
+require 'ext/previous_next'

data/doc/guide/ext/previous_next.rb

@@ -0,0 +1,40 @@
+require 'webgen/tag'
+class PrevNextTag
+    include Webgen::Tag::Base
+
+    def call(tag, body, context)
+        node = context.content_node
+        while !node.is_file?
+            node = node.parent
+        end
+
+        siblings = node.parent.children.sort
+        siblings.delete_if { |n| !n.meta_info['in_menu'] }
+        prev, _ = siblings.
+            enum_for(:each_cons, 2).
+            find { |prev, this| this == node }
+        _, nxt = siblings.
+            enum_for(:each_cons, 2).
+            find { |this, nxt| this == node }
+
+        content = if tag == "next" && nxt
+                      node.link_to(nxt)
+                  elsif tag == "previous" && prev
+                      node.link_to(prev)
+                  end
+
+        if content
+            if !body.empty?
+                body.gsub '%', content
+            else
+                content
+            end
+        end
+    end
+end
+
+config = Webgen::WebsiteAccess.website.config
+config['contentprocessor.tags.map']['previous'] = 'PrevNextTag'
+config['contentprocessor.tags.map']['next'] = 'PrevNextTag'
+
+

data/doc/guide/ext/rdoc_links.rb

@@ -0,0 +1,33 @@
+require 'webgen/tag'
+class RdocLinks
+    include Webgen::Tag::Base
+
+    def call(tag, body, context)
+        name = param('rdoclinks.name')
+        if base_module = param('rdoclinks.base_module')
+            name = base_module + "::" + name
+        end
+
+        if name =~ /(?:\.|#)(\w+)$/
+            class_name  = $` 
+            method_name = $1
+        else
+            class_name = name
+        end
+
+        path = class_name.split('::')
+        path[-1] += ".html"
+        url = "#{param('rdoclinks.base_url')}/#{path.join("/")}"
+
+        "<a href=\"#{context.ref_node.route_to(url)}\">#{param('rdoclinks.name')}</a>"
+    end
+end
+
+config = Webgen::WebsiteAccess.website.config
+config.rdoclinks.name        "", :mandatory => 'default'
+config.rdoclinks.base_webgen "", :mandatory => false
+config.rdoclinks.base_url    "", :mandatory => false
+config.rdoclinks.base_module nil, :mandatory => false
+config.rdoclinks.full_name   false, :mandatory => false
+config['contentprocessor.tags.map']['rdoc_class'] = 'RdocLinks'
+

data/doc/guide/index.rdoc

@@ -0,0 +1,16 @@
+= Roby's User's Guide
+
+This guide is *definitely* a work in progress -- actually it is for now an
+embryo of a user's guide, but things should improve ...
+
+For people which want to extend Roby, see {this
+guide}[link:files/doc/extending/index_rdoc.html]
+
+== Table of Contents
+
+* {Table of Contents}[link:files/doc/using/index_rdoc.html]
+
+
+* {Overview}[link:files/doc/using/overview_rdoc.html]
+* {Plan modifications}[link:files/doc/using/plan_modifications_rdoc.html]
+

data/doc/guide/overview.rdoc

@@ -0,0 +1,62 @@
+= Overview
+
+This page describes the various components that form a Roby application. It is
+meant to be an "entry point" for people to understand what classes are there
+for. This describes the software architecture of the upcoming v0.8.
+
+== Life and death of a Roby Controller
+
+One Roby::Application instance is created per Roby controller. This class sets
+up the various central objects (Roby::Plan, Roby::ExecutionEngine and Roby::DecisionControl, see
+below), starts the execution engine and loads the relevant configuration files.
+
+A Roby controller offers a DRb main server which is a Roby::Interface instance.
+The best way to interact through this channel is to use a Roby::RemoteInterface
+instance, which handles some custom marshalling/demarshalling of data, offering
+a transparent interface to the remote controller. The <tt>scripts/shell</tt>
+default script sets this up properly.
+
+A Roby controller will shut down in the following conditions:
+* CTRL+C is hit in the controller's main terminal
+* the 'exit' command is sent through the remote shell
+* a framework exception is detected, meaning an exception which is not part of
+  the plan-based error recovery mechanism (everything but event commands, event
+  handlers and polling blocks).
+
+== Plan execution
+
+The plan representation and the plan execution is handled by three objects:
+* a Roby::Plan object which manages the various tasks and events which describe the
+  system's plan.
+* an Roby::ExecutionEngine object which manipulates that Roby::Plan object. It propagates
+  events according to a set of "initial event", a set of events that are
+  considered to be emitted. They can be generated by external communication (for
+  instance from external robotic control frameworks like GenoM or Orocos), or
+  internally by the scheduler object (see ExecutionEngine#scheduler). The engine
+  is also responsible for reaction to errors and for the garbage collection
+  mechanism, through which tasks that are useless for the system's goals are
+  automatically killed and removed.
+* a Roby::DecisionControl object which handles runtime error resolution (i.e.
+  situations which require choosing between multiple course of action). For
+  instance, if a signal leads to a task conflict -- i.e. if the signal would
+  start a task which conflicts with another task -- the DecisionControl#conflict
+  method is called. The default policy is to postpone starting the new task
+  until all the conflicting tasks are stopped. Other policies could be to raise
+  an error for instance.
+
+The three "main" instances of these objects -- i.e. the ones that are supposed
+to interact directly with the underlying robotic system -- are available
+through the Roby.plan, Roby.engine and Roby.control attributes. These
+attributes are set up at application start by Roby::Application#run (see below).
+This is for an easy access in the main controller, but the architecture allows
+to run multiple plans in parallel by binding those three different objects
+yourself.
+
+== A note about multi-robot systems
+
+Until now, the Roby plan manager is able to run <b>bi-robot</b> plans, i.e.
+plans where only two robots are interacting with each other. Extending that to
+multi-robot is definitely on the TODO list of the project, but unfortunately it
+will wait until multi-robot is back at the the center of my research. If you are
+interested in doing it, of course, feel free to contact me ;-)
+

data/doc/guide/plan_modifications.rdoc

@@ -0,0 +1,67 @@
+= Plan representation and modifications to plans
+
+Understanding the plan model, and how to modify it, is central to the use of
+Roby. In effect, the plan *is* the information on which the controller bases
+itself to control the robot ...
+
+== Plan objects
+In Roby, plans are made of tasks and events. See {my
+papers}[link:files/doc/papers_rdoc.html] for an in-depth description of the
+model.
+
+On the one hand, Roby::EventGenerator instances represent the plan's _possible_
+events. This is by contrast to the Roby::Event class, whose instances represent
+the <em>actual events</em>. In other words, an Event instance represent an
+event which has already been emitted while an EventGenerator instance
+represents a source of events, therefore a kind of events that could possibly
+be emitted.
+
+On the other hand, instances of Roby::Task represent the activities of the
+system. Special subclasses of Roby::EventGenerator and Roby::Event are used in
+tasks, to represent some particular properties of task's events:
+Roby::TaskEventGenerator and Roby::TaskEvent.
+
+== Plan relations
+Roby::EventGenerator instances can be linked to each other through the use of
+<em>event relations</em>, as Roby::Task can be linked through the use of <em>task relations</em>.
+Task and event relations are defined in the Roby::EventStructure and
+Roby::TaskStructure relation spaces (Roby::RelationSpace instances), through the use of
+Roby::RelationSpace#relation. Each relation object (for instance
+Roby::EventStructure::Signal or Roby::TaskStructure::Hierarchy) is an instance
+of the Roby::RelationGraph class.
+
+In order to be managed in these relations, tasks and events
+include the Roby::DirectedRelationSupport mixin to provide the basic
+management tools needed by the RelationGraph instances. Moreover, all relation
+types define specific methods which allow to more directly modify the relation
+(like #add_signal, #each_parent or #parents in Hierarchy). See RelationSpace#relation
+for details. Due to issues with Ruby's documentation system, those methods are
+listed in 
+
+=== Plan modification
+Modifying the plan therefore boils down to two things:
+1. adding and removing tasks and events in the plan
+2. adding and removing relations between objects of the same type (between tasks
+   or between events).
+
+The first point is done by the following methods:
+* Roby::Plan#discover: simply add tasks and events
+* Roby::Plan#add_mission: adds special tasks, called missions. Missions are the
+  tasks the robot is supposed to execute. They are not subject to the plan's
+  garbage collection, and the tasks that are useful to them are not either.
+
+
+To ease the plan management process, some synthetic
+operations are defined on Roby::Plan:
+* the _replacement_ operation: Roby::Plan#replace_task and
+  Roby::Plan#replace. #replace_task(a, b) will replace +a+ by +b+ in the plan.
+  It means that the operators will add to +b+ all the children and parents of +a+
+  in all relations, and do the same with +b+ and +a+'s events. Moreover, it will
+  remove them from +a+. #replace(a, b) will do the same, but constraining itself
+  to the _parents_ of +b+ and +b+'s events. It therefore replaces +a+ and its
+  generated subplan (i.e. +a+ and all children of +a+) by +b+ and its subplan.
+* the _respawning_ operation: a given task is replaced by a new task of the same
+  kind and with the same parameters. This is used mainly to workaround a
+  "fragile" task which crashed spuriously.
+
+

data/doc/guide/src/abstraction/achieve_with.page

@@ -0,0 +1,8 @@
+---
+title: Achieving event commands with tasks
+sort_info: 400
+--- name:content pipeline:tags,markdown,blocks
+
+* the achieve\_with operator
+* semantics of it
+* what happens when an error occurs ?

data/doc/guide/src/abstraction/forwarding.page

@@ -0,0 +1,8 @@
+---
+title: The forwarding relation
+sort_info: 300
+--- name:content pipeline:tags,markdown,blocks
+
+* we already saw its usefulness inside tasks
+* semantics of forwarding in-between tasks
+* example: loops

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

@@ -0,0 +1,19 @@
+---
+title: Abstraction as task dependencies
+sort_info: 200
+--- name:content pipeline:tags,markdown,blocks
+
+Dependency relations
+--------------------
+* Dependency is also a refinement relation
+* the syntax and other concepts
+  - depends\_on :model
+  - fullfilled\_model
+  - fullfilled\_events
+
+Plan modifications and model abstraction
+----------------------------------------
+
+* the replace operator
+* semantics of the :returns flag in this context
+

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

@@ -0,0 +1,28 @@
+---
+title: Representing Abstraction
+routed_title: Representing Abstraction
+sort_info: 0
+--- name:content pipeline:tags,markdown,blocks
+Being able to abstract away the little details of execution is crucial. Indeed,
+it allows to apply high-level reasoning algorithms, that are not able to take
+into account too much details.
+
+Roby offers a unique ability: to link in the same plan the high-level parts of
+the plan and the low-level ones. What this section will present is how, using
+Roby's plan model, one can represent the _mechanism_ of abstraction. In other
+words, what are the details that are lost in the abstraction mechanism.
+
+More specifically, we will see the following:
+
+* the object-oriented nature of Roby's plan model: how task models are related
+  to each other, and the notion of abstract models.
+* how the hierarchy relation uses this OO principles to not over-constrain the
+  plan. We will see that the hierarchy relation can be used to precisely
+  represent what is _needed_ and not only what _is_.
+* how the execution flow of the low-level parts of the plan can be linked to the
+  higher-level execution flow by means of the _forwarding_ relation.
+* how it is possible to cleanly (and easily) build event commands using tasks
+
+To understand the content of this section, we will assume that you read and
+understood the [basics](../basics/index.html).
+

data/doc/guide/src/abstraction/task_models.page

@@ -0,0 +1,13 @@
+---
+title: Task Models
+sort_info: 100
+--- name:content pipeline:tags,markdown,blocks
+
+* relationship between models
+  - semantics of subclasses
+  - rules of subclasses
+  - the TaskModelTag hack
+* abstract models
+  - why is it useful => abstract actions that have to be chosen later on.
+  - syntax
+  - the :returns flag in planning models => example

data/doc/guide/src/basics.template

@@ -0,0 +1,6 @@
+---
+template: default.template
+--- pipeline:tags,blocks
+<webgen:block name="content" />
+
+--- name:navbar

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

@@ -0,0 +1,139 @@
+---
+title: A First Roby Application
+sort_info: 300
+--- pipeline:tags,markdown,blocks
+
+This page will present another facet of Roby. What we saw until now is how,
+in Roby, one can represent the task actions and build plans that describe the
+task execution. What we will see here is how Roby tie the different models
+together to offer an application environment.
+
+{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
+
+Creation
+--------
+
+Go into a *regular shell* (i.e. not the Ruby shell) and create a new directory.
+That directory will become your first Roby application by running "roby init":
+
+    $ mkdir first_app
+    $ cd first_app
+    $ roby init
+    creating tasks/
+    creating tasks/.gitattributes
+    creating scripts/
+    creating scripts/test
+    creating scripts/shell
+    creating scripts/server
+    creating scripts/run
+    creating scripts/results
+    creating scripts/replay
+    creating scripts/generate/
+    creating scripts/generate/bookmarks
+    creating scripts/distributed
+    creating planners/
+    creating planners/main.rb
+    creating data/
+    creating data/.gitattributes
+    creating controllers/
+    creating controllers/.gitattributes
+    creating config/
+    creating config/roby.yml
+    creating config/init.rb
+    creating config/app.yml
+    creating Rakefile
+    creating README.txt
+
+There's a lot of stuff created, but don't worry we'll learn what this is all
+about later on. Right now, we're only interested in two small parts of it:
+
+* the tasks/ directory, which is where task models (task classes) should be
+  defined
+* the robot's controllers. These files contain the code that is run when the
+  application is started.
+
+The goForward robot
+-------------------
+As an introduction, we will create a simulated robot controller which makes the
+robot go forward at constant speed.
+
+First, let's create the files specific to this robot
+
+    $ roby robot goForward
+    creating planners/goForward/
+    creating planners/goForward/main.rb
+    creating tasks/goForward/
+    creating tasks/goForward/.gitattributes
+    creating controllers/goForward.rb
+    creating config/goForward.rb
+
+Let's define the task model. Edit tasks/go\_forward.rb and add
+
+{coderay:: ruby}
+ class GoForward < Roby::Task
+   # The GoForward task needs the robot speed to be specified
+   arguments :speed
+
+   # Block called at every execution loop if the task is running. It simulates
+   # the robot moving at the specified speed.
+   poll do
+     State.pos.x += speed
+   end
+
+   # This task does not need any specific action to stop
+   terminates
+ end
+{coderay}
+
+In the controller file, controllers/goForward.rb, we add the code that
+should run at startup:
+
+{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
+
+ # Create the task and start moving !
+ Roby.plan.insert(go = GoForward.new(:speed => 0.1))
+ puts "Going forward at speed #{go.speed}"
+ go.start!
+{coderay}
+
+You can then start the robot controller with scripts/run and stop it with CTRL+C.
+
+    $ scripts/run goForward
+    335705:25:08.324 (goForward) loading controller file /home/doudou/dev/roby-tutorials/controllers/goForward.rb
+    Going forward at speed 0.1
+    335705:25:08.356 (goForward) done initialization
+    0
+    0.9
+    1.9
+    2.9
+    335705:25:16.449 (Roby) received interruption request
+    335705:25:16.524 (Roby) control quitting. Waiting for 1 tasks to finish (1 tasks still in plan)
+
+Broken down explanation
+-----------------------
+* the Roby::State object holds all the configuration and state data that
+  represents the robot's state. In our case, we initialize the robot's position
+  in the controller file, and then update it when the robot moves.
+
+* to understand the meaning of the __poll__ statement, you have to understand
+  the idea behind Roby's execution model. Roby relies on a _synchronous_
+  execution model, which is basically a two-steps loops (a more detailed
+  explanation will come later). This two-steps loops is basically:
+  1. gather all events that have occured since the last loop
+  2. propagate to those events through the signal and forward relations
+
+  In practice, this event loop runs with a fixed period which is by default
+  100ms. This period can be changed in the configuration file config/app.yml.
+
+  Now, what is the role of __poll__ here ? The block given to +poll+ is executed
+  at each execution cycle _while the task is running_. It can therefore be
+  used to _implement_ the actual task functionality (or to check the state of
+  external processes, ...)
+