DASL Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 3D Systems Touch Haptic Device ======

**Author:** Ethan Nowery Email: <nowery@unlv.nevada.edu>
\\
**Date:** Last modified on 10/09/23
\\
**Keywords:** DASLHub, Tutorials, 3D System's Touch, Haptics
\\
{{ :touchdevice.jpg?nolink&400 |}}

This tutorial serves as a guideline for setting up your 3D Systems Touch Haptic Device by connecting to RViz as well as an equivalent "Hello World" exercise integrated with Unity. 

===== Parts List =====

3D System Touch haptic device, power cord* (AC/DC adapter 100-240VAC, 40W max), USB cord*, and your preferred computer setup running Ubuntu and ROS.

{{ :touchcords.jpg?nolink&400 |}}
*Both versions of these cords are only rated for the ones that come with the device*

__If you are only interested in the "Hello World!" exercise with Unity, skip this section.__
----
===== Integration with RViz ======

===== Software =====

Need to have downloaded: Ubuntu 20.04 (or newer), ROS Noetic-including catkin workspace.

*NOTE* the Touch haptic device used to be called Phantom Omni. Any further reference to the phantom_omni is referring to the Touch.

Before beginning the tutorial, make sure to download the following packages.

*NOTE* The step-by-step instructions from the following sources are outdated for the specified versions of Ubuntu and ROS, thus only parts of them will be used.

  * Download Libraries from this link: (first line of code under ‘Preliminary Setup’)
