When the target is selected with configure, you can run make configure_packages to pop up the GUI configtool. You need to install this program on your system. Some things to do are :

In between Orocos versions, configuration options may be added or removed to reflect feature additions or removal. In that case, your current orocos.ecc file will not be properly parsed by the tools. To solve this, you need to run

  make upgrade_packages

such that your old configuration is imported in the new one. After an upgrade, your selected template, added packages and so on will remain as before.

	Note
	You can manually save your configuration using ecosconfig export /tmp/savefile.ecc in your old build tree, followed by make new_packages and ecosconfig import /tmp/savefile.ecc in your new build tree. ( manually invoking ecosconfig requires setting ECOS_REPOSITORY ) to your packages directory).

This section goes into more detail how package management is done behind the scenes and is optional literature for the average user.

The above make commands are optional. Take a look at the Makefile to see what they really do. A standard eCos configuration goes as follows :

This section will do its best to help you through the Subversion ( svn ) installation process. Installing Orocos from SVN is optional and requires some familiarity with the tools we use. It is only advised for Orocos developers.

The commands below show how to obtain the orocos-trunk Package Tree from the Subversion tree (read-only)

  svn co http://svn.mech.kuleuven.be/repos/orocos/orocos-trunk 
  cd orocos-trunk 

So, make sure you have the Subversion program installed, i.e., the command "svn" works on your system. The repository is web-browsable through a ViewCVS frontend .

The next step requires that you use automake version 1.9 and autconf version 2.54 or later. You can check your versions with the --version option:

  $ automake --version
  automake (GNU automake) 1.9.5
   ...
  $ autoconf --version
  autoconf (GNU Autoconf) 2.54	

	Note
	You need these programs if you intend to modify the makefiles

When you get something similar, proceed with calling the ./autogen.sh command in the base directory , in order to initialize the autoconf and automake files:

  ./autogen.sh

The configure script will detect the installed software on your system and generate the appropriate scripts.

The next steps are exactly the same as when you install the system starting from a so-called “epk” package, as explained in the next section. Of course, you don't have to apply the ecosadmin.tcl command when installing from SVN.

A Priority inversion is the term used to indicate a scheduling situation in which a high priority thread is blocked on a resource which is held by a low priority thread, while a medium priority thread is running, preventing the low priority thread to free the resource for the high priority thread.

The result is an inverted priority because a medium priority thread is running while the high priority thread should be runnen, hence, the medium priority thread has, in practice, a higher priority than the high priority thread.

There are roughly said two solution to this problem. 1. Do not block on resources from high priority threads. 2. Use priority inheritance, where a thread gets the priority of the highest priority thread being blocked on a resource it holds. Once it releases the resource, its priority goes back to normal and the high priority thread can resume.

In essence, Orocos does not know of priority inversions and does not know if the underlying Operating System properly solves this common situation. Furthermore, it can be prooven that there are situations where priority inheritance does not work. Therefore, we try to provide as much as possible lock-free implementations of inter-thread messaging. Table 3.1, “Classes Possibly Subject to Priority Inversion” lists the know uses of Orocos which might lead to priority inversion.

Table 3.2, “Classes Not Subject to Priority Inversion” shows communication infrastructure in Orocos which is especially designed to be lock-free and which is thus not subject to priority inversions. It is our aim to shrink the former table and grow the latter in Orocos' development lifetime.

As was seen in ???, CoreLib Properties can be added to a task's AttributeRepository. To read and write properties from or to files, you can use the PropertyLoader class. It uses the XML Component Property Format such that it is human readable.

  #include <rtt/PropertyLoader.hpp>
  // ...
  TaskContext* a_task = ...
  PropertyLoader ploader;
  ploader.configure("PropertyFile.cpf", a_task );
  // ...
  ploader.save("PropertyFile.cpf", a_task ); 

Where 'configure' reads the file and configures updates the task's properties and 'save' updates the given file with the properties of the task. It is allowed to share a single file with multiple tasks or update the task's properties from multiple files. Fortunately, the TaskContext has implemented this functionality also as script methods, thus you do not need to do this manually.

The ExecutionEngine is the core class of this package. It executes the decision logic of the TaskContext by executing programs and state machines. Any number of these may be loaded and can be controlled separately. It allows to start, pause, step,... stop programs and state machines. No recompilation is needed in order to use new programs or state machines. Its task is to serialise (do one after the other) the execution of programs, state machines, commands and events such that they are not concurrently executing, and can thus interact thread-safely. A TaskContext is running when it's ExecutionEngine is running. The Task Context provides the interface of the control task, the Execution Engine executes the implementation.

