Magnetometer aiding module configuration & on-board magnetic calibration commands. More...

#include <sbgCommon.h>
#include <sbgECom.h>
#include "sbgEComCmdCommon.h"

Data Structures
struct	_SbgEComMagRejectionConf

struct	_SbgEComMagCalibResults

Macros
#define	SBG_ECOM_MAG_CALIB_NOT_ENOUGH_POINTS (0x0001u << 0)

#define	SBG_ECOM_MAG_CALIB_TOO_MUCH_DISTORTIONS (0x0001u << 1)

#define	SBG_ECOM_MAG_CALIB_X_MOTION_ISSUE (0x0001u << 2)

#define	SBG_ECOM_MAG_CALIB_Y_MOTION_ISSUE (0x0001u << 3)

#define	SBG_ECOM_MAG_CALIB_Z_MOTION_ISSUE (0x0001u << 4)

#define	SBG_ECOM_MAG_CALIB_ALIGNMENT_ISSUE (0x0001u << 5)

Typedefs
typedef enum _SbgEComMagCalibMode	SbgEComMagCalibMode

typedef enum _SbgEComMagCalibBandwidth	SbgEComMagCalibBandwidth

typedef enum _SbgEComMagCalibQuality	SbgEComMagCalibQuality

typedef enum _SbgEComMagCalibConfidence	SbgEComMagCalibConfidence

typedef enum _SbgEComMagModelsStdIds	SbgEComMagModelsStdId

typedef struct _SbgEComMagRejectionConf	SbgEComMagRejectionConf

typedef struct _SbgEComMagCalibResults	SbgEComMagCalibResults

Enumerations
enum	_SbgEComMagCalibMode { SBG_ECOM_MAG_CALIB_MODE_2D = 1 , SBG_ECOM_MAG_CALIB_MODE_3D = 2 }

enum	_SbgEComMagCalibBandwidth { SBG_ECOM_MAG_CALIB_LOW_BW = 0 , SBG_ECOM_MAG_CALIB_MEDIUM_BW = 1 , SBG_ECOM_MAG_CALIB_HIGH_BW = 2 }

enum	_SbgEComMagCalibQuality { SBG_ECOM_MAG_CALIB_QUAL_OPTIMAL = 0 , SBG_ECOM_MAG_CALIB_QUAL_GOOD = 1 , SBG_ECOM_MAG_CALIB_QUAL_POOR = 2 , SBG_ECOM_MAG_CALIB_QUAL_INVALID = 3 }

enum	_SbgEComMagCalibConfidence { SBG_ECOM_MAG_CALIB_TRUST_HIGH = 0 , SBG_ECOM_MAG_CALIB_TRUST_MEDIUM = 1 , SBG_ECOM_MAG_CALIB_TRUST_LOW = 2 }

enum	_SbgEComMagModelsStdIds { SBG_ECOM_MAG_MODEL_INTERNAL_NORMAL = 201 , SBG_ECOM_MAG_MODEL_INTERNAL_RESERVED = 202 , SBG_ECOM_MAG_MODEL_ECOM_NORMAL = 203 }

Functions
SbgErrorCode	sbgEComCmdMagSetModelId (SbgEComHandle *pHandle, SbgEComMagModelsStdId modelId)

SbgErrorCode	sbgEComCmdMagGetModelId (SbgEComHandle pHandle, SbgEComMagModelsStdId pModelId)

SbgErrorCode	sbgEComCmdMagGetRejection (SbgEComHandle pHandle, SbgEComMagRejectionConf pRejectConf)

SbgErrorCode	sbgEComCmdMagSetRejection (SbgEComHandle pHandle, const SbgEComMagRejectionConf pRejectConf)

SbgErrorCode	sbgEComCmdMagSetCalibData (SbgEComHandle pHandle, const float pOffset, const float *pMatrix)

SbgErrorCode	sbgEComCmdMagSetCalibData2 (SbgEComHandle pHandle, const float pOffset, const float *pMatrix, SbgEComMagCalibMode mode)

SbgErrorCode	sbgEComCmdMagStartCalib (SbgEComHandle *pHandle, SbgEComMagCalibMode mode, SbgEComMagCalibBandwidth bandwidth)

SbgErrorCode	sbgEComCmdMagComputeCalib (SbgEComHandle pHandle, SbgEComMagCalibResults pCalibResults)

Detailed Description

Magnetometer aiding module configuration & on-board magnetic calibration commands.

Author: SBG Systems

Date: 11 June 2014

Copyright: Copyright (C) 2007-2024, SBG Systems SAS. All rights reserved.

License

The MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

◆ SBG_ECOM_MAG_CALIB_NOT_ENOUGH_POINTS

