Read Me

RESHL - ROS-Enhanced Scalable Haptic Library - VERSION 2.1.0
Copyright (C)  2015  Fondazione Istituto Italiano di Tecnologia
Author: Emidio Olivieri 


What is it?
-----------

RESHL is a collection of Linux software used to interact with pen-master based
haptic devices. Its name, ROS-Enhanced Scalable Haptic Library, describes all
its main features:

  - ROS-Enhanced: the library can be used as a library in the ROS framework
    (Robot Operating System - http://www.ros.org/) and already provides support
    for master-slave solutions

  - Scalable: the library consists in different sub-libraries with different
    software dependencies. This way you don't have to install software for
    devices or functionality you're not going to use. Refer to Structure
    section for details on the single sub-libraries.

  - Haptic: the end-application is using pen-master devices to simulate the
    sense of touch in a haptic virtual environment.

  - Library: the software is distributed in c++ libraries with an easy
    interface. A graphic environment based on OpenGL is generated to improve
    the user's experience.
    

The Latest Version
------------------

Details of the latest version can be found on the RESHL project page on
sourceforge under https://sourceforge.net/p/reshl/.


Supported Devices
-----------------

All the devices supported by your Open Haptics distibution. If version 3.0 is
used, according to product specifications in Geomagic Open Haptics webpage:
  - PHANTOM Omni (FireWire IEEE 1394a)
  - PHANTOM Desktop (Parallel Port)
  - PHANTOM Premium 1.0, 1.5, 3.0 (Parallel Port)
  - PHANTOM Premium 1.5/6DOF, 3.0/6DOF (Parallel Port)
http://www.geomagic.com/it/products/open-haptics/specifications/

All the devices supported by your Force Dimension SDK version. If version 3.x
is used, according to product specification in Force Dimension SDK webpage:
  - Force Dimension delta family:
    - delta.6
  - Force Dimension omega family:
    - omega.3
    - omega.6
    - omega.7
  - Force Dimension sigma family:
    - sigma.7
http://www.forcedimension.com/products/sdk/specifications


Structure
---------

In the current version, the libraries generated are:

  - libreshl.so
    The core of the library, necessary for all the applications. Dependencies:
    standard library, libx11, librt, OpenGL, GLEW, POSIX Threads

  - libreshloh.so
    Open Haptics device handler, needed to use Open-Haptics-supported devices.
    Dependencies: libreshl.so, Open Haptics, POSIX Threads

  - libreshlfd.a
    Force Dimension device handler, needed to use Force Dimension haptic
    devices. Dependencies: libreshl.so, Force Dimension SDK, libusb-1.0, POSIX
    Threads, librt

  - libreshlqt.so
    Qt windows, needed to include OpenGL scenarios in QWidget, it may be useful
    for Qt developers. Dependencies: libreshl.so, Qt 4, OpenGL, GLEW, POSIX
    Threads

  - libreshlassimp.so
    Used to import meshes inside graphical handlers. Dependencies: libreshl.so,
    Open Asset Import Library (version 2 or 3), OpenGL, GLEW

  - libreshlros.so
    ROS-oriented part. Dependencies: ROS (see manifest for ROS packages used),
    libx11, OpenGL, POSIX Threads


Documentation
-------------

The documentation available as of the date of this release is included in HTML
format in the docs/html/ directory.


Installation
------------

If you have ROS, you have to copy the whole directory inside your ROS 
workspace and then use the command
ROSBUILD (up to fuerte)
$ rosmake reshl
CATKIN (groovy and on)
$ catkin_make --pkg reshl

If you don't have ROS, you have to regenerate the Makefile and then make it;
cd to reshl folder and use the following commands
$ cmake CMakeLists.txt
$ make

In both cases in lib folder you will find the generated libraries, in bin
folder the examples

To recreate the documentation file cd to reshl folder and use the command
$ doxygen Doxyfile


Troubleshooting
---------------

RESHL doesn't include any 3rd part library. This means that you have to install
yourself openhaptics and/or force dimension libraries. The following 
instructions are thought for Ubuntu 64bit.

For Openhaptics: be sure to install the drivers for the device and the 
openhaptics library following the instructions for ubuntu and to link all the
library installed in /usr/lib64 in /usr/lib/x86_64-linux-gnu/.
# ln -s /usr/lib64/* /usr/lib/x86_64-linux-gnu/
You may also need to create extra links like:
# ln -s /usr/lib64/libHD.so.3.0.0 /usr/lib/x86_64-linux-gnu/libHD.so.3.0
# ln -s /usr/lib/x86_64-linux-gnu/libraw1394.so /usr/lib/x86_64-linux-gnu/libraw1394.so.8

For Force Dimension: download the SDK and manually install the libraries in
your operative system. Unpack the tar.gz, then cd inside the sdk.
First, change the premissions
$ chmod 755 lib/release/lin-x86_64-gcc/*
$ chmod 644 include/*
Then copy the files in the system paths.
# cp lib/release/lin-x86_64-gcc/* /usr/lib/x86_64-linux-gnu/
# cp include/* /usr/include/
Finally, notify the changes in the operative system.
# ldconfig
# updatedb

If you are using a USB device you will need to access it, so either you run the
final executable as root, or you create a udev rule.
First, attach the usb and give the command
$ dmesg | tail
You will see a line like
[TIME] usb NUMBER: New USB device found, idVendor=xxxx, idProduct=yyyy
Note xxxx and yyyy; then:
# cd /etc/udev/rules.d
# echo 'ATTRS{idProduct}=="yyyy",ATTRS{idVendor}=="xxxx",MODE="666",GROUP="plugdev"' > 10-NAME.rules
where NAME is a name you can give for each device you use.
Check that you are in plugdev groups by typing
$ groups $(whoami)
otherwise add it with 
# usermod -a -G plugdev $(whoami)
Finally reload rules
$ udevadm trigger

Licensing
---------

RESHL source code is distributed under the GNU LGPL version 3. For more details
please see the file called LICENSE.


Disclaimer
----------

The application generated with this software links several libraries with
different software licenses. Some of them may be not usable in some context 
(for example non-academical applications). Make sure you own the proper rights
before using the software or distributing the binaries.


Contacts
--------

- If you have a concrete bug report for RESHL, open a ticket in
  http://sourceforge.net/p/reshl/tickets/

- To directly contact the author, send an e-mail to Emidio.Olivieri@iit.it