# Hard/Soft-Iron (HSI) Library

This library computes the hard & soft iron (HSI) calibration parameters as defined in the 
VN-100/200/300 User Manuals under Register 23.  In addition to raw magnetometer measurements,
the algorithms require the associated angular rate measurements and yaw-pitch-roll estimates.
The HSI library offers two different algorithms, depending on the motion of the device during
calibration: (1) 3D and (2) 2D.  The 3D algorithm requires the device to be rotated about all
axes. The 2D algorithm requires the device to be rotated 360 degrees about the gravity vector
(eg. driving in a circle on a flat & level surface).

FILE ORGANIZATION:
The files are organized as follows:
src - C and header files for both 2D and 3D algorithms
include - header files that must be included in the user's implementation
examples - sample main.c files along with sample data files demonstrating use of the library

CONFIGURATION:
A configuration structure provides the necessary information to perform the desired 
calibration.  The calibration structure can be filled in directly (see ezhsi example), or can
be read from a file (see advhsi example).  The parameters are defined as follows (names match
those used by the advhsi example for reading from a file).

All Calibrations:
	mode			Calibration mode 
					1 - 3D mode
					2 - 2D mode  
					3 - RESERVED 
					4 - 2D mode with no location 
					5 - RESERVED 
	Longitude		Calibration location longitude (decimal degrees)
	Latitude		Calibration location geodetic latitude (decimal degrees)
	nPatches		3D mode: see flagKM for definition.
					2D mode: data selection algorithm keeps a measurement whenever the heading 
							 has changed by 360/nPatches degrees
	RFRij			Reference Frame Rotation (Register 26) that was in effect when data was 
					collected (i=row,j=col)
	SIij			Soft-Iron matrix (Register 23) that was in effect when data was collected 
					(i=row,j=col)
	HIi				Hard-Iron vector (Register 23) that was in effect when data was collected 
					(i=row)

3D Mode Only: (not required for 2D calibration)
	nDataPerPatch	See flagKM for definition.
	flagKM			Sets the keep measurement mode as follows:
						1 - Deprecated. Defines nPatches equal circular patches on the surface
							of a sphere.  Only keeps nDataPerPatch points per patch according 
							to when the magnetic vector passes through the patch.
						2 - Similar to (1) but also defines a second set of patches to improve 
							observability of the alignment data fit.
						3 - Keeps a measurement whenever the attitude has changed by 
							360/nPatches degrees (does not rely on the spherical patch 
							algorithms).

2D Mode Only: (not required for 3D calibration)
	DataRate		Rate at which data is being logged from the sensor (Hz)

Error Codes:
	If the tool will outputs an error code, then it means the solution failed to converge - or
	the solution invalid. A list of error codes is as follows;
		0 		E_NONE 						No Errors found.
		2001 	E_DATA_NOT_ELLIPTICAL 		The collected data was set not elliptical.
		2002 	E_ILL_CONDITIONED 			The algorithm had a bad condition.
		2003 	E_EXCEEDED_MAX_ITERATIONS 	The algorithm exceeded the number of iterations it 
											is allowed.
		2004 	E_BAD_FINAL_INTERATION 		The algorithm’s last iteration changed exceeded 
											threshold.
		2005 	E_INSUFFICIENT_DATA 		Not enough data points were provided.


FIGURES OF MERIT:
The figures of merit (FOM) computed by these algorithms provide useful feedback on the accuracy
of the final solution.  For all FOM, a lower number is better.  Below are descriptions of each
parameter and suggested thresholds for each.  The FOMscore provided by the figure of merit 
function uses these thresholds to report a 0 (Great) to 3 (Poor) score for each FOM.

FOM Descriptions:
	ellipsoidFitResidualsMean		Mean of residuals from ellipsoid data fit (as percent 
									sphere radius)		
	ellipsoidFitResidualsMax		Maximum residuals from ellipsoid data fit (as percent 
									sphere radius)
	ellipsoidFitResidualsStd		Standard deviation of residuals from ellipsoid data fit 
									(as percent sphere radius)
	alignmentFitResidualsMean		Mean of residuals from alignment data fit (as percent 
									sphere radius)		
	alignmentFitResidualsMax		Maximum residuals from alignment data fit (as percent 
									sphere radius)
	alignmentFitResidualsStd		Standard deviation of residuals from alignment data fit 
									(as percent sphere radius)
	ellipsoidCoverage				Error multiplier based on distribution of data for 
									ellipsoid data fit
	alignmentCoverage				Error multiplier based on distribution of data for 
									alignment data fit

FOM Thresholds:
	FOM								Great		Good		Fair		Poor
	ellipsoidFitResidualsMean		<0.01%		<0.05%		<0.20%		>=0.20%
	ellipsoidFitResidualsMax		<1.5%		<3.0%		<6.0%		>=6.0%
	ellipsoidFitResidualsStd		<0.5%		<1.0%		<2.0%		>=2.0%
	alignmentFitResidualsMean		<0.01%		<0.05%		<0.20%		>=0.20%
	alignmentFitResidualsMax		<1.5%		<3.0%		<6.0%		>=6.0%
	alignmentFitResidualsStd		<0.5%		<1.0%		<2.0%		>=2.0%
	ellipsoidCoverage				<0.1		<0.2		<0.5		>=0.5	
	alignmentCoverage				<0.1		<0.2		<0.5		>=0.5
	
EXAMPLES:
Two separate examples are provided:
(1) ezhsi 	Simple implementation with hard-coded configuration and reading from a data file.
			Good starting point to understand basics of implementation.
(2) advhsi	Provides a command-line utility to run a wide range of calibrations including while
			connected to a live sensor.  Demonstrates full capability of library.

Note that these examples merely provide a sample of the possibilities and can be changed as 
desired.  The header and souorce files "vnhsiexampleutil" and include functions used for the
examples only - none of those functions are required to be used to implement the HSI library,
and can be changed as desired.


