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 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

sudo apt-get install libeigen3-dev sip-dev liburdfdom-dev ros-indigo-angles ros-indigo-tf2-ros ros-indigo-geometric-shapes liblua5.1-0 liblua5.1-0-dev collada-dom-dev libbullet-dev
  • IMPORTANT: your workspace setup should look as follows:

ws/          --CATKIN WORKSPACE
    underlay_isolated
        build_isolated
        install_isolated
        devel_isolated
        src
            orocos
                orocos_kinematics_dynamics
                orocos_toolchain
    underlay
        build
        devel
        src
            geometry
            robot_model
            rtt_geometry
            rtt_ros_integration
  • Afterwards add the following to your .bashrc file:

source /opt/ros/indigo/setup.bash
source ~/ws/underlay/devel/setup.sh

  • Make a new rosbuild workspace (for instance ~/ros_ws) that overlays the catkin workspace:

(http://wiki.ros.org/catkin/Tutorials/using_rosbuild_with_catkin)

mkdir ~/ros_ws
cd ~/ros_ws
rosws init . ~/ws/devel

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 (NOT RECOMMENDED)

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 the following at the end of your ~/.bashrc file, in the here presented order

source $HOME/ros_ws/setup.bash
ROSWSPATH=$HOME/ros_ws
source .bash_itasc_dsl
useITaSC_deb
  • re-source your .bashrc
    • source ~/.bashrc

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)

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

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 the installation

  • 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
  • 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

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