Contributing

How you can get involved and contribute & participate in the Orocos project

Resources

• Wiki
• Bug Tracker
• Mailing list and Forum
• Automated builds

Development strategy

The Orocos toolchain uses git, with the official repositories hosted at gitorious.

Branches

• master : main development line, latest features. Replaces rtt-2.0-mainline
• toolchain-2.0 : stable release branch for the 2.0 release series.
• rtt-1.0-svn-patches: remains for svn bridge of 1.x release series
• ocl-1.0-svn : remains for svn bridge of 1.x release series

The master branch gets updated when new branches are merged into it by its maintainer. This can be a merge from the bugfix branches (ie merge from toolchain-2.x) or a merge from a development branch.

The stable branch should always point to the latest toolchain-2.x tip. This isn't automated, and so it lags (probably something for a hudson job or a git commit hook).

All branches in the rtt-2.0-... are no longer updated. The rtt-2.0-mainline has been merged with master, which means that if you have a rtt-2.0-mainline branch, you can just do git pull origin master, and it will fast-forward your tree to the master branch, or you checkout the local master.

Contributing packages

You may contribute a software package to the community. It must respect the rules set out in the Component Packages section. Packages general enough can be adopted by the Orocos Toolchain Gitorious project. Make sure that your package name only contains word and number characters and underscores. A 'dash' ('-') is not acceptable in a package name.

Contributing patches

Small contributions should go on the mailing lists as patches. Larger features are best communicated using topic branches in a git repository clone from the official repositories. Send pull requests to the mailing lists. These topic branches should be hosted on a publicly available git server (e.g. github, gitorious).

NB for the Orocos v1, no git branches will be merged (due to SVN), use individual patches instead. v2 git branches can be merged without problems.

Making suggestions

The easiest way to make suggestions is to use the mailing list (register here). This allows discussion about what you are suggesting (which after all, someone else may already be working), as well as informing others of what you are interested in (or are willing to do).

Reporting bugs

Before reporting a bug, please check the Bug Tracker and in the Mailing list and Forum to see whether this is a known issue. If this is a new issue then TBD email the mailing lists, OR enter an issue in the bug tracker

Orocos developers meetup at ERF

Goals of the meeting: discuss the future or the Orocos toolchain w.r.t. Rock and ROS.

Identified major goals

• make Orocos components usable across all use cases (ROS, Orocos and Rock). There should be no "rock-only" or "ros-only" components
• make as much as the Rock toolchain usable with "plain Orocos components" (see below)
• make the parallel usage of the three cases (Orocos toolchain, Orocos in ROS and Rock) as painless as possible

Sharing installations of the orocos toolchain

The main issue is the ability to compile the toolchain and components only once, e.g. in a Rock installation, and use them in ROS or vice-versa.

• already existing ignore_packages mechanism. Need to create a wiki page on how to set it up for sharing an orocos installation. Manual, but should be working.
• more automatic mechanisms:
  • allow dependencies between autoproj installations. Fully automatic for orocos toolchain/Rock interoperability
  • point to a prefix and have autoproj find out things (for ROS installs)

Sharing Orocos components across use-cases

Using rock components on plain Orocos should just work [needs testing and documentation].

Using rock tools on plain Orocos

The use of orogen or typegen would be required

• as far as we know, there is no missing "core" functionality in orogen to make typegen usable for "core" orocos libraries like KDL. Need to make some functionality such as opaques available to typegen though (only available to orogen currently). This can be done through the ability to make typegen load an oroGen SL file (trivial)
• allow passing -I options directly to both oroGen and typeGen
• mechanism to define "side-loading" typekits that define constructors and operators separately for scripting
• the core of the Rock tooling is orocos.rb. Need to test and update orocos.rb so that it can work without a model. Method: update the test suite by mocking TaskContext#model to return nil and/or getModelName to not exist. From there, test tools like oroconf and vizkit

Dataflow between ROS and Rock / plain Orocos

• need data conversions: one must be able to publish a C++ type over a ROS topic and vice-versa
• typegen generation for ROS messages
• type specification when creating ROS streams (since the ROS topic and the orocos port might have different types)
• type conversions on the data flow: use already existing constructor infrastructure to do the conversion, need to create the channel element and change the connection code
• add type conversion support in oroGen (equivalent system than opaques)

Other discussed topics

• make TypeInfo very thin so that we can register it once per type and never change it. Only transports / constructors / ... could then be overriden
• make the deployer a library

Roadmap

Where things are going, and how we plan to get there.

See also Roadmap ideas 3x for some really long-term ideas ...

TODO Autoproj, RTT, OCL, etc.

Real-time logging

The goal is to provide a real-time safe, low overhead, flexbible logging system useable throughout an entire system (ie within both components and any user applications, like GUIs).

We chose to base this on log4cpp, one of the C++-based derivates of log4j, the respected Java logging system. With only minor customimzations log4cpp is now useable in user component code (but not RTT code itself, see below). It provides real-time safe, hierarchical logging with multiple levels of logging (e.g. INFO vs DEBUG).

Near future

• Provide a complete system example demonstrating use of the real-time logging framework in both user components, and a GUI-based application. Based on the v2 toolchain.

• Provide a component-based appender demonstrating transport of logging events. Most likely demonstrate centralized logging of a distributed system.

• Add logging system stress tests. (l already have this for v1, but need to port to v2 and submit)

• Able have multiple appenders per category. This is simply a technical limitation of the initial approach, and should be readily changeable.

Long term plans

• Replace the existing RTT::Logger functionality with the real-time logging framework. This really can't involve rewriting all the logging statements in RTT, etc.

• Provide levels of DEBUG logging. Some logging system use FINE, FINER, FINEST levels, whilst others use DEBUG plus an integer level within debug (e.g. debug-1 thru debug-9, from verbose to most-verbose). Chose one approach, and modify log4cpp to support it.

• Support use by scripting and state machines (possibly also Lua?). This means both being able to log, as well as being able to configure categories, appenders, etc.

Roadmap ideas for 3.x

While the project is still in the (heavy?) turmoil of the 1.x-to-2.x transition, it might be useful to start thinking about the next version, 3.x. Below are a number of developments and policies that could eventually become 3.x; please, use the project's (user and developer) mailinglists to give your opinions, using a 3.x Roadmap message tag.

Disclaimer: there is nothing official yet about any of the below-mentioned suggestions; on the contrary, they are currently just the reflections of one single person, Herman Bruyninckx. (Please, update this disclaimer if you add your own suggestions.)

General policies to be followed in this Roadmap:

• the anti-Not Invented Here policy: whenever there exists a FOSS project that has already a solution for (part of) this roadmap, we should try to cooperate with that project, instead of putting efforts in our own version.
• the big critical mass projects first policy: when being confronted with the situation above, it is much preferred to cooperate with (contribute to) projects that have a high critical mass (Cmake, Linux, Eclipse, Qt, etc.) instead of with single-person or single-team projects, even when the latter currently have better functionalities and ideas. At the same time, promising single-person projects will be stimulated to make their efforts useful in a larger critical mass project.

Orocos distribution

• a "Hello Robot!" application, installable as a ROS stack. It could contain a simulated robot, visualised in Morse or Gazebo, and componentized in an RTT component, together with an RTT/KDL/BFL-based set of motion controllers and estimators. (Morse is currently the most promising candidate, from a component-based development point of view.)
• a (Wiki) book that explains the whole setup, not just from a software point of view, but also a motivation why the presented example could be considered as a "best practice" as a robotics system. This Wiki book should not be an Orocos-only effort, but be useful for the whole community.
• a similar "Hello Machine!" application, targeting not the robotics community, but the mechatronics, or machine tools community.

Contributors to this part of the Roadmap need not be RTT developers, but motivated users!

RTT

• RTT will get a complete and explicit component model, existing of component, composite component, connection, port, interface, discrete behaviour, and communication:
  • The OROMACS development at the University of Twente have already produced a core of the composite component. That concept is required for a full support of the Model-Driven Engineering approach.
  • the connection is the data-less, event-less and command-less representation of the architecture of a system, consisting of only the identification of which components will interact with each other.
  • the difference between a port and an interface is that a port belongs to a component, and implements an interface; the interface in itself must become a first-class citizen of the component model.
  • discrete behaviour is the current state machine. Further developments in this context are probably only to be expected at the implementation and tooling front.
  • communication: Orocos has had, from day one, the ambition to not provide communication middleware, since there are so many other projects that do that. RTT should, however, improve its decoupling of (i) using data structures inside a component, (ii) providing them for communication in a port, and (iii) transporting them from one component's port to another component's port. Maybe this is as easy as cleanly separating the configuration files for all three aspects; maybe it's more involved than that.
• the mapping on real hardware resources (computational thread, communication field bus) is separated from the definition of a component.
• the process of defining data flow data structures is supported by an IDL language. This IDL has to be chosen together with other projects, and should not be an Orocos-only effort. A real IDL includes the definition of the meaning of the fields in the data, and not just their computer language representation.
• the codel idea of GenoM3 is supported for the construction of continuous behaviour inside a component. The important role of the codel idea in the context of realtime systems is that one should give the component designer full control over when which computations are to be executed (instead of relying on the OS scheduler); this requires a design in which computations can be subdivided in pre-emptible pieces (codels), and in which they can be scheduled in efficient Directed Acyclic Graphs.

Contributors to this part of the Roadmap need be RTT developers!

BFL, KDL, SCL

All three libraries share a common fundamental design property, and that is that they can all be considered as special cases of executable graphs, so a common support will be developed for the flexible, configurable scheduling off all computations (codels) in complex networks (Bayesian networks, kinematic/dynamic networks, control diagrams).

Contributors to this part of the Roadmap need not be RTT developers, but domain experts that have become power users of the RTT infrastructure!

iTaSC and beyond

As a first step, the instantaneous version of a constrained-based optimization approach to task-level control will be provided. Following steps will extend the instantaneous idea towards non-instantaneous tasks. This extension must be focused on tasks that require realtime performance, since non-realtime solutions are provided by other projects, such as ROS.

Contributors to this part of the Roadmap need not be RTT developers, but domain experts that also happen to be average users of the RTT infrastructure! They will open up the functionalities of Orocos to the normal end-user.

Tooling

The first efforts in this direction have started, in the context of the European project BRICS.

Contributors to this part of the Roadmap need not be RTT developers, but programmers familiar with the advanced Eclipse features, such as ecore models, EMG, etc.

euRobotics Forum Linux Setup

Toolchain Installation

NOTE: ROS is required to participate in the YouBot demo.

With ROS on Ubuntu Lucid/Maverick

Install Diamondback ROS using Debian packages for Ubuntu Lucid (10.04) and Maverick (10.10) or the ROS install scripts, in case you don't run Ubuntu.

• Install the ros-diamondback-orocos-toolchain-ros debian package version 0.3.1 or later:  apt-get install ros-diamondback-orocos-toolchain-ros After this step, proceed to Section 2: Workshop Sources below.

With ROS on Debian, Fedora or other systems

