roby 0.7

data/doc/tutorials/01-GettingStarted.rdoc

@@ -0,0 +1,86 @@
+{Next tutorial}[link:files/doc/tutorials/02-GoForward_rdoc.html]
+= Getting started
+
+== Initializing an empty Roby application
+Go into a shell into the directory you want your application in and run
+  $ 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
+
+
+You can see that the following directories are created:
+tasks:: definition of task models
+planners:: definition of planner models
+controllers:: definition of the robot controllers
+data:: data files
+config:: robots configurations
+test:: the test suites
+log:: the log files (output of the last run)
+results:: sets of logs that have been saved by scripts/results
+scripts:: the standard Roby tools. Call them with --help to know what they are doing
+
+The .gitattributes in empty directories is a trick allowing to commit an
+empty Roby application with +git+ using
+  git init
+  git add .
+  git commit
+
+Without it, +git+ would ignore those directories.
+
+== Overview of Roby applications structure
+
+In a single Roby application, someone can define multiple specific
+_controllers_, tailored for specific robots. A specific Roby controller is
+defined by a /robot name/ and a /robot type/. These two parameters define what
+models and what configuration files the system will load on startup. Both
+models and configuration files can be sorted into:
+* a set common to all robots and robot types
+* a set specific to all robots of the same type
+* a set specific to a single robot
+
+See Roby::Application for more details on the configuration/models loading logic.
+
+== Creating a simple robot
+
+During the tutorials, we will be creating different robots which is done by the
+<tt>roby robot</tt> command. For instance, run
+  $ roby robot EmptyRobot
+  creating planners/EmptyRobot/
+  creating planners/EmptyRobot/main.rb
+  creating tasks/EmptyRobot/
+  creating tasks/EmptyRobot/.gitattributes
+  creating controllers/EmptyRobot.rb
+  creating config/EmptyRobot.rb
+
+This creates the basic templates for the robot named EmptyRobot. The following
+tutorials will explain their role to you.
+
+= Next tutorial
+
+{The next tutorial}[link:files/doc/tutorials/02-GoForward_rdoc.html] will show you
+the basic plan model used by Roby and some central tool, which allow to execute the
+Roby applications and to interact/control them remotely.
+---
+vim: tw=80

data/doc/tutorials/02-GoForward.rdoc

