takuya ichise / HMC5883L

The library for the HMC5883L, which allows you to receive directional information from this library.

Dependents:   Seeed_Grove_Digital_Compass_Example

Fork of HMC5883L by Tyler Weaver

HMC5883L.h@0:8b84d61cee94, 2012-10-31 (annotated)

Committer:
tylerjw
Date:
Wed Oct 31 04:35:08 2012 +0000
Revision:
0:8b84d61cee94
Child:
1:8a1357c351c6
0.1 first version built off of datasheet

Who changed what in which revision?

UserRevisionLine numberNew contents of line
tylerjw 0:8b84d61cee94 1 /*
tylerjw 0:8b84d61cee94 2 * @file HMC5883L.h
tylerjw 0:8b84d61cee94 3 * @author Tyler Weaver
tylerjw 0:8b84d61cee94 4 *
tylerjw 0:8b84d61cee94 5 * @section LICENSE
tylerjw 0:8b84d61cee94 6 *
tylerjw 0:8b84d61cee94 7 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
tylerjw 0:8b84d61cee94 8 * and associated documentation files (the "Software"), to deal in the Software without restriction,
tylerjw 0:8b84d61cee94 9 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
tylerjw 0:8b84d61cee94 10 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
tylerjw 0:8b84d61cee94 11 * furnished to do so, subject to the following conditions:
tylerjw 0:8b84d61cee94 12 *
tylerjw 0:8b84d61cee94 13 * The above copyright notice and this permission notice shall be included in all copies or
tylerjw 0:8b84d61cee94 14 * substantial portions of the Software.
tylerjw 0:8b84d61cee94 15 *
tylerjw 0:8b84d61cee94 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
tylerjw 0:8b84d61cee94 17 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
tylerjw 0:8b84d61cee94 18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
tylerjw 0:8b84d61cee94 19 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
tylerjw 0:8b84d61cee94 20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
tylerjw 0:8b84d61cee94 21 *
tylerjw 0:8b84d61cee94 22 * @section DESCRIPTION
tylerjw 0:8b84d61cee94 23 *
tylerjw 0:8b84d61cee94 24 * HMC5883L 3-Axis Digital Compas IC
tylerjw 0:8b84d61cee94 25 * For use with the Sparkfun 9 Degrees of Freedom - Sensor Stick
tylerjw 0:8b84d61cee94 26 *
tylerjw 0:8b84d61cee94 27 * Datasheet:
tylerjw 0:8b84d61cee94 28 *
tylerjw 0:8b84d61cee94 29 * http://dlnmh9ip6v2uc.cloudfront.net/datasheets/Sensors/Magneto/HMC5883L-FDS.pdf
tylerjw 0:8b84d61cee94 30 */
tylerjw 0:8b84d61cee94 31
tylerjw 0:8b84d61cee94 32 #ifndef HMC5883L_H
tylerjw 0:8b84d61cee94 33 #define HMC5883L_H
tylerjw 0:8b84d61cee94 34
tylerjw 0:8b84d61cee94 35 #include "mbed.h"
tylerjw 0:8b84d61cee94 36
tylerjw 0:8b84d61cee94 37 /*
tylerjw 0:8b84d61cee94 38 * Defines
tylerjw 0:8b84d61cee94 39 */
tylerjw 0:8b84d61cee94 40
tylerjw 0:8b84d61cee94 41 //-----------
tylerjw 0:8b84d61cee94 42 // Registers
tylerjw 0:8b84d61cee94 43 //-----------
tylerjw 0:8b84d61cee94 44 #define CONFIG_A_REG 0x00
tylerjw 0:8b84d61cee94 45 #define CONFIG_B_REG 0x01
tylerjw 0:8b84d61cee94 46 #define MODE_REG 0x02
tylerjw 0:8b84d61cee94 47 #define OUTPUT_REG 0x03
tylerjw 0:8b84d61cee94 48 #define STATUS_REG 0x09
tylerjw 0:8b84d61cee94 49
tylerjw 0:8b84d61cee94 50 // configuration register a
tylerjw 0:8b84d61cee94 51 #define AVG1_SAMPLES 0x00
tylerjw 0:8b84d61cee94 52 #define AVG2_SAMPLES 0x20
tylerjw 0:8b84d61cee94 53 #define AVG4_SAMPLES 0x80
tylerjw 0:8b84d61cee94 54 #define AVG8_SAMPLES 0xC0
tylerjw 0:8b84d61cee94 55
tylerjw 0:8b84d61cee94 56 #define OUTPUT_RATE_0_75 0x00
tylerjw 0:8b84d61cee94 57 #define OUTPUT_RATE_1_5 0x04
tylerjw 0:8b84d61cee94 58 #define OUTPUT_RATE_3 0x08
tylerjw 0:8b84d61cee94 59 #define OUTPUT_RATE_7_5 0x0C
tylerjw 0:8b84d61cee94 60 #define OUTPUT_RATE_15 0x10
tylerjw 0:8b84d61cee94 61 #define OUTPUT_RATE_30 0x14
tylerjw 0:8b84d61cee94 62 #define OUTPUT_RATE_75 0x18
tylerjw 0:8b84d61cee94 63
tylerjw 0:8b84d61cee94 64 #define NORMAL_MEASUREMENT 0x00
tylerjw 0:8b84d61cee94 65 #define POSITIVE_BIAS 0x01
tylerjw 0:8b84d61cee94 66 #define NEGATIVE_BIAS 0x02
tylerjw 0:8b84d61cee94 67
tylerjw 0:8b84d61cee94 68 // mode register
tylerjw 0:8b84d61cee94 69 #define CONTINUOUS_MODE 0x00
tylerjw 0:8b84d61cee94 70 #define SINGLE_MODE 0x01
tylerjw 0:8b84d61cee94 71 #define IDLE_MODE 0x02
tylerjw 0:8b84d61cee94 72
tylerjw 0:8b84d61cee94 73 // status register
tylerjw 0:8b84d61cee94 74 #define STATUS_LOCK 0x02
tylerjw 0:8b84d61cee94 75 #define STATUS_READY 0x01
tylerjw 0:8b84d61cee94 76
tylerjw 0:8b84d61cee94 77 /**
tylerjw 0:8b84d61cee94 78 * The HMC5883L 3-Axis Digital Compass IC
tylerjw 0:8b84d61cee94 79 */
tylerjw 0:8b84d61cee94 80 class HMC5883L
tylerjw 0:8b84d61cee94 81 {
tylerjw 0:8b84d61cee94 82
tylerjw 0:8b84d61cee94 83 public:
tylerjw 0:8b84d61cee94 84
tylerjw 0:8b84d61cee94 85 /**
tylerjw 0:8b84d61cee94 86 * The I2C address that can be passed directly to i2c object (it's already shifted 1 bit left).
tylerjw 0:8b84d61cee94 87 *
tylerjw 0:8b84d61cee94 88 * You don't need to manually set or clear the LSB when calling I2C::read() or I2C::write(),
tylerjw 0:8b84d61cee94 89 * the library takes care of it. We just always clear the LSB.
tylerjw 0:8b84d61cee94 90 */
tylerjw 0:8b84d61cee94 91 static const int I2C_ADDRESS = 0x3D;
tylerjw 0:8b84d61cee94 92
tylerjw 0:8b84d61cee94 93 /**
tylerjw 0:8b84d61cee94 94 * Constructor.
tylerjw 0:8b84d61cee94 95 *
tylerjw 0:8b84d61cee94 96 * Sets FS_SEL to 0x03 for proper opertaion.
tylerjw 0:8b84d61cee94 97 *
tylerjw 0:8b84d61cee94 98 * @param sda - mbed pin to use for the SDA I2C line.
tylerjw 0:8b84d61cee94 99 * @param scl - mbed pin to use for the SCL I2C line.
tylerjw 0:8b84d61cee94 100 */
tylerjw 0:8b84d61cee94 101 HMC5883L(PinName sda, PinName scl);
tylerjw 0:8b84d61cee94 102
tylerjw 0:8b84d61cee94 103 /**
tylerjw 0:8b84d61cee94 104 * Constructor that accepts external i2c interface object.
tylerjw 0:8b84d61cee94 105 *
tylerjw 0:8b84d61cee94 106 * @param i2c The I2C interface object to use.
tylerjw 0:8b84d61cee94 107 */
tylerjw 0:8b84d61cee94 108 HMC5883L(I2C &i2c) : i2c_(i2c) {
tylerjw 0:8b84d61cee94 109 init();
tylerjw 0:8b84d61cee94 110 }
tylerjw 0:8b84d61cee94 111
tylerjw 0:8b84d61cee94 112 ~HMC5883L();
tylerjw 0:8b84d61cee94 113
tylerjw 0:8b84d61cee94 114 /**
tylerjw 0:8b84d61cee94 115 * Initalize function called by all constructors.
tylerjw 0:8b84d61cee94 116 *
tylerjw 0:8b84d61cee94 117 * Place startup code in here.
tylerjw 0:8b84d61cee94 118 */
tylerjw 0:8b84d61cee94 119 void init();
tylerjw 0:8b84d61cee94 120
tylerjw 0:8b84d61cee94 121 /**
tylerjw 0:8b84d61cee94 122 * Function for setting configuration register A
tylerjw 0:8b84d61cee94 123 *
tylerjw 0:8b84d61cee94 124 * Defined constants should be ored together to create value.
tylerjw 0:8b84d61cee94 125 * Defualt is 0x10 - 1 Sample per output, 15Hz Data output rate, normal measurement mode
tylerjw 0:8b84d61cee94 126 *
tylerjw 0:8b84d61cee94 127 * Refer to datasheet for instructions for setting Configuration Register A.
tylerjw 0:8b84d61cee94 128 *
tylerjw 0:8b84d61cee94 129 * @param config the value to place in Configuration Register A
tylerjw 0:8b84d61cee94 130 */
tylerjw 0:8b84d61cee94 131 void setConfigurationA(char);
tylerjw 0:8b84d61cee94 132
tylerjw 0:8b84d61cee94 133 /**
tylerjw 0:8b84d61cee94 134 * Function for retrieving the contents of configuration register A
tylerjw 0:8b84d61cee94 135 *
tylerjw 0:8b84d61cee94 136 * @returns Configuration Register A
tylerjw 0:8b84d61cee94 137 */
tylerjw 0:8b84d61cee94 138 char getConfigurationA();
tylerjw 0:8b84d61cee94 139
tylerjw 0:8b84d61cee94 140 /**
tylerjw 0:8b84d61cee94 141 * Function for setting configuration register B
tylerjw 0:8b84d61cee94 142 *
tylerjw 0:8b84d61cee94 143 * Configuration Register B is for setting the device gain.
tylerjw 0:8b84d61cee94 144 * Default value is 0x20
tylerjw 0:8b84d61cee94 145 *
tylerjw 0:8b84d61cee94 146 * Refer to datasheet for instructions for setting Configuration Register B
tylerjw 0:8b84d61cee94 147 *
tylerjw 0:8b84d61cee94 148 * @param config the value to place in Configuration Register B
tylerjw 0:8b84d61cee94 149 */
tylerjw 0:8b84d61cee94 150 void setConfigurationB(char);
tylerjw 0:8b84d61cee94 151
tylerjw 0:8b84d61cee94 152 /**
tylerjw 0:8b84d61cee94 153 * Function for retrieving the contents of configuration register B
tylerjw 0:8b84d61cee94 154 *
tylerjw 0:8b84d61cee94 155 * @returns Configuration Register B
tylerjw 0:8b84d61cee94 156 */
tylerjw 0:8b84d61cee94 157 char getConfigurationB();
tylerjw 0:8b84d61cee94 158
tylerjw 0:8b84d61cee94 159 /**
tylerjw 0:8b84d61cee94 160 * Funciton for setting the mode register
tylerjw 0:8b84d61cee94 161 *
tylerjw 0:8b84d61cee94 162 * |= 7 |= 6 |= 5 |= 4 |= 3 |= 2 |= 1 |= 0 |
tylerjw 0:8b84d61cee94 163 * | (0)| (0)| (0)| (0)| (0)| (0)|MD1 | MD0|
tylerjw 0:8b84d61cee94 164 *
tylerjw 0:8b84d61cee94 165 * |=MD1 |=MD0 |=Operating Mode |=Constant |
tylerjw 0:8b84d61cee94 166 * | 0 | 0 | Continuous-Measurement Mode | CONTINUOUS_MODE |
tylerjw 0:8b84d61cee94 167 * | 0 | 1 | Single-Measument Mode | SINGLE_MODE |
tylerjw 0:8b84d61cee94 168 * | 1 | 0 | Idle Mode | IDLE_MODE |
tylerjw 0:8b84d61cee94 169 * | 1 | 1 | Idle Mode | IDLE_MODE |
tylerjw 0:8b84d61cee94 170 *
tylerjw 0:8b84d61cee94 171 * When you send a the Single-Measurement Mode instruction to the mode register
tylerjw 0:8b84d61cee94 172 * a single measurement is made, the RDY bit is set in the status register,
tylerjw 0:8b84d61cee94 173 * and the mode is placed in idle mode.
tylerjw 0:8b84d61cee94 174 *
tylerjw 0:8b84d61cee94 175 * When in Continous-Measurement Mode the device continuously performs measurements
tylerjw 0:8b84d61cee94 176 * and places the results in teh data register. After being placed in this mode
tylerjw 0:8b84d61cee94 177 * it takes two periods at the rate set in the data output rate before the first
tylerjw 0:8b84d61cee94 178 * sample is avaliable.
tylerjw 0:8b84d61cee94 179 *
tylerjw 0:8b84d61cee94 180 * Refer to datasheet for more detailed instructions for setting the mode register.
tylerjw 0:8b84d61cee94 181 *
tylerjw 0:8b84d61cee94 182 * @param mode the value for setting in the Mode Register
tylerjw 0:8b84d61cee94 183 */
tylerjw 0:8b84d61cee94 184 void setMode(char);
tylerjw 0:8b84d61cee94 185
tylerjw 0:8b84d61cee94 186 /**
tylerjw 0:8b84d61cee94 187 * Function for retrieving the contents of mode register
tylerjw 0:8b84d61cee94 188 *
tylerjw 0:8b84d61cee94 189 * @returns mode register
tylerjw 0:8b84d61cee94 190 */
tylerjw 0:8b84d61cee94 191 char getMode();
tylerjw 0:8b84d61cee94 192
tylerjw 0:8b84d61cee94 193 /**
tylerjw 0:8b84d61cee94 194 * Function for retriaval of the raw data
tylerjw 0:8b84d61cee94 195 *
tylerjw 0:8b84d61cee94 196 * @param output buffer that is atleast 3 in length
tylerjw 0:8b84d61cee94 197 */
tylerjw 0:8b84d61cee94 198 void getXYZ(int raw[3]);
tylerjw 0:8b84d61cee94 199
tylerjw 0:8b84d61cee94 200 /**
tylerjw 0:8b84d61cee94 201 * Function for retrieving the contents of status register
tylerjw 0:8b84d61cee94 202 *
tylerjw 0:8b84d61cee94 203 * |= 7 |= 6 |= 5 |= 4 |= 3 |= 2 |= 1 |= 0 |
tylerjw 0:8b84d61cee94 204 * | (0)| (0)| (0)| (0)| (0)| (0)|LOCK | RDY|
tylerjw 0:8b84d61cee94 205 *
tylerjw 0:8b84d61cee94 206 * @returns status register
tylerjw 0:8b84d61cee94 207 */
tylerjw 0:8b84d61cee94 208 char getStatus();
tylerjw 0:8b84d61cee94 209
tylerjw 0:8b84d61cee94 210 private:
tylerjw 0:8b84d61cee94 211
tylerjw 0:8b84d61cee94 212 I2C &i2c_;
tylerjw 0:8b84d61cee94 213
tylerjw 0:8b84d61cee94 214 /**
tylerjw 0:8b84d61cee94 215 * The raw buffer for allocating I2C object in its own without heap memory.
tylerjw 0:8b84d61cee94 216 */
tylerjw 0:8b84d61cee94 217 char i2cRaw[sizeof(I2C)];
tylerjw 0:8b84d61cee94 218 };
tylerjw 0:8b84d61cee94 219
tylerjw 0:8b84d61cee94 220 #endif // HMC5883L