HMC5843.h

00001 /**
00002  * @file HMC5843.h
00003  * @author Jose R. Padron
00004  * @author Used HMC5843 library  developed by Aaron Berk as template
00005  * @section LICENSE
00006  *
00007  * Copyright (c) 2010 ARM Limited
00008  *
00009  * Permission is hereby granted, free of charge, to any person obtaining a copy
00010  * of this software and associated documentation files (the "Software"), to deal
00011  * in the Software without restriction, including without limitation the rights
00012  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00013  * copies of the Software, and to permit persons to whom the Software is
00014  * furnished to do so, subject to the following conditions:
00015  *
00016  * The above copyright notice and this permission notice shall be included in
00017  * all copies or substantial portions of the Software.
00018  *
00019  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00020  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00021  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00022  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00023  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00024  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00025  * THE SOFTWARE.
00026  *
00027  * @section DESCRIPTION
00028  *
00029  * Honeywell HMC5843 digital compass.
00030  *
00031  * Datasheet:
00032  *
00033  * http://www.ssec.honeywell.com/magnetic/datasheets/HMC5843.pdf
00034  */
00035 
00036 #ifndef HMC5843_H
00037 #define HMC5843_H
00038 
00039 #include "mbed.h"
00040 
00041 
00042 #define HMC5843_I2C_ADDRESS 0x1E //7-bit address. 0x3C write, 0x3D read.
00043 #define HMC5843_I2C_WRITE   0x3C 
00044 #define HMC5843_I2C_READ    0x3D 
00045 
00046 //Values Config A
00047 #define HMC5843_0_5HZ_NORMAL         0x00
00048 #define HMC5843_0_5HZ_POSITIVE       0x01
00049 #define HMC5843_0_5HZ_NEGATIVE       0x02
00050 
00051 #define HMC5843_1HZ_NORMAL           0x04
00052 #define HMC5843_1HZ_POSITIVE         0x05
00053 #define HMC5843_1HZ_NEGATIVE         0x06
00054 
00055 #define HMC5843_2HZ_NORMAL           0x08
00056 #define HMC5843_2HZ_POSITIVE         0x09
00057 #define HMC5843_2HZ_NEGATIVE         0x0A
00058 
00059 #define HMC5843_5HZ_NORMAL           0x0C
00060 #define HMC5843_5HZ_POSITIVE         0x0D
00061 #define HMC5843_5HZ_NEGATIVE         0x0E
00062 
00063 #define HMC5843_10HZ_NORMAL           0x10
00064 #define HMC5843_10HZ_POSITIVE         0x11
00065 #define HMC5843_10HZ_NEGATIVE         0x12
00066 
00067 #define HMC5843_20HZ_NORMAL           0x14
00068 #define HMC5843_20HZ_POSITIVE         0x15
00069 #define HMC5843_20HZ_NEGATIVE         0x16
00070 
00071 #define HMC5843_50HZ_NORMAL           0x18
00072 #define HMC5843_50HZ_POSITIVE         0x19
00073 #define HMC5843_50HZ_NEGATIVE         0x1A
00074 
00075 //Values Config B
00076 #define HMC5843_0_7GA         0x00
00077 #define HMC5843_1_0GA         0x20
00078 #define HMC5843_1_5GA         0x40
00079 #define HMC5843_2_0GA         0x60
00080 #define HMC5843_3_2GA         0x80
00081 #define HMC5843_3_8GA         0xA0
00082 #define HMC5843_4_5GA         0xC0
00083 #define HMC5843_6_5GA         0xE0
00084 
00085 //Values MODE
00086 #define HMC5843_CONTINUOUS   0x00
00087 #define HMC5843_SINGLE         0x01
00088 #define HMC5843_IDLE         0x02
00089 #define HMC5843_SLEEP         0x03
00090 
00091 
00092 
00093 #define HMC5843_CONFIG_A     0x00
00094 #define HMC5843_CONFIG_B     0x01
00095 #define HMC5843_MODE         0x02
00096 #define HMC5843_X_MSB        0x03
00097 #define HMC5843_X_LSB        0x04
00098 #define HMC5843_Y_MSB        0x05
00099 #define HMC5843_Y_LSB        0x06
00100 #define HMC5843_Z_MSB        0x07
00101 #define HMC5843_Z_LSB        0x08
00102 #define HMC5843_STATUS       0x09
00103 #define HMC5843_IDENT_A      0x0A
00104 #define HMC5843_IDENT_B      0x0B
00105 #define HMC5843_IDENT_C      0x0C
00106 
00107 
00108 
00109 /**
00110  * Honeywell HMC5843 digital compass.
00111  */
00112 class HMC5843 {
00113 
00114 public:
00115 
00116     /**
00117      * The I2C address that can be passed directly to i2c object (it's already shifted 1 bit left).
00118      *
00119      * You don't need to manually set or clear the LSB when calling I2C::read() or I2C::write(),
00120      * the library takes care of it.  We just always clear the LSB.
00121      */
00122     static const int I2C_ADDRESS = HMC5843_I2C_WRITE;
00123 
00124     /**
00125      * Constructor.
00126      *
00127      * @param sda mbed pin to use for SDA line of I2C interface.
00128      * @param scl mbed pin to use for SCL line of I2C interface.
00129      */
00130     HMC5843(PinName sda, PinName scl);
00131     
00132     /**
00133      * Constructor that accepts external i2c interface object.
00134      *
00135      * @param i2c The I2C interface object to use.
00136      */
00137     HMC5843(I2C &i2c) : i2c_(i2c), myI2c(NULL){}
00138     
00139     /**
00140      * Destructor that frees self-allocated I2C object.
00141      */
00142     ~HMC5843(){
00143         delete myI2c;
00144     }
00145 
00146         
00147      /**
00148      * Enter into sleep mode.
00149      *
00150      */
00151     void setSleepMode();
00152     
00153        
00154      /**
00155      * Set Device in Default Mode.
00156      * HMC5843_CONTINUOUS, HMC5843_10HZ_NORMAL HMC5843_1_0GA
00157      */
00158     void setDefault();
00159     
00160        
00161     /**
00162      * Read the memory location on the device which contains the address.
00163      *
00164      * @param Pointer to a buffer to hold the address value
00165      * Expected     H, 4 and 3.
00166      */
00167     void getAddress(char * address);
00168 
00169 
00170     
00171     /**
00172      * Set the operation mode.
00173      *
00174      * @param mode 0x00 -> Continuous
00175      *             0x01 -> Single
00176      *             0x02 -> Idle
00177      * @param ConfigA values
00178     * @param ConfigB values
00179      */
00180     void setOpMode(int mode, int ConfigA, int ConfigB);
00181     
00182      /**
00183      * Write to  on the device.
00184      *
00185      * @param address Address to write to.
00186      * @param data Data to write.
00187      */
00188     
00189     void write(int address, int data);
00190 
00191      /**
00192      * Get the output of all three axes.
00193      *
00194      * @param Pointer to a buffer to hold the magnetics value for the
00195      *        x-axis, y-axis and z-axis [in that order].
00196      */
00197     void readData(int* readings);
00198     
00199     /**
00200      * Get the output of X axis.
00201      *
00202      * @return x-axis magnetic value
00203      */
00204     int getMx(){ return getWord(HMC5843_X_MSB); }
00205     
00206     /**
00207      * Get the output of Y axis.
00208      *
00209      * @return y-axis magnetic value
00210      */
00211     int getMy(){ return getWord(HMC5843_Y_MSB); }
00212     
00213     /**
00214      * Get the output of Z axis.
00215      *
00216      * @return z-axis magnetic value
00217      */
00218     int getMz(){ return getWord(HMC5843_Z_MSB); }
00219    
00220     
00221     /**
00222      * Get the current operation mode.
00223      *
00224      * @return Status register values
00225      */
00226     int getStatus(void);
00227 
00228 
00229 protected:
00230 
00231     /**
00232      * Reads a word (2 bytes) from the sensor via I2C bus.
00233      *
00234      * The queried value is assumed big-endian, 2's complement value.
00235      *
00236      * This protected function is added because we shouldn't write getMx(), getMy() and getMz()
00237      * independently, but collect common codes.
00238      *
00239      * @param regi Register address to be read.
00240      */
00241     int getWord(int regi);
00242   
00243 private:
00244 
00245     /**
00246      * Internal I2C object for communicating with the device.
00247      *
00248      * Changed from a pointer (new allocated object) from embedded object.
00249      * The I2C class object is not meant to be allocated in the heap, but
00250      * in the global storage.
00251      * There's no point dynamically allocating an I2C object in this class,
00252      * at least you should write destructor to release it!
00253      */
00254     I2C &i2c_;
00255     
00256     I2C *myI2c;
00257 
00258     /**
00259      * Converts big-endian 2's complement byte pair to native byte order of
00260      * the CPU and then sign extend it to the CPU's register size.
00261      *
00262      * Implemented here to make the compiler inline expand it.
00263      */
00264     int swapExtend(const char rx[2]){
00265         // Readings are expressed in 16bit 2's complement, so we must first
00266         // concatenate two bytes to make a word and sign extend it to obtain
00267         // correct negative values.
00268         // ARMCC compiles char as unsigned, which means no sign extension is
00269         // performed during bitwise operations to chars. But we should make sure
00270         // that lower byte won't extend its sign past upper byte for other
00271         // compilers if we want to keep it portable.
00272         return int16_t(((unsigned char)rx[0] << 8) | (unsigned char)rx[1]);
00273     }
00274 
00275 };
00276 
00277 #endif /* HMC5843_H */