Mark Gottscho / SensorsLib

A compilation of some hardware sensors and their shared programming interfaces.

MAG3110.h@1:15396cab58d1, 2014-03-19 (annotated)

Committer:
mgottscho
Date:
Wed Mar 19 00:35:31 2014 +0000
Revision:
1:15396cab58d1
Parent:
0:8d34cc2ff388 
Updated for most recent UtilityLib.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mgottscho 0:8d34cc2ff388 1 /* MAG3110.h
mgottscho 0:8d34cc2ff388 2 * Tested with mbed board: FRDM-KL46Z
mgottscho 0:8d34cc2ff388 3 * Author: Mark Gottscho
mgottscho 0:8d34cc2ff388 4 * mgottscho@ucla.edu
mgottscho 0:8d34cc2ff388 5 */
mgottscho 0:8d34cc2ff388 6
mgottscho 0:8d34cc2ff388 7 #ifndef MAG3110_H
mgottscho 0:8d34cc2ff388 8 #define MAG3110_H
mgottscho 0:8d34cc2ff388 9
mgottscho 0:8d34cc2ff388 10 #include "mbed.h"
mgottscho 0:8d34cc2ff388 11 #include "I2CSensor.h"
mgottscho 0:8d34cc2ff388 12 #include "PeriodicSensor.h"
mgottscho 0:8d34cc2ff388 13
mgottscho 0:8d34cc2ff388 14
mgottscho 0:8d34cc2ff388 15 /**
mgottscho 0:8d34cc2ff388 16 * This class allows for easy control of an MAG3110 magnetometer IC.
mgottscho 0:8d34cc2ff388 17 */
mgottscho 0:8d34cc2ff388 18 class MAG3110 : public I2CSensor, public PeriodicSensor {
mgottscho 0:8d34cc2ff388 19 public:
mgottscho 0:8d34cc2ff388 20 /**
mgottscho 0:8d34cc2ff388 21 * Enumeration of allowed ADC sampling data rates.
mgottscho 0:8d34cc2ff388 22 * The device does sample averages such that
mgottscho 0:8d34cc2ff388 23 * the output data rate ODR = ADC_RATE / OVERSMPL_RATIO in all cases except for when ADC_RATE is 80 Hz (min). In this case,
mgottscho 0:8d34cc2ff388 24 * there are multiple ODR for the same ADC_RATE, OVERSMPL_RATIO combination.
mgottscho 0:8d34cc2ff388 25 * Note that there are non-unique combinations for the same ODR.
mgottscho 0:8d34cc2ff388 26 */
mgottscho 0:8d34cc2ff388 27 typedef enum {
mgottscho 0:8d34cc2ff388 28 AHZ1280, //1280 Hz
mgottscho 0:8d34cc2ff388 29 AHZ640, //640 Hz
mgottscho 0:8d34cc2ff388 30 AHZ320, //320 Hz
mgottscho 0:8d34cc2ff388 31 AHZ160, //160 Hz
mgottscho 0:8d34cc2ff388 32 AHZ80 //80 Hz
mgottscho 0:8d34cc2ff388 33 } adc_smpl_rate_t;
mgottscho 0:8d34cc2ff388 34
mgottscho 0:8d34cc2ff388 35 /**
mgottscho 0:8d34cc2ff388 36 * Enumeration of allowed oversampling ratios.
mgottscho 0:8d34cc2ff388 37 * The device does sample averages such that
mgottscho 0:8d34cc2ff388 38 * the output data rate ODR = ADC_RATE / OVERSMPL_RATIO in all cases except for when ADC_RATE is 80 Hz (min). In this case,
mgottscho 0:8d34cc2ff388 39 * there are multiple ODR for the same ADC_RATE, OVERSMPL_RATIO combination.
mgottscho 0:8d34cc2ff388 40 * Note that there are non-unique combinations for the same ODR.
mgottscho 0:8d34cc2ff388 41 */
mgottscho 0:8d34cc2ff388 42 typedef enum {
mgottscho 0:8d34cc2ff388 43 O16, //16:1
mgottscho 0:8d34cc2ff388 44 O32, //32:1
mgottscho 0:8d34cc2ff388 45 O64, //64:1
mgottscho 0:8d34cc2ff388 46 O128 //128:1
mgottscho 0:8d34cc2ff388 47 } oversmpl_ratio_t;
mgottscho 0:8d34cc2ff388 48
mgottscho 0:8d34cc2ff388 49 /**
mgottscho 0:8d34cc2ff388 50 * Enumeration of possible output data rates.
mgottscho 0:8d34cc2ff388 51 * The device does sample averages such that
mgottscho 0:8d34cc2ff388 52 * the output data rate ODR = ADC_RATE / OVERSMPL_RATIO in all cases except for when ADC_RATE is 80 Hz (min). In this case,
mgottscho 0:8d34cc2ff388 53 * there are multiple ODR for the same ADC_RATE, OVERSMPL_RATIO combination.
mgottscho 0:8d34cc2ff388 54 * Note that there are non-unique combinations for the same ODR.
mgottscho 0:8d34cc2ff388 55 */
mgottscho 0:8d34cc2ff388 56 typedef enum {
mgottscho 0:8d34cc2ff388 57 HZ80, //80 Hz
mgottscho 0:8d34cc2ff388 58 HZ40, //40 Hz
mgottscho 0:8d34cc2ff388 59 HZ20, //20 Hz
mgottscho 0:8d34cc2ff388 60 HZ10, //10 Hz
mgottscho 0:8d34cc2ff388 61 HZ5, //5 Hz
mgottscho 0:8d34cc2ff388 62 HZ2_5, //2.5 Hz
mgottscho 0:8d34cc2ff388 63 HZ1_25, //1.25 Hz
mgottscho 0:8d34cc2ff388 64 HZ0_63, //0.63 Hz
mgottscho 0:8d34cc2ff388 65 HZ0_31, //0.31 Hz
mgottscho 0:8d34cc2ff388 66 HZ0_16, //0.16 Hz
mgottscho 0:8d34cc2ff388 67 HZ0_08 //0.08 Hz
mgottscho 0:8d34cc2ff388 68 } smpl_rate_t;
mgottscho 0:8d34cc2ff388 69
mgottscho 0:8d34cc2ff388 70 /**
mgottscho 0:8d34cc2ff388 71 * @param sda the pin identifier for SDA I2C signal
mgottscho 0:8d34cc2ff388 72 * @param scl the pin identifier for SCL I2C signal
mgottscho 0:8d34cc2ff388 73 * @param i2c_addr the 8-bit I2C address for this device. Note that LSB is a don't care.
mgottscho 0:8d34cc2ff388 74 */
mgottscho 0:8d34cc2ff388 75 MAG3110(PinName sda, PinName scl, int i2c_addr);
mgottscho 0:8d34cc2ff388 76
mgottscho 0:8d34cc2ff388 77 /**
mgottscho 0:8d34cc2ff388 78 *
mgottscho 0:8d34cc2ff388 79 */
mgottscho 0:8d34cc2ff388 80 ~MAG3110();
mgottscho 0:8d34cc2ff388 81
mgottscho 0:8d34cc2ff388 82 /**
mgottscho 0:8d34cc2ff388 83 * Self-initialization to some nice preset. You must ensure the device is first deactivated using setActive().
mgottscho 0:8d34cc2ff388 84 */
mgottscho 0:8d34cc2ff388 85 void selfInit();
mgottscho 0:8d34cc2ff388 86
mgottscho 0:8d34cc2ff388 87 //I2C-specific methods
mgottscho 0:8d34cc2ff388 88
mgottscho 0:8d34cc2ff388 89 /**
mgottscho 0:8d34cc2ff388 90 * Implements the pure virtual method of the parent I2CSensor class.
mgottscho 0:8d34cc2ff388 91 * @returns the 8-bit device identifier.
mgottscho 0:8d34cc2ff388 92 */
mgottscho 0:8d34cc2ff388 93 uint8_t whoAmI();
mgottscho 0:8d34cc2ff388 94
mgottscho 0:8d34cc2ff388 95 //Device-specific methods
mgottscho 0:8d34cc2ff388 96
mgottscho 0:8d34cc2ff388 97 /**
mgottscho 0:8d34cc2ff388 98 * @returns true if the device is active
mgottscho 0:8d34cc2ff388 99 */
mgottscho 0:8d34cc2ff388 100 bool isActive();
mgottscho 0:8d34cc2ff388 101
mgottscho 0:8d34cc2ff388 102 /**
mgottscho 0:8d34cc2ff388 103 * @param activate if true, enables the device, else disables it
mgottscho 0:8d34cc2ff388 104 */
mgottscho 0:8d34cc2ff388 105 void setActive(bool activate);
mgottscho 0:8d34cc2ff388 106
mgottscho 0:8d34cc2ff388 107 /**
mgottscho 0:8d34cc2ff388 108 * @returns the 8-bit system mode status
mgottscho 0:8d34cc2ff388 109 */
mgottscho 0:8d34cc2ff388 110 uint8_t getSystemMode();
mgottscho 0:8d34cc2ff388 111
mgottscho 0:8d34cc2ff388 112 /**
mgottscho 0:8d34cc2ff388 113 * @param rate optional pointer, if provided, will be set to the output sampling rate
mgottscho 0:8d34cc2ff388 114 * @param ratio optional pointer, if provided, will be set to the oversampling ratio
mgottscho 0:8d34cc2ff388 115 * @param adc_rate optional pointer, if provided, will be set to the ADC rate
mgottscho 0:8d34cc2ff388 116 */
mgottscho 0:8d34cc2ff388 117 void getOutputSamplingParameters(smpl_rate_t *rate, oversmpl_ratio_t *ratio, adc_smpl_rate_t *adc_rate);
mgottscho 0:8d34cc2ff388 118
mgottscho 0:8d34cc2ff388 119 /**
mgottscho 0:8d34cc2ff388 120 * @param rate the enumerated value corresponding to the output data sample rate to use
mgottscho 0:8d34cc2ff388 121 * @param ratio the number of ADC samples per output sample (averaged)
mgottscho 0:8d34cc2ff388 122 * @param adc_rate optional pointer, set to the resulting adc_rate used for the combination of rate and ratio
mgottscho 0:8d34cc2ff388 123 * @returns true if the operation succeeded and the first two parameters were correct
mgottscho 0:8d34cc2ff388 124 */
mgottscho 0:8d34cc2ff388 125 bool setOutputSamplingParameters(smpl_rate_t rate, oversmpl_ratio_t ratio, adc_smpl_rate_t *adc_rate);
mgottscho 0:8d34cc2ff388 126
mgottscho 0:8d34cc2ff388 127 /**
mgottscho 0:8d34cc2ff388 128 * @returns the value in the data register
mgottscho 0:8d34cc2ff388 129 */
mgottscho 0:8d34cc2ff388 130 uint8_t getDataRegisterStatus();
mgottscho 0:8d34cc2ff388 131
mgottscho 0:8d34cc2ff388 132
mgottscho 0:8d34cc2ff388 133 //Device-specific data sampling methods
mgottscho 0:8d34cc2ff388 134 /**
mgottscho 0:8d34cc2ff388 135 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 136 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 137 * @returns a 16-bit value representing the latest data sample for the X dimension, centered at 0.
mgottscho 0:8d34cc2ff388 138 */
mgottscho 0:8d34cc2ff388 139 int16_t getX(bool sampleNow);
mgottscho 0:8d34cc2ff388 140
mgottscho 0:8d34cc2ff388 141 /**
mgottscho 0:8d34cc2ff388 142 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 143 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 144 * @returns a 16-bit value representing the latest data sample for the Y dimension, centered at 0.
mgottscho 0:8d34cc2ff388 145 */
mgottscho 0:8d34cc2ff388 146 int16_t getY(bool sampleNow);
mgottscho 0:8d34cc2ff388 147
mgottscho 0:8d34cc2ff388 148 /**
mgottscho 0:8d34cc2ff388 149 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 150 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 151 * @returns a 16-bit value representing the latest data sample for the Z dimension, centered at 0.
mgottscho 0:8d34cc2ff388 152 */
mgottscho 0:8d34cc2ff388 153 int16_t getZ(bool sampleNow);
mgottscho 0:8d34cc2ff388 154
mgottscho 0:8d34cc2ff388 155 /**
mgottscho 0:8d34cc2ff388 156 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 157 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 158 * Returns the latest X data reading as a float in uT
mgottscho 0:8d34cc2ff388 159 */
mgottscho 0:8d34cc2ff388 160 float getFloatX(bool sampleNow);
mgottscho 0:8d34cc2ff388 161
mgottscho 0:8d34cc2ff388 162 /**
mgottscho 0:8d34cc2ff388 163 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 164 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 165 * Returns the latest Y data reading as a float in uT
mgottscho 0:8d34cc2ff388 166 */
mgottscho 0:8d34cc2ff388 167 float getFloatY(bool sampleNow);
mgottscho 0:8d34cc2ff388 168
mgottscho 0:8d34cc2ff388 169 /**
mgottscho 0:8d34cc2ff388 170 * @param sampleNow if true, queries the device for the sample and returns it. if false, gets the last queried value.
mgottscho 0:8d34cc2ff388 171 * The latter is preferred if this object is set up to sample using interrupts.
mgottscho 0:8d34cc2ff388 172 * Returns the latest Z data reading as a float in uT
mgottscho 0:8d34cc2ff388 173 */
mgottscho 0:8d34cc2ff388 174 float getFloatZ(bool sampleNow);
mgottscho 0:8d34cc2ff388 175
mgottscho 0:8d34cc2ff388 176 /**
mgottscho 0:8d34cc2ff388 177 * Get the die temperature. Note that the actual sensor range is only -40C to 125C, so not all outputs are valid.
mgottscho 0:8d34cc2ff388 178 * @returns 8-bit die temperature data
mgottscho 0:8d34cc2ff388 179 */
mgottscho 0:8d34cc2ff388 180 int8_t getDieTemp();
mgottscho 0:8d34cc2ff388 181
mgottscho 0:8d34cc2ff388 182 /**
mgottscho 0:8d34cc2ff388 183 * @returns the die temperature in deg Celsius. Note that the actual sensor range is only -40C to 125C, so not all possible outputs may be valid.
mgottscho 0:8d34cc2ff388 184 */
mgottscho 0:8d34cc2ff388 185 float getFloatDieTemp();
mgottscho 0:8d34cc2ff388 186
mgottscho 0:8d34cc2ff388 187 private:
mgottscho 0:8d34cc2ff388 188 /**
mgottscho 0:8d34cc2ff388 189 * Interrupt service routine for fetching magnetometer data from the device.
mgottscho 0:8d34cc2ff388 190 */
mgottscho 0:8d34cc2ff388 191 virtual void __sample_data_ISR();
mgottscho 0:8d34cc2ff388 192
mgottscho 0:8d34cc2ff388 193 ///////////////// CONSTANTS /////////////////////
mgottscho 0:8d34cc2ff388 194
mgottscho 0:8d34cc2ff388 195 //Device register addresses
mgottscho 0:8d34cc2ff388 196 static const uint8_t DR_STATUS = 0x00;
mgottscho 0:8d34cc2ff388 197 static const uint8_t OUT_X_MSB = 0x01;
mgottscho 0:8d34cc2ff388 198 static const uint8_t OUT_X_LSB = 0x02;
mgottscho 0:8d34cc2ff388 199 static const uint8_t OUT_Y_MSB = 0x03;
mgottscho 0:8d34cc2ff388 200 static const uint8_t OUT_Y_LSB = 0x04;
mgottscho 0:8d34cc2ff388 201 static const uint8_t OUT_Z_MSB = 0x05;
mgottscho 0:8d34cc2ff388 202 static const uint8_t OUT_Z_LSB = 0x06;
mgottscho 0:8d34cc2ff388 203 static const uint8_t WHO_AM_I = 0x07;
mgottscho 0:8d34cc2ff388 204 static const uint8_t SYSMOD = 0x08;
mgottscho 0:8d34cc2ff388 205 static const uint8_t OFF_X_MSB = 0x09;
mgottscho 0:8d34cc2ff388 206 static const uint8_t OFF_X_LSB = 0x0A;
mgottscho 0:8d34cc2ff388 207 static const uint8_t OFF_Y_MSB = 0x0B;
mgottscho 0:8d34cc2ff388 208 static const uint8_t OFF_Y_LSB = 0x0C;
mgottscho 0:8d34cc2ff388 209 static const uint8_t OFF_Z_MSB = 0x0D;
mgottscho 0:8d34cc2ff388 210 static const uint8_t OFF_Z_LSB = 0x0E;
mgottscho 0:8d34cc2ff388 211 static const uint8_t DIE_TEMP = 0x0F;
mgottscho 0:8d34cc2ff388 212 static const uint8_t CTRL_REG1 = 0x10;
mgottscho 0:8d34cc2ff388 213 static const uint8_t CTRL_REG2 = 0x11;
mgottscho 0:8d34cc2ff388 214
mgottscho 0:8d34cc2ff388 215 //Register masks
mgottscho 0:8d34cc2ff388 216 static const uint8_t DR_STATUS_ZYXOW_MASK = 0x80; //b1000 0000
mgottscho 0:8d34cc2ff388 217 static const uint8_t DR_STATUS_ZOW_MASK = 0x40; //b0100 0000
mgottscho 0:8d34cc2ff388 218 static const uint8_t DR_STATUS_YOW_MASK = 0x20; //b0010 0000
mgottscho 0:8d34cc2ff388 219 static const uint8_t DR_STATUS_XOW_MASK = 0x10; //b0001 0000
mgottscho 0:8d34cc2ff388 220 static const uint8_t DR_STATUS_ZYXDR_MASK = 0x08; //b0000 1000
mgottscho 0:8d34cc2ff388 221 static const uint8_t DR_STATUS_ZDR_MASK = 0x04; //b0000 0100
mgottscho 0:8d34cc2ff388 222 static const uint8_t DR_STATUS_YDR_MASK = 0x02; //b0000 0010
mgottscho 0:8d34cc2ff388 223 static const uint8_t DR_STATUS_XDR_MASK = 0x01; //b0000 0001
mgottscho 0:8d34cc2ff388 224 static const uint8_t SYSMOD_MASK = 0x03; //b0000 0011
mgottscho 0:8d34cc2ff388 225 static const uint8_t OFF_X_LSB_MASK = 0xFE; //b1111 1110
mgottscho 0:8d34cc2ff388 226 static const uint8_t OFF_Y_LSB_MASK = 0xFE; //b1111 1110
mgottscho 0:8d34cc2ff388 227 static const uint8_t OFF_Z_LSB_MASK = 0xFE; //b1111 1110
mgottscho 0:8d34cc2ff388 228 static const uint8_t CTRL_REG1_DR_MASK = 0xB0; //b1110 0000
mgottscho 0:8d34cc2ff388 229 static const uint8_t CTRL_REG1_OS_MASK = 0x18; //b0001 1000
mgottscho 0:8d34cc2ff388 230 static const uint8_t CTRL_REG1_FR_MASK = 0x04; //b0000 0100
mgottscho 0:8d34cc2ff388 231 static const uint8_t CTRL_REG1_TM_MASK = 0x02; //b0000 0010
mgottscho 0:8d34cc2ff388 232 static const uint8_t CTRL_REG1_AC_MASK = 0x01; //b0000 0001
mgottscho 0:8d34cc2ff388 233 static const uint8_t CTRL_REG2_AUTO_MRST_EN_MASK = 0x80; //b1000 0000
mgottscho 0:8d34cc2ff388 234 static const uint8_t CTRL_REG2_RAW_MASK = 0x20; //b0010 0000
mgottscho 0:8d34cc2ff388 235 static const uint8_t CTRL_REG2_MAG_RST_MASK = 0x10; //b0001 0000
mgottscho 0:8d34cc2ff388 236
mgottscho 0:8d34cc2ff388 237 //Mapping of data values
mgottscho 0:8d34cc2ff388 238 static const float TEMP_DIV = 1; //deg Celsius/level. Note that 8-bit range is -128C to 127C, but the sensor can only do -40C to 125C.
mgottscho 0:8d34cc2ff388 239 static const float DATA_CONVERSION = 0.10; //uT/level
mgottscho 0:8d34cc2ff388 240
mgottscho 0:8d34cc2ff388 241 //////////////// VARIABLES /////////////////////
mgottscho 0:8d34cc2ff388 242 //MAG3110 state ("cached" from the values actually on the device)
mgottscho 0:8d34cc2ff388 243 volatile int16_t __x;
mgottscho 0:8d34cc2ff388 244 volatile int16_t __y;
mgottscho 0:8d34cc2ff388 245 volatile int16_t __z;
mgottscho 0:8d34cc2ff388 246
mgottscho 0:8d34cc2ff388 247 bool __active;
mgottscho 0:8d34cc2ff388 248 adc_smpl_rate_t __adc_rate;
mgottscho 0:8d34cc2ff388 249 oversmpl_ratio_t __ratio;
mgottscho 0:8d34cc2ff388 250 smpl_rate_t __rate;
mgottscho 0:8d34cc2ff388 251 };
mgottscho 0:8d34cc2ff388 252
mgottscho 0:8d34cc2ff388 253 #endif