roby 0.8.0 → 3.0.0

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

@@ -0,0 +1,71 @@
+---
+title: Creating a Roby App - File Layout
+sort_info: 5
+---
+
+Creating a new application
+--------------------------
+New Roby applications are created by going into a new folder and running
+
+~~~ ruby
+roby init
+~~~
+
+Search paths: robot name and robot type
+---------------------------------
+The configuration of the Roby application can be parametrized by a robot name
+and a robot type. If only a single name is given, it is used for both.
+
+These names influence Roby's loading sequence by either adding folders in the
+search path or parametrizing the file that Roby is looking for.
+
+File layout
+-----------
+This section gives an overview of a Roby application's file layout. You will be
+reminded in the rest of the documentation, when it applies, to where certain
+parts of the application should be stored.
+
+config/
+: configuration files. The files that are relevant for Roby are: app.yml,
+  init.rb and files named like robots (e.g. ROBOT_NAME.rb and ROBOT_TYPE.rb)
+
+models/
+: contain definition of models. There are two standard subdirectories, 'tasks'
+  for the [task models](task_models.html) and actions/ for the [action interface
+  and action libraries](actions.html)
+
+scripts/
+: additional scripts useful to manage / maintain the app. The controllers/
+  subfolder has a special meaning for running roby controllers. More on that
+  [later](../interacting/run.html)
+
+data/
+: non-code and non-model files that are relevant for the application
+
+lib/
+: additional library files (i.e. generic, non-roby-specific files). It gets
+  added to the load path automatically
+
+logs/
+: where the log files are going. See [this
+page](../tutorial/relations_display.html) for a description.
+
+Loading sequence
+----------------
+This section will describe which files are loaded in which order. The ROBOT_NAME
+and ROBOT_TYPE placeholders are used in place of robot name and robot type.  Any
+file or folder that is not found is simply ignored.
+
+config/init.rb
+: first file loaded
+
+models/tasks,models/tasks/ROBOT_TYPE,models/tasks/ROBOT_NAME
+: loading of task models. All three folders are searched for
+
+models/actions/main.rb,models/actions/ROBOT_TYPE/main.rb,models/actions/ROBOT_NAME/main.rb
+: loading of action models. Only the most specific file gets loaded.
+
+config/ROBOT_TYPE.rb,config/ROBOT_NAME.rb
+: loading of the robot's configuration file. Only the most specific file gets
+  loaded.
+

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

@@ -0,0 +1,50 @@
+---
+title: Building a Roby app
+sort_info: 0
+---
+
+This section will deal with the issue of how to create global behaviour(s) by
+__coordinating__ single-purpose units using Roby.
+
+This behaviour-building is done at two levels when using Roby:
+
+ * at the _local_ level by creating interfaces, where high-level behaviours --
+   built using smaller pieces -- are "hidden" behind high-level tasks.
+ * at the _global_ level by coordinating behaviours, as for instance by
+   switching between them.
+
+For instance, a move-to-goal behaviour could be represented by a simple MoveTo
+task that gets an argument (the target), read the position information while
+executing the task and emit an event (reached_target) when the goal is reached.
+Additionally, one would model that the reached_target event also means that the
+task is successful.
+
+However, having an actual robot realize this behaviour is a bit more
+complicated. One would for instance want to run a planner first to plan the path
+to the goal, then execute it. While executing it, one would also like to monitor
+localization and abort if it gets too bad.
+
+In Roby, the local interface-building code is done at the level of models by
+defining events and arguments to Roby tasks, and at runtime by adding actual
+code to tasks. There are various places where the code can be hooked. The main
+goal of this code is to make sure that events are emitted whenever _what they
+represent_ happened. Sometimes, achieving this is as easy as regularly executing
+code blocks that check for conditions and emit events accordingly. Sometimes, it
+requires more advanced concepts such as for instance a state machine.
+
+The global-coordination code is created __outside__ the tasks. Roby allows you
+to define __actions__, whose job it to bind tasks together to form more complex
+behaviours. These actions also form the "public" interface for your robot: you
+can start / stop them and track their progress remotely using the Roby shell. It
+is also the basis for generic error recovery.
+
+This section will first detail the programming interfaces for these two aspects.
+Then, a few pages will try to explain the role that they all have to play into a
+Roby controller.
+
+In other words, this section will describe:
+
+ * how to add code into tasks
+ * how to create plans inside planning methods
+ * where to put what
+

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

