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@5:6a47ae8ee7ea, 2018-10-03 (annotated)

Committer:
tichise
Date:
Wed Oct 03 13:30:54 2018 +0000
Revision:
5:6a47ae8ee7ea
Parent:
3:14d274e0f9de 
corrected a fatal defect that can not be oriented properly

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 1:8a1357c351c6 77 // Utility
tylerjw 1:8a1357c351c6 78 #ifndef M_PI
tylerjw 1:8a1357c351c6 79 #define M_PI 3.1415926535897932384626433832795
tylerjw 1:8a1357c351c6 80 #endif
tylerjw 1:8a1357c351c6 81
tylerjw 2:8eb755577f83 82 #define PI2 (2*M_PI)
tylerjw 1:8a1357c351c6 83 #define RAD_TO_DEG (180.0/M_PI)
tylerjw 1:8a1357c351c6 84 #define DEG_TO_RAD (M_PI/180.0)
tylerjw 1:8a1357c351c6 85
tylerjw 0:8b84d61cee94 86 /**
tylerjw 0:8b84d61cee94 87 * The HMC5883L 3-Axis Digital Compass IC
tylerjw 0:8b84d61cee94 88 */
tylerjw 0:8b84d61cee94 89 class HMC5883L
tylerjw 0:8b84d61cee94 90 {
tylerjw 0:8b84d61cee94 91
tylerjw 0:8b84d61cee94 92 public:
tylerjw 0:8b84d61cee94 93
tylerjw 0:8b84d61cee94 94 /**
tylerjw 0:8b84d61cee94 95 * The I2C address that can be passed directly to i2c object (it's already shifted 1 bit left).
tylerjw 0:8b84d61cee94 96 */
tylerjw 0:8b84d61cee94 97 static const int I2C_ADDRESS = 0x3D;
tylerjw 0:8b84d61cee94 98
tylerjw 0:8b84d61cee94 99 /**
tylerjw 0:8b84d61cee94 100 * Constructor.
tylerjw 0:8b84d61cee94 101 *
tylerjw 1:8a1357c351c6 102 * Calls init function
tylerjw 0:8b84d61cee94 103 *
tylerjw 0:8b84d61cee94 104 * @param sda - mbed pin to use for the SDA I2C line.
tylerjw 0:8b84d61cee94 105 * @param scl - mbed pin to use for the SCL I2C line.
tylerjw 0:8b84d61cee94 106 */
tylerjw 0:8b84d61cee94 107 HMC5883L(PinName sda, PinName scl);
tylerjw 0:8b84d61cee94 108
tylerjw 0:8b84d61cee94 109 /**
tylerjw 0:8b84d61cee94 110 * Constructor that accepts external i2c interface object.
tylerjw 1:8a1357c351c6 111 *
tylerjw 1:8a1357c351c6 112 * Calls init function
tylerjw 0:8b84d61cee94 113 *
tylerjw 0:8b84d61cee94 114 * @param i2c The I2C interface object to use.
tylerjw 0:8b84d61cee94 115 */
tylerjw 0:8b84d61cee94 116 HMC5883L(I2C &i2c) : i2c_(i2c) {
tylerjw 0:8b84d61cee94 117 init();
tylerjw 0:8b84d61cee94 118 }
tylerjw 0:8b84d61cee94 119
tylerjw 0:8b84d61cee94 120 ~HMC5883L();
tylerjw 0:8b84d61cee94 121
tylerjw 0:8b84d61cee94 122 /**
tylerjw 0:8b84d61cee94 123 * Initalize function called by all constructors.
tylerjw 0:8b84d61cee94 124 *
tylerjw 0:8b84d61cee94 125 * Place startup code in here.
tylerjw 0:8b84d61cee94 126 */
tylerjw 0:8b84d61cee94 127 void init();
tylerjw 0:8b84d61cee94 128
tylerjw 0:8b84d61cee94 129 /**
tylerjw 0:8b84d61cee94 130 * Function for setting configuration register A
tylerjw 0:8b84d61cee94 131 *
tylerjw 0:8b84d61cee94 132 * Defined constants should be ored together to create value.
tylerjw 0:8b84d61cee94 133 * Defualt is 0x10 - 1 Sample per output, 15Hz Data output rate, normal measurement mode
tylerjw 0:8b84d61cee94 134 *
tylerjw 0:8b84d61cee94 135 * Refer to datasheet for instructions for setting Configuration Register A.
tylerjw 0:8b84d61cee94 136 *
tylerjw 0:8b84d61cee94 137 * @param config the value to place in Configuration Register A
tylerjw 0:8b84d61cee94 138 */
tylerjw 0:8b84d61cee94 139 void setConfigurationA(char);
tylerjw 0:8b84d61cee94 140
tylerjw 0:8b84d61cee94 141 /**
tylerjw 0:8b84d61cee94 142 * Function for retrieving the contents of configuration register A
tylerjw 0:8b84d61cee94 143 *
tylerjw 0:8b84d61cee94 144 * @returns Configuration Register A
tylerjw 0:8b84d61cee94 145 */
tylerjw 0:8b84d61cee94 146 char getConfigurationA();
tylerjw 0:8b84d61cee94 147
tylerjw 0:8b84d61cee94 148 /**
tylerjw 0:8b84d61cee94 149 * Function for setting configuration register B
tylerjw 0:8b84d61cee94 150 *
tylerjw 0:8b84d61cee94 151 * Configuration Register B is for setting the device gain.
tylerjw 0:8b84d61cee94 152 * Default value is 0x20
tylerjw 0:8b84d61cee94 153 *
tylerjw 0:8b84d61cee94 154 * Refer to datasheet for instructions for setting Configuration Register B
tylerjw 0:8b84d61cee94 155 *
tylerjw 0:8b84d61cee94 156 * @param config the value to place in Configuration Register B
tylerjw 0:8b84d61cee94 157 */
tylerjw 0:8b84d61cee94 158 void setConfigurationB(char);
tylerjw 0:8b84d61cee94 159
tylerjw 0:8b84d61cee94 160 /**
tylerjw 0:8b84d61cee94 161 * Function for retrieving the contents of configuration register B
tylerjw 0:8b84d61cee94 162 *
tylerjw 0:8b84d61cee94 163 * @returns Configuration Register B
tylerjw 0:8b84d61cee94 164 */
tylerjw 0:8b84d61cee94 165 char getConfigurationB();
tylerjw 0:8b84d61cee94 166
tylerjw 0:8b84d61cee94 167 /**
tylerjw 0:8b84d61cee94 168 * Funciton for setting the mode register
tylerjw 0:8b84d61cee94 169 *
tylerjw 1:8a1357c351c6 170 * Constants: CONTINUOUS_MODE, SINGLE_MODE, IDLE_MODE
tylerjw 0:8b84d61cee94 171 *
tylerjw 0:8b84d61cee94 172 * When you send a the Single-Measurement Mode instruction to the mode register
tylerjw 0:8b84d61cee94 173 * a single measurement is made, the RDY bit is set in the status register,
tylerjw 0:8b84d61cee94 174 * and the mode is placed in idle mode.
tylerjw 0:8b84d61cee94 175 *
tylerjw 0:8b84d61cee94 176 * When in Continous-Measurement Mode the device continuously performs measurements
tylerjw 0:8b84d61cee94 177 * and places the results in teh data register. After being placed in this mode
tylerjw 0:8b84d61cee94 178 * it takes two periods at the rate set in the data output rate before the first
tylerjw 0:8b84d61cee94 179 * sample is avaliable.
tylerjw 0:8b84d61cee94 180 *
tylerjw 0:8b84d61cee94 181 * Refer to datasheet for more detailed instructions for setting the mode register.
tylerjw 0:8b84d61cee94 182 *
tylerjw 0:8b84d61cee94 183 * @param mode the value for setting in the Mode Register
tylerjw 0:8b84d61cee94 184 */
tylerjw 0:8b84d61cee94 185 void setMode(char);
tylerjw 0:8b84d61cee94 186
tylerjw 0:8b84d61cee94 187 /**
tylerjw 0:8b84d61cee94 188 * Function for retrieving the contents of mode register
tylerjw 0:8b84d61cee94 189 *
tylerjw 0:8b84d61cee94 190 * @returns mode register
tylerjw 0:8b84d61cee94 191 */
tylerjw 0:8b84d61cee94 192 char getMode();
tylerjw 0:8b84d61cee94 193
tylerjw 0:8b84d61cee94 194 /**
tylerjw 0:8b84d61cee94 195 * Function for retriaval of the raw data
tylerjw 0:8b84d61cee94 196 *
tylerjw 0:8b84d61cee94 197 * @param output buffer that is atleast 3 in length
tylerjw 0:8b84d61cee94 198 */
tylerjw 3:14d274e0f9de 199 void getXYZ(int16_t raw[3]);
tylerjw 0:8b84d61cee94 200
tylerjw 0:8b84d61cee94 201 /**
tylerjw 0:8b84d61cee94 202 * Function for retrieving the contents of status register
tylerjw 0:8b84d61cee94 203 *
tylerjw 1:8a1357c351c6 204 * Bit1: LOCK, Bit0: RDY
tylerjw 0:8b84d61cee94 205 *
tylerjw 0:8b84d61cee94 206 * @returns status register
tylerjw 0:8b84d61cee94 207 */
tylerjw 0:8b84d61cee94 208 char getStatus();
tylerjw 1:8a1357c351c6 209
tylerjw 1:8a1357c351c6 210 /**
tylerjw 1:8a1357c351c6 211 * Function for getting radian heading using 2-dimensional calculation.
tylerjw 1:8a1357c351c6 212 *
tylerjw 1:8a1357c351c6 213 * Compass must be held flat and away from an magnetic field generating
tylerjw 1:8a1357c351c6 214 * devices such as cell phones and speakers.
tylerjw 1:8a1357c351c6 215 *
tylerjw 1:8a1357c351c6 216 * TODO: declenation angle compensation
tylerjw 1:8a1357c351c6 217 *
tylerjw 1:8a1357c351c6 218 * @returns heading in radians
tylerjw 1:8a1357c351c6 219 */
tylerjw 1:8a1357c351c6 220 double getHeadingXY();
tylerjw 1:8a1357c351c6 221
tylerjw 1:8a1357c351c6 222 /**
tylerjw 1:8a1357c351c6 223 * Function for getting degree heading using 2-dimensional calculation.
tylerjw 1:8a1357c351c6 224 *
tylerjw 1:8a1357c351c6 225 * Compass must be held flat and away from an magnetic field generating
tylerjw 1:8a1357c351c6 226 * devices such as cell phones and speakers.
tylerjw 1:8a1357c351c6 227 *
tylerjw 1:8a1357c351c6 228 * TODO: declenation angle compensation
tylerjw 1:8a1357c351c6 229 *
tylerjw 1:8a1357c351c6 230 * @returns heading in degrees
tylerjw 1:8a1357c351c6 231 */
tylerjw 1:8a1357c351c6 232 double getHeadingXYDeg() {
tylerjw 1:8a1357c351c6 233 return (getHeadingXY() * RAD_TO_DEG);
tylerjw 1:8a1357c351c6 234 }
tylerjw 0:8b84d61cee94 235
tylerjw 0:8b84d61cee94 236 private:
tylerjw 0:8b84d61cee94 237
tylerjw 0:8b84d61cee94 238 I2C &i2c_;
tylerjw 0:8b84d61cee94 239
tylerjw 0:8b84d61cee94 240 /**
tylerjw 0:8b84d61cee94 241 * The raw buffer for allocating I2C object in its own without heap memory.
tylerjw 0:8b84d61cee94 242 */
tylerjw 0:8b84d61cee94 243 char i2cRaw[sizeof(I2C)];
tylerjw 0:8b84d61cee94 244 };
tylerjw 0:8b84d61cee94 245
tylerjw 0:8b84d61cee94 246 #endif // HMC5883L