sbgECom Library  4.0.1987-stable
C library to interface SBG Systems IMU/AHRS/INS
Data Structures | Macros | Typedefs | Enumerations | Functions
sbgEComCmdMag.h File Reference
Commands

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

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

Go to the source code of this file.

Data Structures

struct  _SbgEComMagRejectionConf
 
struct  _SbgEComMagCalibResults
 

Macros

#define SBG_ECOM_MAG_CALIB_NOT_ENOUGH_POINTS   (0x0001u)
 
#define SBG_ECOM_MAG_CALIB_TOO_MUCH_DISTORTIONS   (0x0002u)
 
#define SBG_ECOM_MAG_CALIB_X_MOTION_ISSUE   (0x0004u)
 
#define SBG_ECOM_MAG_CALIB_Y_MOTION_ISSUE   (0x0008u)
 
#define SBG_ECOM_MAG_CALIB_Z_MOTION_ISSUE   (0x0010u)
 
#define SBG_ECOM_MAG_CALIB_ALIGNMENT_ISSUE   (0x0020u)
 

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_NORMAL = 201 ,
  SBG_ECOM_MAG_MODEL_NOISY_MAG_TOLERANT = 202
}
 

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 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) 2022, 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)

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   (0x0002u)

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   (0x0004u)

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   (0x0008u)

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   (0x0010u)

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   (0x0020u)

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

Typedef Documentation

◆ SbgEComMagCalibMode

typedef enum _SbgEComMagCalibMode SbgEComMagCalibMode

Define if the on-board magnetic calibration should acquire points for a 3D or 2D calibration.

◆ SbgEComMagCalibBandwidth

typedef enum _SbgEComMagCalibBandwidth SbgEComMagCalibBandwidth

Used to select the expected dynamics during the magnetic calibration.

◆ 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

This enum defines the different magnetometer model IDs available in standard

◆ 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

Define if the on-board magnetic calibration should acquire points for a 3D or 2D calibration.

Enumerator
SBG_ECOM_MAG_CALIB_MODE_2D 

Tell the device that the magnetic calibration will be performed with limited motions. This calibration mode is only designed to be used when roll and pitch motions are less than ± 5°. To work correctly, the device should be rotated through at least a full circle.

SBG_ECOM_MAG_CALIB_MODE_3D 

Tell the device to start a full 3D magnetic calibration procedure. The 3D magnetic calibration offers the best accuracy but needs at least motion of ± 30° on the roll and pitch angles.

◆ _SbgEComMagCalibBandwidth

enum _SbgEComMagCalibBandwidth

Used to select the expected dynamics during the magnetic calibration.

Enumerator
SBG_ECOM_MAG_CALIB_LOW_BW 

Tell the device that low dynamics will be observed during the magnetic calibration process.

SBG_ECOM_MAG_CALIB_MEDIUM_BW 

Tell the device that normal dynamics will be observed during the magnetic calibration process.

SBG_ECOM_MAG_CALIB_HIGH_BW 

Tell the device that high dynamics will be observed during the magnetic calibration process.

◆ _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

This enum defines the different magnetometer model IDs available in standard

Enumerator
SBG_ECOM_MAG_MODEL_NORMAL 

Should be used in most applications

SBG_ECOM_MAG_MODEL_NOISY_MAG_TOLERANT 

Should be used in disturbed magnetic environment

Function Documentation

◆ sbgEComCmdMagSetModelId()

SbgErrorCode sbgEComCmdMagSetModelId ( SbgEComHandle *  pHandle,
SbgEComMagModelsStdId  modelId 
)

Set magnetometer error model id.

Parameters
[in]pHandleA valid sbgECom handle
[in]modelIdMagnetometer 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]pHandleA valid sbgECom handle
[out]pModelIdRetrieved 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]pHandleA valid sbgECom handle.
[out]pRejectConfPointer 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]pHandleA valid sbgECom handle.
[in]pRejectConfPointer 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 
)

Send a command that set the magnetometers calibration parameters.

Parameters
[in]pHandleA valid sbgECom handle.
[in]pOffsetMagnetometers calibration offset vector.
[in]pMatrixMagnetometers calibration 3x3 matrix.
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]pHandleA valid sbgECom handle.
[in]modeDefine which magnetic calibration type to perform. It could be 3D or 2D.
[in]bandwidthTell the device that we should have low, medium or high dynamics during the magnetic calibration process.
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]pHandleA valid sbgECom handle.
[out]pCalibResultsPointer 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.