@@ -0,0 +1,86 @@
+---
+title: Patterns and Protocols
+sort_info: 400
+---
+
+The art of building code in Roby is the art of putting __plan patterns and
+protocols__ in tasks, and creating plans that conform to these patterns and
+protocols in the planning methods. This page lists a few guidelines on how that
+can be achieved
+
+Keep Isolation
+--------------
+Moreover, a good guideline when building plans is to avoid having a given task
+access other tasks that are at a distance of more than 1 in any given relation.
+I.e. a task should only access other tasks that are in its direct neighborhood.
+
+The most useful tool to achieve this is the forwarding relation: it allows to
+"forward" an event between tasks, making the child event an equivalent of the
+parent event. This is often used to declare that a high-level event is the
+equivalent of a child event.
+
+![Example of using forwarding to create high-level events from low-level
+ones](patterns_forwarding.png)
+{: .align-center}
+
+__Using forwarding to create high-level events from low-level ones__. This
+allows the rest of the plan to only synchronize on the high-level "leak_found"
+event instead of explicitely looking at the children. If the PipelineRepair is
+implemented in a different way, the rest of the behaviour will stay unchanged.
+{: .figurecaption}
+
+This pattern is commonly used to forward failure and/or success up in the
+dependency hierarchy: the success event of one child task is forwarded to the
+success event of the parent task(s).
+
+Don't put too much assumptions in
+---------------------------------
+Ideally, when writing tasks, one should seek to write it in a way that has as
+as little assumptions as possible about the tasks that are around it. It can
+obviously require some functionalities / interfaces from them. But it should
+not assume, say, that "localization_child is a task of type X".
+
+The trick to achieve this is to use events as much as possible as an interface
+to other tasks. The general guidelines here are:
+
+ * use events for synchronization
+ * use attributes for data transfer
+
+Embed protocols in task code, embed plan building in actions
+------------------------------------------------------------
+What tasks do with each other form __protocols__. I.e., any given task assumes
+that other task will emit events A, B, C and have attributes filled in with data
+when e.g. these events are emitted.
+
+However, to be reusable, a task should not __by itself__ build the plan, i.e.
+add the relevant tasks. This should be left to actions.
+
+Embedding placeholders in the plan {#abstract-tasks}
+----------------------------------
+If, at any point in execution, one wants to represent that a task __will__ be
+there and executed, but without explaining __how__, it is possible, in Roby, to
+add a task that will act as a placeholder.
+
+This is simply done by adding an instance of the right task model and marking it
+as abstract:
+
+{coderay:: ruby}
+task = MoveTo.new
+task.abstract = true
+root.depends_on(task)
+{coderay}
+
+Moreover, if a certain task model is used as a base for other models, but
+without being executable, the model itself can be marked as abstract:
+
+{coderay:: ruby}
+class AbstractMoveModel < Roby::Task
+  abstract
+end
+{coderay}
+
+__Note__ This is different from having an abstract class, as one can define one
+in C++ or Java. Here, it is possible to create instances of AbstractMoveModel
+and add the task instance in the plan. What is impossible is to execute this
+task
+{: .warning}

data/doc/guide/src/building/patterns_forwarding.svg

@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="2416.17mm"
+   height="127.353mm"
+   version="1.2"
+   id="svg4167"
+   inkscape:version="0.47 r22583"
+   sodipodi:docname="02_leak_found.svg">
+  <metadata
+     id="metadata4599">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title>Qt Svg Document</dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1672"
+     inkscape:window-height="1023"
+     id="namedview4597"
+     showgrid="false"
+     inkscape:zoom="1.2021339"
+     inkscape:cx="826.15833"
+     inkscape:cy="209.536"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg4167" />
+  <title
+     id="title4169">Qt Svg Document</title>
+  <desc
+     id="desc4171">Generated with Qt</desc>
+  <defs
+     id="defs4173">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 225.62538 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="8561.2324 : 225.62538 : 1"
+       inkscape:persp3d-origin="4280.6162 : 150.41692 : 1"
+       id="perspective4601" />
+    <inkscape:perspective
+       id="perspective5356"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective5391"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective5422"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective6229"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective6251"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective6273"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective6295"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective9373"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+  </defs>
+  <path
+     d="m 305.82972,258.63923 -7.74932,-4.46037 6.66802,-4.41531 1.0813,8.87568"
+     id="path4189"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#808080;fill-opacity:1;fill-rule:evenodd;stroke:#808080;stroke-width:0.79973406;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans" />
+  <polyline
+     points="-82.7557,0 0,0 "
+     id="polyline4195"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:none;stroke:#808080;stroke-width:1.50321531;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+     transform="matrix(0.28996405,0.44933638,-0.43790495,0.29753351,303.10297,255.91248)" />
+  <path
+     d="m 180.7602,259.51316 6.1442,-6.49583 2.73898,7.51369 -8.88318,-1.01786"
+     id="path4201"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#808080;fill-opacity:1;fill-rule:evenodd;stroke:#808080;stroke-width:0.79973465;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans" />
+  <polyline
+     points="-170.81,0 0,0 "
+     id="polyline4207"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:none;stroke:#808080;stroke-width:1.23056054;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+     transform="matrix(-0.56977681,0.23852362,-0.20770184,-0.65432843,181.78376,259.4697)" />
+  <path
+     d="m 287.105,215.326 5.7945,-6.8096 3.12988,7.35944 -8.92438,-0.54984"
+     id="path4297"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#808080;fill-opacity:1;fill-rule:evenodd;stroke:#808080;stroke-width:0.79973435;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans" />
+  <polyline
+     points="-178.215,0 0,0 "
+     id="polyline4303"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:none;stroke:#808080;stroke-width:3.17111087;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+     transform="matrix(-0.22491352,0.10184367,-0.09565297,-0.23947,287.105,215.326)" />
+  <text
+     xml:space="preserve"
+     x="117.76881"
+     y="287.1925"
+     font-size="9"
+     font-weight="400"
+     font-style="normal"
+     id="text4367"
+     style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans">PipelineDetector::Task</text>
+  <g
+     id="g5378"
+     transform="translate(41.173856,-10.906982)">
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#b0ffa6;fill-opacity:1;fill-rule:evenodd;stroke:#b0ffa6;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4357"
+       d="m 93.36057,270.96561 45.87246,0 0,19.33827 -45.87246,0 0,-19.33827" />
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4381"
+       d="m 118.696,275.54505 c 0,1.32504 -1.07416,2.3992 -2.3992,2.3992 -1.32504,0 -2.3992,-1.07416 -2.3992,-2.3992 0,-1.32504 1.07416,-2.3992 2.3992,-2.3992 1.32504,0 2.3992,1.07416 2.3992,2.3992" />
+    <text
+       style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans"
+       id="text4391"
+       font-style="normal"
+       font-weight="400"
+       font-size="9"
+       y="285.0687"
+       x="96.659775"
+       xml:space="preserve">leak_found</text>
+  </g>
+  <path
+     d="m 300.48038,258.63956 15.99468,0 0,7.99734 -15.99468,0 0,-7.99734"
+     id="path4453"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#b0ffa6;fill-opacity:1;fill-rule:evenodd;stroke:#b0ffa6;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans" />
+  <text
+     xml:space="preserve"
+     x="272.05612"
+     y="275.25073"
+     font-size="9"
+     font-weight="400"
+     font-style="normal"
+     id="text4463"
+     style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans">Camera::CameraTask</text>
+  <text
+     xml:space="preserve"
+     x="313.95895"
+     y="212.44673"
+     font-size="9"
+     font-weight="400"
+     font-style="normal"
+     id="text4559"
+     style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans">PipelineRepair</text>
+  <g
+     id="g5378-1"
+     transform="translate(146.01611,-58.975948)">
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#b0ffa6;fill-opacity:1;fill-rule:evenodd;stroke:#b0ffa6;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4357-9"
+       d="m 93.36057,270.9656 45.87246,0 0,21.65199 -45.87246,0 0,-21.65199" />
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4381-4"
+       d="m 118.696,275.54505 c 0,1.32504 -1.07416,2.3992 -2.3992,2.3992 -1.32504,0 -2.3992,-1.07416 -2.3992,-2.3992 0,-1.32504 1.07416,-2.3992 2.3992,-2.3992 1.32504,0 2.3992,1.07416 2.3992,2.3992" />
+    <text
+       style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans"
+       id="text4391-7"
+       font-style="normal"
+       font-weight="400"
+       font-size="9"
+       y="290.27457"
+       x="96.659775"
+       xml:space="preserve">leak_found</text>
+  </g>
+  <g
+     id="g5378-1-8"
+     transform="translate(223.45568,-87.334106)">
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#b0ffa6;fill-opacity:1;fill-rule:evenodd;stroke:#b0ffa6;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4357-9-4"
+       d="m 93.36057,270.9656 45.87246,0 0,21.65199 -45.87246,0 0,-21.65199" />
+    <path
+       style="font-size:9px;font-style:normal;font-weight:400;fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.799734;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;font-family:DejaVu Sans"
+       id="path4381-4-5"
+       d="m 118.696,275.54505 c 0,1.32504 -1.07416,2.3992 -2.3992,2.3992 -1.32504,0 -2.3992,-1.07416 -2.3992,-2.3992 0,-1.32504 1.07416,-2.3992 2.3992,-2.3992 1.32504,0 2.3992,1.07416 2.3992,2.3992" />
+    <text
+       style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans"
+       id="text4391-7-0"
+       font-style="normal"
+       font-weight="400"
+       font-size="9"
+       y="290.66019"
+       x="96.659775"
+       xml:space="preserve">leak_found</text>
+  </g>
+  <polyline
+     points="-41,0 0,0 "
+     id="polyline870-3"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:none;stroke:#000000;stroke-width:0.23482139;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;stroke-dasharray:0.23482139, 0.46964277;stroke-dashoffset:0;font-family:DejaVu Sans"
+     transform="matrix(2.4512254,-1.0558633,0.58150454,4.4507975,259.61204,219.1917)" />
+  <polyline
+     points="-41,0 0,0 "
+     id="polyline870-3-6"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:none;stroke:#000000;stroke-width:0.36133578;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;stroke-dasharray:0.3613358, 0.72267159;stroke-dashoffset:0;font-family:DejaVu Sans"
+     transform="matrix(1.7725875,-0.61664697,0.42051117,2.5993617,337.31448,190.07738)" />
+  <path
+     d="m 259.75338,218.7237 -5.30838,7.15899 -3.60384,-7.1103 8.91222,-0.0487"
+     id="path864"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.79714501;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;stroke-dasharray:0.797145, 1.59429;stroke-dashoffset:0;font-family:DejaVu Sans" />
+  <path
+     d="m 337.0534,190.2699 -5.30838,7.15899 -3.60384,-7.1103 8.91222,-0.0487"
+     id="path864-1"
+     style="font-size:9px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.79714501;stroke-linecap:square;stroke-linejoin:bevel;stroke-opacity:1;stroke-dasharray:0.797145, 1.59429;stroke-dashoffset:0;font-family:DejaVu Sans" />
+  <text
+     xml:space="preserve"
+     x="204.50826"
+     y="240.30687"
+     font-size="9"
+     font-weight="400"
+     font-style="normal"
+     id="text7981"
+     style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans">Compositions::FeatureDetection</text>
+  <text
+     xml:space="preserve"
+     x="204.58138"
+     y="247.42001"
+     font-size="9"
+     font-weight="400"
+     font-style="normal"
+     id="text8005-0-6"
+     style="font-size:7.19760609px;font-style:normal;font-weight:400;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans"><tspan
+       style="font-size:6px"
+       id="tspan8506-3">detector.is_a?(PipelineDetector::Task)</tspan></text>
+</svg>