@@ -0,0 +1,220 @@
+{Previous tutorial}[link:files/doc/tutorials/01-GettingStarted_rdoc.html]
+{Next tutorial}[link:files/doc/tutorials/03-PlannedPath_rdoc.html]
+= The GoForward tutorial: making a simple robot move
+This tutorial will make you create a simulated robot controller which makes the
+robot go forward at constant speed. It will show you what a task is, how to
+start a Roby controller and how to interact with it using the Roby shell.
+
+First, we will define a GoForward task model, represented by a subclass
+of Roby::Task. Tasks, which are instances of this model, have two roles:
+* they _represent_ the 'go forward' activity in the plan. i.e. it represents
+  its properties, allowing to assess that its execution is going well
+* they actually _make_ the robot 'go forward': they execute the code necessary
+  to do it, or activate an external process which will do that.
+
+What we will see here is the second point. The first point will be discussed in
+more details in the fourth tutorial: {error handling}[link:files/doc/tutorials/04-ErrorHandling_rdoc.html]
+
+= A first attempt
+== Writing the robot task model, and writing the robot controller
+Edit <tt>tasks/go_forward.rb</tt> and add
+  class GoForward < Roby::Task
+    # The GoForward task needs the robot speed to be specified
+    arguments :speed
+
+    # Block called at every execution loop. It simulates the robot moving at
+    # the specified speed.
+    poll do
+      State.pos.x += speed
+    end
+
+    # No specific action should be taken to make the task stop
+    terminates
+  end
+
+Now, create the robot we will be working on. In the roby application we
+have created in {the first tutorial}[link:files/doc/tutorials/01-GettingStarted_rdoc.html],
+run
+  roby robot goForward
+
+And in the controller file, <tt>controllers/goForward.rb</tt> do
+  # 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!
+
+You can then start the robot controller with <tt>scripts/run</tt> 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 line
+    State.pos.x = 0 
+  initializes the robot's state. In general, it is done in the robot's
+  configuration file, config/goForward.rb (see below)
+* the line
+    arguments :speed
+  in the task model tells Roby that the GoForward tasks require a 'speed'
+  argument. If it is omitted, the task has no means to actually perform its
+  action (it does not know at what speed it is supposed to move), and therefore
+  cannot be started. Replace
+    Roby.plan.insert(go = GoForward.new(:speed => 0.1))
+  by
+    Roby.plan.insert(go = GoForward.new)
+  and you'll get
+
+    Roby::EventNotExecutable in GoForward{}:0x4854d110[]/start: start! called on GoForward{}:0x4854d110[] which is partially instanciated
+      ./controllers/goForward.rb:15
+
+  a <i>partially instanciated</i> task being a task whose all required
+  arguments are not set.
+
+* 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 in the following tutorials). This two-steps loops
+  is basically:
+  1. gather all events that have occured since the last loop
+  2. react to those events
+
+  What should be noted here is that the duration of this whole execution loop
+  is also a higher bound for the plan-based reaction to new situations. In
+  other words, it means that the worst-case latency between the moment
+  something happens and the moment the system reacts to it is the duration of
+  the execution cycle.  In general, one considers that the duration of the
+  execution cycle should be small with respect to the system's dynamic (the
+  latency in reaction must not have a physical effect).
+
+  Now, what is the role of +poll+ here ? The block given to +poll+ is executed
+  at each execution cycle <i>while the task is running</i>. It can therefore be
+  used to break done lengthy computation in small steps, or represent a computation
+  thread in the plan, using a task (Roby::PlannerTask does this to represent a plan
+  generation thread).
+
+* we did not specify a robot name in the call to <tt>scripts/run</tt>. In that
+  case, Roby instantiated a robot named 'goForward' of type 'goForward'
+* in general, one does not want the robot to start moving just after
+  initialization. To have an interactive interface to the robot's actions, you
+  can use the <tt>scripts/shell</tt> tool. See below.
+
+= Refining the goForward controller
+== File loading at startup and configuration files
+Roby loads many files at startup, whose exact set of files is determined by the
+robot name and type. The general rule is that the files are loaded from the
+least specific ones (i.e. the files common to all robots) to the most specific ones
+(i.e. the files that are specific to a given robot name).
+
+In this tutorial, the <i>task model</i> is global and will be loaded in all
+controllers of this Roby application. The controller file, on the other hand,
+is defined for the goForward robot.
+
+What we want here is move the state initialization from the controller file
+into the robot's configuration file. To do that, you just have to move the
+corresponding line into <tt>config/$NAME.rb</tt>, which is in our case
+<tt>config/goForward.rb</tt>, so that this latter file looks like
+
+  Roby::State.update do |s|
+    # define the original value of x
+    s.pox.x = 0
+  end
+
+and test that everything still works !.
+
+See Roby::Application for an explanation of how files are organized in a Roby
+application.
+
+== Interacting with the Roby controller
+First, we usually don't want to hardcode the robot actions in its controller.
+Instead, it is better to be able to <em>send a command</em> to the robot.  Do
+do that, we must first define an <em>action</em> in the robot's main planner.
+Edit <tt>planners/goForward/main.rb</tt> and add the following code to the
+definition of the MainPlanner class.
+
+  method(:move) do
+      GoForward.new :speed => arguments[:speed]
+  end
+
+and remove the last three lines of controllers/goForward.rb. You can now start
+the application and wait for the "done initialization" line.
+
+  $ scripts/run goForward
+  335814:29:25.107 (goForward) loading controller file /home/doudou/dev/roby-tutorials/controllers/goForward.rb
+  335814:29:25.108 (goForward) done initialization
+  0
+  0
+
+Now, start a shell and wait its prompt.
+
+  $ scripts/shell
+  >>
+
+Let's now check that the <tt>move</tt> action does exist
+  >> actions
+  => [move]
+
+... and start the move
+  >> m = move! :speed => 0.2
+  => GoForward{speed => 0.2}:0x4886b248[]
+
+  >> m.running?
+  => true
+  >> running_tasks
+  =>
+
+                                  Task                            Since     State
+  GoForward{speed => 0.2}:0x4886b248[]   Wed Apr 23 08:31:29 +0200 2008   running
+
+
+Now, to stop it ...
+  >> m.stop!
+  => []
+  task GoForward{speed => 0.2}:0x4886b248[] stopped by user request
+  >> m.running?
+  => false
+  >> m.finished?
+  => true
+  >> m.success?
+  => false
+  >> m.failed?
+  => true
+
+The task has been interrupted. From the system point of view, it means that it
+has not finished successfully, hence <tt>m.success?</tt> and <tt>m.failed?</tt>
+return respectively false and true.
+
+Now, to make the whole Roby controller quit:
+  >> quit
+  =>
+
+Note that you don't have to restart the shell between to runs: if you start the
+controller again, the same shell will reconnect automatically to the new
+controller.
+
+= Next tutorial
+
+This tutorial showed you how to build a very simple task model, and how to
+create planner methods to interface with the shell. The {next
+tutorial}[link:files/doc/tutorials/03-PlannedPath_rdoc.html] will build upon
+that by making you create a very small plan, in which different tasks represent
+different aspects of the robot activity. The fourth tutorial will then be about
+displaying the execution trace of that plan to understand what happens under the
+hood.
+---
+vim: tw=80 et