In order to start a task context, its execution engine must be run in a periodic corelib task.

  #include <rtt/TaskContext.hpp>
  #include <rtt/PeriodicActivity.hpp>

  RTT::TaskContext mytaskC;
  RTT::PeriodicActivity ptask(5, 0.01 ); // Periodic task 100Hz.

  ptask.run( mytaskC.engine() ); // run the execution engine.

  ptask.start();
      

After it is started, it will execute all the processors in each periodic step. First the Program Processor, then the State Machine Processor, then the Command Processor and finally the Event Processor.

The FunctionGraph is a tree composed of command nodes ( See : ActionInterface class ), where each node contains one or more statements. A FunctionGraph keeps track of the start node and the node to be executed next. As such a program is executed one node at a time and the transition to the next node is done on a given boolean condition ( See : ConditionInterface class). The FunctionGraph is built by the program parser and almost never by the programmer by hand.

In order to access (start, stop, pause,...) a loaded program, use :

  ProgramInterface* prog = mytaskC.engine()->programs()->getProgram("ProgName");
  if (prog == 0 ) {
      // program not found.
  }
  int line = prog->getLineNumber();
  prog->start();
  // ...
  prog->pause();
  // .. etc. 	  
	

All commands are also accessible from within the interactive 'TaskBrowser'.

Figure 5.1. Executing Program Statements

Programs are generated from a script. The Parser is able to convert Orocos Program Scripts to a Program which can be loaded in the Program Processor.

Figure 5.2. Using a Program

Loading, unloading and deleting a Program may throw an exception. The program_load_exception and program_unload_exception should be try'ed and catch'ed on load and unload or deletion of a Program in the Program Processor.

	Tip
	Alternatively, you can use the ProgramLoader class as a user-friendly frontend for loading Programs and Functions in tasks.

The StateMachine is a collection of states, linked to each other through transition definitions. It represents a state machine of the realtime system's logic and may access internal and external data for deciding on its state transitions. Every 'device' has some states or configurations in which a specific action must be taken (on entry, during or on exit) and transitions between states are defined by boundary conditions (guards) or triggered by events. Every such state is defined by the StateInterface. A state itself is defined by four programs : entry, run, handle and exit. They are called by the State Machine Processor when this state is entered, run or left. When no state transition took place, handle is called in a periodic execution step of the StateMachineProcessor. Otherwise, first the exit program of the current state is called, then the entry program and then the run program of the new state is called. The next periodic step will continue the run program, or when finished, evaluate transition conditions, and if none succeeds, handle will be called, and so on. Orocos Events may be processed during the run program. The exit program can check for interuption and clean up if necessary. After the exit program (if any), the transition program is executed (again, if any).

As transitions define when a state will be left, preconditions are used to define when a state should not be entered, and function as an extra condition which is checked before the transition is tried.

Figure 5.3. Executing a StateMachine

The Parser is able to convert Orocos State Descriptions to a State Machine wich can be loaded in the Processor.

In order to access (activate, start, stop, pause,...) a loaded state machine, use :

  StateMachine* smach = mytaskC.engine()->states()->getStateMachine("MachineName");
  if (smach == 0 ) {
      // state machine not found.
  }
  smach->activate();
  string state = smach->getCurrentStateName();
  smach->start();
  // ...
  smach->stop();
  // .. etc. 	  
	

All commands are also accessible from within the interactive 'TaskBrowser'.

Figure 5.4. Using a StateMachine

Loading, unloading and deleting a State Machine may throw an exception. The program_load_exception and program_unload_exception should be try'ed and catch'ed on load and unload or deletion of a State Machine in the Processor.

	Tip
	Alternatively, you can use the ProgramLoader class as a user-friendly frontend for loading State Machines.

The CommandProcessor is responsible for accepting command requests from other (realtime) tasks. It uses a non-blocking atomic queue to store incoming requests and fetch-and-execute them in its periodic step. It offers thus a thread-safe realtime means of message passing between threads, without intervention of the Operating System.

  #include <rtt/TaskContext.hpp>

  ActionInterface* com = ... // Create a command, see the next Section.

  int ticket = mytaskC.engine()->commands()->process( com ); 

If ticket is zero, the command was not accepted by the processor, possibly the queue was full or it was not running. You can query if a command has been fetched and executed by calling :

  if ( mytaskC.engine()->commands()->isProcessed( ticket ) )
     // done !
  else
     // still busy ! 

Figure 5.5. Tasks Sending Commands

