iTaSC quick start

Overview

The framework is ordered following a OROCOS-ROS approach and consists of 1 meta-stack:
  • itasc: This ROS unary stack serving as a meta-stack, it's purpose is to keep the framework stacks together

This meta-stack consists of following stacks:

  • itasc_core: This ROS unary stack contains the core functionality of iTaSC: the scene and template (headers) for all itasc component types (solvers, virtual kinematic chains, controller/constraints, robots, objects)
  • itasc_solvers: Contains a number of solver packages for iTaSC
  • itasc_robots_objects: Contains a number of robot and object packages for iTaSC
  • itasc_tasks: Contains a number of task packages for iTaSC (combination of virtual kinematic chains and constraint/controllers)

Each package contains the following subdirectories:

  • src/ containing the source code of the components (C++)
  • cpf/ containing the property files for the components and FSM's
  • scripts/ containing the FSM's and components in a LUA implementation (eg. Supervisors)
  • launch/ containing eventual ROS launch files

Code

The installation instructions further on will cover the installation of the source code and dependencies.

Dependencies

Source code

Source code of iTaSC can be found on following git repositories:
  • https://gitlab.mech.kuleuven.be/groups/rob-itasc

and for the iTaSC DSL

  • https://bitbucket.org/dvanthienen/itasc_dsl.git

Installation instructions for ROS Fuerte or Groovy

The following explanation uses the ROS workspace and rosinstall tools, it is however easy to follow the same instructions without these tools, as will be hinted further on.

Pre-requisites

  • Install following stacks:
    • sudo apt-get install libeigen3-dev ros-groovy-rtt-ros-integration ros-groovy-rtt-geometry ros-groovy-rtt-common-msgs ros-groovy-rtt-ros-comm
  • rosws (ROS workspace, optional but highly recommended):
    • Create a new ros workspace or use an existing one
    • Add the following to your .bashrc file:

source /opt/ros/groovy/setup.bash source ~/path_to_workspace/setup.bash

Installation file

  • Download the ROS installation file here
  • Merge this file into your workspace:
    • rosws merge itasc_dsl.rosinstall
    • rosws update
  • OR manually clone each repository mentioned in the file, switch to the correct branch/tag, and add to your ROS_PACKAGE_PATH

Application dependent install files

  • When using the KUKA youBot:
    • Download the ROS installation file here
    • rosws merge itasc_youbot_fuerte.rosinstall
    • rosws update

Setup

  • Download this file, move and rename it to ~/.bash_itasc_dsl
  • Add at the following at the end of your ~/.bashrc file, in following order:
    • source /path/to/your/rosworkspace/setup.bash
    • source .bash_itasc_dsl
    • useITaSC_deb
  • re-source your .bashrc
    • source ~/.bashrc
  • The Eigen typekit has moved from itasc_core to rtt_geometry in the newest version of Orocos: when using this version, disable the typekit that comes with itasc_core (unfortunately still manual work):
    • go to itasc_core/CMakeLists.txt
    • comment the line: orocos_typekit(eigen_toolkit src/eigen_toolkit.cpp)
    • delete the installation of the eigen_toolkit header: src/eigen_toolkit.hpp

For your convenience we put here some extra instructions for commonly used platforms:

When using a PR2 robot

This assumes you have PR2 related packages installed, see PR2 installation.
  • Go to your ros workspace
  • Create the rtt pr2 controller messages and add it to your ros workspace
    • rosrun rtt_rosnode create_rtt_msgs pr2_controllers_msgs
    • rosws set rtt_pr2_controllers_msgs
  • Convert the following XACRO scripts:
    • roscd itasc_pr2
    • ./convert_xacro.sh

When using a KUKA YouBot robot

This assumes you have KUKA YouBot related packages installed, see for example ERF 2012 laser tracing tutorial.
  • add the location of YouBot related lua files to your LUA_PATH:
    • uncomment the line mentioning 'youbot_driver_rtt' in ~/.bash_itasc_dsl

Build the packages

Build the core packages

  • rosmake itasc_core trajectory_generators itasc_tasks rFSM rttlua_completion itasc_solvers fixed_object  itasc_robot_object moving_object moving_object_tf

Build application dependent packages

  • Compile the dedicated itasc components for the PR2 or Youbot, located in the itasc_robots_objects stack
  • To compile for all supported platforms:
    • rosmake itasc