data/doc/tutorials/03-PlannedPath.rdoc

@@ -0,0 +1,268 @@
+{Previous tutorial}[link:files/doc/tutorials/02-GoForward_rdoc.html]
+{Next tutorial}[link:files/doc/tutorials/04-EventPropagation_rdoc.html]
+= Planning and following a path
+We'll now use a (slightly) more complex system to make our robot move. The
+robot will now have a goal, defined as a (x, y) point. It will generate a
+trajectory which leads it to that goal, and then execute that trajectory.
+
+This tutorial therefore shows the following:
+* how multiple activities can be _temporally_ coordinated to make the robot
+  reach a defined goal, and
+* how the plan represents how one activity relates to another.
+
+In this new robot, three activities will be used to make the robot reach
+its goal. The plan will therefore represent various things:
+* the three activities: the high-level activity which represent the goal of
+  the robot; the path planning activity and the path execution activity.
+* how these activities relate to each other. For that, Roby defines <it>
+  task relations</it>.
+* how the plan describes the temporal relations between these activities (i.e.
+  when a given activity should be started).
+
+To hold all these, we will create a new robot:
+
+  roby robot PathPlan
+
+== Defining the task models
+This section will describe the task models, without the actual implementation
+of the actual implementation of these activities. That implementation is
+discussed later in that tutorial. The goal is to first make you grasp what the
+task models, and the plan model is about and only then how the tasks can
+actually control the robot itself.
+
+* the +MoveTo+ task express the current goal of the robot, and holds the path
+  data. Open <tt>tasks/move_to.rb</tt> and add the following:
+    class MoveTo < Roby::Task
+        terminates
+
+        # The movement goal
+        argument :goal
+        # The generated path
+        def path; data end
+    end
+
+* the +ComputePath+ task generates the path on behalf of a +MoveTo+. When
+  successful, it updates the +data+ attribute of the +MoveTo+ task it is
+  planning. It uses a standard task, Roby::ThreadTask, which allows to
+  represent the execution of a separate thread into the main plan. Open
+  <tt>tasks/compute_path.rb</tt> and add the following:
+
+    require 'roby/thread_task'
+    class ComputePath < Roby::ThreadTask
+      # The movement goal
+      argument :goal
+      # The maximum speed limit
+      argument :max_speed
+    end
+
+* finally, +TrackPath+ takes the path generated and follows it. Open
+  <tt>tasks/track_path.rb</tt> and add the following:
+    class TrackPath < Roby::Task
+      terminates
+
+      # The task holding the path data
+      argument :path_task
+    end
+
+*Note*: the file names are "best practice" recommandations. They are not at all
+required for the application to work.
+
+== Building the movement plan
+Let's add a +move_to+ action to our robot, which builds the plan corresponding
+to the whole movement. The action definition, in
+<tt>planners/PathPlan/main.rb</tt> would look like this:
+
+  # Note: the method arguments are accessed through the +arguments+ hash
+  method(:move_to) do
+    # The goal point
+    goal = Pos::Vector3D.new(*arguments.values_at(:x, :y))
+    # The high-level representation of the movement
+    move = MoveTo.new :goal => goal
+    move.realized_by compute = ComputePath.new(:goal => goal, :max_speed => 1.0)
+    move.realized_by track   = TrackPath.new(:path_task => move)
+
+    move.on       :start,   compute, :start
+    compute.on    :success, track,   :start
+    track.forward :success, move,    :success
+
+    move
+  end
+
+The first part creates the <em>task structure</em>, which expresses the
+relationships of the different tasks of the plan. This simple plan uses only
+one kind of relation, the RealizedBy relation. In this relation, the child task
+(i.e. +compute+ and +track+) are simple activities which achieve the parent's higher-level
+action.
+
+The second part creates the <em>event structure</em>, which expresses how the
+plan should respond to new situations. In our case, the three line describe the following:
+* the path planning must be started when the movement is started. This uses the Signal
+  event relation.
+* the path execution must be started when the path planning has successfully finished, and
+* the movement <it>has finished</it> when the path tracking <it>has finished</it>. This uses
+  the Forward relation.
+
+The difference between those two relations is subtle, so let's try to explain a bit more:
+* in the first two cases, what the system must do is <it>executing a new action</it> in
+  response to a new situation. When the +start+ event of +move+ is emitted, the +move+
+  activity has just started (i.e. all necessary actions have been taken to start that
+  new activity). The system should then make what is necessary to start computing the
+  path: it calls the _command_ of the +start+ event of +compute+.
+* in the third case, however, no specific action should be taken to end the
+  +move+ task. Instead, the plan expresses that the +move+ task is finished
+  <it>as soon as</it> the +track+ task is. Another way to put it is that the
+  situation represented by the +success+ event of MoveTo is, in this particular
+  plan, the same than the situation represented by the +success+ event of
+  TrackPath. More generally, if +a+ is forwarded to +b+ all situations that lead
+  to the emission of +a+ also lead to the emission of +b+. Or, in other words, that
+  the situation represented by +b+ is a superset of the one represented by +a+
+  (the equality, like here, is a particular case)
+
+  link:../../images/event_generalization.png
+
+  *Example*: in this plan, the +success+ event of a particular low-level action
+  is forwarded in more high-level parts of the plan. This allows to actually
+  link the low and high level parts of the plan and reason on that link.
+
+Task relations allow the system to keep track of what a given task is useful for,
+what are error conditions and how to react to errors. The next two tutorials will
+describe these parts in more details.
+
+== Running this unfinished controller
+
+Let's run this controller. Launch the controller
+  $ scripts/run PathPlan
+  
+In another terminal, launch the shell and start the move_to! action
+  $ scripts/shell
+  >> move_to! :x => 10, :y => 10
+  => MoveTo{goal => Vector3D(x=10.000000,y=10.000000,z=0.000000)}:0x48350370[]
+  >>
+  !Roby::ChildFailedError
+  !at [336040:01:45.419/186] in the failed event of ComputePath:0x483502e0
+  !block not supplied (ArgumentError)
+  !  /home/doudou/dev/roby/lib/roby/thread_task.rb:51:in `instance_eval',
+  !    /home/doudou/dev/roby/lib/roby/thread_task.rb:61:in `value',
+  !    /home/doudou/dev/roby/lib/roby/thread_task.rb:61:in the polling handler,
+  !    /home/doudou/system/powerpc-linux/ruby-1.8.6/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require',
+  !    /home/doudou/system/powerpc-linux/ruby-1.8.6/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require',
+  !    scripts/run:3
+  !
+  !The failed relation is
+  !  MoveTo:0x48350370
+  !    owners: Roby::Distributed
+  !    arguments: {:goal=>Vector3D(x=10.000000,y=10.000000,z=0.000000)}
+  !  realized_by ComputePath:0x483502e0
+  !    owners: Roby::Distributed
+  !    arguments: {:max_speed=>1.0,
+  !     :goal=>Vector3D(x=10.000000,y=10.000000,z=0.000000)}
+  !The following tasks have been killed:
+  !  ComputePath:0x483502e0
+  !  MoveTo:0x48350370
+
+Mmmm... What happened ? The call to <tt>move_to!</tt> returned properly, which
+means that the plan has been properly generated and the MoveTo high-level
+action started. Nonetheless, an error occured.
+
+The error message appeared because an ArgumentError exception has been raised
+in <tt>thread_task.rb:51</tt> Looking at the documentation of Roby::ThreadTask,
+we see that the definition of ComputePath has not called the Roby::ThreadTask.implementation
+statement, and as such the polling handler failed. Roby answers to that by
+emitting the +failed+ event of the problematic task.
+
+The plan-related error (ChildFailedError) has then been generated by Roby's
+plan analysis:
+* a +realized_by+ relation between MoveTo and ComputePath exists, which means
+  that MoveTo cannot be achieved without executing ComputePath first.
+* ComputePath failed, so <i>in the current state of the plan</i>, the MoveTo
+  action cannot be achieved either.
+
+A more complete description of errors and, more importantly, of how to handle
+them is given in the following tutorials.
+
+== Implementation of +ComputePath+ and +TrackPath+
+The first section did mainly explain how the plan represents the logical
+relations between each tasks and each task's events. We will now get into the
+details of actually implementing these tasks.
+
+* First, we have to initialize the position in <tt>tasks/PathPlan.rb</tt>
+
+    Roby::State.update do |s|
+      s.pos = Roby::Pos::Vector3D.new
+    end
+
+* for +ComputePath+, we will simply generate a random set of points in-between
+  the current robot position and the specified goal. In general (i.e. not here,
+  but in a real case), this process takes time and as such cannot be done in
+  one pass of the execution cycle. We will therefore use a thread to do it,
+  leaving the actual thread management to Roby::ThreadTask:
+
+    # The robot position at which we should start planning
+    # the path
+    attr_reader :start_point
+
+    # Initialize start_point and call ThreadTask's start command
+    event :start do |context|
+      @start_point = State.pos.dup
+      super
+    end
+
+    # Implementation of the computation thread
+    implementation do
+      path = [start_point]
+      while goal.distance(path.last) > max_speed
+        u = goal - path.last
+        u /= u.length / max_speed
+        path << path.last + u
+      end
+      path << goal
+
+      Robot.info "#{path.size} points between #{start_point} and #{goal}"
+      path
+    end
+
+    on :success do |ev|
+      # Parents is a ValuSet, it has no #first method. Get
+      # the first element with #find
+      parents.find { true }.data = result
+    end
+
+  See Roby::ThreadTask to implement _interruptible_ external threads.
+
+  Robot is a namespace which (among other things) can be used to access an
+  application-specific logger set up by Roby itself. It answers to #debug,
+  #info, #warning and #fatal, and by default is at the INFO level.  The Logger
+  object itself is accessible at Robot.logger. Therefore, use
+  Robot.logger.level= to change the logger level itself.
+
+* as stated before, MoveTo does not require any special code. It is here
+  only to represent a high level activity (the whole movement), not to actually
+  execute it.
+
+* TrackPath will then take the path data and execute the corresponding movement. For
+  the purpose of this tutorial, it will simply move to the next point in the path
+  at each execution cycle:
+
+    # The current waypoint
+    def current_waypoint; path_task.data[@waypoint_index] end
+
+    poll do
+      @waypoint_index ||= 0
+      State.pos = current_waypoint
+      @waypoint_index += 1
+      if @waypoint_index == path_task.data.size
+        emit :success
+      end
+
+      Robot.info "moved to #{current_waypoint}"
+    end
+
+= Next tutorial
+
+The {next tutorial}[link:files/doc/tutorials/04-EventPropagation_rdoc.html] will
+allow you to understand more by actually seeing what happens during the plan
+execution. After this tutorial, you should be able to build simple task
+models and simple plans, as well as execute them and understand the most common
+error -- ChildFailedError.
+---
+vim: tw=80 et