Tasks of different threads communicate by sending commands to each other's Command Processors. When Task T1, running in Thread (a), requests that T2, running in Thread (b) processes a command, the command is stored in a command queue of that task's Command Processor. When T2 runs its Command Processor, the queue is checked and the command is executed. T1 can optionally check if the command was accepted and executed, using a Completion Condition ( see TaskContext and Program Parser manuals. )

Orocos uses the 'Generic Functor' paradigm to encapsulate Commands. This means that an object (the functor) is created which holds a pointer to the function to be executed. If this function needs arguments, these are also stored in the functor. The object can then be passed around until another object decides to execute the functor. Execution of a functor leads to the original function to be called, together with the arguments.

Figure 5.6. A Generic Functor

The CommandFunctor is the object used to store the function pointer in. It implements the ActionInterface such that it can be execute()'ed by the Processor :

  #include <rtt/CommandFunctor.hpp>
  void foo();

  ActionInterface* command = newCommandFunctor( &foo );

  command->execute(); // calls foo()

  delete command;
	

notice that we use a factory-function newCommandFunctor in order to avoid providing a template parameter.

It is possible to wrap more complex functions in a CommandFunctor, if the boost::bind library is used :

  #include <rtt/CommandFunctor.hpp>
  #include <boost/bind.hpp>
  
  void foo( int x, int y );
  int a1 = 1, a2 = 2;

  ActionInterface* command = newCommandFunctor( boost::bind( &foo, a1, a2 ) );

  command->execute(); // calls foo(a1,a2)

  delete command;
	

Argument 'binding' is a very powerful feature of C++. It allows to provide the arguments of a function in advance and execute the function lateron.

It is also possible to call the memberfunction of an object. In that case, the first parameter of the function becomes the pointer to the object, followed by the arguments of the function ( which must all be variables ) :

  #include <rtt/CommandFunctor.hpp>
  #include <boost/bind.hpp>
  
  class X {
  public:
    void foo( int x, int y );
  };

  X x_object;
  int a1 = 1, a2 = 2;
  ActionInterface* command = newCommandFunctor( boost::bind( &X::foo, x_object, a1, a2 ) );

  command->execute(); // calls x_object.foo(a1,a2)

  delete command;
	

notice that the foo function is now prefixed by the class scope 'X::'.

The CommandFunctor allows us to bind a function to a ActionInterface. Since the Program Processor can execute ActionInterface objects, it is a powerful way to delay calling of a function to a later moment.

Using the CommandFunctor from the previous section, we can pass the command to the processor :

  ActionInterface* command = ...
  Processor* proc = ...

  int nr = proc->process( command );
	

If nr is non-zero, the command was accepted, if zero, the command fifo is full and a new process attempt must be made.

Another thread instructs the processor to execute all queued commands (and programs) synchronically calling the

  proc->step();
	

function. The easiest way to do this is to create a Task which runs the Processor.

The CommandFunctor can be used when a separate thread of execution wants to execute a function in the Processor thread. In Orocos, this happens when an external commando must be processed by the realtime control kernel. In one thread, the CommandFunctor is created (which contains the function to be called) and is passed to the Processor of the ExecutionExtension, which is part of the control kernel. The control kernel thread executes all queued commands in the Processor after the control calculations are done. In this way, safe data access can be guaranteed.

The ConditionEdge defines an edge of the state diagram. It contains a condition on which a next state is entered. The ConditionInterface encapsulates that logic. Conditions can be ordered by priority, so that it is defined in which order they are checked. A multiple of conditions can lead to the same state.

The CommandNode contains a Command and is connected by edges of the type ConditionEdge, these edges connect one node with another and allow the transition if the contained condition evaluates to true. When a program is executed, it executes the command and runs through the list of edges of that node. When a Condition is found valid, the next program node to be executed is found. If no condition is fulfilled, the same command node will be executed again. Also a line number can be associated with each command node, as a reference to the input file formatted by the user.

The Command is the abstraction of a user directive that has to be executed. A Command can be execute()'ed and reset()'ed. For each action exists one Command, but a Command can be composed of other Commands. The basic interface, ActionInterface, is provided by the Orocos CoreLib.

The Condition is the abstraction of a user expression that has to be evaluated. A Condition can be evaluated()'ed and reset()'ed. Many primitive expressions can be evaluated and a Condition can be composed of other Conditions. The basic interface, ConditionInterface, is provided by the Orocos CoreLib

For various reasons, during the development of the Orocos parser, it has proven necessary to hard-code various things, mostly relating to the defined types, and the operations supported on them. The parser supports using different types of objects than the predefined ones, but the major limitations are:

We will address the ways to address the various limitations.