# 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.