• We did not succeed in releasing the Diamondback 0.3.0 binary packages for your target of the Orocos Toolchain. This means that you need to build this 'stack' yourself with 'rosmake', after you installed ROS (See http://www.ros.org/wiki/diamondback/Installation). This 'rosmake' step may take about 30 minutes to an hour, depending on your laptop.

Instructions after ROS is installed:

source /opt/ros/diamondback/setup.bash
mkdir ~/ros
cd ~/ros
export ROS_PACKAGE_PATH=$HOME/ros:$ROS_PACKAGE_PATH
git clone http://git.mech.kuleuven.be/robotics/orocos_toolchain_ros.git
cd orocos_toolchain_ros
git checkout -b diamondback origin/diamondback
git submodule init
git submodule update --recursive
rosmake --rosdep-install orocos_toolchain_ros

NOTE: setting the ROS_PACKAGE_PATH is mandatory for each shell that will be used. It's a good idea to add the export ROS_PACKAGE_PATH line above to your .bashrc file (or equivalent)..

Without ROS

• Run the bootstrap.sh (version 2.3.1) script in an empty directory.

Workshop Sources

euRobotics Forum Mac OS-X Setup

Toolchain Installation

Due to a dynamic library issue in the current 2.3 release series, Mac OS-X can not be supported during the Workshop. We will make available a bootable USB stick which contains a pre-installed Ubuntu environment containing all necessary packages.

euRobotics Forum Windows Setup

Toolchain Installation

Requirements:

• Visual Studio 2005 or 2008
• CMake 2.6.3 or newer (2.8.x works too)
• Boost C++ 1.40.0
• Readline for Windows (see Taskbrowser with readline on Windows)
• Cygwin installation (default setup is fine)

See the Compiling on Windows with Visual Studio wiki page for instructions. The TAO/Corba part is not required to participate in the workshop.

You need to follow the instructions for RTT/OCL v2.3.1 or newer, which you can download from the Orocos Toolchain page. We recommend to build for Release.

In case you have no time nor the experience to set this up, we provide bootable USB sticks that contain Ubuntu Linux with all workshop files.

Workshop Sources

Windows users might also install the Kst program which is a KDE plot program that also runs on Linux. We provided a .kst file for plotting the workshop data. See the Kst download page.

Testing Your Setup

set PATH=%PATH%;c:\orocos\bin;c:\orocos\lib;c:\orocos\lib\orocos\win32;c:\orocos\lib\orocos\win32\plugins

You repeat the classical CMake steps with this package, generate the Solution file and build and install it. Then start up the deployer with the deployer-win32.exe program and type 'ls'. It should start and show meaningful information. If you see strange characters in the output, you need to turn of the colors with the '.nocolors' command at the Deployer's prompt.

euRobotics Workshop Material

The euRobotics Forum workshop on Orocos has been a great success. About 30 people attended and participated in the hands-on workshop. The Real-Time & Open Source in Robotics track drew more than 60 people. Both tracks were overbooked.

You can find all presentation material in PDF form below

• Real-Time Robotics with state-of-the art open source software: case studies
• Introduction to the Orocos Toolchain
• Introducing the Hello World Exercises
• YouBot Exercise

euRobotics Workshop Sources

There are two ways you can get the sources for the workshop:

• Using Git
• Using a zip file

Since the sources are still evolving, it might be necessary to update your version before the workshop.

Hello World application

You can either check it out with

mkdir ~/ros
cd ~/ros
git clone git://gitorious.org/orocos-toolchain/rtt_examples
cd rtt_examples/rtt-exercises

Or you can download the examples from here. You need at least version 2.3.1 of the exercises.

If you're not using ROS, you can download/unzip it in another directory than ~/ros.

Youbot demo application

The hands-on session involves working on a demo application with a YouBot robot. The application allows you to

• Drive the YouBot around based on pose estimates using laser scan measurements
• Simulate the YouBot on your own computer

The Youbot demo application is available on https://github.com/bellenss/euRobotics_orocos_ws (this is still work in progress and will be updated regularly)

You can either check it out with

mkdir ~/ros
export ROS_PACKAGE_PATH=\$ROS_PACKAGE_PATH:$HOME/ros
cd ~/ros
git clone http://robotics.ccny.cuny.edu/git/ccny-ros-pkg/scan_tools.git
git clone http://git.mech.kuleuven.be/robotics/orocos_bayesian_filtering.git
git clone http://git.mech.kuleuven.be/robotics/orocos_kinematics_dynamics.git
git clone git://github.com/bellenss/euRobotics_orocos_ws.git
roscd youbot_supervisor
rosmake --rosdep-install

Check that ~/ros is in your ROS_PACKAGE_PATH environment variable at all times, by also adding the export line above to your .bashrc file.

Testing your setup

Non-ROS users

cd orocos-toolchain
source env.sh

Next, cd to the rtt-exercises directory that you unpacked, enter hello-1-task-execution, and type make:

cd rtt-exercises-2.3.0/hello-1-task-execution
make all
cd build
./HelloWorld-gnulinux

ROS users

cd rtt-exercises-2.3.0
source /opt/ros/diamondback/setup.bash
export ROS_PACKAGE_PATH=\$ROS_PACKAGE_PATH:\$(pwd)

Next, you proceed with going into an example directory and type make:

cd hello-1-task-execution
make all
./HelloWorld-gnulinux

Testing the YouBot Demo

After you have built the youbot_supervisor, you can test the demo by opening two consoles and do in them:

First console:

roscd youbot_supervisor
./simulation.sh

Second console:

roscd youbot_supervisor
./changePathKst (you only have to do this once after installation)
kst plotSimulation.kst

If you do not have 'kst', install it with  sudo apt-get install kst kst-plugins

Installation instructions

Ubuntu Installation with ROS

Installation

• Install Electric ROS using Debian packages for Ubuntu Lucid (10.04) or later. In case you don't run Ubuntu you can use the ROS install scripts. See the ros installation instructions.

• • Make sure the following debian packages are installed: ros-electric-rtt-ros-integration ros-electric-rtt-ros-comm ros-electric-rtt-geometry ros-electric-rtt-common-msgs ros-electric-pr2-controllers ros-electric-pr2-simulator ruby

• Create a directory in which you want to install all the workshops source (for instance erf)

mkdir ~/erf

• Add this directory to your $ROS_PACKAGE_PATH

export ROS_PACKAGE_PATH=~/erf:$ROS_PACKAGE_PATH

• Get rosinstall

sudo apt-get install python-setuptools
sudo easy_install -U rosinstall

• Get the workshop's rosinstall file . Save it as erf.rosinstall in the erf folder.

• Run rosinstall

rosinstall ~/erf erf.rosinstall /opt/ros/electric

• As the rosinstall tells you source the setup script

source ~/erf/setup.bash

• Install all dependencies (ignore warnings)

rosdep install itasc_examples
rosdep install rFSM

• Compile the workshop sources

rosmake itasc_examples

Setup

• Add the following functions in your $HOME/.bashrc file:

useERF(){
    source $HOME/erf/setup.bash;
    source $HOME/erf/setup.sh;
    source /opt/ros/electric/stacks/orocos_toolchain/env.sh;
    setLUA;
}
 
setLUA(){
    if [ "x$LUA_PATH" == "x" ]; then LUA_PATH=";;"; fi
    if [ "x$LUA_CPATH" == "x" ]; then LUA_CPATH=";;"; fi
    export LUA_PATH="$LUA_PATH;`rospack find rFSM`/?.lua"
    export LUA_PATH="$LUA_PATH;`rospack find ocl`/lua/modules/?.lua"
    export LUA_PATH="$LUA_PATH;`rospack find kdl`/?.lua"
    export LUA_PATH="$LUA_PATH;`rospack find rttlua_completion`/?.lua"
    export LUA_PATH="$LUA_PATH;`rospack find youbot_master_rtt`/lua/?.lua"
    export LUA_PATH="$LUA_PATH;`rospack find kdl_lua`/lua/?.lua"
    export LUA_CPATH="$LUA_CPATH;`rospack find rttlua_completion`/?.so"
    export PATH="$PATH:`rosstack find orocos_toolchain`/install/bin"
}
 
useERF

Running the demo

Gazebo simulation

• Open a terminal and go to the itasc_erf_2012 package:

roscd itasc_erf2012_demo/

• Run the script that starts the gazebo simulator (and two translator topics to communicate with the itasc code)

./run_gazebo.sh

• Open another terminal and go to the itasc_erf_2012 package:

roscd itasc_erf2012_demo/

• Run the script that starts the itasc application

./run_simulation.sh

Real youbot

• Make sure that you are connected to the real youbot.
• Open another terminal and go to the itasc_erf_2012 package:

roscd itasc_erf2012_demo/

• Check the name of the network connection with the robot (for instance eth0) and put this connection name in the youbot_driver cpf file (cpf/youbot_driver.cpf)
• Run the script that starts the itasc application

./run.sh

rfsm-session

Additonal Information on the Practical Session

Documentation Links

• rFSM documentation
• rFSM cheatsheet
• OROCOS RTT-Lua Cookbook including rFSM recipies.
• minimal rFSM - RTT example

Other

• Markus' slides (see below)

What is it?

This wiki contains a summary of the article accepted as a tutorial for IEEE Robotics and Automation Magazine on the 4th June 2012.

Rigid bodies are essential primitives in the modelling of robotic devices, tasks and perception, starting with the basic geometric relations such as relative position, orientation, pose, translational velocity, rotational velocity, and twist. This wiki elaborates on the background and the software for the semantics underlying rigid body relationships. This wiki is based on the research of the KU Leuven robotics group, in this case mainly conducted by Tinne De Laet, to explain semantics of all coordinate-invariant properties and operations, and, more importantly, to document all the choices that are made in coordinate representations of these geometric relations. This resulted in a set of concrete suggestions for standardizing terminology and notation, and software with a fully unambiguous software interface, including automatic checks for semantic correctness of all geometric operations on rigid-body coordinate representations.

The geometric relations semantics software prevents commonly made errors in geometric rigid-body relations calculations like:

• Logic errors in geometric relation calculations: A lot of logic errors can occur during geometric relation calculations. For instance (there is no need to understand the details just have a look at the difference in syntax), the inverse of $\textrm{Position} \left(e|\mathcal{C}, f |\mathcal{D}\right)$ is $\textrm{Position} \left(f|\mathcal{D}, e |\mathcal{C}\right)$, while the inverse of the translational velocity $\textrm{TranslationVelocity} \left(e|\mathcal{C}, \mathcal{D}\right)$ is $\textrm{TranslationVelocity} \left(e|\mathcal{D}, \mathcal{C}\right)$. When using the semantic representation proposed in this paper, the semantics of the inverse geometric relation can be automatically derived from the forward geometric relation, preventing logic errors. A second example emerges when composing the relations involving three rigid bodies: in order to get the geometric relation of $\mathcal{C}$ with respect to body $\mathcal{D}$ one can compose the geometric relation between $\mathcal{C}$ and third body $\mathcal{E}$ with the geometric relation between body $\mathcal{E}$ and the body $\mathcal{D}$ (and not the geometric relation between the body $\mathcal{D}$ and the body $\mathcal{E}$ for instance). Such a logic constraint can be checked easily by including, for instance, the body and reference body in the semantic representation of the geometric relations.
• Composition of twists with different velocity reference point: Composing twists requires a common velocity reference point (i.e. the twists have to express the translational velocity of the same point on the body). By including the velocity reference point of the twist in the semantic representation, this constraint can be checked explicitly.
• Composition of geometric relations expressed in different coordinate frames: Composing geometric relations using coordinate representations like position vectors, translational and rotational velocity vectors, and 6D vector twists, requires that the coordinates are expressed in the same coordinate frame. By including the coordinate frame in the coordinate semantic representation of the geometric relations, this constraint can be checked explicitly.
• Composition of poses and orientation coordinate representations in wrong order: The rotation matrix and homogeneous transformation matrix coordinate representations can be composed using simple multiplication. Since matrix multiplication is however not commutative, a common error is to use a wrong multiplication order in the composition. The correct multiplication order can however be directly derived when including the bodies, frames, and points in the coordinate semantic representation of the geometric relations.
• Integration of twists when velocity reference point and coordinate frame do not belong to same frame: A twist can only be integrated when it expresses the translational velocity of the origin of the coordinate frame the twist is expressed in. When including the velocity reference point and the coordinate frame in the coordinate semantic representation of the twist, this constraint can be explicitly checked.

Background

This wiki contains a summary of the article accepted as a tutorial for IEEE Robotics and Automation Magazine on the 4th June 2012.

Background and terminology

A rigid body is an idealization of a solid body of infinite or finite size in which deformation is neglected. We often abbreviate “rigid body” to “body”, and denotes it by the symbol $\mathcal{A}$. A body in three-dimensional space has six degrees of freedom: three degrees of freedom in translation and three in rotation. The subspace of all body motions that involve only changes in the orientation is often denoted by SO(3) (the Special Orthogonal group in three-dimensional space). It forms a group under the operation of composition of relative motion. The space of all body motions, including translations, is denoted by SE(3) (the Special Euclidean group in three-dimensional space).

A general six-dimensional displacement between two bodies is called a (relative) pose: it contains both the position and orientation. Remark that the position, orientation, and pose of a body are not absolute concepts, since they imply a second body with respect to which they are defined. Hence, only the relative position, orientation, and pose between two bodies are relevant geometric relations.

A general six-dimensional velocity between two bodies is called a (relative) twist: it contains both the rotational and the translational velocity. Similar to the position, orientation, and pose, the translational velocity, rotational velocity, and twist of a body are not absolute concepts, since they imply a second body with respect to which they are defined. Hence, only the relative translational velocity, rotational velocity, and twist between two bodies are relevant geometric relations.

When doing actual calculations with the geometric relations between rigid bodies, one has to use the coordinate representation of the geometric relations, and therefore has to choose a coordinate frame in which the coordinates are expressed in order to obtain numerical values for the geometric relations.

Semantics

Geometric primitives

• A (spatial) point is the primitive to represent the position of a body. Points have neither volume, area, length, nor any other higher dimensional analogue. We denote points by the symbols $a$, $b$, ...
• A vector is the geometric primitive that connects a point $a$ to a point $b$. It has a magnitude (the straight-line distance between the two points), and a direction (from $a$ to $b$). To express the magnitude of a vector, a (length) scale must be chosen.
• An orientation frame represents an orientation, by means of three orthonormal vectors indicating the frame’s X-axis $X$, Y-axis $Y$ , and Z-axis $Z$. We denote orientation frames by the symbols $\left[a\right]$, $\left[b\right]$, ...
• A (displacement) frame represents position and orientation of a body, by means of an orientation frame and a point (which is the orientation frame’s origin). We denote frames by the symbols $\left\{a\right\}$, $\left\{b\right\}$, ...

Each of these geometric primitives can be fixed to a body, which means that the geometric primitive coincides with the body not only instantaneously, but also over time. For the point $a$ and the body $\mathcal{C}$ for instance, this is written as $a|\mathcal{C}$. The figure below presents the geometric primitives body, point, vector, orientation frame, and frame graphically.

Geometric Primitives

Geometric relations

The table below summarizes the semantics for the following geometric relations between rigid bodies: position, orientation, pose, translational velocity, rotational velocity, and twist.

Geometric relations

Force, Torque, and Wrench

Geometric relations force, torque, and wrench

Design

The software implements the geometric relation semantics, hereby offering support for semantic checks for your rigid body relations. This will avoid commonly made errors, and hence reduce application (and, especially, system integration) development time considerably. The proposed software is to our knowledge the first to offer a semantic interface for geometric operation software libraries.

The design idea

For the semantic checking, we created the (templated) geometric_semantics core library, providing all the necessary semantic support for geometric relations (relative positions, orientations, poses, translational velocities, rotational velocities, twists, forces, torques, and wrenches) and the operations on these geometric relations (composition, integration, inversion, ...).

If you want to perform actual geometric relation calculations, you will need particular coordinate representations (for instance a homogeneous transformation matrix for a pose) and a geometric library offering support for calculations on these coordinate representations (for instance multiplication of homogeneous transformation matrices). To this end, you can build your own library depending on the geometric_semantics core library in which you implement a limited number of functions, which make the connection between semantic operations (for instance composition) and actual coordinate representation calculations (for instance multiplication of homogeneous transformation matrices). We already provide support for two geometric libraries: the Orocos Kinematics and Dynamics library and the ROS geometry library, in the geometric_semantics_kdl and geometric_semantics_tf libraries, respectively.

The design

• PositionSemantics: This class contains the semantics of the (coordinate-free) Position geometric relation. For instance in this case it contains the information on the point, reference point, body, and reference body.
• PositionCoordinatesSemantics: This class contains a PositionSemantics object of the geometric relation at hand and the extra semantic information needed for semantics of position coordinate geometric relation, i.e. the coordinate frame in which the coordinates are expressed.
• PositionCoordinates: This templated class contains the actual coordinate representation of the geometric relation, for instance a position vector for the position geometric relation. The template is the actual geometry object (of an external library) you will use as a coordinate representation, for instance a KDL::Vector.
• Position: This templated class is a composition of a PositionCoordinatesSemantics object and a PositionCoordinates object. In case you want both semantic support and want to do actual geometric calculations, this is the level you will work at.

Again, the template is the actual geometry (of an external library) you will use as a coordinate representation, for instance a KDL::Vector.

The above described design is illustrated by the figure below. Position geometric relation design

Remark that all four of the above 'levels' are of actual use:

• PositionSemantics: to do coordinate-free semantic checking (without actual geometric calculations);
• PositionCoordinateSemantics: to do semantic checking involving coordinate systems (without actual geometric calculations);
• PositionCoordinates: to do the actual geometric calculations; and
• Position: to do both semantic checking and the actual geometric calculations.

Pose, Twist, and Wrench

Pose geometric relation design as a basic geometric relation

Pose geometric relation design as an composition of a Position and Orientation geometric relation

The software structure and content

Core library: geometric_semantics

KDL support: geometric_semantics_kdl

ROS tf support: geometric_semantics_tf

ROS messages: geometric_semantics_msgs

ROS message conversions: geometric_semantics_msgs_conversions

ROS tf messages support: geometric_semantics_tf_msgs

ROS tf message conversions: geometric_semantics_tf_msgs_conversions

Examples: geometric_semantics_examples

API

The API is available at: http://people.mech.kuleuven.be/~tdelaet/geometric_relations_semantics/doc/.

Quick start

Overview

• geometric_relations_semantics.

This stack consists of following packages:

• geometric_semantics: geometric_semantics is the core of the geometric_relations_semantics stack and provides c++ code for the semantic support of geometric relations between rigid bodies (relative position, orientation, pose, translational velocity, rotational velocity, twist, force, torque, and wrench). If you want to use semantic checking for the geometric relation operations between rigid bodies in your application you can check the geometric_semantics_examples package. If you want to create support for your own geometry types on top of the geometric_semantics package, the geometric_semantics_kdl provides a good starting point.
• geometric_semantics_examples: geometric_semantics_examples groups some examples showing how the geometric_semantics can be used to provide semantic checking for the geometric relations between rigid bodies in your application.
• geometric_semantics_orocos_typekit: geometric_semantics_orocos_typekit provides Orocos typekit support for the geometric_semantics types, such that the geometric semantics types are visible within Orocos (in the TaskBrowser component, in Orocos script, reporting, reading and writing to files (for instance for properties), ... ).
• geometric_semantics_orocos_typekit_kdl: geometric_semantics_orocos_typekit_kdl provides Orocos typekit support for geometric semantics coordinate representations using KDL types.
• geometric_semantics_msgs: geometric_semantics_msgs provides ROS messages matching the C++ types defined on the geometric_semantics package, in order to support semantic support during message based communication.
• geometric_semantics_msgs_conversions: geometric_semantics_msgs_conversions provides support conversions between geometric_semantics_msgs and the C++ geometric_semantics types defined on the geometric_semantics package.
• geometric_semantics_msgs_kdl: geometric_semantics_kdl provides support for orocos_kdl types on top of the geometric_semantics package (for instance KDL::Frame to represent the relative pose of two rigid bodies). If you want to create support for your own geometry types on top of the geometric_semantics package, this package provides a good starting point.
• geometric_semantics_msgs_tf: geometric_semantics_tf provides support for tf datatypes (see http://www.ros.org/wiki/tf/Overview/Data%20Types) on top of the geometric_semantics package (for instance tf::Pose to represent the relative pose of two rigid bodies).
• geometric_semantics_tf_msgs: geometric_semantics_tf_msgs provides ROS messages matching the C++ types defined on the geometric_semantics_tf package, in order to support semantic support for tf types during message based communication.
• geometric_semantics_tf_msgs_conversions: geometric_semantics_tf_msgs_conversions provides support conversions between geometric_semantics_tf_msgs and the C++ geometric_semantics_tf types defined on the geometric_semantics_tf package.

Each package contains the following subdirectories:

• src/ containing the source code of the components (mainly C++ or python for the ROS msgs support).

Installation instructions

Dependencies

• Boost version 1.42 or up (for ubuntu you can use the libboost1.4*-dev libraries)
• Orocos Kinematics and Dynamics Library 0.2.3 and up. For more information visit the Orocos website
• rtt_geometry stack: the Orocos typekit support for KDL types, introduces a dependency on the kdl_typekit
• ROS Electric/Fuerte/Groovy: optional unless you want to use the PR2, but highly recommended: build system and tools like rospack find are practical and are used in the example scripts
• ros_comm
• geometry
• common_msgs

Compiling from source

• First you should get the sources from git using:

git clone https://gitlab.mech.kuleuven.be/rob-dsl/geometric-relations-semantics.git

• Go into the geometric_relations_semantics directory using:

cd geometric_relations_semantics

• Add this directory to your ROS_PACKAGE_PATH environment variable using:

export ROS_PACKAGE_PATH=$PWD:$ROS_PACKAGE_PATH

• Install the dependencies and build the library using:

rosdep install geometric_relations_semantics
rosmake geometric_relations_semantics

• Everything should compile out of the box, and you are now ready to start using geometric relation semantics support.
• If you want to run the test of the packages you should use for instance (for the geometric_semantics core package):

roscd geometric_semantics
make test

Setup

(Re)building the stack or individual packages

• To build the geometric_relations_semantics stack use:

rosmake geometric_relations_semantics

• You can also (re)build any package individually using:

rosmake PACKAGE_NAME

Running the tests

• If you want to run the test of the packages you should for go to the package for instance (for the geometric_semantics core package):

roscd geometric_semantics

• And next make and run the tests:

make test

User guide

If you are looking for installation instructions you should read the quick start.

Setting the build options of the core library

• add_definitions(-DCHECK): when using this build flag, the semantic checking will be enabled.
• add_definitions(-DOUTPUT_CORRECT): when using this build flag, you will get screen output for operations that are semantically correct.
• add_definitions(-DOUTPUT_WRONG): when using this build flag, you will get screen output for operations that are semantically wrong.

roscreate-pkg myApplication geometric_semantics_kdl

cd myApplication
export ROS_PACKAGE_PATH=$PWD:$ROS_PACKAGE_PATH

roscd myApplication

touch myApplication.cpp

#include <Pose/Pose.h>
#include <Pose/PoseCoordinatesKDL.h>

using namespace geometric_semantics;                                                                                                                                                                                                    using namespace KDL;

Rotation coordinatesRotB2_B1=Rotation::EulerZYX(M_PI,0,0);
Vector coordinatesPosB2_B1(2.2,0,0);
KDL::Frame coordinatesFrameB2_B1(coordinatesRotB2_B1,coordinatesPosB2_B1)

PoseCoordinates<KDL::Frame> poseCoordB2_B1(coordinatesFrameB2_B1);

Pose<KDL::Frame> poseB2_B1("b2","b2","B2","b1","b1","B1","b1",poseCoordB2_B1);

Pose<KDL::Frame> poseB1_B2 = poseB2_B1.inverse()

rosbuild_add_executable(myApplication myApplication.cpp)

rosmake myApplication

bin/myApplication

roscd geometric_semantics_kdl/

    /**                                                                                                                                                                                                                                      
      *\brief Constraints imposed by the orientation coordinate representation to the semantics                                                                                                                                              
      */                                                                                                                                                                                                                                     
    enum Constraints{                                                                                                                                                                                                                        
        noConstraints = 0x00,                                                                                                                                                                                                                
        coordinateFrame_equals_referenceOrientationFrame = 0x01, // constraint that the orientation frame on the reference body has to be equal to the coordinate frame                                                                      
    };  

// template specialization for KDL::Rotation                                                                                                                                                                                             
    template <>                                                                                                                                                                                                                              
    OrientationCoordinates<KDL::Rotation>::OrientationCoordinates(const KDL::Rotation& coordinates):                                                                                                                                         
        data(coordinates),                                                                                                                                                                                                                   
        constraints(coordinateFrame_equals_referenceOrientationFrame){    };  

   template <>                                                                                                                                                                                                                              
    OrientationCoordinates<KDL::Rotation> OrientationCoordinates<KDL::Rotation>::inverse2Impl() const                                                                                                                                        
    {                                                                                                                                                                                                                                        
        return OrientationCoordinates<KDL::Rotation>(this->data.Inverse());                                                                                                                                                                  
    }        

Tutorials

roscd myApplication

touch myFirstApplication.cpp

vim myFirstApplication.cpp

#include <Position/PositionSemantics.h>
#include <Orientation/OrientationSemantics.h>
#include <Pose/PoseSemantics.h>
#include <LinearVelocity/LinearVelocitySemantics.h>
#include <AngularVelocity/AngularVelocitySemantics.h>
#include <Twist/TwistSemantics.h>
#include <Force/ForceSemantics.h>
#include <Torque/TorqueSemantics.h>
#include <Wrench/WrenchSemantics.h>

using namespace geometric_semantics;

int main (int argc, const char* argv[])
{
// Here comes the code of our first application
}

vim CMakeLists.txt

rosbuild_add_executable(myFirstApplication myFirstApplication.cpp)

rosmake myApplication

bin/myFirstApplication

    // Creating the geometric relations semantics
    PositionSemantics position("a","C","b","D");
    OrientationSemantics orientation("e","C","f","D");
    PoseSemantics pose("a","e","C","b","f","D");
 
    LinearVelocitySemantics linearVelocity("a","C","D");
    AngularVelocitySemantics angularVelocity("C","D");
    TwistSemantics twist("a","C","D");
 
    TorqueSemantics torque("a","C","D");
    ForceSemantics force("C","D");
    WrenchSemantics wrench("a","C","D");

    //Doing semantic operations with the geometric relations
    // inverting
    PositionSemantics positionInv = position.inverse();
    OrientationSemantics orientationInv = orientation.inverse();
    PoseSemantics poseInv = pose.inverse();
    LinearVelocitySemantics linearVelocityInv = linearVelocity.inverse();
    AngularVelocitySemantics angularVelocityInv = angularVelocity.inverse();
    TwistSemantics twistInv = twist.inverse();
    TorqueSemantics torqueInv = torque.inverse();
    ForceSemantics forceInv = force.inverse();
    WrenchSemantics wrenchInv = wrench.inverse();

    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Inverses: " << std::endl;
    std::cout << "     " << positionInv << " is the inverse of " << position << std::endl;
    std::cout << "     " << orientationInv << " is the inverse of " << orientation << std::endl;
    std::cout << "     " << poseInv << " is the inverse of " << pose << std::endl;
    std::cout << "     " << linearVelocityInv << " is the inverse of " << linearVelocity << std::endl;
    std::cout << "     " << angularVelocityInv << " is the inverse of " << angularVelocity << std::endl;
    std::cout << "     " << twistInv << " is the inverse of " << twist << std::endl;
    std::cout << "     " << torqueInv << " is the inverse of " << torque << std::endl;
    std::cout << "     " << forceInv << " is the inverse of " << force << std::endl;
    std::cout << "     " << wrenchInv << " is the inverse of " << wrench << std::endl;

    //Composing
    PositionSemantics positionComp = compose(position,positionInv);
    OrientationSemantics orientationComp = compose(orientation,orientationInv);
    PoseSemantics poseComp = compose(pose,poseInv);
    LinearVelocitySemantics linearVelocityComp = compose(linearVelocity,linearVelocityInv);
    AngularVelocitySemantics angularVelocityComp = compose(angularVelocity,angularVelocityInv);
    TwistSemantics twistComp = compose(twist,twistInv);
    TorqueSemantics torqueComp = compose(torque,torqueInv);
    ForceSemantics forceComp = compose(force,forceInv);
    WrenchSemantics wrenchComp = compose(wrench,wrenchInv);

    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Composed objects: " << std::endl;
    std::cout << "     " << positionComp << " is the composition of " << position << " and " << positionInv << std::endl;
    std::cout << "     " << orientationComp << " is the composition of " << orientation << " and " << orientationInv <<  std::endl;
    std::cout << "     " << poseComp << " is the composition of " << pose <<  " and " << poseInv << std::endl;
    std::cout << "     " << linearVelocityComp << " is the composition of " << linearVelocity  << " and " << linearVelocityInv << std::endl;
    std::cout << "     " << angularVelocityComp << " is the composition of " << angularVelocity  << " and " << angularVelocityInv << std::endl;
    std::cout << "     " << twistComp << " is the composition of " << twist <<  " and " << twistInv << std::endl;
    std::cout << "     " << torqueComp << " is the composition of " << torque <<  " and " << torqueInv << std::endl;
    std::cout << "     " << forceComp << " is the composition of " << force <<  " and " << forceInv << std::endl;
    std::cout << "     " << wrenchComp << " is the composition of " << wrench <<  " and " << wrenchInv << std::endl;

vim mySecondApplication.cpp

#include <Position/PositionCoordinatesSemantics.h>
#include <Orientation/OrientationCoordinatesSemantics.h>
#include <Pose/PoseCoordinatesSemantics.h>
#include <LinearVelocity/LinearVelocityCoordinatesSemantics.h>
#include <AngularVelocity/AngularVelocityCoordinatesSemantics.h>
#include <Twist/TwistCoordinatesSemantics.h>
#include <Force/ForceCoordinatesSemantics.h>
#include <Torque/TorqueCoordinatesSemantics.h>
#include <Wrench/WrenchCoordinatesSemantics.h>

using namespace geometric_semantics;

int main (int argc, const char* argv[])
{
// Here comes the code of our second application
}

rosbuild_add_executable(mySecondApplication mySecondApplication.cpp)

rosmake myApplication

bin/mySecondApplication

    // Creating the geometric relations coordinates semantics
    PositionCoordinatesSemantics position("a","C","b","D","r");
    OrientationCoordinatesSemantics orientation("e","C","f","D","r");
    PoseCoordinatesSemantics pose("a","e","C","b","f","D","r");
 
    LinearVelocityCoordinatesSemantics linearVelocity("a","C","D","r");
    AngularVelocityCoordinatesSemantics angularVelocity("C","D","r");
    TwistCoordinatesSemantics twist("a","C","D","r");
 
    TorqueCoordinatesSemantics torque("a","C","D","r");
    ForceCoordinatesSemantics force("C","D","r");
    WrenchCoordinatesSemantics wrench("a","C","D","r");

    //Doing semantic operations with the geometric relations
    // inverting
    PositionCoordinatesSemantics positionInv = position.inverse();
    OrientationCoordinatesSemantics orientationInv = orientation.inverse();
    PoseCoordinatesSemantics poseInv = pose.inverse();
    LinearVelocityCoordinatesSemantics linearVelocityInv = linearVelocity.inverse();
    AngularVelocityCoordinatesSemantics angularVelocityInv = angularVelocity.inverse();
    TwistCoordinatesSemantics twistInv = twist.inverse();
    TorqueCoordinatesSemantics torqueInv = torque.inverse();
    ForceCoordinatesSemantics forceInv = force.inverse();
    WrenchCoordinatesSemantics wrenchInv = wrench.inverse();

    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Inverses: " << std::endl;
    std::cout << "     " << positionInv << " is the inverse of " << position << std::endl;
    std::cout << "     " << orientationInv << " is the inverse of " << orientation << std::endl;
    std::cout << "     " << poseInv << " is the inverse of " << pose << std::endl;
    std::cout << "     " << linearVelocityInv << " is the inverse of " << linearVelocity << std::endl;
    std::cout << "     " << angularVelocityInv << " is the inverse of " << angularVelocity << std::endl;
    std::cout << "     " << twistInv << " is the inverse of " << twist << std::endl;
    std::cout << "     " << torqueInv << " is the inverse of " << torque << std::endl;
    std::cout << "     " << forceInv << " is the inverse of " << force << std::endl;
    std::cout << "     " << wrenchInv << " is the inverse of " << wrench << std::endl;

    //Composing
    PositionCoordinatesSemantics positionComp = compose(position,positionInv);
    OrientationCoordinatesSemantics orientationComp = compose(orientation,orientationInv);
    PoseCoordinatesSemantics poseComp = compose(pose,poseInv);
    LinearVelocityCoordinatesSemantics linearVelocityComp = compose(linearVelocity,linearVelocityInv);
    AngularVelocityCoordinatesSemantics angularVelocityComp = compose(angularVelocity,angularVelocityInv);
    TwistCoordinatesSemantics twistComp = compose(twist,twistInv);
    TorqueCoordinatesSemantics torqueComp = compose(torque,torqueInv);
    ForceCoordinatesSemantics forceComp = compose(force,forceInv);
    WrenchCoordinatesSemantics wrenchComp = compose(wrench,wrenchInv);

    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Composed objects: " << std::endl;
    std::cout << "     " << positionComp << " is the composition of " << position << " and " << positionInv << std::endl;
    std::cout << "     " << orientationComp << " is the composition of " << orientation << " and " << orientationInv <<  std::endl;
    std::cout << "     " << poseComp << " is the composition of " << pose <<  " and " << poseInv << std::endl;
    std::cout << "     " << linearVelocityComp << " is the composition of " << linearVelocity  << " and " << linearVelocityInv << std::endl;
    std::cout << "     " << angularVelocityComp << " is the composition of " << angularVelocity  << " and " << angularVelocityInv << std::endl;
    std::cout << "     " << twistComp << " is the composition of " << twist <<  " and " << twistInv << std::endl;
    std::cout << "     " << torqueComp << " is the composition of " << torque <<  " and " << torqueInv << std::endl;
    std::cout << "     " << forceComp << " is the composition of " << force <<  " and " << forceInv << std::endl;
    std::cout << "     " << wrenchComp << " is the composition of " << wrench <<  " and " << wrenchInv << std::endl;

vim myThirdApplication.cpp

#include <Position/Position.h>
#include <Orientation/Orientation.h>
#include <Pose/Pose.h>
#include <LinearVelocity/LinearVelocity.h>
#include <AngularVelocity/AngularVelocity.h>
#include <Twist/Twist.h>
#include <Force/Force.h>
#include <Torque/Torque.h>
#include <Wrench/Wrench.h>
 
#include <Position/PositionCoordinatesKDL.h>
#include <Orientation/OrientationCoordinatesKDL.h>
#include <Pose/PoseCoordinatesKDL.h>
#include <LinearVelocity/LinearVelocityCoordinatesKDL.h>
#include <AngularVelocity/AngularVelocityCoordinatesKDL.h>
#include <Twist/TwistCoordinatesKDL.h>
#include <Force/ForceCoordinatesKDL.h>
#include <Torque/TorqueCoordinatesKDL.h>
#include <Wrench/WrenchCoordinatesKDL.h>
 
#include <kdl/frames.hpp>
#include <kdl/frames_io.hpp>

using namespace geometric_semantics;
using namespace KDL;

int main (int argc, const char* argv[])
{
// Here goes the code of our third application
}

rosbuild_add_executable(myThirdApplication myThirdApplication.cpp)

rosmake myApplication

bin/myThirdApplication

  // Creating the geometric relations 
 
    // a Position with a KDL::Vector
    Vector coordinatesPosition(1,2,3);
    Position<Vector> position("a","C","b","D","r",coordinatesPosition);
 
    // an Orientation with KDL::Rotation
    Rotation coordinatesOrientation=Rotation::EulerZYX(M_PI/4,0,0);
    Orientation<Rotation> orientation("e","C","f","D","f",coordinatesOrientation);
 
    // a Pose with a KDL::Frame
    KDL::Frame coordinatesPose(coordinatesOrientation,coordinatesPosition);
    Pose<KDL::Frame> pose1("a","e","C","b","f","D","f",coordinatesPose);
 
    // a Pose as aggregation of a Position and a Orientation
    Pose<Vector,Rotation> pose2(position,orientation);
 
    // a LinearVelocity with a KDL::Vector
    Vector coordinatesLinearVelocity(1,2,3);
    LinearVelocity<Vector> linearVelocity("a","C","D","r",coordinatesLinearVelocity);
 
    // a AngularVelocity with a KDL::Vector
    Vector coordinatesAngularVelocity(1,2,3);
    AngularVelocity<Vector> angularVelocity("C","D","r",coordinatesAngularVelocity);
 
    // a Twist with a KDL::Twist
    KDL::Twist coordinatesTwist(coordinatesLinearVelocity,coordinatesAngularVelocity);
    geometric_semantics::Twist<KDL::Twist> twist1("a","C","D","r",coordinatesTwist);
 
    // a Twist of a LinearVelocity and a AngularVelocity
    geometric_semantics::Twist<Vector,Vector> twist2(linearVelocity,angularVelocity);
 
    // a Torque with a KDL::Vector
    Vector coordinatesTorque(1,2,3);
    Torque<Vector> torque("a","C","D","r",coordinatesTorque);
 
    // a Force with a KDL::Vector
    Vector coordinatesForce(1,2,3);
    Force<Vector> force("C","D","r",coordinatesForce);
 
    // a Wrench with a KDL::Wrench
    KDL::Wrench coordinatesWrench(coordinatesForce,coordinatesTorque);
    geometric_semantics::Wrench<KDL::Wrench> wrench1("a","C","D","r",coordinatesWrench);
 
    // a Wrench of a Force and a Torque
    geometric_semantics::Wrench<KDL::Vector,KDL::Vector> wrench2(torque,force);

    //Doing operations with the geometric relations
    // inverting
    Position<Vector> positionInv = position.inverse();
    Orientation<Rotation> orientationInv = orientation.inverse();
    Pose<KDL::Frame> pose1Inv = pose1.inverse();
    Pose<Vector,Rotation> pose2Inv = pose2.inverse();
    LinearVelocity<Vector> linearVelocityInv = linearVelocity.inverse();
    AngularVelocity<Vector> angularVelocityInv = angularVelocity.inverse();
    geometric_semantics::Twist<KDL::Twist> twist1Inv = twist1.inverse();
    geometric_semantics::Twist<Vector,Vector> twist2Inv = twist2.inverse();
    Torque<Vector> torqueInv = torque.inverse();
    Force<Vector> forceInv = force.inverse();
    geometric_semantics::Wrench<KDL::Wrench> wrench1Inv = wrench1.inverse();
    geometric_semantics::Wrench<Vector,Vector> wrench2Inv = wrench2.inverse();

    // print the inverses
    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Inverses: " << std::endl;
    std::cout << "     " << positionInv << " is the inverse of " << position << std::endl;
    std::cout << "     " << orientationInv << " is the inverse of " << orientation << std::endl;
    std::cout << "     " << pose1Inv << " is the inverse of " << pose1 << std::endl;
    std::cout << "     " << pose2Inv << " is the inverse of " << pose2 << std::endl;
    std::cout << "     " << linearVelocityInv << " is the inverse of " << linearVelocity << std::endl;
    std::cout << "     " << angularVelocityInv << " is the inverse of " << angularVelocity << std::endl;
    std::cout << "     " << twist1Inv << " is the inverse of " << twist1 << std::endl;
    std::cout << "     " << twist2Inv << " is the inverse of " << twist2 << std::endl;
    std::cout << "     " << torqueInv << " is the inverse of " << torque << std::endl;
    std::cout << "     " << forceInv << " is the inverse of " << force << std::endl;
    std::cout << "     " << wrench1Inv << " is the inverse of " << wrench1 << std::endl;
    std::cout << "     " << wrench2Inv << " is the inverse of " << wrench2 << std::endl;

    //Composing
    Position<Vector> positionComp = compose(position,positionInv);
    Orientation<Rotation> orientationComp = compose(orientation,orientationInv);
    Pose<KDL::Frame> pose1Comp = compose(pose1,pose1Inv);
    Pose<Vector,Rotation> pose2Comp = compose(pose2,pose2Inv);
    LinearVelocity<Vector> linearVelocityComp = compose(linearVelocity,linearVelocityInv);
    AngularVelocity<Vector> angularVelocityComp = compose(angularVelocity,angularVelocityInv);
    geometric_semantics::Twist<KDL::Twist> twist1Comp = compose(twist1,twist1Inv);
    geometric_semantics::Twist<Vector,Vector> twist2Comp = compose(twist2,twist2Inv);
    Torque<Vector> torqueComp = compose(torque,torqueInv);
    Force<Vector> forceComp = compose(force,forceInv);
    geometric_semantics::Wrench<KDL::Wrench> wrench1Comp = compose(wrench1,wrench1Inv);
    geometric_semantics::Wrench<Vector,Vector> wrench2Comp = compose(wrench2,wrench2Inv);;    

    // print the composed objects
    std::cout << "-----------------------------------------" << std::endl;
    std::cout << "Composed objects: " << std::endl;
    std::cout << "     " << positionComp << " is the composition of " << position << " and " << positionInv << std::endl;
    std::cout << "     " << orientationComp << " is the composition of " << orientation << " and " << orientationInv <<  std::endl;
    std::cout << "     " << pose1Comp << " is the composition of " << pose1 <<  " and " << pose1Inv << std::endl;
    std::cout << "     " << pose2Comp << " is the composition of " << pose2 <<  " and " << pose2Inv << std::endl;
    std::cout << "     " << linearVelocityComp << " is the composition of " << linearVelocity  << " and " << linearVelocityInv << std::endl;
    std::cout << "     " << angularVelocityComp << " is the composition of " << angularVelocity  << " and " << angularVelocityInv << std::endl;
    std::cout << "     " << twist1Comp << " is the composition of " << twist1 <<  " and " << twist1Inv << std::endl;
    std::cout << "     " << twist2Comp << " is the composition of " << twist2 <<  " and " << twist2Inv << std::endl;
    std::cout << "     " << torqueComp << " is the composition of " << torque <<  " and " << torqueInv << std::endl;
    std::cout << "     " << forceComp << " is the composition of " << force <<  " and " << forceInv << std::endl;
    std::cout << "     " << wrench1Comp << " is the composition of " << wrench1 <<  " and " << wrench2Inv << std::endl;
    std::cout << "     " << wrench2Comp << " is the composition of " << wrench1 <<  " and " << wrench2Inv << std::endl;

FAQ

Use cases

Semantics Reasoning

Coordinate Semantics Reasoning

Coordinate Calculations

Coordinate Semantics Reasoning and Coordinate Calculations

Installation Manual

This document is not ready yet, but it's a wiki page so feel free to contribute

Requirements

• Eigen2
• Sip 4.7.9 and python for the python bindings
• Cmake 2.6

Supported Platforms

• Linux
• Windows
• Mac

Installation

There are different ways for getting the software.

From debian/ubuntu packages

Orocos KDL is part of the geometry stack in the ROS distributions pre-Electric.

• ros-cturtle/diamondback-geometry

Since ROS Electric it is available stand-alone as the orocos-kinematics-dynamics stack.

• ros-electric/fuerte-orocos-kinematics-dynamics

Source using git

git clone https://github.com/orocos/orocos_kinematics_dynamics.git

Building source with ROS

• Follow the guidelines at Building ROS packages to build orocos_kdl with catkin_make_isolated

Building source with plain CMake

• goto your orocos_kdl directory
• create a build directory inside the orocos_kdl-dir and go inside:

mkdir <kdl-dir>/build ; cd <kdl-dir>/build

• Launch ccmake

ccmake ..

• configure [c], select the bindings you want to create, choose an appropriate installation directory
• configure[c], generate makefiles [g]
• make, wait, install and check

make;make check;make install

KDL typekit

The use of KDL types in the TaskBrowser

Compiling

 http://github.com/orocos-toolchain/rtt_geometry

Importing

Import the kdl_typekit in Orocos by using the 'import' Deployment command in the TaskBrowser or the 'Import' Deployment property in your deployment xml file:

 import("kdl_typekit")

Creation of variables of a KDL type

• Make sure you've loaded the KDL typekit, by checking all available types in the TaskBrowser:

.types

• In the list you should find eg. KDL.Frame, so you can create a variable z of this type by: var KDL.Frame z
• z has a standard value now (Identity frame), there are multiple ways to change it:
  • value by value:

z.p.X=1 or z.M.X_x=2

• • the full position vector

z.p = KDL.Vector(1,2,3)

• • the full rotation matrix

z.M=KDL.Rotation(0,1.57,0) (roll, pitch, yaw angles???)

• You can check the current value by just typing it's variable name, for this example, z.

z

• Look in the KDL typekit for more details

User Manual

Why to use KDL?

• Extensive support for :
  • Geometric primitives: point, frame, twist ...
  • Kinematic Trees: chain and tree structures. In literature, multiple definitions exist for a kinematic structure: a chain as the equivalent for all types of kinematic structures (chain, tree, graph) or chain as the serial version of a kinematic structure. KDL uses the last, or using graph-theory terminology:
    • A closed-loop mechanism is a graph,
    • an open-loop mechanism is a tree, and
    • an unbranched tree is a chain.

Next to kinematics, also parameters for dynamics are included (inertia...)

• • Kinematic and Dynamic Solvers: various generic forward and inverse kinematic algorithms, redundancy resolution, ...
  • Instantaneous Motions: under construction (Expected release, Spring 2011)
  • Motion Trajectories: Cartesian paths, velocity profiles, Cartesian trajectories

• Realtime-safe operations/functions whenever relevant: they do not lead to dynamic memory allocations and all of them are deterministic in time.

• Python bindings

• Typekits and transport-kits for Orocos/RTT

• Integrated in ROS

Getting Help

• Mailinglists
• The API documentation
• The Installation Manual

  Vector v1; //The default constructor, X-Y-Z are initialized to zero
  Vector v2(x,y,z); //X-Y-Z are initialized with the given values 
  Vector v3(v2); //The copy constructor
  Vector v4 = Vector::Zero(); //All values are set to zero

  v1[0]=v2[1];//copy y value of v2 to x value of v1 
  v2(1)=v3(3);//copy z value of v3 to y value of v2
  v3.x( v4.y() );//copy y value of v4 to x value of v3

  v2=2*v1;
  v3=v1/2;

  v2+=v1;
  v3-=v1;
  v4=v1+v2;
  v5=v2-v3;

  v3=v1*v2; //Cross product
  double a=dot(v1,v2)//Scalar product

  SetToZero(v1);

  v1==v2;
  v2!=v3;
  Equal(v3,v4,eps);//with accuracy eps

  Rotation r1; //The default constructor, initializes to an 3x3 identity matrix
  Rotation r1 = Rotation::Identity();//Identity Rotation = zero rotation
  Rotation r2 = Rotation::RPY(roll,pitch,yaw); //Rotation built from Roll-Pitch-Yaw angles
  Rotation r3 = Rotation::EulerZYZ(alpha,beta,gamma); //Rotation built from Euler Z-Y-Z angles
  Rotation r4 = Rotation::EulerZYX(alpha,beta,gamma); //Rotation built from Euler Z-Y-X angles
  Rotation r5 = Rotation::Rot(vector,angle); //Rotation built from an equivalent axis(vector) and an angle.

  Rotation r6( Xx,Yx,Zx,Xy,Yy,Zy,Xz,Yz,Zz);//Give each individual element (Column-Major)
  Rotation r7(vectorX,vectorY,vectorZ);//Give each individual column

  double Zx = r1(0,2);

  r1.GetEulerZYZ(alpha,beta,gamma);
  r1.GetEulerZYX(alpha,beta,gamma);
  r1.GetRPY(roll,pitch,yaw);
  axis = r1.GetRot();//gives only rotation axis
  angle = r1.GetRotAngle(axis);//gives both angle and rotation axis

  vecX=r1.UnitX();//or
  r1.UnitX(vecX);
  vecY=r1.UnitY();//or
  r1.UnitY(vecY);
  vecZ=r1.UnitZ();//or
  r1.UnitZ(vecZ);

  r1.SetInverse();//r1 is inverted and overwritten

  r2=r1.Inverse();//r2 is the inverse rotation of r1

  r3=r1*r2;
 

  r1.DoRotX(angle);
  r2.DoRotY(angle);
  r3.DoRotZ(angle);

  r1 = r1*Rotation::RotX(angle)

  v2=r1*v1;

  r1==r2;
  r1!=r2;
  Equal(r1,r2,eps);

  Frame f1;//Creates Identity frame
  Frame f1=Frame::Identity();//Creates an identity frame: Rotation::Identity() and Vector::Zero()
  Frame f2(your_rotation);//Create a frame with your_rotation and a zero vector
  Frame f3(your_vector);//Create a frame with your_vector and a identity rotation
  Frame f4(your_rotation,your_vector);//Create a frame with your_rotation
  Frame f5(your_vector,your_rotation);//and your_vector
  Frame f5(f6);//the copy constructor

  double x = f1(0,3);
  double Yy = f1(1,1);

   Vector p = f1.p;
   Rotation M = f1.M;

  Frame F_A_C = F_A_B * F_B_C;

  //not yet implemented

  f2=f1.Inverse();//f2 is the inverse of f1

  f1==f2;
  f1!=f2;
  Equal(f1,f2,eps);

  Twist t1; //Default constructor, initializes both vel and rot to Zero
  Twist t2(vel,rot);//Vector vel, and Vector rot
  Twist t3 = Twist::Zero();//Zero twist

  double vx = t1(0);
  double omega_y = t1[4];
  t1(1) = vy;
  t1[5] = omega_z;

  double vx = t1.vel.x();//or
  vx = t1.vel(0);
  double omega_y = t1.rot.y();//or
  omega_y = t1.rot(1);
  t1.vel.y(v_y);//or
  t1.vel(1)=v_y;
  //etc

  t2=2*t1;
  t2=t1*2;
  t2=t1/2;

  t1+=t2;
  t1-=t2;
  t3=t1+t2;
  t3=t1-t2;

  t1==t2;
  t1!=t2;
  Equal(t1,t2,eps);

  Wrench w1; //Default constructor, initializes force and torque to Zero
  Wrench w2(force,torque);//Vector force, and Vector torque
  Wrench w3 = Wrench::Zero();//Zero wrench

  double fx = w1(0);
  double ty = w1[4];
  w1(1) = fy;
  w1[5] = tz;

  double fx = w1.force.x();//or
  fx = w1.force(0);
  double ty = w1.torque.y();//or
  ty = w1.torque(1);
  w1.force.y(fy);//or
  w1.force(1)=fy;//etc

  w2=2*w1;
  w2=w1*2;
  w2=w1/2;

  w1+=w2;
  w1-=w2;
  w3=w1+w2;
  w3=w1-w2;

  w1==w2;
  w1!=w2;
  Equal(w1,w2,eps);

t2 = t1.RefPoint(v_old_new);
w2 = w1.RefPoint(v_old_new);

ta = R_AB*tb;
wa = R_AB*wb;

ta = F_AB*tb;
wa = F_AB*wb;

t = diff(F_w_A,F_w_B,timestep)//differentiation
F_w_B = F_w_A.addDelta(t,timestep)//integration

Joint rx = Joint(Joint::RotX);//Rotational Joint about X
Joint ry = Joint(Joint::RotY);//Rotational Joint about Y
Joint rz = Joint(Joint::RotZ);//Rotational Joint about Z
Joint tx = Joint(Joint::TransX);//Translational Joint along X
Joint ty = Joint(Joint::TransY);//Translational Joint along Y
Joint tz = Joint(Joint::TransZ);//Translational Joint along Z
Joint fixed = Joint(Joint::None);//Rigid Connection

Joint rx = Joint(Joint::RotX);
double q = M_PI/4;//Joint position
Frame f = rx.pose(q);
double qdot = 0.1;//Joint velocity
Twist t = rx.twist(qdot);

Segment s = Segment(Joint(Joint::RotX),
                Frame(Rotation::RPY(0.0,M_PI/4,0.0),
                          Vector(0.1,0.2,0.3) )
                    );

double q=M_PI/2;//joint position
Frame f = s.pose(q);//s constructed as in previous example
double qdot=0.1;//joint velocity
Twist t = s.twist(q,qdot);

Chain chain1;
Chain chain2(chain3);
Chain chain4 = chain5;

chain1.addSegment(segment1);
chain1.addChain(chain2);

unsigned int nj = chain1.getNrOfJoints();
unsigned int js = chain1.getNrOfSegments();

Segment& segment3 = chain1.getSegment(3);

Tree tree1;
Tree tree2("RootName");
Tree tree3(tree4);
Tree tree5 = tree6;

bool exit_value;
exit_value = tree1.addSegment(segment1,"root");
exit_value = tree1.addChain(chain1,"Segment 1");
exit_value = tree1.addTree(tree2,"root");

unsigned int nj = tree1.getNrOfJoints();
unsigned int js = tree1.getNrOfSegments();

std::map<std::string,TreeElement>::const_iterator root = tree1.getRootSegment();

std::map<std::string,TreeElement>::const_iterator segment3 = tree1.getSegment("Segment 3");

std::map<std::string,TreeElement>& segments = tree1.getSegments();

bool exit_value;
Chain chain;
exit_value = tree1.getChain("Segment 1","Segment 3",chain);
//Segment 1 and segment 3 are included but segment 1 is renamed.
Chain chain2;
exit_value = tree1.getChain("Segment 3","Segment 1",chain2);
//Segment 1 and segment 3 are included but segment 3 is renamed.

Joint rx = Joint(Joint::RotX);//Rotational Joint about X
Joint ry = Joint(Joint::RotY);//Rotational Joint about Y
Joint rz = Joint(Joint::RotZ);//Rotational Joint about Z
Joint tx = Joint(Joint::TransX);//Translational Joint along X
Joint ty = Joint(Joint::TransY);//Translational Joint along Y
Joint tz = Joint(Joint::TransZ);//Translational Joint along Z
Joint fixed = Joint(Joint::None);//Rigid Connection

Joint rx = Joint(Joint::RotX);
double q = M_PI/4;//Joint position
Frame f = rx.pose(q);
double qdot = 0.1;//Joint velocity
Twist t = rx.twist(qdot);

Segment s = Segment(Joint(Joint::RotX),
                Frame(Rotation::RPY(0.0,M_PI/4,0.0),
                          Vector(0.1,0.2,0.3) )
                    );

double q=M_PI/2;//joint position
Frame f = s.pose(q);//s constructed as in previous example
double qdot=0.1;//joint velocity
Twist t = s.twist(q,qdot);

Chain chain1;
Chain chain2(chain3);
Chain chain4 = chain5;

bool exit_value;
bool exit_value = chain1.addSegment(segment1);
exit_value = chain1.addChain(chain2);

unsigned int nj = chain1.getNrOfJoints();
unsigned int js = chain1.getNrOfSegments();

Segment segment3;
bool exit_value = chain1.getSegment(3, segment3);

Segment segment3;
bool exit_value = chain1.getSegment("Segment 3", segment3);

bool exit_value;
Segment root_segment;
Segment leaf_segment;
std::vector<Segment> segments;
exit_value = chain1.getRootSegment(root_segment);
exit_value = chain1.getLeafSegment(leaf_segment);
exit_value = chain1.getSegments(segments);

bool exit_value;
Chain part_chain;
 
exit_value = chain1.getChain_Including(1,3, part_chain);
exit_value = chain1.getChain_Including("Segment 1","Segment 3", part_chain);
//Segment 1 and Segment 3 are included in the new chain!
 
exit_value = chain1.getChain_Excluding(1,3, part_chain);
exit_value = chain1.getChain_Excluding("Segment 1","Segment 3", part_chain);
//Segment 1 is not included in the chain. Segment 3 is included in the chain.

bool exit_value;
Chain chain_copy;
exit_value = chain1.copy(3, chain_copy);
exit_value = chain1.copy("Segment 3", chain_copy);
//Segment 3, 4,... are not included in the copy!

Tree tree1;
Tree tree2("RootName");
Tree tree3(tree4);
Tree tree5 = tree6;

bool exit_value;
exit_value = tree1.addSegment(segment1,"root");
exit_value = tree1.addChain(chain1,"Segment 1");
exit_value = tree1.addTree(tree2,"root");

unsigned int nj = tree1.getNrOfJoints();
unsigned int js = tree1.getNrOfSegments();

bool exit_value;
std::map<std::string,TreeElement>::const_iterator root;
std::map<std::string,TreeElement> leafs;
exit_value = tree1.getRootSegment(root);
exit_value = tree1.getLeafSegments(leafs);

std::map<std::string,TreeElement>::const_iterator segment3;
bool exit_value = tree1.getSegment("Segment 3",segment3);

std::map<std::string,TreeElement> segments;
bool exit_value = tree1.getSegments(segments);

bool exit_value;
Chain chain;
exit_value = tree1.getChain("Segment 1","Segment 3",chain);
//Segment 1 and segment 3 are included but segment 1 is renamed.
Chain chain2;
exit_value = tree1.getChain("Segment 3","Segment 1",chain2);
//Segment 1 and segment 3 are included but segment 3 is renamed.

bool exit_value;
Tree tree;
exit_value = tree1.getChain("Segment 1","Segment 3",tree,"RootName");
Tree tree2;
exit_value = tree1.getChain("Segment 3","Segment 1",tree2,"RootName");

bool exit_value;
Tree tree_copy;
exit_value = tree1.copy("Segment 3", tree_copy);
//tree1 is copied up to segment 3 (excluding segment 3).
std::vector<std::string> vect;
vect.push_back("Segment 1");
vect.push_back("Segment 7");
exit_value = tree1.copy(vect,tree_copy);

ChainFkSolverPos_recursive fksolver(chain1);
JntArray q(chain1.getNrOfJoints);
q=...
Frame F_result;
fksolver.JntToCart(q,F_result,segment_nr);

Taskbrowser with readline on Windows

In order to have readline tab-completion in the taskbrowser, you'll need OCL 1.12.0 or 2.1.0 or later.

Download Readline

homepage:

• http://gpsim.sourceforge.net/gpsimWin32/gpsimWin32.html

download:

• http://gpsim.sourceforge.net/gpsimWin32/packages/readline-5.2-20061112-lib.zip

It is advised to keep copies/backups of these files on your own site, since they are not official readline releases, but patched to work on Windows.

Build Readline (OPTIONAL)

• http://gpsim.sourceforge.net/gpsimWin32/packages/readline-5.2-20061112-src.zip

and then open the solution in the directory:

• src/readline/5.2/readline-5.2/msvc/readline.sln

The build will place a static readline.lib in the ../lib directory.

Configuring OCL

 set(CMAKE_INCLUDE_PATH ${CMAKE_INCLUDE_PATH} "C:/Documents and Settings/virtual/My documents/readline5.2/include")
 set(CMAKE_LIBRARY_PATH ${CMAKE_LIBRARY_PATH} "C:/Documents and Settings/virtual/My documents/readline5.2/lib")

Continue to configure OCL in the cmake GUI by turning off the NO_GPL flag (by default on on Windows). It will then try to link the taskbrowser with the readline.lib file, which should succeed. After installing ocl, readline should work as on Linux, but only on the standard cygwin or cmd.exe prompts, not on rxvt

quotes from "Really Reusable Robot Code and the Player/Stage Project"

Further some significants parts of the paper "Really Reusable Robot Code and the Player/Stage Project" have been copied. The purpose it to present a possible philosophy to drive the development of OCL 2.0 (it is recommended to read the entire paper). Feel free to discuss these concepts in the forum.

Documentation suggestions

From recent discussion on ML, simply a place to put down ideas before we forget them ...

• Use Wiki for FAQ instead of XML doc

FAQ

• My shared libraries won't load
• The deployer won't load my plugins
• Can I use dynamic memory allocation, and where?
• How do I run in real time? ie how do I configure my system to allow

Orocos to run in real-time

• Why do I have periodic delays when attaching a remote deployer?
• Configuring OmniORB instead of TAO
• OmniORB options for IDL
• How do I set a client application using pyOmniOrb (OmniORB python bindings)?

<quote> Actually it's an option of the omniidl compiler... the command to use is

omniidl -bcxx -Wba myIdlFile.idl

This will become definately a FAQ item :-) <quote>

• My wiki page is blank

<quote> When your text is not appearing on your wiki page, it's because you ended your wiki page with an indented line. So if your last line is:

this is my last line

the wiki code clears the whole page. It's clearly a Drupal/wiki module thing/bug. <quote>

• Is it possible to log messages from scripts and state machines?

Check out OCL's HmiConsoleOutput component.

• What is the coding style used by Orocos?

You can take a look at the CODING_STYLE.txt file. Also, we worked out the indentation rules for Eclipse and Emacs.

• Error linking readline with OCL's taskbrowser

Tutorials

• Seems like I have to first read up on Activities. Can you point me to a good example for such a component test and mockobject in rtt/tests?
• Hello world as an application
• Hello world with the deployer
• Use of reporting component
• CMake and non-standard install location for Orocos
• Distributed deployment - ie how to use more than one deployer, and setting up CORBA
• Adding types to Orocos
• Adding types to Orocos+Corba
• Changing ReadDataPort/WriteDataPort to DataPort for CORBA-based deployment

System examples

• Robotics

Examples like Stephen proposed earlier

Focus on : Kinematics, path planning, HMI/interfacing

• Machine control

Similar to Robotics with without kinematics or path planning

Master controller that controls slave devices through a state machine

Focus on : state machines & events

• Distributed

Sensor data processing using various distributed components

Focus on : Data flow

end

Examples and Tutorials

The tutorials and example code are split in two parts, one for new users and one for experienced users of the RTT.

There are several sources where you can find code and tutorials. Click below to read the rest of this post.The tutorials and example code are split in two parts, one for new users and one for experienced users of the RTT.

There are several sources where you can find code and tutorials. Some code is listed in wiki pages, other is downloadable in a separate package and finally you can find code snippets in the manuals too.

Simple examples

RTT Examples Get started with simple, ready-to-compile examples of how to create a component

Naming connections, not ports: Orocos' best kept secret

Using omniORBpy to interact with a component from Python

Advanced examples

These advanced examples are mainly about extending and configuring the RTT for your specific needs.

Using plugins and toolkits to support custom data types

Using non-periodic components to implement a simple TCP client

Using XML substitution to manage complex deployments

Using real-time logging

.
|-- BoostToolkit.cpp
|-- BoostToolkit.hpp
|-- CMakeLists.txt
|-- config
|   |-- FindACE.cmake
|   |-- FindCorba.cmake
|   |-- FindOmniORB.cmake
|   |-- FindOrocos-OCL.cmake
|   |-- FindOrocos-RTT.cmake
|   |-- FindTAO.cmake
|   |-- UseCorba.cmake
|   `-- UseOrocos.cmake
|-- corba
|   |-- BoostCorbaConversion.hpp
|   |-- BoostCorbaToolkit.cpp
|   |-- BoostCorbaToolkit.hpp
|   |-- BoostTypes.idl
|   |-- CMakeLists.txt
|   `-- tests
|       |-- CMakeLists.txt
|       |-- corba-combined.cpp
|       |-- corba-recv.cpp
|       `-- corba-send.cpp
`-- tests
    |-- CMakeLists.txt
    |-- combined.cpp
    |-- no-toolkit.cpp
    |-- recv.cpp
    |-- recv.hpp
    |-- send.cpp
    `-- send.hpp

cd /path/to/plugins
mkdir build
cd build
cmake .. -DOROCOS_TARGET=macosx -DENABLE_CORBA=OFF
make

cd /path/to/plugins/build
./no-toolkit

 Data Flow Ports: 
 RW(C)   unknown_t ptime          = (unknown_t)
 RW(C)   unknown_t timeDuration   = (unknown_t)

cd /path/to/plugins/build
./combined

RW(C) boost_ptime ptime          = 2009-Aug-09 16:14:19.724622
RW(C) boost_timeduration timeDuration   = 00:00:00.200005

namespace Examples
{
    /// \remark these do not need to be in the same namespace as the plugin
 
    /// put the time onto the stream
    std::ostream& operator<<(std::ostream& os, const boost::posix_time::ptime& t);
    /// put the time onto duration the stream
    std::ostream& operator<<(std::ostream& os, const boost::posix_time::time_duration& d);
    /// get a time from the stream
    std::istream& operator>>(std::istream& is, boost::posix_time::ptime& t);
    /// get a time duration from the stream
    std::istream& operator>>(std::istream& is, boost::posix_time::time_duration& d);

    class BoostPlugin : public RTT::ToolkitPlugin
    {
    public:
        virtual std::string getName();
 
        virtual bool loadTypes();
        virtual bool loadConstructors();
        virtual bool loadOperators();
    };
 
    /// The singleton for the Toolkit.
    extern BoostPlugin BoostToolkit;

    /// provide ptime type to RTT type system
    /// \remark the 'true' argument indicates that we supply stream operators
    struct BoostPtimeTypeInfo : 
        public RTT::TemplateTypeInfo<boost::posix_time::ptime,true> 
    {
        BoostPtimeTypeInfo(std::string name) :
                RTT::TemplateTypeInfo<boost::posix_time::ptime,true>(name)
        {};
        bool decomposeTypeImpl(const boost::posix_time::ptime& img, RTT::PropertyBag& targetbag);
        bool composeTypeImpl(const RTT::PropertyBag& bag, boost::posix_time::ptime& img);
    };
 
    /// provide time duration type to RTT type system
    /// \remark the 'true' argument indicates that we supply stream operators
    struct BoostTimeDurationTypeInfo : 
        public RTT::TemplateTypeInfo<boost::posix_time::time_duration,true> 
    {
        BoostTimeDurationTypeInfo(std::string name) :
                RTT::TemplateTypeInfo<boost::posix_time::time_duration,true>(name)
        {};
        bool decomposeTypeImpl(const boost::posix_time::time_duration& img, RTT::PropertyBag& targetbag);
        bool composeTypeImpl(const RTT::PropertyBag& bag, boost::posix_time::time_duration& img);
    };
 
} // namespace Exampels

namespace Examples
{
    using namespace RTT;
    using namespace RTT::detail;
    using namespace std;
 
    std::ostream& operator<<(std::ostream& os, const boost::posix_time::ptime& t)
    {
        os << boost::posix_time::to_simple_string(t);
        return os;
    }
 
    std::ostream& operator<<(std::ostream& os, const boost::posix_time::time_duration& d)
    {
        os << boost::posix_time::to_simple_string(d);
        return os;
    }
 
    std::istream& operator>>(std::istream& is, boost::posix_time::ptime& t)
    {
        is >> t;
        return is;
    }
 
    std::istream& operator>>(std::istream& is, boost::posix_time::time_duration& d)
    {
        is >> d;
        return is;
    }

    BoostPlugin BoostToolkit;
 
    std::string BoostPlugin::getName()
    {
        return "Boost";
    }

    bool BoostPlugin::loadTypes()
    {
        TypeInfoRepository::shared_ptr ti = TypeInfoRepository::Instance();
 
        /* each quoted name here (eg "boost_ptime") must _EXACTLY_ match that
           in the associated TypeInfo::composeTypeImpl() and
           TypeInfo::decomposeTypeImpl() functions (in this file), as well as
           the name registered in the associated Corba plugin's 
           registerTransport() function (see corba/BoostCorbaToolkit.cpp)
        */
        ti->addType( new BoostPtimeTypeInfo("boost_ptime") );
        ti->addType( new BoostTimeDurationTypeInfo("boost_timeduration") );
 
        return true;
    }

    bool BoostPlugin::loadConstructors()
    {
        // no constructors for these particular types
 
        return true;
    }
 
    bool BoostPlugin::loadOperators()
    {
        // no operators for these particular types
 
        return true;
    }

    bool BoostPtimeTypeInfo::decomposeTypeImpl(const boost::posix_time::ptime& source, 
                                             PropertyBag& targetbag)
    {
        targetbag.setType("boost_ptime");
        assert(0);
        return true;
    }
 
    bool BoostPtimeTypeInfo::composeTypeImpl(const PropertyBag& bag, 
                                              boost::posix_time::ptime& result)
    {
        if ( "boost_ptime" == bag.getType() ) // ensure is correct type
        {
            // \todo
            assert(0);
        }
        return false;
    }

ORO_TOOLKIT_PLUGIN(Examples::BoostToolkit)

cmake_minimum_required(VERSION 2.6)
 
# pick up additional cmake package files (eg FindXXX.cmake) from this directory
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/config")

find_package(Orocos-RTT 1.6.0 REQUIRED corba)
find_package(Orocos-OCL 1.6.0 REQUIRED taskbrowser)

include(${CMAKE_SOURCE_DIR}/config/UseOrocos.cmake)

create_component(BoostToolkit-${OROCOS_TARGET} 
  VERSION 1.0.0 
  BoostToolkit.cpp)
 
TARGET_LINK_LIBRARIES(BoostToolkit-${OROCOS_TARGET} 
  boost_date_time)

SUBDIRS(tests)

class Send : public RTT::TaskContext
{
public:
    RTT::DataPort<boost::posix_time::ptime>                ptime_port;
    RTT::DataPort<boost::posix_time::time_duration>    timeDuration_port;
public:
    Send(std::string name);
    virtual ~Send();
 
    virtual bool startHook();
    virtual void updateHook();
protected:
    boost::posix_time::ptime    lastNow;
};

#include "send.hpp"
 
Send::Send(std::string name) :
        RTT::TaskContext(name),
        ptime_port("ptime"),
        timeDuration_port("timeDuration")
{
    ports()->addPort(&ptime_port);
    ports()->addPort(&timeDuration_port);
}
 
Send::~Send()
{
}
 
bool Send::startHook()
{
    // just set last to now
    lastNow            = boost::posix_time::microsec_clock::local_time();
    return true;
}
 
void Send::updateHook()
{
    boost::posix_time::ptime            now;
    boost::posix_time::time_duration    delta;
 
    // send the current time, and the duration since the last updateHook()
    now        = boost::posix_time::microsec_clock::local_time();
    delta   = now - lastNow;
 
    ptime_port.Set(now);
    timeDuration_port.Set(delta);
 
    lastNow = now;
}

class Recv : public RTT::TaskContext
{
public:
    RTT::DataPort<boost::posix_time::ptime>                ptime_port;
    RTT::DataPort<boost::posix_time::time_duration>        timeDuration_port;
 
public:
    Recv(std::string name);
    virtual ~Recv();
};

#include "recv.hpp"
 
Recv::Recv(std::string name) :
        RTT::TaskContext(name),
        ptime_port("ptime"),
        timeDuration_port("timeDuration")
{
    ports()->addPort(&ptime_port);
    ports()->addPort(&timeDuration_port);
}
 
Recv::~Recv()
{
}

#include <rtt/RTT.hpp>
#include <rtt/PeriodicActivity.hpp>
#include <rtt/TaskContext.hpp>
#include <rtt/os/main.h>
#include <rtt/Ports.hpp>
#include <ocl/TaskBrowser.hpp>
 
#include "send.hpp"
#include "recv.hpp"
#include "../BoostToolkit.hpp"
 
using namespace std;
using namespace Orocos;
 
int ORO_main(int argc, char* argv[])
{
    RTT::Toolkit::Import(Examples::BoostToolkit);

 
    Recv                recv("Recv");
    PeriodicActivity    recv_activity(ORO_SCHED_OTHER, 0, 0.1, recv.engine());
    Send                 send("Send");
    PeriodicActivity    send_activity(ORO_SCHED_OTHER, 0, 0.2, send.engine());
 
    if ( connectPeers( &send, &recv ) == false )
    {
        log(Error) << "Could not connect peers !"<<endlog();
        return -1;
    }
    if ( connectPorts( &send, &recv) == false )
    {
        log(Error) << "Could not connect ports !"<<endlog();
        return -1;
    }

    send.configure();
    recv.configure();
    send_activity.start();
    recv_activity.start();
 
    TaskBrowser browser( &recv );
    browser.setColorTheme( TaskBrowser::whitebg );
    browser.loop();

    send_activity.stop();
    recv_activity.stop();
 
    return 0;
}

cd /path/to/plugins
mkdir build
cd build
cmake .. -DOROCOS_TARGET=macosx -DENABLE_CORBA=ON
make

cd /path/to/plugins/build/corba/tests
./corba-recv

cd /path/to/plugins/build/corba/tests
./corba-send

cd /path/to/plugins/build/corba/tests
./corba-recv-no-toolkit

 Data Flow Ports: 
 RW(U) boost_ptime ptime          = not-a-date-time
 RW(U) boost_timeduration timeDuration   = 00:00:00

cd /path/to/plugins/build/corba/tests
./corba-send-no-toolkit

$ ./build/corba/tests/corba-send-no-toolkit 
0.008 [ Warning][./build/corba/tests/corba-send-no-toolkit::main()] Forcing priority (0) of thread to 0.
0.008 [ Warning][PeriodicThread] Forcing priority (0) of thread to 0.
0.027 [ Warning][SingleThread] Forcing priority (0) of thread to 0.
5.078 [ Warning][./build/corba/tests/corba-send-no-toolkit::main()] ControlTask 'Send' already bound \
to CORBA Naming Service.
5.078 [ Warning][./build/corba/tests/corba-send-no-toolkit::main()] Trying to rebind... done. New \
ControlTask bound to Naming Service.
5.130 [ Warning][./build/corba/tests/corba-send-no-toolkit::main()] Can not create a proxy for data \
connection.
5.130 [ ERROR  ][./build/corba/tests/corba-send-no-toolkit::main()] Dynamic cast failed \
for 'PN3RTT14DataSourceBaseE', 'unknown_t', 'unknown_t'. Do your typenames not match?
Assertion failed: (doi && "Dynamic cast failed! See log file for details."), function createConnection, \
file /opt/install/include/rtt/DataPort.hpp, line 462.
Abort trap

*** corba/tests/corba-recv.cpp    2009-07-29 22:08:32.000000000 -0400
--- corba/tests/corba-recv-no-toolkit.cpp    2009-08-09 16:32:03.000000000 -0400
***************
*** 11,17 ****
  #include <rtt/os/main.h>
  #include <rtt/Ports.hpp>
 
- #include "../BoostCorbaToolkit.hpp"
  #include "../../BoostToolkit.hpp"
 
  // use Boost RTT Toolkit test components
--- 11,16 ----
***************
*** 27,33 ****
  int ORO_main(int argc, char* argv[])
  {
      RTT::Toolkit::Import( Examples::BoostToolkit  );
-     RTT::Toolkit::Import( Examples::Corba::corbaBoostPlugin  );
 
      Recv                recv("Recv");
      PeriodicActivity    recv_activity(
--- 26,31 ----

// must be in RTT namespace to match some rtt/corba code
module RTT {
module Corba {

    struct time_duration
    {
        short    hours;
        short    minutes;
        short    seconds;
        long    nanoseconds;
    };

    // can't get at underlying type, so send this way (yes, more overhead)
    // see BoostCorbaConversion.hpp::struct AnyConversion<boost::posix_time::ptime>
    // for further details.
    struct ptime
    {
        // julian day
        long            date;    
        time_duration    time_of_day;
    };
};
};

namespace Examples {
namespace Corba {
 
    class CorbaBoostPlugin : public RTT::TransportPlugin
    {
    public:
        /// register this transport into the RTT type system
        bool registerTransport(std::string name, RTT::TypeInfo* ti);
 
        /// return the name of this transport type (ie "CORBA")
        std::string getTransportName() const;
 
        /// return the name of this transport
        std::string getName() const;
    };
 
    // the global instance
    extern CorbaBoostPlugin     corbaBoostPlugin;
 
// namespace
}
}

namespace Examples {
namespace Corba {
 
bool CorbaBoostPlugin::registerTransport(std::string name, TypeInfo* ti)
{
    assert( name == ti->getTypeName() );
    // name must match that in plugin::loadTypes() and 
    // typeInfo::composeTypeInfo(), etc
    if ( name == "boost_ptime" )
        return ti->addProtocol(ORO_CORBA_PROTOCOL_ID, new CorbaTemplateProtocol< boost::posix_time::ptime >() );
    if ( name == "boost_timeduration" )
        return ti->addProtocol(ORO_CORBA_PROTOCOL_ID, new CorbaTemplateProtocol< boost::posix_time::time_duration >() );
    return false;
}

std::string CorbaBoostPlugin::getTransportName() const {
    return "CORBA";
}
 
std::string CorbaBoostPlugin::getName() const {
    return "CorbaBoost";
}

CorbaBoostPlugin corbaBoostPlugin;
 
// namespace
}
}
 
ORO_TOOLKIT_PLUGIN(Examples::Corba::corbaBoostPlugin);

#include "BoostTypesC.h"
#include <rtt/corba/CorbaConversion.hpp>
#include <boost/date_time/posix_time/posix_time_types.hpp>  // no I/O

// must be in RTT namespace to match some rtt/corba code
namespace RTT
{

template<>
struct AnyConversion< boost::posix_time::time_duration >
{
    // define the Corba and standard (ie non-Corba) types we are using
    typedef Corba::time_duration                CorbaType;
    typedef boost::posix_time::time_duration    StdType;

    // convert CorbaType to StdTypes
    static void convert(const CorbaType& orig, StdType& ret) 
    {
        ret = boost::posix_time::time_duration(orig.hours,
                                               orig.minutes,
                                               orig.seconds,
                                               orig.nanoseconds);
    }
 
    // convert StdType to CorbaTypes
    static void convert(const StdType& orig, CorbaType& ret) 
    {
        ret.hours       = orig.hours();
        ret.minutes     = orig.minutes();
        ret.seconds     = orig.seconds();
        ret.nanoseconds = orig.fractional_seconds();
    }

    static CorbaType* toAny(const StdType& orig) {
        CorbaType* ret = new CorbaType();
        convert(orig, *ret);
        return ret;
    }
 
    static StdType get(const CorbaType* orig) {
        StdType ret;
        convert(*orig, ret);
        return ret;
    }
 
    static bool update(const CORBA::Any& any, StdType& ret) {
        CorbaType* orig;
        if ( any >>= orig ) 
        {
            convert(*orig, ret);
            return true;
        }
        return false;
    }
 
    static CORBA::Any_ptr createAny( const StdType& t ) {
        CORBA::Any_ptr ret = new CORBA::Any();
        *ret <<= toAny( t );
        return ret;
    }
};