#define SBG_ECOM_MAG_CALIB_NOT_ENOUGH_POINTS (0x0001u << 0)

Status bit masks used to report advanced information on the on-board magnetic calibration. Not enough valid magnetic points have been acquired.

◆ SBG_ECOM_MAG_CALIB_TOO_MUCH_DISTORTIONS

#define SBG_ECOM_MAG_CALIB_TOO_MUCH_DISTORTIONS (0x0001u << 1)

Unable to compute a magnetic calibration due to magnetic interferences or incorrect data set distribution.

◆ SBG_ECOM_MAG_CALIB_X_MOTION_ISSUE

#define SBG_ECOM_MAG_CALIB_X_MOTION_ISSUE (0x0001u << 2)

For a 3D calibration: not enough motion on X axis. For a 2D calibration; too much motion on X axis.

◆ SBG_ECOM_MAG_CALIB_Y_MOTION_ISSUE

#define SBG_ECOM_MAG_CALIB_Y_MOTION_ISSUE (0x0001u << 3)

For a 3D calibration: not enough motion on Y axis. For a 2D calibration; too much motion on Y axis.

◆ SBG_ECOM_MAG_CALIB_Z_MOTION_ISSUE

#define SBG_ECOM_MAG_CALIB_Z_MOTION_ISSUE (0x0001u << 4)

For a 3D or 2D calibration: not enough motion on Z axis.

◆ SBG_ECOM_MAG_CALIB_ALIGNMENT_ISSUE

#define SBG_ECOM_MAG_CALIB_ALIGNMENT_ISSUE (0x0001u << 5)

For a 3D calibration: the alignment between the magnetometers and the inertial frame seems to be invalid.

Typedef Documentation

◆ SbgEComMagCalibMode

typedef enum _SbgEComMagCalibMode SbgEComMagCalibMode

Defines the algorithm mode used for compensating magnetometers against soft and hard iron effects.

The 2D calibration mode can only be used by the INS filter when roll and pitch are minimal (± 5°) as it assumes a near-horizontal orientation of the sensor.

The 3D calibration mode, in contrast, provides a valid magnetic field compensation for any sensor orientation, thereby improving the overall quality and reliability of the magnetic heading data.

◆ SbgEComMagCalibBandwidth

typedef enum _SbgEComMagCalibBandwidth SbgEComMagCalibBandwidth

Define the expected motions bandwidth during the magnetic field compensation acquisition.

Note: This parameter is deprecated and has no effect for ELLIPSE firmware v3.0 and above.
For ELLIPSE firmware v2.x and before, please use SBG_ECOM_MAG_CALIB_HIGH_BW.

◆ SbgEComMagCalibQuality

typedef enum _SbgEComMagCalibQuality SbgEComMagCalibQuality

General quality indicator of an on-board magnetic calibration.

◆ SbgEComMagCalibConfidence

typedef enum _SbgEComMagCalibConfidence SbgEComMagCalibConfidence

Confidence indicator on results of an on-bard magnetic calibration.

◆ SbgEComMagModelsStdId

typedef enum _SbgEComMagModelsStdIds SbgEComMagModelsStdId

Defines the magnetometers aiding error model and protocol configuration.

◆ SbgEComMagRejectionConf

typedef struct _SbgEComMagRejectionConf SbgEComMagRejectionConf

Holds all necessary information for Magnetometer module data rejection.

◆ SbgEComMagCalibResults

typedef struct _SbgEComMagCalibResults SbgEComMagCalibResults

Helper structure to retrieve on-board magnetic calibration results.

Enumeration Type Documentation

◆ _SbgEComMagCalibMode

enum _SbgEComMagCalibMode

Defines the algorithm mode used for compensating magnetometers against soft and hard iron effects.

The 2D calibration mode can only be used by the INS filter when roll and pitch are minimal (± 5°) as it assumes a near-horizontal orientation of the sensor.

The 3D calibration mode, in contrast, provides a valid magnetic field compensation for any sensor orientation, thereby improving the overall quality and reliability of the magnetic heading data.

Enumerator
SBG_ECOM_MAG_CALIB_MODE_2D	Calibration using 2D mode, requiring at least a full 360° and motions less than 5°
SBG_ECOM_MAG_CALIB_MODE_3D	Calibration using 3D mode, accurate in all orientations but needs motions greater than ± 30°

◆ _SbgEComMagCalibBandwidth

enum _SbgEComMagCalibBandwidth

Define the expected motions bandwidth during the magnetic field compensation acquisition.

Note: This parameter is deprecated and has no effect for ELLIPSE firmware v3.0 and above.
For ELLIPSE firmware v2.x and before, please use SBG_ECOM_MAG_CALIB_HIGH_BW.

