roby 0.8.0 → 3.0.0

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

@@ -1,11 +0,0 @@
----
-title: Introduction
-sort_info: 0
---- name:content pipeline:tags,markdown,blocks
-This section will present the basics of plan management using Roby. You will
-learn the following things:
-* the two core objects used in Roby to represent the robot's actions
-* what is a Roby application and how create one
-* how it is possible to interact with a running Roby application
-* how to build complex actions from simple ones
-

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

@@ -1,203 +0,0 @@
----
-title: Using Plan Display
-sort_info: 600
---- pipeline:tags,markdown
-
-What we will see in this page is how to trace the execution flow (the flow of
-events), and understand a bit more how the plans you will build are actually
-executed by the system. We will re-use the planned\_move planning action we just
-built.
-
-Getting a log file
-------------------
-
-Plan execution logs are expensive from a CPU point of view, so they are disabled
-by default. Enable them back by editing config/app.yml and uncomment
-"events: true" around line 23. 
-
-Now, run again the controller
-
-    # scripts/run goForward
-
-and in the shell, do
-
-    >> planned_move! :x => 10, :y => 10
-    => MoveTo{goal => Vector3D(x=10.000000,y=10.000000,z=0.000000)}:0x4840c8d8[]
-    >>
-    !task MoveTo{goal => Vector3D(x=10.000000,y=10.000000,z=0.000000)}:0x4840c8d8[] finished successfully
-
-Finally, let's save the log files for further analysis (otherwise, one could
-destroy them by restarting the controller).
-
-    # scripts/results planned_move
-    moving /home/doudou/dev/first_app/log to /home/doudou/dev/roby-tutorials/results/20080502-planned_move
-
-"scripts/results" copies all files in "log/" into a subdirectory
-of the result dir (by default APP\_DIR/results, but can be changed in
-"config/app.yml"). The target directory name is generated following a pattern of
-"current\_date-name\_provided\_on\_command\_line".
-
-Displaying the log file
------------------------
-Go in the directory where the results are (see <tt>scripts/results</tt> output).
-On my machine, the command would look like this:
-
-    $ cd /home/doudou/dev/roby-tutorials/results/20080502-planned_move
-    $ ls
-    goForward-events.log
-    goForward-index.log
-
-If you look into it, two PathPlan files are present: <tt>PathPlan-events.log</tt> and
-"PathPlan-index.log".  The first one includes a trace of everything that
-happens in the Roby controller which has been traced. The second one can
-actually be generated from data in the first one. It is simply used to speed up
-operations.
-
-The data in the event log can be used to display the plan operations in a GUI.
-For that, you need to have installed [Ruby/Qt4](http://korundum.rubyforge.org), as
-the GUI is written using Qt and Ruby.
-
-To start it, simply do the following in the directory of the log files:
-
-    $ roby-log replay goForward
-
-The following window should appear:
-
-![](log_replay/roby_log_main_window.png)
-
-This window is separated in three:
-
-* the toplevel part ("Data sources") is the list of data sources defined for
-  this project. It is for instance possible to have a synchronized display of
-  the logs of two different Roby controllers -- for multi-robot setup.
-* the second part ("Displays") is the set of displays defined. More about that later.
-* the third part ("Play") is the replay controls: play, fast forward, position, ...
-
-Right now, we will be looking at the plan structure and execution trace. The
-"Relations" display is designed for that. Let's add one by clicking on the
-"Add" button just next to the display type combo. The configuration options
-appear (including the data source associated with the display), and a new
-window:
-
-![](log_replay/roby_log_relation_window.png)
-
-This display will show two things: the task structure (i.e. how tasks are
-related to each other) and the event propagation (i.e. how events call and/or
-emit each other). The set of task relations to display has to be selected on
-the configuration part of the relation display, including the colors for each
-displayed relation. For our purposes, we only need the "Hierarchy" and the
-"PlannedBy" relations, so check them in the display configuration, as it is done
-one the image above.
-
-Moreover,
-* go in the "View" menu of the relation display and uncheck "Hide
-  finalized", that will be useful for later.
-* go in the "Task labels" and uncheck "Ownership". Ownership is only useful for
-  multi-robot plans.
-
-**Very important note** your own display may not look exactly like the ones
-displayed here. Some of the features showed here (like threaded planning) are
-asynchronous and as such the exact displays depend on the execution timing. Note
-that, even though it is the case, the robot _behaviour_ remains unchanged.
-{.warning}
-
-Startup of the "planned\_move!" action
----------------------------------------
-
-Let's get to the first task-related events. Click on the 'Step' button until
-something appears on the display. It should look like the next image:
-
-![](log_replay/goForward_1.png)
-
-The displays shows two plans (black boxes). The left one is the plan as it is
-being executed. The right one is called a _transaction_ and allows to build a
-new plan without interfering with the execution. You don't really need to know
-how it works, only that it does the job. The task description includes the task
-model and the task owners (which is only useful in multi-robot setup). The
-_Task labels_ menu allows to customize that.
-
-The left part is a representation of the plan built when the planned\_move!
-command is entered in the shell. It consists of a generic task (Roby::Task)
-which is planned\_by a Roby::PlanningTask. This is how Roby handles action
-requests from the shell: (i) it searches a planner defined for that robot with
-the specific action and (ii) generates the plan representing the planning
-process _in a separate thread_.
-
-Once that initial plan has been built, the Roby::PlanningTask task has been
-started. The various cases of event propagation are represented in different
-ways, based on whether or not the event is controlable or contingent, if it has been
-called and/or emitted. Finally, two different arrow representations are used for
-signalling (plain) and forwarding (dotted):
-
-![](log_replay/roby_replay_event_representation.png)
-
-A note about propagation representation: it would be useless to represent all
-the event propagation from the beginning of the execution to the current point.
-The display therefore represents only the propagations that have taken place
-_since the last display point_. It means that, if you go forward 10
-seconds, it will display 10 seconds worth of propagation. In our case, we
-displayed only the first execution cycle and we see that, in this cycle, the
-planning task "start" event has been called and emitted.
-
-The MoveTo plan
----------------
-
-Advance again using 'Step' until the display looks like this:
-
-![](log_replay/goForward_2.png)
-
-The MoveTo action has been planned and the executed plan is modified to reflect
-that. The MoveTo action itself is then started, and that is propagated to the
-ComputePath 'start' event through the signalling relation that was established
-in planned\_move.
-
-Next execution step gives us the following:
-
-![](log_replay/goForward_3.png)
-
-ComputePath emitted its "success" event. We see here that the emission of the
-"success" event of that task does not mean 'the plan modification has just took
-place' but instead that 'it has taken place some time earlier'.
-
-The ComputePath task has also finished generating the path, which is why
-ExecutePath is started. Here, the dotted lines between the events
-represent a forwarding relation between them, while the plain lines
-represent signal relations.
-
-Finally, light grey here represents tasks that have finished with the "success"
-event. Tasks whose "failed" event has been emitted are represented in red.
-
-To finish: the garbage collection process
------------------------------------------
-
-Advance a few steps further, until something more happens. You should see
-something like this:
-
-![](log_replay/goForward_5.png)
-
-Here, ExecutePath has finished its execution with success and MoveTo is therefore
-finished as well -- per the forwarding relation between those two events. Note
-that the tasks are now in a dark grey instead than a light one. 
-
-The mission of the robot, MoveTo, is therefore finished. From the plan
-management point of view, it makes keeping a reference to it useless. In the
-same way, the tasks that were in the plan for the purpose of fullfilling that
-mission are rendered useless as well and can also be removed. The process which
-removes those tasks is called the <i>garbage collection process</i> and runs at
-the end of the execution cycle.
-
-The general idea is to kill and remove from the plan the tasks that are not
-useful for the achievement of the robot's missions. The "important" tasks for
-the robot is defined by the set of its missions.  These are added by calling
-Plan#add\_mission instead of the Plan#add that we were using until now. Note
-that, by calling the action through the shell, #add\_mission has been called
-automatically by the framework.
-
-Then, the task relations are used to determine what are the tasks, in the plan,
-which are actually useful for those "important" tasks. This is based on the
-convention that if a <tt>a=>b</tt> relation exists, then "b" is useful for "a".
-
-The remaining tasks, i.e. the tasks that are not useful, are killed (if possible)
-and removed from the plan. When it is done, the task is said to be finalized and
-are displayed in dark grey (if they are not hidden in the View menu).
-

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

@@ -1,102 +0,0 @@
----
-title: Interactive Shell
-sort_info: 400
---- pipeline:tags,markdown,blocks
-
-As we saw earlier, the execution of Roby applications is done by an _event
-loop_. The reactivity of the supervision system obviously depend on the
-non-interruption of that event loop. Therefore, in a Roby application, the user
-runs a remote shell that is used to send specific commands to the Roby
-application itself.
-
-{include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
-
-Planners
---------
-Right now, we saw two different places where code is stored:
-1. the tasks/ files, where task models are defined
-2. the controllers/ files, which is the startup code for the application
-
-What we will see in this section is a third component: the **planners**. These
-planners define the aggregate actions that the robot knows about. As we will see
-later, they also are the user interface of the robot.
-
-Exporting actions to the user's shell
--------------------------------------
-
-Edit planners/goForward/main.rb and edit so that it looks like this:
-
-{coderay:: ruby}
- require 'planners/main'
- class MainPlanner
-   method(:move) do
-       GoForward.new :speed => arguments[:speed]
-   end
- end
-{coderay}
-
-That exports a very simple action to the user's shell. Now, we can try out the
-Roby shell. First, remove the last three lines in controllers/goForward.rb so
-that it looks like this:
-
-{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
-{coderay}
-
-Now, start the roby application in one console:
-
-    $ scripts/run goForward
-    44848:44:51.498 (Roby) GC.enable does not accept an argument. GC will not be controlled by Roby
-    344848:44:51.581 (goForward) loaded Roby 0.7.90 on ruby 1.8.7 (2008-08-11 patchlevel 72) [powerpc-linux]
-    344848:44:51.603 (goForward) loading controller file /home/doudou/dev/roby-tutorials/controllers/goForward.rb
-    344848:44:51.605 (goForward) done initialization
-    0
-    0
-
-Finally, start the shell in another console:
-
-    $ scripts/shell
-    localhost:48902 >
-
-The new prompt you get is a Ruby prompt (i.e. you should type Ruby code in it).
-Some special commands are available to interact with the Roby controller. For
-instance:
-
-{coderay:: ruby}
- > actions
- => [move]
-{coderay}
-
-The 'action' command lists the available planning methods that are exported
-through the MainPlanner class. Let's try it (**notice the '!' at the end of
-move!**):
-
-{coderay:: ruby}
- > task = move! :speed => 1
- => GoForward{speed => 1}:0x48410aa8[]
- > task.running?
- => true
- > task.stop!
- => []
- !task GoForward{speed => 1}:0x4850ddb0[] failed
- !task GoForward{speed => 1}:0x4850ddb0[] stopped by user request
- > task.running?
- => false
-{coderay}
-
-The new task is running just after it has been added ! In Roby, a new task, when
-added in the main plan, becomes eligible for _scheduling_, i.e. a special
-component tries to find the best time to start it (which, in our case, is
-"now"). We'll see more about this later.
-{: .warning}
-
-You can see that the action method returns the task that the planning method has
-returned. Even though we are on a remote shell, the returned task object
-supports sending commands, checking its status, emitting events, ...
-

data/doc/guide/src/default.css

@@ -1,319 +0,0 @@
-/* andreas03 - an open source xhtml/css website layout by Andreas Viklund - http://andreasviklund.com . Free to use for any purpose as long as the proper credits are given to the original author.
-
-Version: 1.2
-(Nov 28, 2005)
-
-Screen layout: */
-
-body{
-margin:0;
-padding:30px 0;
-font:76% tahoma,verdana,sans-serif;
-background:#047 url(images/bodybg.png) repeat-x fixed;
-color:#222;
-}
-
-#thetop{
-margin:0;
-}
-
-#container{
-width:720px;
-margin:0 auto;
-padding:20px 20px 0 20px;
-background:#fff url(images/contbg.png) no-repeat;
-color:#222;
-}
-
-a{
-text-decoration:none;
-background-color:inherit;
-color:#26c;
-}
-
-a:hover {
-text-decoration:underline;
-}
-
-a img{
-border:0;
-}
-
-p{
-margin:0 0 15px 0;
-line-height:1.5em;
-}
-
-#main p,#sidebar p{
-padding:0 0 0 10px;
-}
-
-#logo{
-float:left;
-width:240px;
-margin:0 20px 0 0;
-padding:0 0 25px 0;
-background:#eee;
-border:4px solid #dde;
-text-align:center;
-color:#555;
-overflow:auto;
-}
-
-#logo h1{
-margin:50px 5px 1px 5px;
-letter-spacing:-3px;
-}
-
-#logo a{
-background-color:inherit;
-color:#26a;
-text-decoration:none;
-}
-
-#logo a:hover{
-background-color:inherit;
-color:#69e;
-}
-
-#tagline{
-text-align:center;
-font-size:1.2em;
-}
-
-#intro p{
-line-height:1.5em;
-}
-
-#main{
-float:left;
-width:530px;
-margin-right:20px;
-padding:0;
-}
-
-#main h2, .navbar {
-display:block;
-margin:30px 0 10px 0;
-padding:5px 0 5px 8px;
-background:#eee url(images/gradient2.png) repeat-x;
-color:#222;
-border-top:1px solid #ddd;
-border-right:1px solid #bbb;
-border-bottom:1px solid #bbb;
-border-left:1px solid #ddd;
-text-decoration:none;
-}
-
-#sidebar{
-width:155px;
-float:right;
-margin-top:20px;
-font-size:1em;
-line-height:1.3em;
-}
-
-#sidebar p, #sidebar .linklist {
-font-size:0.9em;
-}
-
-#sidebar ul.linklist {
-list-style-type: none;
-margin: 0px;
-padding: 5px 0px 5px 8px;
-}
-
-#sidebar #menu ul, #sidebar #submenu ul {
-list-style-type: none;
-margin: 0px;
-padding: 0px;
-}
-
-ul li ul li {
-    margin-left: -2em;
-    padding-left: 0;
-}
-
-#sidebar #menu li, .sidelink, #sidebar #submenu li, #sidebar #submenu li {
-display:block;
-width:140px;
-margin:3px 10px 2px 0;
-padding:5px 0 5px 8px;
-font-size:1.1em;
-font-weight:bold;
-text-align:left;
-background:#eee url(images/gradient1.png) repeat-x;
-color:#26c;
-border-top:1px solid #ddd;
-border-right:1px solid #bbb;
-border-bottom:1px solid #bbb;
-border-left:1px solid #ddd;
-}
-
-#sidebar #menu a:hover {
-    text-decoration: none;
-}
-
-#sidebar #menu li.webgen-menu-submenu-inhierarchy, .menuheader {
-background:#fff url(images/gradient2.png) repeat-x;
-color:#222;
-border-top:1px solid #ddd;
-border-right:1px solid #888;
-border-bottom:1px solid #888;
-border-left:1px solid #ddd;
-text-decoration:none;
-}
-
-#sidebar #menu li.webgen-menu-item-selected {
-    color: #222;
-}
-#sidebar #menu li.webgen-menu-item-selected:hover {
-    color: #222;
-    background: none;
-    border: none;
-}
-
-.menuheader {
-    font-size: 1.4em;
-    text-align: center;
-    margin-bottom: .4em;
-}
-
-#sidebar #submenu li.webgen-menu-item-selected, #sidebar #submenu li:hover {
-background: none;
-font-size: 1em: 
-}
-
-#sidebar #menu li ul li, #sidebar #submenu li ul li, #sidebar #submenu li ul li.webgen-menu-item-selected {
-display:block;
-width:130px;
-margin:3px 10px 2px 0;
-padding:0px 0 0px 8px;
-font-size:0.8em;
-font-weight:bold;
-text-align:left;
-background: none;
-color:#26c;
-border: none;
-}
-
-
-#footer{
-margin:0 auto 20px auto;
-width:760px;
-background:#fff url(images/footerbg.png) bottom left no-repeat;
-padding:0 0 5px 0;
-font-size:0.9em;
-color:#888;
-text-align:center;
-}
-
-h1,h2,h3,h4{
-margin:0 0 10px 0;
-font-weight:normal;
-}
-
-h1{
-font-size:2.8em;
-margin-top: 5px;
-margin-bottom: 5px;
-}
-
-h2{
-margin:0 0 4px 0;
-font-size:1.8em;
-}
-
-h3{
-margin:20px 0 8px 0;
-font-size:1.4em;
-}
-
-h4{
-margin:10px 0 5px 0;
-font-size:1.2em;
-}
-
-.clear{
-clear:both;
-margin:0;
-}
-
-.right{
-text-align:right;
-}
-
-.internallink{
-font-size:0.9em;
-text-align:center;
-}
-
-.block{
-padding:20px;
-background:#eee;
-color:#222;
-border:2px solid #ddd;
-}
-
-.warning{
-padding:20px;
-background:#fbb;
-color:#222;
-border:2px solid #eaa;
-margin-top: 3em;
-margin-bottom: 3em;
-margin-left: 2em;
-margin-right: 2em;
-
-}
-
-.credit{
-color:#888;
-background-color:inherit;
-}
-
-.hide{
-display:none;
-}
-
-pre .code{
-margin-left: 2.5em;
-}
-pre {
-margin-left: 2.5em;
-}
-
-/* Original open source design by Andreas Viklund - http://andreasviklund.com
-Released through OSWD.org */
-
-.navbar {
-    padding-left: 1em;
-    padding-right: 1em;
-    padding-bottom: 2em;
-}
-.previous .next {
-    margin: 1em;
-    display: inline;
-    font-size: 1.2em;
-}
-.previous {
-    float: left;
-}
-.next {
-    float: right;
-}
-
-.fullfigure {
-    text-align: center;
-}
-.figurecaption {
-    text-align: center;
-    margin-top: -1em;
-    margin-bottom: 4em;
-    margin-left: 10%;
-    margin-right: 10%;
-    background:#eee;
-    color:#222;
-    border:2px solid #ddd;
-}
-