Test it

  • Easy application on a PR2: (TODO move to tutorials/dsl readme)
    • start a real or simulated PR2. For the simulated environment:
      • roslaunch pr2_gazebo pr2_empty_world.launch
    • Go to the itasc_dsl package and run the bunny pose example
    • roscd itasc_dsl
    • ./run_bunny.sh
    • This should move the arms in a grippers down 'bunny' pose
    • Play around the task browser or manually quit the application using CTRL+d
  • More info on the usage of the DSL on https://bitbucket.org/dvanthienen/itasc_dsl/overview
  • The itasc_dsl package contains more example models to try out
  • Interaction with a running iTaSC application happens through events, multiple options exist (see ERF 2012 laser tracing tutorial for an example):
    • sending events using a python Qt GUI: see python_gui
    • sending events on a ROS topic
    • sending events using the Orocos event_firer (automatically loaded when using the DSL parser)
  • Follow one of the tutorials (deprecated, needs update)
  • For known compatibility issues: see below

Installation instructions for ROS Indigo

The following explanation uses the ROS workspace and rosinstall tools, it is however easy to follow the same instructions without these tools, as will be hinted further on. IMPORTANT: We combine catkin packages and rosbuild packages by combining catkin and rosws workspaces!!

Pre-requisites

  • ROS Indigo
  • Orocos (installation instructions on http://wiki.ros.org/orocos_toolchain)
    • IMPORTANT: Different website than for Groovy instructions!! Preferably install in a catkin workspace named ~/orocos_ws
    • Afterwards add the following to your .bashr file:
      •  export PKG_CONFIG_PATH=~/orocos_ws/devel_isolated/eigen_typekit/lib/pkgconfig:$PKG_CONFIG_PATH
  • Install rtt_geometry: https://github.com/orocos/rtt_geometry
    • (clone it into a catkin_ws (for instance ~/catkin_ws), needs to be different from orocos_ws) and also perform a catkin_build_isolate similar to orocos installation instructions.
  • Make a new rosbuild workspace (for instance ~/rosbuild_ws) or use an existing workspace and add the catkin workspaces to your rosbuild environment through:

rosws set path/to/your/orocos/workspace/src 
rosws set path/to/your/catkin/workspace/src 
  • Install following stacks:
    • sudo apt-get install libeigen3-dev ros-indigo-rtt-ros-integration ros-indigo-rtt-geometry ros-indigo-rtt-common-msgs ros-indigo-rtt-ros-comm ros-indigo-rtt-kdl-conversions ros-indigo-rtt ros-indigo-eigen-conversions ros-indigo-eigen-typekit ros-indigo-kdl-parser ros-indigo-orocos-kdl ros-indigo-orocos-kinematics-dynamics ros-indigo-orocos-toolchain ros-indigo-tf-conversions

Installation file

  • Download the ROS installation file here
  • Merge this file into your workspace:

rosws merge itasc_dsl.rosinstall
rosws update
  • OR manually clone each repository mentioned in the file, switch to the correct branch/tag, and add to your ROS_PACKAGE_PATH

Application dependent install files

The KUKA youBot and PR2 have not yet been tested in Indigo.

Setup

  • Download this file, move and rename it to ~/.bash_itasc_dsl
  • Add at the following at the end of your ~/.bashrc file, in following order:

source /path/to/your/rosworkspace/setup.bash
source .bash_itasc_dsl
useITaSC_deb
  • re-source your .bashrc
    • source ~/.bashrc
  • The Eigen typekit has moved from itasc_core to rtt_geometry in the newest version of Orocos: when using this version, disable the typekit that comes with itasc_core (unfortunately still manual work):
    • go to itasc_core/CMakeLists.txt
    • comment the line: orocos_typekit(eigen_toolkit src/eigen_toolkit.cpp)
    • delete the installation of the eigen_toolkit header: src/eigen_toolkit.hpp

Changes to iTaSC files

As iTaSC was originally based on ROS Groovy, some adaptations of the code are necessary for it to compile in Indigo. Unfortunately these changes are still manual work.

.bash_itasc_dsl

   # export ROS_PACKAGE_PATH=$ROS_WORKSPACE/rtt_pr2_controllers_msgs:$ROS_PACKAGE_PATH
   # export ROS_PACKAGE_PATH=$ROS_WORKSPACE/itasc_tests:$ROS_PACKAGE_PATH
   # source `rospack find rtt`/../env.sh;
     export LUA_PATH="$LUA_PATH;`rospack find orocos_kdl`/?.lua"
   # export LUA_PATH="$LUA_PATH;`rospack find rtt_geometry`/kdl_typekit/lua/?.lua" #automatically solved by catkin version of rtt_geometry
   # export LUA_PATH="$LUA_PATH;`rospack find youbot_driver_rtt`/lua/?.lua"

itasc_core/CMakeList.txt

orocos_use_package(rtt-marshalling)
orocos_component(iTaSC_Scene src/Scene.hpp src/Scene.cpp )
target_link_libraries(iTaSC_Scene eigen_typekit)
orocos_install_headers( src/ConstraintController.hpp )
orocos_install_headers( src/ConstraintControllerInequality.hpp )
orocos_install_headers( src/VirtualKinematicChain.hpp )
orocos_install_headers( src/Solver.hpp )
orocos_install_headers( src/SubRobot.hpp )
#TODO SHOULD BE DELETED WHEN CHOLESKI MOVED TO KDL
#orocos_install_headers( src/choleski_semidefinite.hpp src/eigen_toolkit.hpp)
orocos_install_headers( src/choleski_semidefinite.hpp)
 
orocos_typekit(eigen_typekit src/eigen_toolkit.cpp)
 
#TODO DELETE THIS WHEN NEW KDL VERSION WITH CHOLESKI IS STABLE
orocos_library(choleski_semidefinite src/choleski_semidefinite.cpp)
orocos_generate_package()

itasc_core/src/CMakeList.txt

orocos_typekit(eigen_typekit eigen_toolkit.cpp)

itasc_core/src/ConstraintController.hpp

//#include "eigen_toolkit.hpp"

itasc_core/src/VirtualKinematicChain.hpp

//#include "eigen_toolkit.hpp"

itasc_core/src/Solver.hpp

//#include "eigen_toolkit.hpp"

itasc_core/src/SubRobot.hpp

//#include "eigen_toolkit.hpp"

trajectory_generators/fixed_joint_generator/CMakeLists.txt

#find_package(Eigen REQUIRED)
#include_directories(${Eigen_INCLUDE_DIRS})

trajectory_generators/fixed_joint_generator/manifest.xml

<rosdep name="eigen"/>
    <depend package="rtt" />
    <depend package="ocl"/>
    <depend package="orocos_kdl"/>

itasc_tasks/sixDof_pff/manifest.xml

    <rosdep name="eigen"/>
    <depend package="orocos_kdl"/>
    <depend package="ocl"/>
    <depend package="rtt" />
    <depend package="itasc_core"/>
<!--<depend package="kdl_typekit"/>  -->

Build the packages

Build the core packages

  • rosmake itasc_core trajectory_generators itasc_tasks rFSM rttlua_completion itasc_solvers fixed_object  itasc_robot_object moving_object moving_object_tf

Build application dependent packages

  • Compile the dedicated itasc components for the PR2 or Youbot, located in the itasc_robots_objects stack (not yet tested in Indigo)

Design Workflow

Multiple files should be created or adapted to create a new application, a good workflow could be:
  1. Make a list of all tasks that have to be executed
  2. Draw the kinematic loops for each task (see also Comanipulation Demo)
  3. Draw the component layout of your application
  4. Draw the behavior of your application (coordination of the behavior at runtime), this will afterwards be implemented in the composite_task_fsm.lua and the running_task_fsm.lua files. Consult 'subFSM's of the running state' of the iTaSC user guide for more information.
  5. Create or download all necessary packages (tasks, robots, objects, solvers...)
    1. Create the components (computational part)
    2. Create the skills (FSM: coordination and configurational part), but leave the sub state machines dictating behavior at runtime for now (eg. running_taskname_fsm.lua).
  6. Create the FSM on the iTaSC level: itasc_configuration.lua
  7. Create the FSM on the application level
  8. Check, create or adapt the configuration files (.cpf) of your components.
  9. Create a deploy script: run.ops and run.sh (after this step, you can test that your application gets to the running state, without errors)
  10. Create the FSMs that coordinate the behavior at runtime
    1. on itasc level: composite_task_fsm.lua
    2. on task level (for each task): running_taskname_fsm.lua

Known compatibility issues

  • robot_model/kdl_parser from the ROS Groovy debian packages: downgrade to robot_model-1.8
    • used in itasc_pr2 and itasc_robot_object to convert urdf model to kdl tree
    • this version returns foo-bar tree
    • prevents itasc_pr2 and itasc_robot_object components to configure
  • In case your computer has limited RAM (2GB):
    • In .bashr file: add  export ROS_PARALLEL_JOBS=' -j1 -l1'
    • When performing rosmake:  rosmake --threads 1