Stubby

Full featured, miniature hexapod

 

Calibration

The Stubby software includes powerful calibration routines. You can calibrate both the raw angles as well as the foot offset position for each leg independently. This page details how to run the calibration routines. To do this, you need a protractor (a simple clear plastic one like you get in your school geometry sets would work perfectly). It also helps if you place Stubby on some sort of platform (an inverted bowl or tupperware container works great).

You can currently calibrate in one of two ways. The easiest, and recommended way, is to use the Python calibration script, available in the git repository.

To run this script, you will need the Python interpreter (version 2.7 is recommended), as well as the 'pyserial' library. If you are on Linux it is recommended to get both requirements through your distribution's package manager (e.g. 'apt-get install python2.7 python-serial' on Debian based systems). For Windows, you can download python from the official download page and pyserial from here. On OS X, I have had success using MacPorts for installing both packages; I don't know if it is possible to use the built-in python or not.

If you don't have computer connectivity, you can instead use the Universal Controller to calibrate.

Using the Python script for Calibration

    Setup

  1. Turn on Stubby. You should see the power light on, but the status light dim white (or off depending on the PCB revision).
  2. Run the Python program. You are presented with the main menu, showing what options you have.
  3. Joint Neutral Angle Calibration

  4. It is recommended to calibrate all legs in neutral angle mode first, and then use foot position mode as fine-tuning if needed. If neutral angle mode calibration is not done accurately, the math behind the inverse kinematics will not work properly.
  5. Start by going into the Joint calibration menu. Reset all calibration in this mode to zero by typing "R". (You should do this the first time you calibrate, to clear any junk values out of the EEPROM, but you don't need to do it subsequent times.)
  6. Starting with the coxa joints, use the protractor to ensure that each leg is sticking out directly from the body. This means that there should be 120 degrees between one edge of the body and the leg. It helps to close one eye and try to align your line of sight directly above the axle, so that you can see exactly what the angle is.
    The first photo shows an incorrect calibration (the angle is around 135 degrees); the second photo shows correct calibration (about 120 degrees).
  7. Next up is the femur joints. Unlike the coxa, here we attempt to calibrate the servo arm, rather than the desired angle:

    Look in Leg.h to see the FEMUR_NEUTRAL_SERVO_ANGLE. (In my code it is 132 degrees). Try to match this as closely as possible. (When assembling you should try to get it as close as possible; calibration should only account for maybe 10 - 15 degrees at most. Any calibration which is added will reduce the total range of motion which this joint is capable of, since calibration is applied by directly adding to / subtracting from the PWM phase.
    The first photo shows an incorrect calibration; the second photo shows a correct calibration.
  8. Finally we do the tibia joints. These are the same as the femur: we try to match the angle in Leg.h with the actual servo angle. In my case, this is 135 degrees. The photo shows the completed calibration.
  9. When completed, exit to the main menu, and save the changes by typing "S".
  10. Foot Position Calibration

  11. Start by going into the Joint calibration menu. Reset all calibration in this mode to zero by typing "R". (You should do this the first time you calibrate, to clear any junk values out of the EEPROM, but you don't need to do it subsequent times.)
  12. If required, we can now adjust the absolute foot positioning. On my version of Stubby, we really only need to adjust the Z offset in this way, but if needed you can adjust X and Y as well. The easiest way to do the Z calibration is to hold Stubby over top of a flat surface, and the slowly lower it until the legs touch, but without putting any pressure on the legs.
  13. If one leg touches first, then raise it. If 5 legs touch but one doesn't, then lower it. You get the idea. Basically, when completed, all 6 legs should be on the same vertical plane. From what I have seen, you shouldn't have to change this calibration more than 1 or 2mm per leg.
  14. When completed, save the changes by going back to the main menu and typing "S".
  15. Magnetometer Calibration

  16. Start by going into the Magnetometer calibration menu.
  17. Place Stubby on a flat surface such as the floor, and type "S". Stubby will turn in place for about a minute; while doing this, you will see a bunch of numbers quickly scrolling by on-screen.
  18. Once finished, the calibration program will present a suggested new calibration value, based on the average of the measurements. You can choose to accept this or not.
  19. If you want to manually adjust the calibration settings, you can do so by typing "M".
  20. By running the "S" automatic calibration again, you can see the new, adjusted values. You can copy these values into a spreadsheet to graph an X,Y scatterplot showing the readings. If all is well, they should be centered around the origin (0,0):
  21. When completed, exit to the main menu, and save the changes by typing "S".






Using the Universal Controller for Calibration



This is a more difficult way of calibrating Stubby. You should only do it if you are unable to connect the robot to a computer.

    Setup

  1. Turn on Stubby. You should see the power light on, but the status light off.
  2. Hit Select on the Universal Controller. You should see the status light flash blue 5 times, and then turn solid red. You are now in "neutral angle calibration" mode.
  3. Using the Universal Controller, when in calibration mode the following buttons will perform the following actions:
    • Select: Toggle between "neutral angle calibration" mode and "foot position calibration" mode. The status light will flash blue 5 times when entering neutral angle mode and will flash purple 5 times when entering foot position mode.
    • Square: Switch between legs. Leg 1 is the front left leg, and legs are numbered counter clockwise from there (so leg 2 is middle left, leg 4 is rear right, and leg 6 is front right, etc). When switching legs, the status light will change color to indicate the leg number: Leg 1 is red, Leg 2 is yellow (well, an ugly red + green), Leg 3 is green, Leg 4 is cyan (green + blue), Leg 5 is blue, Leg 6 is purple (red + blue).
    • Triangle (while holding Circle): reset all values (in the current mode) to 0.
    • Triangle: reset all values (in both modes) to the last saved values.
    • Cross: commit all current values (in both modes).
    • D-Pad right / left: adjust the Coxa angle (neutral angle mode) or X axis offset (foot position mode).
    • D-Pad up / down: adjust the Femur angle (neutral angle mode) or Y axis offset (foot position mode).
    • L1 / L2: adjust the Tibia angle (neutral angle mode) or Z axis offset (foot position mode).
    • Start: exit calibration mode and go back to the initial startup state (power light on, status light off).
  4. Joint Neutral Angle Calibration

  5. It is generally recommended to calibrate all legs in neutral angle mode first, and then use foot position mode as fine-tuning if needed. If neutral angle mode calibration is not done accurately, the math behind the inverse kinematics will not work properly.
  6. Start by resetting all calibration in this mode to zero by holding Circle and pressing Triangle. (You should do this the first time you calibrate, to clear any junk values out of the EEPROM, but you don't need to do it subsequent times.)
  7. Starting with the coxa joints, use the protractor to ensure that each leg is sticking out directly from the body. This means that there should be 120 degrees between one edge of the body and the leg. It helps to close one eye and try to align your line of sight directly above the axle, so that you can see exactly what the angle is.
    The first photo shows an incorrect calibration (the angle is around 135 degrees); the second photo shows correct calibration (about 120 degrees).
  8. Next up is the femur joints. Unlike the coxa, here we attempt to calibrate the servo arm, rather than the desired angle:

    Look in Leg.h to see the FEMUR_NEUTRAL_SERVO_ANGLE. (In my code it is 132 degrees). Try to match this as closely as possible. (When assembling you should try to get it as close as possible; calibration should only account for maybe 10 - 15 degrees at most. Any calibration which is added will reduce the total range of motion which this joint is capable of, since calibration is applied by directly adding to / subtracting from the PWM phase.
    The first photo shows an incorrect calibration; the second photo shows a correct calibration.
  9. Finally we do the tibia joints. These are the same as the femur: we try to match the angle in Leg.h with the actual servo angle. In my case, this is 135 degrees. The photo shows the completed calibration.
  10. When completed, save the changes by hitting the Cross button.
  11. Foot Position Calibration

  12. Switch into foot position mode by hitting Select. The status light will flash purple for 5 times.
  13. Start by resetting all calibration in this mode to zero by holding Circle and pressing Triangle. (You should do this the first time you calibrate, to clear any junk values out of the EEPROM, but you don't need to do it subsequent times.)
  14. If required, we can now adjust the absolute foot positioning. On my version of Stubby, we really only need to adjust the Z offset in this way, but if needed you can adjust X and Y as well. The easiest way to do the Z calibration is to hold Stubby over top of a flat surface, and the slowly lower it until the legs touch, but without putting any pressure on the legs.
  15. If one leg touches first, then raise it. If 5 legs touch but one doesn't, then lower it. You get the idea. Basically, when completed, all 6 legs should be on the same vertical plane. From what I have seen, you shouldn't have to change this calibration more than 1 or 2mm per leg.
  16. When completed, save the changes by hitting the Cross button.
  17. You can now hit Start to go back to startup mode, then Start again to turn the robot on.