Version 4 (modified by bz, 15 months ago) (diff)


WAM Arm Calibration

Calibration Videos

Zeroing Position Calibration


The WAM has traditionally used relative encoders. These position-measuring devices, mounted at each motor, provide the feedback that enables the WAM to effectively control its motion. Unfortunately, since the encoders were relative, the WAM had to be precisely moved, by hand, to its "home" or "park" location on each system start-up. This has been a relatively tedious task for users to perform, especially with tasks where precise position feedback is crucial.

Recently, Barrett has switched to using "quasi-absolute" magnetic encoders in the WAM, that are able to measure the absolute angle of each motor on startup. While absolute position measurement of the motor is now possible, the the drivetrain ratios in the WAM (ranging from 10-to-1 to 42-to-1) prevent the same absolute knowledge of the joint position (hence "quasi-absolute"). Still, the added motor position information can be used to decrease the needed precision of the homing process on each system startup.

Once the WAM has been zero-calibrated, the it will compensate for small position errors from its home position on start-up. The range of allowed error corresponds to one-half of one motor revolution around the home position for each motor. This leads to different joint angles for each link (refer to the wam.conf configuration file's j2mp matrix for the drive ratios), but in general, as long as the tick marks line up within about 0.5 cm, the system will correctly compensate for any errors. Anecdotally, this allowed inaccuracy on startup makes it significantly faster to home the WAM.


Note: Barrett has produced an informal video which shows an example of the zero-calibration procedure. We highly recommend you watch the video:

In order to take advantage of the zeroing position calibration feature, you should use the WAM library's new calibration program, located in the btclient/src/calibrate directory name "calibrate". As long as the WAM has not been re-tensioned, a calibration should only need to be performed once.

To proceed with the calibration, change to the directory, and type "./calibrate". You will be presented with several options; choose the "Calibrate Zero Position" option. The program will step you through the initialization process. Take care to follow the steps, including E-Stopping the system, and ensuring that the WAM is very carefully placed in the home position!

The calibration process consists of using the arrow keys on each joint to move the WAM to the "zero" position - straight up-and-down. Using the arrow keys, select "Move To Current Zero" initially will move the arm close to zero.

Then, move down to the list of joints, and select "Joint 1". Pressing [Enter] will move to the "Set" point for that joint, where the cursor will be selecting one of the digits of the set point. Use the left and right arrow keys to change the current digit. Use the up and down arrow keys to increment and decrement that digit. The goal is to line up the tick marks on the WAM such that it is in its true "zero" position - the actual values on the screen are unimportant. Once you are satisfied that the zero position for Joint 1 has been reached, press [Backspace] to move back to the upper menu.

Next, select Joint 2, and repeat this process. For joints 1, 3, 5, and 7, the various tick marks on the WAM are the easiest way to measure the zero position. For joints 2, 4, and 6, it may be easier to use a pocket level to adjust the system to the straight-up-and-down configuration (assuming the table or other mounting point is level).

Once the WAM is zeroed, select "Print Calibrated Values and Exit". This will move the WAM back to the home position, and will both print the results to the screen and save them to a file. The results consist of two configuration lines: "home" and "zeromag". They are already formatted for inclusion in the wam.conf file; simply copy-paste or otherwise insert them into the root WAM configuration section. It is customary to insert them just after the "name" and "dof" settings near the top of the wam configuration. Ensure that any old "home" or "zeromag" lines are removed or commented.


Once the system has been calibrated, any future system start-up will automatically use the calibration values. To troubleshoot the calibration, examine your syslog file at /var/log/syslog.

Before calibration, you will see the following:

WAM: WAM zeroed by application (no zeromag)

After calibration, the following should be printed:

WAM: WAM zeroed by application (using zeromag)

Keep in mind that these values are only used on the first system start-up after a power cycle or an E-Stop event. During subsequent runs, you will see:

WAM was already zeroed

Gravity Compensation Calibration


For a high-performance, backdrivable, torque-controlled robotic arm, the ability to "gravity compensate" each of the links -- so that the robot's joints apply torque to support its own weight -- is an essential feature that enables users to easily interact with the robot. Since the WAM is such a low-friction, backdrivable robot, it is important that the computed torques are sufficiently accurate. In the past, the WAM has relied upon CAD data -- namely, the mass and center-of-mass location for each of its links -- to compute the required gravity-compensation torques.

This method has a number of drawbacks. First, the CAD data might not accurately represent the mass parameters of the robot. A number of steps throughout the machining and assembly process can affect the robot's mass distribution. Second, using explicit CAD data makes it difficult for the user to add different tools or other additions to the links of the robot. In these cases, the user must compute the exact mass parameters of the addition, and compute a new link mass and center-of-mass location manually.

To mitigate these drawbacks, version r459 of the btclient software library includes a new calibrated gravity routine. This routine consists of a calibration step which produces a set of 3-dimensional vectors, one for each moving link, which encode the mass parameters of the robot. Once calibrated, and "calibrated gravity" mode is available in the WAM library, although the traditional CAD-based gravity compensation mode is still available (and is, in fact, the default mode).


Note: for a more detailed derivation, please refer to the document entitled "Newton-Euler First-Moment Gravity Compensation" available in the btclient/src/calibrate directory.

The calibrated gravity compensation scheme used for the new routine is derived explicitly from the Newton-Euler equations for rigid-body robots. Once all velocity and acceleration terms are ignored, the mass parameters for each moving link can be represented as a "first moment of the mass" vector. This vector has units of kg-m, and is expressed in each link's local Denavit-Hartenberg reference frame. One such vector for each moving link is sufficient to compute the gravity compensation torque for any arbitrary pose of the robot.

It is worth quickly noting the relationship between this vector and the traditional mass-and-center-of-mass parameterization. Each link's first-moment vector is simply the product of its mass and its center-of-mass location vector. However, it is impossible to derive the four traditional parameters from the three first-moment parameters.

During the calibration step, these vectors are computed by moving the robot through a series of pre-defined poses, and then performing a series of simple linear regressions. When referencing the "First-Moment" document above, note that the library currently uses the "Iterative Algorithm" for this regression. The computed vectors are then inserted into the WAM configuration file, and subsequent WAM library initializations can access the new calibrated gravity-compensation routine.


The WAM library now includes a new calibration program, located in the btclient/src/calibrate directory name "calibrate". In order to perform the calibration, the program moves the WAM through a number of poses, defined in the file "cal.conf". Each pose is a list of joint positions. Depending on the WAM's orientation or the presence of objects in the its workspace, the user may wish to alter some of the defined poses.

In theory, only four poses are required. However, the regression algorithm benefits from additional poses that explore each of the dimensions of the WAM's links. Care must be taken to ensure that each moving link is oriented sufficiently differently relative to the direction of gravity in at least four different poses. Also, ensure that none of the joint commands exceed (or closely approach) any physical joint limits. If, once the calibration is completed, there exists a pose which experiences significant drift, it is advisable to add the problem pose to the list for re-calibration.

To proceed with the calibration, change to the directory, and type "./calibrate". You will be presented with several options; choose the "Calibrate Gravity Compensation" option. The program will step you through the initialization process. Once the calibration has begun, take care to ensure that the WAM is not touched during the measurement process. The process can be canceled at any time by typing [Control+C].

During the measurement process, the WAM approaches each pose twice -- once from "above" the pose in each joint, and once from "below" it. As reported on-screen during the calibration, the two sets of torques are slightly different on account of stiction in each joint. After performing both moves, the calibration simply averages the two sets of joint torque/position measurements. This step is necessary as a first-order stiction compensator.

Once complete, the results are printed to the screen and logged to a file. They are already formatted for inclusion in the wam.conf file; simply copy-paste or otherwise insert them into the root WAM configuration section. It is customary to insert them above the safety{} section. Ensure that any old calibration sections are removed or commented.


Since the release of this calibration routine, new WAMs will come with a set of calibrated vectors already saved to the onboard configuration file. Once the vectors are saved, a new set of functions in the btwam library become available:

  • GetGravityIsCalibrated(wam_struct * wam);
  • int GetGravityUsingCalibrated(wam_struct * wam);
  • void SetGravityUsingCalibrated(wam_struct * wam, int onoff);

As is customary, a non-zero value is interpreted as "on", and a zero value is "off". The GetGravityIsCalibrated() function can be used to determine whether a set of calibration vectors have successfully been read from the configuration file. The calibrated gravity routine obeys the scale factor provided through the Get/SetSetGravityComp() functions.

By default, the WAM uses the traditional CAD-driven gravity compensation routine. To switch to the new routine, simply issue:

SetGravityUsingCalibrated(wam, 1);

A new key binding has been added to btdiag to support the calibrated gravity compensation routine. Simply press 'G' to toggle between calibrated and traditional modes.