motion_fx.h

00001 /**
00002   ******************************************************************************
00003   * @file    motion_fx.h
00004   * @author  MEMS Application Team
00005   * @version V2.0.0
00006   * @date    01-May-2017
00007   * @brief   Header for motion_fx module
00008   ******************************************************************************
00009   * @attention
00010   *
00011   * <h2><center>&copy; COPYRIGHT(c) 2017 STMicroelectronics</center></h2>
00012   *
00013   * Redistribution and use in source and binary forms, with or without modification,
00014   * are permitted provided that the following conditions are met:
00015   *   1. Redistributions of source code must retain the above copyright notice,
00016   *      this list of conditions and the following disclaimer.
00017   *   2. Redistributions in binary form must reproduce the above copyright notice,
00018   *      this list of conditions and the following disclaimer in the documentation
00019   *      and/or other materials provided with the distribution.
00020   *   3. Neither the name of STMicroelectronics nor the names of its contributors
00021   *      may be used to endorse or promote products derived from this software
00022   *      without specific prior written permission.
00023   *
00024   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00025   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00028   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00029   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00030   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00032   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00033   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034   *
00035   ********************************************************************************
00036   */
00037 
00038 /* Define to prevent recursive inclusion -------------------------------------*/
00039 #ifndef _MOTION_FX_H_
00040 #define _MOTION_FX_H_
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /* Includes ------------------------------------------------------------------*/
00047 #include <stdint.h>
00048 
00049 /** @addtogroup MIDDLEWARES
00050   * @{
00051   */
00052 
00053 /** @defgroup MOTION_FX MOTION_FX
00054   * @{
00055   */
00056 
00057 
00058 /** @defgroup MOTION_FX_Exported_Types MOTION_FX_Exported_Types
00059  * @{
00060  */
00061 /* Exported constants --------------------------------------------------------*/
00062 #define MFX_NUM_AXES    3
00063 #define MFX_QNUM_AXES   4
00064 
00065 /* Exported types ------------------------------------------------------------*/
00066 typedef enum
00067 {
00068   MFX_ENGINE_DISABLE = 0,
00069   MFX_ENGINE_ENABLE = 1
00070 } MFX_engine_state_t;
00071 
00072 typedef enum
00073 {
00074   MFX_ENGINE_OUTPUT_NED = 0,
00075   MFX_ENGINE_OUTPUT_ENU = 1
00076 } MFX_engine_output_ref_sys;
00077 
00078 typedef struct
00079 {
00080   float ATime;                              /* merge rate to the accel */
00081   float MTime;                              /* merge rate to the mag */
00082   float FrTime;                             /* merge rate to the accel when external accelerations occours */
00083   unsigned char LMode;                      /* gyro bias learn mode: 1-static learning, 2-dynamic learning */
00084   float gbias_mag_th_sc_6X;                 /* 6 axes scaler for the gyro bias mag threshold nominal */
00085   float gbias_acc_th_sc_6X;                 /* 6 axes scaler for the gyro bias acc threshold nominal */
00086   float gbias_gyro_th_sc_6X;                /* 6 axes scaler for the gyro bias gyro threshold nominal */
00087   float gbias_mag_th_sc_9X;                 /* 9 axes scaler for the gyro bias mag threshold nominal */
00088   float gbias_acc_th_sc_9X;                 /* 9 axes scaler for the gyro bias acc threshold nominal */
00089   float gbias_gyro_th_sc_9X;                /* 9 axes scaler for the gyro bias gyro threshold nominal */
00090   unsigned char modx;                       /* setting to indicate the decimation, set to 1 in smartphone/tablet, set to >=1 in embedded solutions */
00091   char acc_orientation[MFX_QNUM_AXES];      /* accelerometer data orientation */
00092   char gyro_orientation[MFX_QNUM_AXES];     /* gyroscope data orientation */
00093   char mag_orientation[MFX_QNUM_AXES];      /* magnetometer data orientation */
00094   MFX_engine_output_ref_sys output_type;    /* 0: NED, 1: ENU */
00095   int start_automatic_gbias_calculation;
00096 } MFX_knobs_t;
00097 
00098 typedef struct
00099 {
00100   float mag[MFX_NUM_AXES];                  /* Calibrated mag [uT]/50 */
00101   float acc[MFX_NUM_AXES];                  /* Acceleration in [g] */
00102   float gyro[MFX_NUM_AXES];                 /* Angular rate [dps] */
00103 } MFX_input_t;
00104 
00105 typedef struct
00106 {
00107   float rotation_9X[MFX_NUM_AXES];              /* 9 axes yaw, pitch and roll */
00108   float quaternion_9X[MFX_QNUM_AXES];           /* 9 axes quaternion */
00109   float gravity_9X[MFX_NUM_AXES];               /* 9 axes device frame gravity */
00110   float linear_acceleration_9X[MFX_NUM_AXES];   /* 9 axes device frame linear acceleration */
00111   float heading_9X;             /* 9 axes heading */
00112   float rotation_6X[MFX_NUM_AXES];              /* 6 axes yaw, pitch and roll */
00113   float quaternion_6X[MFX_QNUM_AXES];           /* 6 axes quaternion */
00114   float gravity_6X[MFX_NUM_AXES];               /* 6 axes device frame gravity */
00115   float linear_acceleration_6X[MFX_NUM_AXES];   /* 6 axes device frame linear acceleration */
00116   float heading_6X;             /* 6 axes heading */
00117 } MFX_output_t;
00118 
00119 typedef enum
00120 {
00121   MFX_MAGCALUNKNOWN = 0,
00122   MFX_MAGCALPOOR,
00123   MFX_MAGCALOK,
00124   MFX_MAGCALGOOD
00125 } MFX_MagCal_quality_t;
00126 
00127 typedef struct {
00128   float mag[MFX_NUM_AXES];                  /* Uncalibrated mag [uT]/50 */
00129   int time_stamp;                           /* Timestamp [ms] */
00130 } MFX_MagCal_input_t;
00131 
00132 typedef struct {
00133   float hi_bias[3];                         /* Hard iron offset array [uT]/50 */
00134   MFX_MagCal_quality_t cal_quality;         /* Calibration quality factor */
00135 } MFX_MagCal_output_t;
00136 
00137 /**
00138   * @}
00139   */
00140 
00141 /* Exported variables --------------------------------------------------------*/
00142 /* Exported macro ------------------------------------------------------------*/
00143 
00144 /** @defgroup MOTION_FX_Exported_Functions MOTION_FX_Exported_Functions
00145  * @{
00146  */
00147 
00148 /* Exported functions ------------------------------------------------------- */
00149 
00150 /**
00151  * @brief  Initialize the MotionFX engine
00152  * @param  none
00153  * @retval none
00154  */
00155 void MotionFX_initialize(void);
00156 
00157 /**
00158  * @brief  Set the internal knobs
00159  * @param  knobs knobs structure
00160  * @retval None
00161  */
00162 void MotionFX_setKnobs(MFX_knobs_t *knobs);
00163 
00164 /**
00165  * @brief  Get the current internal knobs
00166  * @param  knobs knobs structure
00167  * @retval None
00168  */
00169 void MotionFX_getKnobs(MFX_knobs_t *knobs);
00170 
00171 /**
00172  * @brief  Get the status of the 6 axes library
00173  * @retval 1 if enabled, 0 if disabled
00174  */
00175 MFX_engine_state_t MotionFX_getStatus_6X(void);
00176 
00177 /**
00178  * @brief  Get the status of the 9 axes library
00179  * @retval 1 if enabled, 0 if disabled
00180  */
00181 MFX_engine_state_t MotionFX_getStatus_9X(void);
00182 
00183 /**
00184  * @brief  Enable or disable the 6 axes function (ACC + GYRO)
00185  * @param  enable 1 to enable, 0 to disable
00186  * @retval none
00187  */
00188 void MotionFX_enable_6X(MFX_engine_state_t enable);
00189 
00190 /**
00191  * @brief  Enable or disable the 9 axes function (ACC + GYRO + MAG)
00192  * @param  enable 1 to enable, 0 to disable
00193  * @retval none
00194  */
00195 void MotionFX_enable_9X(MFX_engine_state_t enable);
00196 
00197 /**
00198  * @brief  Set the initial gbias
00199  * @param  gbias pointer to a float array containing the 3 gbias values
00200  * @retval none
00201  */
00202 void MotionFX_setGbias(float *gbias);
00203 
00204 /**
00205  * @brief  Get the initial gbias
00206  * @param  pointer to a float array containing the 3 gbias values
00207  * @retval none
00208  */
00209 void MotionFX_getGbias(float *gbias);
00210 
00211 /**
00212  * @brief  Run the Kalman filter update
00213  * @param  data_out pointer to the MFX_output_t structure
00214  * @param  data_in pointer to the MFX_input_t structure
00215  * @param  eml_deltatime delta time between two propagate calls [sec]
00216  * @param  eml_q_update set to NULL
00217  * @retval none
00218  */
00219 void MotionFX_update(MFX_output_t *data_out, MFX_input_t *data_in, float eml_deltatime, float *eml_q_update);
00220 
00221 /**
00222  * @brief  Run the Kalman filter propagate
00223  * @param  data_out pointer to the MFX_output_t structure
00224  * @param  data_in pointer to the MFX_input_t structure
00225  * @param  eml_deltatime delta time between two propagate calls [sec]
00226  * @retval none
00227  */
00228 void MotionFX_propagate(MFX_output_t *data_out, MFX_input_t *data_in, float eml_deltatime);
00229 
00230 /**
00231  * @brief  Initialize the compass calibration library
00232  * @param  sampletime  period in milliseconds [ms] between the update function call
00233  * @param  enable  enable (1) or disable (0) library
00234  * @retval none
00235  */
00236 void MotionFX_MagCal_init(int sampletime, unsigned short int enable);
00237 
00238 /**
00239  * @brief  Run magnetic calibration algorithm
00240  * @param  data_in  structure containing input data
00241  * @retval none
00242  */
00243 void MotionFX_MagCal_run(MFX_MagCal_input_t *data_in);
00244 
00245 /**
00246  * @brief  Get magnetic calibration parameters
00247  * @param  data_out  structure containing output data
00248  * @retval none
00249  */
00250 void MotionFX_MagCal_getParams(MFX_MagCal_output_t *data_out);
00251 
00252 /**
00253  * @brief  Get the library version
00254  * @param  version pointer to an array of 35 char
00255  * @retval Number of characters in the version string
00256  */
00257 uint8_t MotionFX_GetLibVersion(char *version);
00258 
00259 /**
00260   * @}
00261   */
00262 
00263 /**
00264   * @}
00265   */
00266 
00267 /**
00268   * @}
00269   */
00270 
00271 #ifdef __cplusplus
00272 }
00273 #endif
00274 
00275 #endif /* _MOTION_FX_H_ */
00276 
00277 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/