HMC5883L.h

00001 /*
00002  * @file HMC5883L.h
00003  * @author Oskar Lopez de Gamboa
00004  *
00005  * @section LICENSE
00006  *
00007  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00008  * and associated documentation files (the "Software"), to deal in the Software without restriction,
00009  * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00010  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00011  * furnished to do so, subject to the following conditions:
00012  *
00013  * The above copyright notice and this permission notice shall be included in all copies or
00014  * substantial portions of the Software.
00015  *
00016  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00017  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00018  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00019  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00020  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00021  *
00022  * @section DESCRIPTION
00023  *
00024  * HMC5883L 3-Axis Digital Compas IC
00025  * The library done by Tyler Weaver with:
00026  *
00027  *  *Corrected the XZY order instead of the previous XYZ to match the datasheet.
00028  *  *Added Declination compensation by a define
00029  * 
00030  *
00031  */
00032 
00033 #ifndef HMC5883L_H
00034 #define HMC5883L_H
00035 
00036 #include "mbed.h"
00037 
00038 /*
00039 * Defines
00040 */
00041 
00042 //-----------
00043 // Registers
00044 //-----------
00045 #define CONFIG_A_REG    0x00
00046 #define CONFIG_B_REG    0x01
00047 #define MODE_REG        0x02
00048 #define OUTPUT_REG      0x03
00049 #define STATUS_REG      0x09
00050 
00051 // configuration register a
00052 #define AVG1_SAMPLES    0x00
00053 #define AVG2_SAMPLES    0x20
00054 #define AVG4_SAMPLES    0x80
00055 #define AVG8_SAMPLES    0xC0
00056 
00057 #define OUTPUT_RATE_0_75    0x00
00058 #define OUTPUT_RATE_1_5     0x04
00059 #define OUTPUT_RATE_3       0x08
00060 #define OUTPUT_RATE_7_5     0x0C
00061 #define OUTPUT_RATE_15      0x10
00062 #define OUTPUT_RATE_30      0x14
00063 #define OUTPUT_RATE_75      0x18
00064 
00065 #define NORMAL_MEASUREMENT  0x00
00066 #define POSITIVE_BIAS       0x01
00067 #define NEGATIVE_BIAS       0x02
00068 
00069 // mode register
00070 #define CONTINUOUS_MODE     0x00
00071 #define SINGLE_MODE         0x01
00072 #define IDLE_MODE           0x02
00073 
00074 // status register
00075 #define STATUS_LOCK         0x02
00076 #define STATUS_READY        0x01
00077 
00078 // Utility
00079 #ifndef M_PI
00080 #define M_PI 3.1415926535897932384626433832795
00081 #endif
00082 
00083 #define PI2         (2*M_PI)
00084 #define RAD_TO_DEG  (180.0/M_PI)
00085 #define DEG_TO_RAD  (M_PI/180.0)
00086 
00087 // Once you have your heading, you must then add your 'Declination Angle', 
00088 // which is  the 'Error' of the magnetic field in your location.
00089 // Find yours here: http://www.magnetic-declination.com/
00090 // Mine is:  -1° 13' WEST which is -1.2167 Degrees, or (which we need) 
00091 // 0,021234839232597676519238237683278  radians, I will use 0.02123
00092 // If you cannot find your Declination, put 0, your compass will be slightly off.
00093 
00094 #define  DECLINATION_ANGLE -0.02123
00095 //#define  DECLINATION_ANGLE 0
00096 
00097 
00098 /**
00099  * The HMC5883L 3-Axis Digital Compass IC
00100  */
00101 class HMC5883L
00102 {
00103 
00104 public:
00105 
00106     /**
00107      * The I2C address that can be passed directly to i2c object (it's already shifted 1 bit left).
00108      */
00109     static const int I2C_ADDRESS = 0x3D;
00110 
00111     /**
00112      * Constructor.
00113      *
00114      * Calls init function
00115      *
00116      * @param sda - mbed pin to use for the SDA I2C line.
00117      * @param scl - mbed pin to use for the SCL I2C line.
00118      */
00119     HMC5883L(PinName sda, PinName scl);
00120 
00121     /**
00122     * Constructor that accepts external i2c interface object.
00123     * 
00124     * Calls init function
00125     *
00126     * @param i2c The I2C interface object to use.
00127     */
00128     HMC5883L(I2C &i2c) : i2c_(i2c) {
00129         init();
00130     }
00131 
00132     ~HMC5883L();
00133     
00134     /**
00135     * Initalize function called by all constructors.
00136     * 
00137     * Place startup code in here.
00138     */
00139     void init();
00140     
00141     /**
00142     * Function for setting configuration register A
00143     *
00144     * Defined constants should be ored together to create value.
00145     * Defualt is 0x10 - 1 Sample per output, 15Hz Data output rate, normal measurement mode
00146     *
00147     * Refer to datasheet for instructions for setting Configuration Register A.
00148     *
00149     * @param config the value to place in Configuration Register A
00150     */
00151     void setConfigurationA(char);
00152     
00153     /**
00154     * Function for retrieving the contents of configuration register A
00155     * 
00156     * @returns Configuration Register A
00157     */
00158     char getConfigurationA();
00159     
00160     /**
00161     * Function for setting configuration register B
00162     *
00163     * Configuration Register B is for setting the device gain.
00164     * Default value is 0x20
00165     * 
00166     * Refer to datasheet for instructions for setting Configuration Register B
00167     *
00168     * @param config the value to place in Configuration Register B
00169     */
00170     void setConfigurationB(char);
00171     
00172     /**
00173     * Function for retrieving the contents of configuration register B
00174     * 
00175     * @returns Configuration Register B
00176     */
00177     char getConfigurationB();
00178     
00179     /**
00180     * Funciton for setting the mode register
00181     * 
00182     * Constants: CONTINUOUS_MODE, SINGLE_MODE, IDLE_MODE
00183     * 
00184     * When you send a the Single-Measurement Mode instruction to the mode register
00185     * a single measurement is made, the RDY bit is set in the status register,
00186     * and the mode is placed in idle mode.
00187     *
00188     * When in Continous-Measurement Mode the device continuously performs measurements
00189     * and places the results in teh data register.  After being placed in this mode
00190     * it takes two periods at the rate set in the data output rate before the first
00191     * sample is avaliable.
00192     *
00193     * Refer to datasheet for more detailed instructions for setting the mode register.
00194     *  
00195     * @param mode the value for setting in the Mode Register
00196     */
00197     void setMode(char);
00198     
00199     /**
00200     * Function for retrieving the contents of mode register
00201     * 
00202     * @returns mode register
00203     */
00204     char getMode();
00205     
00206     /**
00207     * Function for retriaval of the raw data
00208     * Caution!!  the HMC5883L gives you the data in XZY order
00209     *
00210     * @param output buffer that is at least 3 in length
00211     */
00212     void getXYZ(int16_t raw[3]);
00213     
00214     /**
00215     * Function for retrieving the contents of status register
00216     * 
00217     * Bit1: LOCK, Bit0: RDY
00218     *
00219     * @returns status register
00220     */
00221     char getStatus();
00222     
00223     /**
00224     * Function for getting radian heading using 2-dimensional calculation.
00225     * 
00226     * Compass must be held flat and away from an magnetic field generating
00227     * devices such as cell phones and speakers.
00228     *
00229     * 
00230     * 
00231     * @returns heading in radians
00232     */
00233     double getHeadingXY();
00234     
00235     /**
00236     * Function for getting degree heading using 2-dimensional calculation.
00237     * 
00238     * Compass must be held flat and away from an magnetic field generating
00239     * devices such as cell phones and speakers.
00240     *
00241     * 
00242     * 
00243     * @returns heading in degrees
00244     */
00245     double getHeadingXYDeg() {
00246         return (getHeadingXY() * RAD_TO_DEG);
00247     }
00248 
00249 private:
00250 
00251     I2C &i2c_;
00252 
00253     /**
00254      * The raw buffer for allocating I2C object in its own without heap memory.
00255      */
00256     char i2cRaw[sizeof(I2C)];
00257 };
00258 
00259 #endif // HMC5883L