Enumerator
SBG_ECOM_MAG_CALIB_LOW_BW	Not used anymore.
SBG_ECOM_MAG_CALIB_MEDIUM_BW	Not used anymore.
SBG_ECOM_MAG_CALIB_HIGH_BW	Not used anymore.

◆ _SbgEComMagCalibQuality

enum _SbgEComMagCalibQuality

General quality indicator of an on-board magnetic calibration.

Enumerator
SBG_ECOM_MAG_CALIB_QUAL_OPTIMAL	All acquired points fit very well on a unit sphere after the calibration.
SBG_ECOM_MAG_CALIB_QUAL_GOOD	Small deviations of the magnetic field norm have been detected. The magnetic calibration should although provide accurate heading.
SBG_ECOM_MAG_CALIB_QUAL_POOR	Large deviations of the magnetic field norm have been detected. It may come from external magnetic distortions during the calibration.
SBG_ECOM_MAG_CALIB_QUAL_INVALID	No valid magnetic calibration has been computed. It could comes from too much magnetic disturbances, insufficient or invalid motions.

◆ _SbgEComMagCalibConfidence

enum _SbgEComMagCalibConfidence

Confidence indicator on results of an on-bard magnetic calibration.

Enumerator
SBG_ECOM_MAG_CALIB_TRUST_HIGH	Reported quality indicator can be trusted as enough remarkable magnetic field points have been acquired.
SBG_ECOM_MAG_CALIB_TRUST_MEDIUM	Few remarkable magnetic field points have been used to compute the magnetic calibration leading to a medium confidence in reported quality indicators.
SBG_ECOM_MAG_CALIB_TRUST_LOW	Even if the quality indicator could report an excellent calibration, The data set used to compute the magnetic calibration was not meaningful enough to compute meaningful quality indicators. This calibration should be used carefully.

◆ _SbgEComMagModelsStdIds

enum _SbgEComMagModelsStdIds

Defines the magnetometers aiding error model and protocol configuration.

Enumerator
SBG_ECOM_MAG_MODEL_INTERNAL_NORMAL	Internal magnetometer - implements world leading magnetic rejection and interference mitigation solutions.
SBG_ECOM_MAG_MODEL_INTERNAL_RESERVED	Internal magnetometer - only used for backward compatibility with ELLIPSE firmware v2.x
SBG_ECOM_MAG_MODEL_ECOM_NORMAL	External magnetometer - sbgECom protocol, implements world leading magnetic rejection and interference mitigation solutions.

Function Documentation

◆ sbgEComCmdMagSetModelId()

SbgErrorCode sbgEComCmdMagSetModelId	(	SbgEComHandle *	pHandle,
		SbgEComMagModelsStdId	modelId )

Set magnetometer error model id.

Parameters

[in]	pHandle	A valid sbgECom handle
[in]	modelId	Magnetometer model id to set

Returns: SBG_NO_ERROR if the command has been executed successfully

◆ sbgEComCmdMagGetModelId()

SbgErrorCode sbgEComCmdMagGetModelId	(	SbgEComHandle *	pHandle,
		SbgEComMagModelsStdId *	pModelId )

Retrieve magnetometer error model id

Parameters

[in]	pHandle	A valid sbgECom handle
[out]	pModelId	Retrieved magnetometer model id

Returns: SBG_NO_ERROR if the command has been executed successfully

◆ sbgEComCmdMagGetRejection()

SbgErrorCode sbgEComCmdMagGetRejection	(	SbgEComHandle *	pHandle,
		SbgEComMagRejectionConf *	pRejectConf )

Retrieve the rejection configuration of the magnetometer module.

Parameters

[in]	pHandle	A valid sbgECom handle.
[out]	pRejectConf	Pointer to a SbgEComMagRejectionConf struct to hold rejection configuration of the magnetometer module.

Returns: SBG_NO_ERROR if the command has been executed successfully.

◆ sbgEComCmdMagSetRejection()

SbgErrorCode sbgEComCmdMagSetRejection	(	SbgEComHandle *	pHandle,
		const SbgEComMagRejectionConf *	pRejectConf )

Set the rejection configuration of the magnetometer module.

Parameters

[in]	pHandle	A valid sbgECom handle.
[in]	pRejectConf	Pointer to a SbgEComMagRejectionConf struct holding rejection configuration for the magnetometer module.

Returns: SBG_NO_ERROR if the command has been executed successfully.

◆ sbgEComCmdMagSetCalibData()

SbgErrorCode sbgEComCmdMagSetCalibData	(	SbgEComHandle *	pHandle,
		const float *	pOffset,
		const float *	pMatrix )

