Instructions for Running the Arm

Before attempting to run the arm, it is very important to read through all of the manuals and get a feel for how it works. Be sure to get very familiar with how the Shift-Activate, Shift-Idle, and E-STOP buttons work. They are very important for safety reasons. It is also very important to please be sure that nobody is in the area of the arm while you are using it. The arm is extremely powerful, and can move at very high speeds if you are not careful. Once you are familiar with the system, there are a couple of Simulink models that you can run to get started.

NOTE: The small power supply underneath the table is for the hand. Be sure not to turn off the power supply to the hand for more than a couple days, or you will have to reinstall the firmware.

Running Gravity Compensation

1. Switch on power to the arm (the big silver power supply under the table).
2. Align the tick marks for joint 3 and joint 1 of the WAM as accurately as possible (the joints are labeled on the physical arm). This will put the arm in home position, which is crucially important in order for the joint position readings to be correct.
3. Once you are sure you have put the arm in home position, make sure that the E-STOP is not pressed in. Then hold "Shift" on the pendant and press "Idle". This will initialize the WAM.
4. Turn on the xPC target machine (the old Dell computer underneath the desk). It should boot from CD and display a very basic interface on the screen.
5. Locate wam_init.mat in the grasp folder, and open it. This contains variables necessary for compiling the Simulink model.
6. Locate the gravcomp.mdl file in the grasp folder. Open it and build the model. This will compile the block diagrams into C code which is then downloaded to the xPC target machine.
7. Open xPC Target Explorer in Matlab either by typing "xpcexplr" in the Command Window or by clicking the shortcut.
8. Connect to the WAM target machine using xPC Target Explorer.
9. In xPC Target Explorer, press the "Play" button. This will start the model running on the xPC target machine.
10. Hold "Shift" on the pendant, then press "Activate". This will start applying torques to the arm to cancel gravity.
11. Try moving the arm around to different positions, and it should hold itself up.
12. When you are done, put the arm back to the home position. Hold "Shift" on the pendant, then press "Idle".
13. To stop running the model on xPC target, you can press "Stop" in xPC Target Explorer.

Making the Arm Move Around

Next you can try running a more sophisticated model than gravity compensation. Believe it or not, the procedure is exactly the same except for the Simulink model you will download. Rather than building gravcomp.mdl, locate wamjc.mdl and download this new model. The rest of the steps are the same.

This time you will notice that the arm is very stiff. You will not be able to move it around like you could before, because now the PID controller is actively holding its position. Start by sending a simple joint space move, moving one joint at a time. The home position has joint angles approximately equal to [0 -1.95 0 3.04]. The [0 0 0 0] position is when the arm is pointing straight up in the air.

To start out, you could try the following in the Matlab command window. This will keep all joints stationary and move joint 4 to pi/2.

q = [0 -1.95 0 pi/2];
netInfo = initUdpCommunication();
sendArmJspaceMove(netInfo, q);

You will notice that when you loaded wam_init.mat, it loaded a bunch of variables, two of which were arm_home and arm_home_norest. arm_home is the actual home position of the arm. arm_home_norest is offset slightly from home so that the upper arm doesn't rest on the rubber joint stop (this causes vibrations). If you want to send the arm back to home position, simply execute the following command. Notice that this just takes the shortest path back to the home position, and could cause the arm to run into something (i.e. the table) depending on where it starts moving from. Always proceed with caution, but for the simple case we are running here, the arm will obviously not run into anything.

sendArmJspaceMove(netInfo, arm_home_norest);

Try sending some other joint space moves, but when in doubt, be sure to test things out in simulation first! If you are feeling ambitious, you can even try moving the joints of the hand or sending a Cartesian space move, but make sure you know what you are doing before trying this. You should always run Cartesian space moves in simulation first to make sure they will do what you expect them to. Singularities can wreak havoc and cause the arm to swing wildly if you are not careful.

Finally, to clean up your open sockets, you should run this command when you are done (or just exit out of Matlab).

netInfo.udpSock.close();
clear netInfo;

Running Experiments

Once you feel comfortable with using the arm and tracking system, you can try setting up an actual experiment. There are some sample experiments in the grasp folder prefixed with exp_something_.m. Start with something simple and work your way up to an actual experiment. And as always, be sure that you have tested any joint/Cartesian space/hand moves before running them blindly in experiments. runExperiment.m has been coded as robustly as possible, and should shut down the arm, tracking system, and UDP communication gracefully on any kind of error.

All you have to do to run an experiment is create a callback function (use one of the functions prefixed with "exp" as a template), then call runExperiment with the appropriate inputs. You will also need to create a Tracking Tools project file. You can do this by running the Tracking Tools software, calibrating the cameras (by wanding), and setting the ground frame. Be sure to do this as accurately as possible. Once you have your callback function and a Tracking Tools project file, you are ready to run your experiment. Most of the time, it is easiest to run the Matlab calibration only once (recall that this finds the transformation between the camera frame and WAM base frame). You can do this as follows.

[exp, tformInfo, wamInfo, cal] = runExperiment('myproject.ttp', 'expDummyCallback');

expDummyCallback is a callback function that just sets experiment.state=0 right away, meaning that you will get the calibration result without running your own experiment yet. It is usually best to save tformInfo in a ".mat" file, so you can retrieve it later. Now you are ready to run your actual experiment. This time, since you will pass in the optional argument "tformInfo", runExperiment.m will not rerun the calibration procedure and will instead use your pre-existing calibration result. In addition, you can pass in the optional argument "inputParams", which will be sent to your callback function along with the current frame data. This is just to make things more modular in case you want to run several experiments which are similar in structure, and vary only in some input values.

inputParams = struct('myInputVar', 56);
[exp, tformInfo, wamInfo, cal] = runExperiment('myproject.ttp', 'expMyCallback', inputParams, tformInfo);

Importing/Exporting Experiments to the Database

There are functions in the grasp folder for importing and exporting data to the database from Matlab. These are dbImportTrackingData.m and dbExportTrackingData.m, respectively. They are named such because they used to only export tracking data, but they have now evolved to export all experiment data (calibration, WAM, and tracking data). You can rename them if you'd like. These functions have been coded as robustly as possible, and should safely rollback database changes if the network suddenly goes out while you are exporting data, for example.

dbExportTrackingData takes as input the experiment struct, calibration result (tformInfo), and a brief description of the experiment. On success, it will return the experiment ID which you can then look back up and visualize using the web interface.

expId = dbExportTrackingData(exp, tformInfo, 'My grasping experiment');

dbImportTrackingData does the reverse. Given the experiment ID, it will load the experiment, calibration result, and meta data back into Matlab.

[exp, tformInfo, metaData] = dbImportTrackingData(expId);