[[https://github.com/TzeLun/PhantomOmniUbuntu|GitHub PhantomOmniUbuntu]]
{{ :touchgithub.png?nolink&600 |}}
  * Using git clone in terminal, download files from:
[[https://github.com/fsuarez6/phantom_omni.git|GitHub fsuarez6]]
{{ :touch_phantom_omni_package.png?nolink&600 |}}
  * Download these three libraries:
sudo apt-get install libncurses5 libncurses5-dev libncursesw5-dev
  * Download Openhaptics Installer and Touch Device Drivers from:
[[https://support.3dsystems.com/s/article/OpenHaptics-for-Linux-Developer-Edition-v34?language=en_US|3dsystems.com]] (Unzip both of these installers by using tar -xfvz <name of .zip> or by extracting the files into your /catkin_ws/src directory)

*NOTE* If any of the above links are no longer available, here is my compressed .zip file of all the drivers and packages needed: {{ :touch_drivers_src.zip }}

After all of those are installed:

===== Step 1: Finish Installing Touch Drivers =====

Go into ~/catkin_ws/src/openhaptics…amd64$ and type sudo ./install to install further Touch device drivers. When prompted, type [y] to restart the computer. 

===== Step 2: Relocate Necessary Libraries =====

Once your computer restarts, cd into touch driver. Then cd usr/lib to go into the lib folder. Type sudo cp <libphantom.so file> /usr/lib/ to move this library into the proper path.
{{ :touchstep2.png?nolink&800 |}}

===== Step 3: Initializing Device =====

Cd ../.. To go back 2 directories, into the TouchDriver.. directory. Plug in the Touch device into a USB port on your computer. Type sudo chmod 777 /dev/ttyACM0 to initialize device usage. To check that the Touch is being detected, type ./ListUSBHapticDevices, it should print out /dev/ttyACM0 (which means its recognized and ACM0 is the USB port that its plugged into)
{{ :touchstep3.1.png?nolink&800 |}}
{{ :touchstep3.2.png?nolink&800 |}}

===== Step 4: Adding Configuration Files =====

Cd bin and run  ./Touch_Setup . A menu should appear and show you the name of the device and the serial number. Just click ‘apply’ there's no need to change anything right now. This step adds configuration files necessary to operate the Touch.
{{ :touchstep4.png?nolink&800 |}}
{{ :touchstep4.2.png?nolink&400 |}}
===== Step 5: Running Diagnostics =====

 Next run ./Touch_Diagnostic . Another menu should pop up and a diagnostic test should start automatically. Here you can click the other tabs at the top left and calibrate the device. This step further adds configuration files pertaining to the diagnostics of the device.
{{ :touchstep5.1.png?nolink&800|}}
{{ :touchstep5.2.png?nolink&400 |}}

===== Step 6: Editing .cpp Files =====

Next, we need to locate two .cpp files and make a minor change. Both are located through the path (/catkin_ws/src/phantom_omni/omni_common/src). gedit the omni.cpp file first. Use ctrl+f and type in “hHD =” this should find only one reference and be on line 298. change this line to read “hHD = hdInitDevice(“Default Device”) *This is case and space sensitive* save the file using ctrl+s and close the window.
{{ :touchstep6.1.png?nolink&600 |}}
{{ :touchstep6.3.png?nolink&600 |}}
Go into the omni_state.cpp file and repeat above step (is located on line 370, but says the same thing). Make sure to save the changes.
{{ :touchstep7.1.png?nolink&600 |}}
{{ :touchstep7.2.png?nolink&600 |}}

===== Step 7: Edit omni.launch File =====

Go back to your terminal and change path to (/catkin_ws/src/phantom_omni/omni_common/launch). Gedit omni.launch to open the file. On line 3, the last few words should say type=”state_publisher” to type=”robot_state_publisher”. (Just add ‘robot_’ within the parentheses). Make sure to save the changes.
{{ :touchstep8.1.png?nolink&600 |}}
{{ :touchstep8.2.png?nolink&600 |}}

===== Step 8: Edit bash.rc File =====

Go to cd to /catkin_ws and type gedit ~/.bashrc to open the bash file. Scroll all the way down to the bottom of the file and add two empty lines. On the last line add <source ~/catkin_ws/devel/setup.bash> save the file and exit. If this step is skipped, you will have to source the bash file manually every time you want to run the program. 
{{ :touchstep9.1.png?nolink&600 |}}
*Your line # may be different than mine as I have other projects that i’ve added to this file.*
{{ :touchstep9.2.png?nolink&600 |}}
===== Step 9: Make Your Project =====

Go back to the catkin directory and type catkin_make (green text will show up saying that it is building the object)
{{ :touchstep10.1.png?nolink&600 |}}

===== Step 10: Launch RViz =====

When that has finished, type <roslaunch omni_common omni.launch> to launch RViz. *Note* roscore does not to be launched before this as the command roslaunch starts it automatically.
{{ :touchstep11.png?nolink&600 |}}

*RViz should have opened and you can see a 3D simulation of the Touch device with a blue stylus and blue head. Take the stylus out of the inkwell and you should see the simulation move with you.*
{{ :touchstep12.png?nolink&400 |}}


----
===== "Hello World!" Exercise in Unity =====

Haptic devices are used to feel virtual objects by using force feedback. A good introductory "Hello World!" equivalent exercise would be to test 3 springs with different magnitudes to feel the different forces pushing back on the device. 
 *NOTE* Experience with creating scenes, placing objects, adding/editing components to objects, and general overall knowledge of how to maneuver in Unity is required.
===== Software =====
Need to have downloaded:  
  * Windows 10 or 11
  * Unity 2020.4
  * OpenHaptics Installer and Touch Device Drivers: [[https://support.3dsystems.com/s/article/OpenHaptics-for-Linux-Developer-Edition-v34?language=en_US|3dsystems.com]]

===== Step 1: Create Project =====
Open Unity Hub and create a new project using the 3D core template.


===== Step 2: Import Haptic Packages =====
When the new scene opens, click on the Asset Store tab in the top middle of the screen and open the store in your browser. Type in "haptics direct" and download the only free package that shows up. Follow the instructions to download. When prompted, leave all the boxes checked and import into your project.
{{ :unityassetstore.png?nolink&400 |}}
{{ :unitypackage.png?nolink&400 |}}

===== Step 3: Setting the Scene =====
After importing the Haptic Direct package, its time to set up your scene. Add the following haptic objects to your Hierarchy: HapticActor_DefaultDevice, a SimpleStylus, and a sphere with 0.02 scale and is attached to the tip of the stylus (need to also attach the Haptic Collider script found in the Haptic Direct package to this sphere). Also add 3 3D objects of your choice (these will act as the bodies for your springs. I chose cylinders for mine.) and a plane for the 3 objects to sit on.
{{ ::unityscene1.png?nolink&600 |}}

===== Step 4: Adjust the Settings =====
Follow this button path starting at the very top left of your Unity window. Edit> Project Settings...> Player> Other Settings. Scroll down to where it says "API Compatibility Level" under "Configuration" and change ".NET Standard 2.0" to ".NET 4.x".
{{ :unitysettings1.png?nolink&600 |}}

Next, in the menu where you clicked on "Player" go to the "Physics" tab. There are three values we need to change. These are: Default Contact Offset = 0.001 (add an additional 0), Default Solver Iterations = 12, and Default Solver Velocity Iterations = 2. 
{{ :unitysettings2.png?nolink&600 |}}
===== Step 5: Attaching Components to Objects =====
Make sure that the 3 objects being used for spring bodies have the following components: 
{{ :unitycomponents.png?nolink&400 |}}

Attach the script "Haptic Plugin" to your HapticActor_DefaultDevice object.
Under "Haptic Plugin" attach the simplestylus to the Visual Mesh. Attach the "Haptic Collider" to the Collision Mesh. 
{{ :unityplugin.png?nolink&400 |}}

===== Step 6: Applying Physics =====
Make sure the "Is Kinematic" box is checked under Rigidbody components on your spring objects. Adjust each objects spring magnitude to: 0.1, 0.5, and 1 to give them different stiffness. Give your objects some mass and play the scene. You should be able to feel different spring strengths for each spring.

----
===== Conclusion =====

The goal of this tutorial was to get your Touch haptic device to feel force feedback with both Ubuntu and Windows using ROS RViz and Unity respectively. At this point, the reader should have a decent knowledge of both making a scene in Unity as well as navigating and troubleshooting code in ROS. 

This tutorial helps to analyze various ways of applying haptic feedback to your work for better understanding and a more immersive environment for learning. 

For questions or clarifications, Email: <nowery@unlv.nevada.edu>