Set the magnetometers soft and hard iron compensation parameters (Firmware v2.x and earlier).

Note: : This command should ONLY be used for ELLIPSE firmware v2 and below.
Please use sbgEComCmdMagSetCalibData2 for ELLIPSE firmware v3 and after.

Parameters

[in]	pHandle	A valid sbgECom handle.
[in]	pOffset	Magnetometers calibration offset vector (array of 3 floats).
[in]	pMatrix	Magnetometers calibration 3x3 matrix (array of 9 floats).

Returns: SBG_NO_ERROR if the command has been executed successfully.

◆ sbgEComCmdMagSetCalibData2()

SbgErrorCode sbgEComCmdMagSetCalibData2	(	SbgEComHandle *	pHandle,
		const float *	pOffset,
		const float *	pMatrix,
		SbgEComMagCalibMode	mode )

Set the magnetometers soft and hard iron compensation parameters (Firmware v3.x and later).

With the introduction of ELLIPSE firmware version 3, the soft/hard iron compensation algorithm mode information is provided to refine magnetometer aiding within the Inertial Navigation System (INS) filter.

Note: : Firmware versions 2 and earlier do not support this feature and 'sbgEComCmdMagSetCalibData' method should be used instead.

Parameters

[in]	pHandle	A valid sbgECom handle.
[in]	pOffset	Magnetometers calibration offset vector (array of 3 floats).
[in]	pMatrix	Magnetometers calibration 3x3 matrix (array of 9 floats).
[in]	mode	Defines if the magnetic calibration is a 2D or 3D one.

Returns: SBG_NO_ERROR if the command has been executed successfully.

◆ sbgEComCmdMagStartCalib()

SbgErrorCode sbgEComCmdMagStartCalib	(	SbgEComHandle *	pHandle,
		SbgEComMagCalibMode	mode,
		SbgEComMagCalibBandwidth	bandwidth )

Start the magnetic calibration process.

As soon as this command is sent, the device will start logging magnetic field data internally. This set of data will be used later by the magnetic calibration algorithms to map the surrounding magnetic field.

Parameters

[in]	pHandle	A valid sbgECom handle.
[in]	mode	Define which magnetic calibration type to perform. It could be 3D or 2D.
[in]	bandwidth	Not used anymore for ELLIPSE firmware v3.0, this value has no effect.

Returns: SBG_NO_ERROR if the command has been executed successfully.

◆ sbgEComCmdMagComputeCalib()

SbgErrorCode sbgEComCmdMagComputeCalib	(	SbgEComHandle *	pHandle,
		SbgEComMagCalibResults *	pCalibResults )

This command computes a magnetic calibration solution based on the magnetic field logged since the last call to the command SBG_ECOM_CMD_START_MAG_CALIB (15).

As soon as the computations are done, the device will answer with quality indicators, status flags and if possible a valid magnetic calibration matrix and offset.

Parameters

[in]	pHandle	A valid sbgECom handle.
[out]	pCalibResults	Pointer on a SbgEComMagCalibResults structure that can hold on-board magnetic calibration results and status.

Returns: SBG_NO_ERROR if the command has been executed successfully.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SBG_ECOM_MAG_CALIB_NOT_ENOUGH_POINTS

◆ SBG_ECOM_MAG_CALIB_TOO_MUCH_DISTORTIONS

◆ SBG_ECOM_MAG_CALIB_X_MOTION_ISSUE

◆ SBG_ECOM_MAG_CALIB_Y_MOTION_ISSUE

◆ SBG_ECOM_MAG_CALIB_Z_MOTION_ISSUE

◆ SBG_ECOM_MAG_CALIB_ALIGNMENT_ISSUE

Typedef Documentation

◆ SbgEComMagCalibMode

◆ SbgEComMagCalibBandwidth

◆ SbgEComMagCalibQuality

◆ SbgEComMagCalibConfidence

◆ SbgEComMagModelsStdId

◆ SbgEComMagRejectionConf

◆ SbgEComMagCalibResults

Enumeration Type Documentation

◆ _SbgEComMagCalibMode

◆ _SbgEComMagCalibBandwidth

◆ _SbgEComMagCalibQuality

◆ _SbgEComMagCalibConfidence

◆ _SbgEComMagModelsStdIds

Function Documentation

◆ sbgEComCmdMagSetModelId()

◆ sbgEComCmdMagGetModelId()

◆ sbgEComCmdMagGetRejection()

◆ sbgEComCmdMagSetRejection()

◆ sbgEComCmdMagSetCalibData()

◆ sbgEComCmdMagSetCalibData2()

◆ sbgEComCmdMagStartCalib()

◆ sbgEComCmdMagComputeCalib()