FusionAhrs.h

00001 /**
00002  * @file FusionAhrs.h
00003  * @author Seb Madgwick
00004  * @brief The AHRS sensor fusion algorithm to combines gyroscope, accelerometer,
00005  * and magnetometer measurements into a single measurement of orientation
00006  * relative to the Earth (NWU convention).
00007  *
00008  * The algorithm behaviour is governed by a gain.  A low gain will decrease the
00009  * influence of the accelerometer and magnetometer so that the algorithm will
00010  * better reject disturbances causes by translational motion and temporary
00011  * magnetic distortions.  However, a low gain will also increase the risk of
00012  * drift due to gyroscope calibration errors.  A typical gain value suitable for
00013  * most applications is 0.5.
00014  *
00015  * The algorithm allows the application to define a minimum and maximum valid
00016  * magnetic field magnitude.  The algorithm will ignore magnetic measurements
00017  * that fall outside of this range.  This allows the algorithm to reject
00018  * magnetic measurements that do not represent the direction of magnetic North.
00019  * The typical magnitude of the Earth's magnetic field is between 20 uT and
00020  * 70 uT.
00021  *
00022  * The algorithm can be used without a magnetometer.  Measurements of
00023  * orientation obtained using only gyroscope and accelerometer measurements
00024  * can be expected to drift in the yaw component of orientation only.  The
00025  * application can reset the drift in yaw by setting the yaw to a specified
00026  * angle at any time.
00027  *
00028  * The algorithm provides the measurement of orientation as a quaternion.  The
00029  * library includes functions for converting this quaternion to a rotation
00030  * matrix and Euler angles.
00031  *
00032  * The algorithm also provides a measurement of linear acceleration and Earth
00033  * acceleration.  Linear acceleration is equal to the accelerometer  measurement
00034  * with the 1 g of gravity removed.  Earth acceleration is a measurement of
00035  * linear acceleration in the Earth coordinate frame.
00036  */
00037 
00038 #ifndef FUSION_AHRS_H
00039 #define FUSION_AHRS_H
00040 
00041 //------------------------------------------------------------------------------
00042 // Includes
00043 
00044 #include "FusionTypes.h"
00045 #include <stdbool.h>
00046 
00047 //------------------------------------------------------------------------------
00048 // Definitions
00049 
00050 /**
00051  * @brief AHRS algorithm structure.  Structure members are used internally and
00052  * should not be used by the user application.
00053  */
00054 typedef struct {
00055     float gain;
00056     float minimumMagneticFieldSquared;
00057     float maximumMagneticFieldSquared;
00058     FusionQuaternion quaternion; // describes the Earth relative to the sensor
00059     FusionVector3 linearAcceleration;
00060     float rampedGain;
00061     bool zeroYawPending;
00062 } FusionAhrs;
00063 
00064 //------------------------------------------------------------------------------
00065 // Function prototypes
00066 
00067 void FusionAhrsInitialise(FusionAhrs * const fusionAhrs, const float gain);
00068 void FusionAhrsSetGain(FusionAhrs * const fusionAhrs, const float gain);
00069 void FusionAhrsSetMagneticField(FusionAhrs * const fusionAhrs, const float minimumMagneticField, const float maximumMagneticField);
00070 void FusionAhrsUpdate(FusionAhrs * const fusionAhrs, const FusionVector3 gyroscope, const FusionVector3 accelerometer, const FusionVector3 magnetometer, const float samplePeriod);
00071 void FusionAhrsUpdateWithoutMagnetometer(FusionAhrs * const fusionAhrs, const FusionVector3 gyroscope, const FusionVector3 accelerometer, const float samplePeriod);
00072 FusionQuaternion FusionAhrsGetQuaternion(const FusionAhrs * const fusionAhrs);
00073 FusionVector3 FusionAhrsGetLinearAcceleration(const FusionAhrs * const fusionAhrs);
00074 FusionVector3 FusionAhrsGetEarthAcceleration(const FusionAhrs * const fusionAhrs);
00075 void FusionAhrsReinitialise(FusionAhrs * const fusionAhrs);
00076 bool FusionAhrsIsInitialising(const FusionAhrs * const fusionAhrs);
00077 void FusionAhrsSetYaw(FusionAhrs * const fusionAhrs, const float yaw);
00078 
00079 #endif
00080 
00081 //------------------------------------------------------------------------------
00082 // End of file