HMC5883L.h

00001 /*
00002  * @file HMC5883L.h
00003  * @author Tyler Weaver
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  * For use with the Sparkfun 9 Degrees of Freedom - Sensor Stick
00026  *
00027  * Datasheet:
00028  *
00029  * http://dlnmh9ip6v2uc.cloudfront.net/datasheets/Sensors/Magneto/HMC5883L-FDS.pdf
00030  */
00031 
00032 #ifndef HMC5883L_H
00033 #define HMC5883L_H
00034 
00035 #include "mbed.h"
00036 
00037 /*
00038 * Defines
00039 */
00040 
00041 //-----------
00042 // Registers
00043 //-----------
00044 #define CONFIG_A_REG    0x00
00045 #define CONFIG_B_REG    0x01
00046 #define MODE_REG        0x02
00047 #define OUTPUT_REG      0x03
00048 #define STATUS_REG      0x09
00049 
00050 // configuration register a
00051 #define AVG1_SAMPLES    0x00
00052 #define AVG2_SAMPLES    0x20
00053 #define AVG4_SAMPLES    0x80
00054 #define AVG8_SAMPLES    0xC0
00055 
00056 #define OUTPUT_RATE_0_75    0x00
00057 #define OUTPUT_RATE_1_5     0x04
00058 #define OUTPUT_RATE_3       0x08
00059 #define OUTPUT_RATE_7_5     0x0C
00060 #define OUTPUT_RATE_15      0x10
00061 #define OUTPUT_RATE_30      0x14
00062 #define OUTPUT_RATE_75      0x18
00063 
00064 #define NORMAL_MEASUREMENT  0x00
00065 #define POSITIVE_BIAS       0x01
00066 #define NEGATIVE_BIAS       0x02
00067 
00068 // mode register
00069 #define CONTINUOUS_MODE     0x00
00070 #define SINGLE_MODE         0x01
00071 #define IDLE_MODE           0x02
00072 
00073 // status register
00074 #define STATUS_LOCK         0x02
00075 #define STATUS_READY        0x01
00076 
00077 // Utility
00078 #ifndef M_PI
00079 #define M_PI 3.1415926535897932384626433832795
00080 #endif
00081 
00082 #define PI2         (2*M_PI)
00083 #define RAD_TO_DEG  (180.0/M_PI)
00084 #define DEG_TO_RAD  (M_PI/180.0)
00085 
00086 /**
00087  * The HMC5883L 3-Axis Digital Compass IC
00088  */
00089 class HMC5883L
00090 {
00091 
00092 public:
00093 
00094     /**
00095      * The I2C address that can be passed directly to i2c object (it's already shifted 1 bit left).
00096      */
00097     static const int I2C_ADDRESS = 0x3D;
00098 
00099     /**
00100      * Constructor.
00101      *
00102      * Calls init function
00103      *
00104      * @param sda - mbed pin to use for the SDA I2C line.
00105      * @param scl - mbed pin to use for the SCL I2C line.
00106      */
00107     HMC5883L(PinName sda, PinName scl);
00108 
00109     /**
00110     * Constructor that accepts external i2c interface object.
00111     * 
00112     * Calls init function
00113     *
00114     * @param i2c The I2C interface object to use.
00115     */
00116     HMC5883L(I2C &i2c) : i2c_(i2c) {
00117         init();
00118     }
00119 
00120     ~HMC5883L();
00121     
00122     /**
00123     * Initalize function called by all constructors.
00124     * 
00125     * Place startup code in here.
00126     */
00127     void init();
00128     
00129     /**
00130     * Function for setting configuration register A
00131     *
00132     * Defined constants should be ored together to create value.
00133     * Defualt is 0x10 - 1 Sample per output, 15Hz Data output rate, normal measurement mode
00134     *
00135     * Refer to datasheet for instructions for setting Configuration Register A.
00136     *
00137     * @param config the value to place in Configuration Register A
00138     */
00139     void setConfigurationA(char);
00140     
00141     /**
00142     * Function for retrieving the contents of configuration register A
00143     * 
00144     * @returns Configuration Register A
00145     */
00146     char getConfigurationA();
00147     
00148     /**
00149     * Function for setting configuration register B
00150     *
00151     * Configuration Register B is for setting the device gain.
00152     * Default value is 0x20
00153     * 
00154     * Refer to datasheet for instructions for setting Configuration Register B
00155     *
00156     * @param config the value to place in Configuration Register B
00157     */
00158     void setConfigurationB(char);
00159     
00160     /**
00161     * Function for retrieving the contents of configuration register B
00162     * 
00163     * @returns Configuration Register B
00164     */
00165     char getConfigurationB();
00166     
00167     /**
00168     * Funciton for setting the mode register
00169     * 
00170     * Constants: CONTINUOUS_MODE, SINGLE_MODE, IDLE_MODE
00171     * 
00172     * When you send a the Single-Measurement Mode instruction to the mode register
00173     * a single measurement is made, the RDY bit is set in the status register,
00174     * and the mode is placed in idle mode.
00175     *
00176     * When in Continous-Measurement Mode the device continuously performs measurements
00177     * and places the results in teh data register.  After being placed in this mode
00178     * it takes two periods at the rate set in the data output rate before the first
00179     * sample is avaliable.
00180     *
00181     * Refer to datasheet for more detailed instructions for setting the mode register.
00182     *  
00183     * @param mode the value for setting in the Mode Register
00184     */
00185     void setMode(char);
00186     
00187     /**
00188     * Function for retrieving the contents of mode register
00189     * 
00190     * @returns mode register
00191     */
00192     char getMode();
00193     
00194     /**
00195     * Function for retriaval of the raw data
00196     *
00197     * @param output buffer that is atleast 3 in length
00198     */
00199     void getXYZ(int16_t raw[3]);
00200     
00201     /**
00202     * Function for retrieving the contents of status register
00203     * 
00204     * Bit1: LOCK, Bit0: RDY
00205     *
00206     * @returns status register
00207     */
00208     char getStatus();
00209     
00210     /**
00211     * Function for getting radian heading using 2-dimensional calculation.
00212     * 
00213     * Compass must be held flat and away from an magnetic field generating
00214     * devices such as cell phones and speakers.
00215     *
00216     * TODO: declenation angle compensation
00217     * 
00218     * @returns heading in radians
00219     */
00220     double getHeadingXY();
00221     
00222     /**
00223     * Function for getting degree heading using 2-dimensional calculation.
00224     * 
00225     * Compass must be held flat and away from an magnetic field generating
00226     * devices such as cell phones and speakers.
00227     *
00228     * TODO: declenation angle compensation
00229     * 
00230     * @returns heading in degrees
00231     */
00232     double getHeadingXYDeg() {
00233         return (getHeadingXY() * RAD_TO_DEG);
00234     }
00235 
00236 private:
00237 
00238     I2C &i2c_;
00239 
00240     /**
00241      * The raw buffer for allocating I2C object in its own without heap memory.
00242      */
00243     char i2cRaw[sizeof(I2C)];
00244 };
00245 
00246 #endif // HMC5883L