MEAM.Design - MEAM 520 - PHANToM Haptics: Rendering

Now that you have your team, it's time to get to work on project 2. This assignment is due by 5:00 p.m. on Tuesday, December 4.

Start by downloading the starter code (v1). We are providing you with p-coded versions of all the functions described in the Phantom Guide. For example, calling phantomStart(false); starts the simulated phantom so you can work on your code on any computer. Instead of getting encoder readings from the real PHANToM, the system simulates the presence of a human user by reading a pre-recorded trajectory from the included encsHistory.mat file.

Demo: Haptic Box

Run haptic_box_demo.m and look at how it is written. This demonstration creates a virtual haptic box for the user to feel, as seen in the top illustration at right. The user is trapped inside the virtual box and feels a virtual spring force each time they contact a wall. The position of the PHANToM tip is shown as a red circle, the box is shown in transparent colors, and a scaled version of the force vector is shown as a thick black line.

The system simulates the presence of a human user by default because you probably don't have a PHANToM connected to your computer. Look at how the forces Fx, Fy, and Fz are calculated from the positions hx, hy, and hz. This is the type of mapping you will need to create in this assignment.

Once you understand how the haptic box demo works, your team's task on this project is to complete the following two haptic rendering scenes created for the PHANToM.


Task 1: Haptic Ball

Complete the haptic ball scene that has been started for you in haptic_ball_team50.m. Change the filename to match your team number, and list your team number and the names of your team members at the top of the file.

The graphics for this scene are shown in the middle image at left. Again, the position of the PHANToM tip is shown as a red circle, the ball is shown as a transparent rainbow sphere, and a scaled version of the force vector is shown as a thick black line.

Modify the code between the two lines of stars to push the user out of the ball whenever they come inside, using a virtual spring mapping. The force should push them straight out of the ball, and the magnitude of the force should be proportional to their penetration depth. The stiffness of your spring should be k (already defined for you in the code). Please comment your code.

Use the graphics to debug your calculations in simulation (with hardware set to false) until all of your team members are convinced the calculations are correct. Only then are you allowed to try your code on the real PHANToM. You are welcome to show your code's output to a member of the teaching team to get their opinion of its correctness if you are not sure.


Task 2: Haptic Damping

Complete the haptic damping scene that has been started for you in haptic_damping_team50.m. Change the filename to match your team number, and note your team number and the names of your team members at the top of the file.

The graphics for this scene are shown in the bottom image at right. Again, the position of the PHANToM tip is shown as a red circle, and a scaled version of the force vector is shown as a thick black line.

Modify the code between the two lines of stars to output a viscous damping force that always acts to slow the user down. This force should act in the opposite direction to the user's velocity vector, and its magnitude should scale with the magnitude of their velocity vector. The viscosity of your damper should be b (already defined for you in the code). Please comment your code.

When correctly implemented, viscous damping should feel like you are moving your hand through molasses or honey. There should not be any jittering in the force. This means you will need to low-pass filter your velocity vector to reduce quantization noise.

Use the graphics to debug your calculations in simulation (with hardware set to false) until all of your team members are convinced the calculations are correct. Only then are you allowed to try your code on the real PHANToM. You are welcome to show your code's output to a member of the teaching team to get their opinion of its correctness if you are not sure.

Extra Credit: Haptic Box

If you have extra time and interest, update the haptic box demo so the user is outside the box and can touch all surfaces. Massie and Salisbury discuss this situation, which is more tricky to program than putting the user inside the box, as the demo does. The solution Massie and Salisbury put forward suffers from a problem where the user can pop through the surface of the box when they push close to the edges. You're welcome to implement their solution, but that will garner you / your team only a small amount of extra credit. To earn more, solve it better than Massie and Salisbury. If you decide to do this extra credit, please make that clear in your submission email, and briefly explain the approach you used. The deadline is the same. Do not attempt this unless you get the main parts of the assignment working correctly on the PHANToM.

PHANToM Rules

  • You will need to reserve the PHANToM computer in order to test your code. Here is the link to the reservation system.
  • Copy only your haptic_box_demo.m, haptic_ball_teamXX.m, and haptic_damping_teamXX.m scripts, not the rest of the phantom simulator files. Use your team's directory in the working directory on the computer's desktop.
  • Check the calibration of the PHANToM by calling phantomJointAngles from the command line. If the encoders are not correctly zeroed, run phantomZero from the command line.
  • Start by running haptic_box_demo.m to get a feel for how it works.
  • You must have the PHANToM emergency stop down (no forces) the first time you run any code, even the demo code.
  • You must firmly grip the PHANToM gimbal every time you run any code.
  • Someone must have their hand on the emergency stop whenever the PHANToM is running.

Submission

  1. Start an email to meam520@seas.upenn.edu
  2. Make the subject PHANToM Haptics: Team XX, replacing XX with your team number.
  3. Attach both of your correctly named MATLAB files to the email. It should be haptic_ball_teamXX.m and haptic_damping_teamXX.m, where XX is your team number, plus any additional files you may have created, also named according to this convention.
  4. Send the email.

Please come talk to the teaching team or post questions on Piazza if you get stuck on any part of this assignment.

PHANToM Haptics Starter Code (v1)