Lab 4: Creating Your Own Device Class

Transcription

1 Department of Mechanical Engineering ME EN Haptics Lab 4: Creating Your Own Device Class Out: Thursday 2/24/2011 Due: Thursday 3/8/2011 by class time Please read this entire document before starting the lab. This project must be completed and submitted individually or in pairs of two. You are welcome to discuss the assignment with other students in the class, but you do need to program your own solutions. Summiting Lab assignments Before you submit your assignment be sure to read this section completely. Points will be deducted if you get this wrong. If you are going to deviate talk to me beforehand. All previous lab environments and README documents are to be included. You will be compressing and turning in only the LabFiles folder highlighted below. Do not include all of chai as it will make your file far too large. Make a copy of this folder somewhere else for modification before handing in. If something goes wrong you won't lose your work or mess up your project files. ME 7960 Haptics Lab 2 Page 1 of 9

2 Within the copied LabFiles folder remove the Debug/Release folders, the.ncb file, and any project user options files to reduce size. All that should be left is the project solution, the project file, the source folder, the executable folder, and the README document(s). I will be recompiling all of the projects even though you are handing in the executable and I do not want to include the.dll files for each one myself. Gmail does not like zip files containing executables. You may delete the executable leaving the.dll files or use a different compression method. Rename the LabFiles folder to Lab#-StudentNames, replacing the # with the actual lab number and filling in your name or names as necessary. Then compress it into zip or some other format. The end result compressed file should be less than 1Mb. It will grow as the semester progresses but it will always remain small. the file to your TA, Andrew Doxon at adoxon@gmail.com. The heading should state it is a lab assignment handin and the body should contain the first and last names of the students responsible for the lab. ME 7960 Haptics Lab 2 Page 2 of 9

3 README files Each lab assignment will contain a readme document titled "README-Lab#". Replace the # with the corresponding lab number. These readme files simply contain information on each environment developed. A basic README file was provided with the template for lab1. The first page of the README file is a title page. This page must contain the name(s) of the students who worked on the lab as well as a list of the environments that are contained within the document. The remainder of the document lists each environment in turn and provides a brief description along with any special features or items you included. It can be as simple as the example or as complex as you like so long as it is readable. A new README file will be added to the LabFiles folder with each lab. All prior README files will remain and be included in the handin. Lab 4 Assignment This lab will build on your work from labs 1, 2 & 3. Your new device and each new environment must have a new class file (appropriately named). All environments previously implemented will be included in the project and handin file but will not be included in the environments list. Refer to other instructions from previous lab handouts as necessary. Correctly written class files should compile and work automatically in the template. The easiest way to create proper class files is to copy the.cpp and.h files from a working environment class and rename as appropriate. You will also need to modify the environment list within the main.cpp file. For each class you create in this lab you will need to add the correct #include statement and push it onto the environment list. Please comment out prior lab environments so that they can be easily accessed but will not render in the current code. ME 7960 Haptics Lab 2 Page 3 of 9

4 Remember, before you run your code. FIRMLY GRASP THE HANDLE/KNOB OF THE HAPTIC PADDLE TO PREVENT IT FROM ACCIDENTALLY DESTROYING ITSELF BY SLAMMING INTO ITS OWN HARD STOPS OR OTHER OBJECTS IF IT HAS AN UNSTABLE OR UNINTENDED PROGRAMMED BEHAVIOR!!! IT IS STRONGER THAN YOU MAY EXPECT. Your task for this lab is to create a new device class for a haptic paddle using a Sensoray 626 card and some testing environments. All the information you will need to write the device class is contained within the two reference manuals provided. Plan out your code before writing it. This will help organize your code, make it easier to write, and contain fewer errors. Continuously compile your code to make sure that each added change still works. Your end goal is to create a device class to control the haptic paddle and a vibrotactor along with a few test environments. The following instructions are a suggested method to follow to complete this lab. Be sure to include a brief description of the device class in the README file along with your environments. The environments you are writing are haptic systems. As such they should feel stable for all users. This commonly means using lower gains. A good way to test if your system is stable is to use a light grip and tap the virtual surface. If you feel a slight buzzing or more you need to reduce your gains. Start with lower gains as the haptic paddles can produce a high maximum force. Extra credit: Extra credit may be given for work above and beyond the basic instructions if it is deemed suitable. If you are unsure about your idea, ask. Writing the device to handle multiple 626 cards or devices per card will grant extra credit. But doing this correctly will require quite a bit of thought. 1. First be sure to download the package provided for you. This package contains the two reference manuals on the 626 card as well as the three files needed to interface with the card. A short description of each file is provided below. Downloading the current lab template will make this lab easier. Andrew has implemented the starting environment separately as well as a few minor changes that will be helpful in this lab. Simply update the main file to include your previous environments. 626 DLL Manual.pdf - contains descriptions of all the function calls and C code examples for each. This is your primary resource in coding the device class. 626 Instruction Manual.PDF - contains reference material on the physical 626 card itself. You will need this to determine what inputs and outputs to use based on pin connections provided in the schematics below. APP626.h - lists #defines used by the function calls Win626.h - defines the function calls that interface with the 626 card. You will need this #included in your device class file. WIN626.c - contains the actual function call links with the.dll file ME 7960 Haptics Lab 2 Page 4 of 9

