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:
  • http://git.mech.kuleuven.be/robotics/itasc.git
  • http://git.mech.kuleuven.be/robotics/itasc_core.git
  • http://git.mech.kuleuven.be/robotics/itasc_robots_objects.git
  • http://git.mech.kuleuven.be/robotics/itasc_solvers.git
  • http://git.mech.kuleuven.be/robotics/itasc_tasks.git

and for the iTaSC DSL

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

Installation instructions

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

  • ROS Fuerte or Groovy
  • Orocos (installation instructions on http://www.ros.org/wiki/orocos_toolchain_ros)
  • Install following stacks:
    • sudo apt-get install libeigen3-dev ros-fuerte-rtt-ros-integration ros-fuerte-rtt-geometry ros-fuerte-rtt-common-msgs ros-fuerte-rtt-ros-comm ros-fuerte-orocos-toolchain
  • rosws (ROS workspace, optional but highly recommended):
    • Create a new ros workspace or use an existing one
    • Manually add core ros stacks to your .rosinstall
    • (Copy and paste from /opt/ros/<distro>/.rosinstall to the TOP of your local .rosinstall file)
    • Regenerate your setup.* files by calling rosws regenerate

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

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