To allow for automatic magnetometer calibration, I decided to write a simple python program. It can do all the calibration which the Universal Controller can do (joint angles and foot x/y/z adjustments), as well as calibrate the magnetometer offsets, which the Universal Controller cannot do.

The program is located in the git repository, at path stubby/calibration/calibration.py. To start calibration, run the program, passing the serial port as the command line argument:

python ./calibration/calibration.py /dev/ttyUSB0

When you run the program, you are presented with a main menu of options:

Stubby Calibration: Please selection an option below:
    J) Joint Calibration
    F) X,Y,Z Foot Position Calibration
    M) Magnetometer Calibration
    L) Load all values from EEPROM (revert changes for this session)
    S) Save all values to EEPROM
    Q) Quit (Any unsaved changes will be lost)

Drilling into each of the numbered options will present further sub-menus.

Selected Option: J

Joint calibration allows builders to ensure that each joint (coxa, femur, and tibia) is set to the correct neutral angle, despite tolerances between each servo, mounting horn, etc.  For the Inverse Kinematics engine to work accurately, it is essential that each joint is as close to nominal as possible.

When entering this mode, Stubby should be lifted off the ground by its main body.  Each leg will return to its neutral position (i.e. the position where each servo is sent a 1500us PWM signal).  A protractor can then be used to measure each joint, according to the diagrams available at: http://git.digitalcave.ca/gitweb/?p=projects.git;a=blob_plain;f=projects/stubby/doc/diagrams.pdf

The calibration units for this mode are tens of mirco seconds (us), modifying the PWM signal directly.  For instance, if the drive calculations indicate that a servo should be sent a 1200us PWM signal to achieve the desired angle, and there is a calibration value of 3, the actual signal will be 1230us.

See http://stubby.digitalcave.ca/stubby/calibration.jsp for additional instructions on calibration, including pictures.

Press enter to set the logs to their PWM neutral positions, and to begin calibration.


Please select a leg to modify
	0) Front Left
	1) Middle Left
	2) Rear Left
	3) Rear Right
	4) Middle Right
	5) Front Right
	R) Reset all joint values to 0
	Q) Return to main menu

The joint / foot calibration options are pretty easy; select a leg, then a joint, and then the value (either using + / - keys to increment or decrement, or by typing a value).

For the magnetometer, you have the option of entering a value manually (i.e. if you had obtained it via other experimental methods). The best option for most people, though, is to run the automatic calibration routine. Using this method, Stubby will slowly rotate in place, completing about four full rotations over the course of a minute or so. The raw magnetometer values (plus the adjusted values, using the current offsets) are streamed to the console. When the calibration is finished, the program computes the average for both X and Y, and asks if you want to set this as the new value:

Current offsets: 118, 1473
New (auto calculated) offsets: 143, 1483
Do you want to use these new offsets? (Y/N)

You can use the streamed raw / adjusted values to graph an X,Y scatterplot in your favourite spreadsheet program:

Whenever you are finished any calibration, back out to the main menu and select "Save" to persist the calibration values to EEPROM. These values are then automatically loaded on startup.

This program has been tested on Debian Jessie using python 2.7.8, and on OSX using python 2.6.9, but in theory it should be compatible with most modern python versions and operating systems - I have not used any weird modules or syntax here. The only non-standard dependency is pyserial, which is readily available on all platforms. If anyone tries to run it on Windows, please let me know how it works (whether good, bad, or ugly).

Cheers