5 2. Set up your device class file. You should start by creating the shell of the device class. This is just a placeholder and the actual functions will be written later. This way you can insert the shell into the haptic program and test the functions as your write them. A good starting point for this is to take the cfalcondevice class from chai and prune out all the unnecessary parts including the contents of the function calls. Your haptic paddle device class will be a public child of cgenerichapticdevice. This means you will need to #include "devices/cgenerichapticdevice.h" in your class and put :public cgenerichapticdevice after the class name when defining it. The cfalcondevice class is already a child of cgenerichapticdevice and thus far you have been defining all your environments as public children of the Environment class. This way your device can be swapped out with any chai device easily. Your device class will contain the following four specific functions: open, close, getposition, and setforce. You may add additional functions if you wish. Remember this is just a shell and the functions should contain nothing {} as you have no way of testing them. Below is a brief description of each of the four necessary functions. Feel free to change the inputs to the open and close functions but getposition and setforce will take the inputs defined below. The names of these functions match those used in the all chai devices. open(); load the.dll open the 626 card initialize encoder(s) analog and digital outputs do not need setup on the 626 card close(); write 0 values to all outputs close the 626 card close the.dll encoders and other inputs do not need to be changed getposition(double& a_position); This function should get the current encoder count convert the count to a position o beware the returned count is signed 24 bit return the position in the a_position variable setforce(const double& a_force); compute output voltage using the kinematics and a_force variable o current amplifiers have a gain of 1V to 0.25A set the output voltage on the appropriate DAC (limit in code to ±10V) ME 7960 Haptics Lab 2 Page 5 of 9

6 3. Replace Falcon device with your new one. Now you want to place your device shell into the haptic program. This will allow you to know that you have set it up correctly and test its functionality as you go. Create a new instance of your haptic paddle device in the GlobalVariables.h file. In the main file open this device and pass it to the environment. Commenting out the falcon if you wish. You will need to #include your class header file anywhere you use the class. Appropriately add the close() method call to the main file, in the keyselect function under the escape case. The Falcon did not necessarily need to be closed but the 626 card does. You now need to make a starting environment to work with the haptic paddle device class properly. Make a copy of the current starting environment for 1 DOF motion. You always want a starting environment. Really, you just need to have a starting environment that provides no forces to the device. 4. Modify the cgenerichapticdevice.h file. You will also need to modify the cgenerichapticdevice.h file. The makers of chai did not include proper support for 1 and 2 DOF devices. Open the file and find the function description for getposition and setforce and add an additional definition matching the ones you have in your device shell. Make sure these are virtual so that they can be properly accessed. ME 7960 Haptics Lab 2 Page 6 of 9

7 5. Complete your device methods. Now that your device shell is integrated in the program you can begin writing your device methods. You may want to make a dummy environment which will not be included in the final handin to test functionality as you go. The schematic below shows how the haptic paddle is connected to the Sensoray 626 card. You will need to look up the ports that the pins below correspond to in the card reference manual and the correct commands for controlling the 626 card in the DLL reference manual. Almost all the code you will need to write the device class is provided for you in the examples of the DLL reference manual. Maxon RE35 motor External Power Must turn external power on to get forces Haptic Paddle Motor Motor Encoder + - E I-D-D-B 5V A B GND Amplifier Box 1V input => 0.25A output GND 5V J4 pin 21 J4 pin 24 enc. A J4 pin 20 enc. B J4 pin 23 DAC out J1 pin 42 AGND J1 pin 40 The necessary methods and what they should do are listed again below. open(); load the.dll open the 626 card initialize encoder(s) analog and digital outputs do not need setup on the 626 card close(); write 0 values to all outputs close the 626 card close the.dll encoders and other inputs do not need to be changed getposition(double& a_position); This function should get the current encoder count convert the count to a position o beware the returned count is signed 24 bit return the position in the a_position variable setforce(const double& a_force); compute output voltage using the kinematics and a_force variable o current amplifiers have a gain of 1V to 0.25A set the output voltage on the appropriate DAC (limit in code to ±10V) ME 7960 Haptics Lab 2 Page 7 of 9

8 6. Create 1 simple testing environment with the Haptic Paddle. Once you have a working device class, you will need to create a simple environment to demonstrate it works. Examples are detents, a wall, textures, etc. Many of the environments you have already made can quickly be copied and altered to 1D. Make sure your gains are altered as the Haptic Paddles have different characteristics than the Falcon. You can try adding dimensionality to your system through graphics for extra credit (i.e., while motion may be constrained to 1D the rendered position does not need to be). 7. Add vibrotactor functionality. Now add a fifth method to your haptic paddle device to control the digital IO pins connected to the vibrotactor, shown below (we will have the vibrotactors connected as shown below). For uniformity this method should be defined as vibrotactor(bool ONOFF);. It should use the bool to turn on and off the vibrotactor and should not affect the other IO pins. You will need to add this functionality to the cgenerichapticdevice.h file as well, like you did in step 4, in order to access it. External Power Must turn external power on to get forces Vibrotactor Transistor Switch GND 5V input J2 pin 48 J2 pin 49 J2 pin Create a vibrotactor environment. Create a second environment to control the vibrotactor. Using timers, implement three distinct feeling haptic icons (buzz-tones) in this environment (think back to the vibrotactor demo we showed you on the first day). These haptic icons will be activated when the 1, 2, and 3 keys are pressed. Try to describe what you think these haptic icons should represent to a user in your README (e.g. emergency, stop, go, happy,...). Hints: Virtually everything you need is already in the template in some form or another. Google is your friend, use it. Try to think about how to perform the task specified before coding it. Whenever possible think in terms of vector math. It will only cause problems down the line if you break things ME 7960 Haptics Lab 2 Page 8 of 9

9 up into their components. provides some really good opengl resources and tutorials for just about everything you could want. has definitions and examples of basically every standard function in the C++ language. If you are using Google to search for functions this will likely show hits in the top few links. We would like to acknowledge Francois Conti, Federico Barbagli, and Kenneth Salisbury at Stanford University. The lab exercises presented herein largely come directly from their Experimental Haptics Course, CS277, and is based on their CHAI-3D environment. ME 7960 Haptics Lab 2 Page 9 of 9