Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/inc/drivers/MicroBitCompass.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /*
MrBedfordVan 0:b9164b348919 2 The MIT License (MIT)
MrBedfordVan 0:b9164b348919 3
MrBedfordVan 0:b9164b348919 4 Copyright (c) 2016 British Broadcasting Corporation.
MrBedfordVan 0:b9164b348919 5 This software is provided by Lancaster University by arrangement with the BBC.
MrBedfordVan 0:b9164b348919 6
MrBedfordVan 0:b9164b348919 7 Permission is hereby granted, free of charge, to any person obtaining a
MrBedfordVan 0:b9164b348919 8 copy of this software and associated documentation files (the "Software"),
MrBedfordVan 0:b9164b348919 9 to deal in the Software without restriction, including without limitation
MrBedfordVan 0:b9164b348919 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
MrBedfordVan 0:b9164b348919 11 and/or sell copies of the Software, and to permit persons to whom the
MrBedfordVan 0:b9164b348919 12 Software is furnished to do so, subject to the following conditions:
MrBedfordVan 0:b9164b348919 13
MrBedfordVan 0:b9164b348919 14 The above copyright notice and this permission notice shall be included in
MrBedfordVan 0:b9164b348919 15 all copies or substantial portions of the Software.
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
MrBedfordVan 0:b9164b348919 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
MrBedfordVan 0:b9164b348919 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
MrBedfordVan 0:b9164b348919 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
MrBedfordVan 0:b9164b348919 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
MrBedfordVan 0:b9164b348919 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
MrBedfordVan 0:b9164b348919 23 DEALINGS IN THE SOFTWARE.
MrBedfordVan 0:b9164b348919 24 */
MrBedfordVan 0:b9164b348919 25
MrBedfordVan 0:b9164b348919 26 #ifndef MICROBIT_COMPASS_H
MrBedfordVan 0:b9164b348919 27 #define MICROBIT_COMPASS_H
MrBedfordVan 0:b9164b348919 28
MrBedfordVan 0:b9164b348919 29 #include "mbed.h"
MrBedfordVan 0:b9164b348919 30 #include "MicroBitConfig.h"
MrBedfordVan 0:b9164b348919 31 #include "MicroBitComponent.h"
MrBedfordVan 0:b9164b348919 32 #include "MicroBitCoordinateSystem.h"
MrBedfordVan 0:b9164b348919 33 #include "MicroBitAccelerometer.h"
MrBedfordVan 0:b9164b348919 34 #include "MicroBitStorage.h"
MrBedfordVan 0:b9164b348919 35
MrBedfordVan 0:b9164b348919 36 /**
MrBedfordVan 0:b9164b348919 37 * Relevant pin assignments
MrBedfordVan 0:b9164b348919 38 */
MrBedfordVan 0:b9164b348919 39 #define MICROBIT_PIN_COMPASS_DATA_READY P0_29
MrBedfordVan 0:b9164b348919 40
MrBedfordVan 0:b9164b348919 41 /**
MrBedfordVan 0:b9164b348919 42 * I2C constants
MrBedfordVan 0:b9164b348919 43 */
MrBedfordVan 0:b9164b348919 44 #define MAG3110_DEFAULT_ADDR 0x1D
MrBedfordVan 0:b9164b348919 45
MrBedfordVan 0:b9164b348919 46 /**
MrBedfordVan 0:b9164b348919 47 * MAG3110 Register map
MrBedfordVan 0:b9164b348919 48 */
MrBedfordVan 0:b9164b348919 49 #define MAG_DR_STATUS 0x00
MrBedfordVan 0:b9164b348919 50 #define MAG_OUT_X_MSB 0x01
MrBedfordVan 0:b9164b348919 51 #define MAG_OUT_X_LSB 0x02
MrBedfordVan 0:b9164b348919 52 #define MAG_OUT_Y_MSB 0x03
MrBedfordVan 0:b9164b348919 53 #define MAG_OUT_Y_LSB 0x04
MrBedfordVan 0:b9164b348919 54 #define MAG_OUT_Z_MSB 0x05
MrBedfordVan 0:b9164b348919 55 #define MAG_OUT_Z_LSB 0x06
MrBedfordVan 0:b9164b348919 56 #define MAG_WHOAMI 0x07
MrBedfordVan 0:b9164b348919 57 #define MAG_SYSMOD 0x08
MrBedfordVan 0:b9164b348919 58 #define MAG_OFF_X_MSB 0x09
MrBedfordVan 0:b9164b348919 59 #define MAG_OFF_X_LSB 0x0A
MrBedfordVan 0:b9164b348919 60 #define MAG_OFF_Y_MSB 0x0B
MrBedfordVan 0:b9164b348919 61 #define MAG_OFF_Y_LSB 0x0C
MrBedfordVan 0:b9164b348919 62 #define MAG_OFF_Z_MSB 0x0D
MrBedfordVan 0:b9164b348919 63 #define MAG_OFF_Z_LSB 0x0E
MrBedfordVan 0:b9164b348919 64 #define MAG_DIE_TEMP 0x0F
MrBedfordVan 0:b9164b348919 65 #define MAG_CTRL_REG1 0x10
MrBedfordVan 0:b9164b348919 66 #define MAG_CTRL_REG2 0x11
MrBedfordVan 0:b9164b348919 67
MrBedfordVan 0:b9164b348919 68 /**
MrBedfordVan 0:b9164b348919 69 * Configuration options
MrBedfordVan 0:b9164b348919 70 */
MrBedfordVan 0:b9164b348919 71 struct MAG3110SampleRateConfig
MrBedfordVan 0:b9164b348919 72 {
MrBedfordVan 0:b9164b348919 73 uint32_t sample_period;
MrBedfordVan 0:b9164b348919 74 uint8_t ctrl_reg1;
MrBedfordVan 0:b9164b348919 75 };
MrBedfordVan 0:b9164b348919 76
MrBedfordVan 0:b9164b348919 77 extern const MAG3110SampleRateConfig MAG3110SampleRate[];
MrBedfordVan 0:b9164b348919 78
MrBedfordVan 0:b9164b348919 79 #define MAG3110_SAMPLE_RATES 11
MrBedfordVan 0:b9164b348919 80
MrBedfordVan 0:b9164b348919 81 /**
MrBedfordVan 0:b9164b348919 82 * Compass events
MrBedfordVan 0:b9164b348919 83 */
MrBedfordVan 0:b9164b348919 84 #define MICROBIT_COMPASS_EVT_CAL_REQUIRED 1 // DEPRECATED
MrBedfordVan 0:b9164b348919 85 #define MICROBIT_COMPASS_EVT_CAL_START 2 // DEPRECATED
MrBedfordVan 0:b9164b348919 86 #define MICROBIT_COMPASS_EVT_CAL_END 3 // DEPRECATED
MrBedfordVan 0:b9164b348919 87
MrBedfordVan 0:b9164b348919 88 #define MICROBIT_COMPASS_EVT_DATA_UPDATE 4
MrBedfordVan 0:b9164b348919 89 #define MICROBIT_COMPASS_EVT_CONFIG_NEEDED 5
MrBedfordVan 0:b9164b348919 90 #define MICROBIT_COMPASS_EVT_CALIBRATE 6
MrBedfordVan 0:b9164b348919 91
MrBedfordVan 0:b9164b348919 92 /**
MrBedfordVan 0:b9164b348919 93 * Status Bits
MrBedfordVan 0:b9164b348919 94 */
MrBedfordVan 0:b9164b348919 95 #define MICROBIT_COMPASS_STATUS_CALIBRATED 2
MrBedfordVan 0:b9164b348919 96 #define MICROBIT_COMPASS_STATUS_CALIBRATING 4
MrBedfordVan 0:b9164b348919 97 #define MICROBIT_COMPASS_STATUS_ADDED_TO_IDLE 8
MrBedfordVan 0:b9164b348919 98
MrBedfordVan 0:b9164b348919 99 /**
MrBedfordVan 0:b9164b348919 100 * Term to convert sample data into SI units
MrBedfordVan 0:b9164b348919 101 */
MrBedfordVan 0:b9164b348919 102 #define MAG3110_NORMALIZE_SAMPLE(x) (100*x)
MrBedfordVan 0:b9164b348919 103
MrBedfordVan 0:b9164b348919 104 /**
MrBedfordVan 0:b9164b348919 105 * MAG3110 MAGIC ID value
MrBedfordVan 0:b9164b348919 106 * Returned from the MAG_WHO_AM_I register for ID purposes.
MrBedfordVan 0:b9164b348919 107 */
MrBedfordVan 0:b9164b348919 108 #define MAG3110_WHOAMI_VAL 0xC4
MrBedfordVan 0:b9164b348919 109
MrBedfordVan 0:b9164b348919 110 struct CompassSample
MrBedfordVan 0:b9164b348919 111 {
MrBedfordVan 0:b9164b348919 112 int x;
MrBedfordVan 0:b9164b348919 113 int y;
MrBedfordVan 0:b9164b348919 114 int z;
MrBedfordVan 0:b9164b348919 115
MrBedfordVan 0:b9164b348919 116 CompassSample()
MrBedfordVan 0:b9164b348919 117 {
MrBedfordVan 0:b9164b348919 118 this->x = 0;
MrBedfordVan 0:b9164b348919 119 this->y = 0;
MrBedfordVan 0:b9164b348919 120 this->z = 0;
MrBedfordVan 0:b9164b348919 121 }
MrBedfordVan 0:b9164b348919 122
MrBedfordVan 0:b9164b348919 123 CompassSample(int x, int y, int z)
MrBedfordVan 0:b9164b348919 124 {
MrBedfordVan 0:b9164b348919 125 this->x = x;
MrBedfordVan 0:b9164b348919 126 this->y = y;
MrBedfordVan 0:b9164b348919 127 this->z = z;
MrBedfordVan 0:b9164b348919 128 }
MrBedfordVan 0:b9164b348919 129
MrBedfordVan 0:b9164b348919 130 bool operator==(const CompassSample& other) const
MrBedfordVan 0:b9164b348919 131 {
MrBedfordVan 0:b9164b348919 132 return x == other.x && y == other.y && z == other.z;
MrBedfordVan 0:b9164b348919 133 }
MrBedfordVan 0:b9164b348919 134
MrBedfordVan 0:b9164b348919 135 bool operator!=(const CompassSample& other) const
MrBedfordVan 0:b9164b348919 136 {
MrBedfordVan 0:b9164b348919 137 return !(x == other.x && y == other.y && z == other.z);
MrBedfordVan 0:b9164b348919 138 }
MrBedfordVan 0:b9164b348919 139 };
MrBedfordVan 0:b9164b348919 140
MrBedfordVan 0:b9164b348919 141 /**
MrBedfordVan 0:b9164b348919 142 * Class definition for MicroBit Compass.
MrBedfordVan 0:b9164b348919 143 *
MrBedfordVan 0:b9164b348919 144 * Represents an implementation of the Freescale MAG3110 I2C Magnetmometer.
MrBedfordVan 0:b9164b348919 145 * Also includes basic caching, calibration and on demand activation.
MrBedfordVan 0:b9164b348919 146 */
MrBedfordVan 0:b9164b348919 147 class MicroBitCompass : public MicroBitComponent
MrBedfordVan 0:b9164b348919 148 {
MrBedfordVan 0:b9164b348919 149 uint16_t address; // I2C address of the magnetmometer.
MrBedfordVan 0:b9164b348919 150 uint16_t samplePeriod; // The time between samples, in millseconds.
MrBedfordVan 0:b9164b348919 151
MrBedfordVan 0:b9164b348919 152 CompassSample average; // Centre point of sample data.
MrBedfordVan 0:b9164b348919 153 CompassSample sample; // The latest sample data recorded.
MrBedfordVan 0:b9164b348919 154 DigitalIn int1; // Data ready interrupt.
MrBedfordVan 0:b9164b348919 155 MicroBitI2C& i2c; // The I2C interface the sensor is connected to.
MrBedfordVan 0:b9164b348919 156 MicroBitAccelerometer* accelerometer; // The accelerometer to use for tilt compensation.
MrBedfordVan 0:b9164b348919 157 MicroBitStorage* storage; // An instance of MicroBitStorage used for persistence.
MrBedfordVan 0:b9164b348919 158
MrBedfordVan 0:b9164b348919 159 public:
MrBedfordVan 0:b9164b348919 160
MrBedfordVan 0:b9164b348919 161 /**
MrBedfordVan 0:b9164b348919 162 * Constructor.
MrBedfordVan 0:b9164b348919 163 * Create a software representation of an e-compass.
MrBedfordVan 0:b9164b348919 164 *
MrBedfordVan 0:b9164b348919 165 * @param _i2c an instance of i2c, which the compass is accessible from.
MrBedfordVan 0:b9164b348919 166 *
MrBedfordVan 0:b9164b348919 167 * @param _accelerometer an instance of the accelerometer, used for tilt compensation.
MrBedfordVan 0:b9164b348919 168 *
MrBedfordVan 0:b9164b348919 169 * @param _storage an instance of MicroBitStorage, used to persist calibration data across resets.
MrBedfordVan 0:b9164b348919 170 *
MrBedfordVan 0:b9164b348919 171 * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 172 *
MrBedfordVan 0:b9164b348919 173 * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 174 *
MrBedfordVan 0:b9164b348919 175 * @code
MrBedfordVan 0:b9164b348919 176 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
MrBedfordVan 0:b9164b348919 177 *
MrBedfordVan 0:b9164b348919 178 * MicroBitAccelerometer accelerometer(i2c);
MrBedfordVan 0:b9164b348919 179 *
MrBedfordVan 0:b9164b348919 180 * MicroBitStorage storage;
MrBedfordVan 0:b9164b348919 181 *
MrBedfordVan 0:b9164b348919 182 * MicroBitCompass compass(i2c, accelerometer, storage);
MrBedfordVan 0:b9164b348919 183 * @endcode
MrBedfordVan 0:b9164b348919 184 */
MrBedfordVan 0:b9164b348919 185 MicroBitCompass(MicroBitI2C& _i2c, MicroBitAccelerometer& _accelerometer, MicroBitStorage& _storage, uint16_t address = MAG3110_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_COMPASS);
MrBedfordVan 0:b9164b348919 186
MrBedfordVan 0:b9164b348919 187 /**
MrBedfordVan 0:b9164b348919 188 * Constructor.
MrBedfordVan 0:b9164b348919 189 * Create a software representation of an e-compass.
MrBedfordVan 0:b9164b348919 190 *
MrBedfordVan 0:b9164b348919 191 * @param _i2c an instance of i2c, which the compass is accessible from.
MrBedfordVan 0:b9164b348919 192 *
MrBedfordVan 0:b9164b348919 193 * @param _accelerometer an instance of the accelerometer, used for tilt compensation.
MrBedfordVan 0:b9164b348919 194 *
MrBedfordVan 0:b9164b348919 195 * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 196 *
MrBedfordVan 0:b9164b348919 197 * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 198 *
MrBedfordVan 0:b9164b348919 199 * @code
MrBedfordVan 0:b9164b348919 200 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
MrBedfordVan 0:b9164b348919 201 *
MrBedfordVan 0:b9164b348919 202 * MicroBitAccelerometer accelerometer(i2c);
MrBedfordVan 0:b9164b348919 203 *
MrBedfordVan 0:b9164b348919 204 * MicroBitCompass compass(i2c, accelerometer, storage);
MrBedfordVan 0:b9164b348919 205 * @endcode
MrBedfordVan 0:b9164b348919 206 */
MrBedfordVan 0:b9164b348919 207 MicroBitCompass(MicroBitI2C& _i2c, MicroBitAccelerometer& _accelerometer, uint16_t address = MAG3110_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_COMPASS);
MrBedfordVan 0:b9164b348919 208
MrBedfordVan 0:b9164b348919 209 /**
MrBedfordVan 0:b9164b348919 210 * Constructor.
MrBedfordVan 0:b9164b348919 211 * Create a software representation of an e-compass.
MrBedfordVan 0:b9164b348919 212 *
MrBedfordVan 0:b9164b348919 213 * @param _i2c an instance of i2c, which the compass is accessible from.
MrBedfordVan 0:b9164b348919 214 *
MrBedfordVan 0:b9164b348919 215 * @param _storage an instance of MicroBitStorage, used to persist calibration data across resets.
MrBedfordVan 0:b9164b348919 216 *
MrBedfordVan 0:b9164b348919 217 * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 218 *
MrBedfordVan 0:b9164b348919 219 * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 220 *
MrBedfordVan 0:b9164b348919 221 * @code
MrBedfordVan 0:b9164b348919 222 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
MrBedfordVan 0:b9164b348919 223 *
MrBedfordVan 0:b9164b348919 224 * MicroBitStorage storage;
MrBedfordVan 0:b9164b348919 225 *
MrBedfordVan 0:b9164b348919 226 * MicroBitCompass compass(i2c, storage);
MrBedfordVan 0:b9164b348919 227 * @endcode
MrBedfordVan 0:b9164b348919 228 */
MrBedfordVan 0:b9164b348919 229 MicroBitCompass(MicroBitI2C& _i2c, MicroBitStorage& _storage, uint16_t address = MAG3110_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_COMPASS);
MrBedfordVan 0:b9164b348919 230
MrBedfordVan 0:b9164b348919 231 /**
MrBedfordVan 0:b9164b348919 232 * Constructor.
MrBedfordVan 0:b9164b348919 233 * Create a software representation of an e-compass.
MrBedfordVan 0:b9164b348919 234 *
MrBedfordVan 0:b9164b348919 235 * @param _i2c an instance of i2c, which the compass is accessible from.
MrBedfordVan 0:b9164b348919 236 *
MrBedfordVan 0:b9164b348919 237 * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 238 *
MrBedfordVan 0:b9164b348919 239 * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 240 *
MrBedfordVan 0:b9164b348919 241 * @code
MrBedfordVan 0:b9164b348919 242 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
MrBedfordVan 0:b9164b348919 243 *
MrBedfordVan 0:b9164b348919 244 * MicroBitCompass compass(i2c);
MrBedfordVan 0:b9164b348919 245 * @endcode
MrBedfordVan 0:b9164b348919 246 */
MrBedfordVan 0:b9164b348919 247 MicroBitCompass(MicroBitI2C& _i2c, uint16_t address = MAG3110_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_COMPASS);
MrBedfordVan 0:b9164b348919 248
MrBedfordVan 0:b9164b348919 249 /**
MrBedfordVan 0:b9164b348919 250 * Configures the compass for the sample rate defined in this object.
MrBedfordVan 0:b9164b348919 251 * The nearest values are chosen to those defined that are supported by the hardware.
MrBedfordVan 0:b9164b348919 252 * The instance variables are then updated to reflect reality.
MrBedfordVan 0:b9164b348919 253 *
MrBedfordVan 0:b9164b348919 254 * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be configured.
MrBedfordVan 0:b9164b348919 255 */
MrBedfordVan 0:b9164b348919 256 int configure();
MrBedfordVan 0:b9164b348919 257
MrBedfordVan 0:b9164b348919 258 /**
MrBedfordVan 0:b9164b348919 259 * Attempts to set the sample rate of the compass to the specified value (in ms).
MrBedfordVan 0:b9164b348919 260 *
MrBedfordVan 0:b9164b348919 261 * @param period the requested time between samples, in milliseconds.
MrBedfordVan 0:b9164b348919 262 *
MrBedfordVan 0:b9164b348919 263 * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
MrBedfordVan 0:b9164b348919 264 *
MrBedfordVan 0:b9164b348919 265 * @code
MrBedfordVan 0:b9164b348919 266 * // sample rate is now 20 ms.
MrBedfordVan 0:b9164b348919 267 * compass.setPeriod(20);
MrBedfordVan 0:b9164b348919 268 * @endcode
MrBedfordVan 0:b9164b348919 269 *
MrBedfordVan 0:b9164b348919 270 * @note The requested rate may not be possible on the hardware. In this case, the
MrBedfordVan 0:b9164b348919 271 * nearest lower rate is chosen.
MrBedfordVan 0:b9164b348919 272 */
MrBedfordVan 0:b9164b348919 273 int setPeriod(int period);
MrBedfordVan 0:b9164b348919 274
MrBedfordVan 0:b9164b348919 275 /**
MrBedfordVan 0:b9164b348919 276 * Reads the currently configured sample rate of the compass.
MrBedfordVan 0:b9164b348919 277 *
MrBedfordVan 0:b9164b348919 278 * @return The time between samples, in milliseconds.
MrBedfordVan 0:b9164b348919 279 */
MrBedfordVan 0:b9164b348919 280 int getPeriod();
MrBedfordVan 0:b9164b348919 281
MrBedfordVan 0:b9164b348919 282 /**
MrBedfordVan 0:b9164b348919 283 * Gets the current heading of the device, relative to magnetic north.
MrBedfordVan 0:b9164b348919 284 *
MrBedfordVan 0:b9164b348919 285 * If the compass is not calibrated, it will raise the MICROBIT_COMPASS_EVT_CALIBRATE event.
MrBedfordVan 0:b9164b348919 286 *
MrBedfordVan 0:b9164b348919 287 * Users wishing to implement their own calibration algorithms should listen for this event,
MrBedfordVan 0:b9164b348919 288 * using MESSAGE_BUS_LISTENER_IMMEDIATE model. This ensures that calibration is complete before
MrBedfordVan 0:b9164b348919 289 * the user program continues.
MrBedfordVan 0:b9164b348919 290 *
MrBedfordVan 0:b9164b348919 291 * @return the current heading, in degrees. Or MICROBIT_CALIBRATION_IN_PROGRESS if the compass is calibrating.
MrBedfordVan 0:b9164b348919 292 *
MrBedfordVan 0:b9164b348919 293 * @code
MrBedfordVan 0:b9164b348919 294 * compass.heading();
MrBedfordVan 0:b9164b348919 295 * @endcode
MrBedfordVan 0:b9164b348919 296 */
MrBedfordVan 0:b9164b348919 297 int heading();
MrBedfordVan 0:b9164b348919 298
MrBedfordVan 0:b9164b348919 299 /**
MrBedfordVan 0:b9164b348919 300 * Attempts to read the 8 bit ID from the magnetometer, this can be used for
MrBedfordVan 0:b9164b348919 301 * validation purposes.
MrBedfordVan 0:b9164b348919 302 *
MrBedfordVan 0:b9164b348919 303 * @return the 8 bit ID returned by the magnetometer, or MICROBIT_I2C_ERROR if the request fails.
MrBedfordVan 0:b9164b348919 304 *
MrBedfordVan 0:b9164b348919 305 * @code
MrBedfordVan 0:b9164b348919 306 * compass.whoAmI();
MrBedfordVan 0:b9164b348919 307 * @endcode
MrBedfordVan 0:b9164b348919 308 */
MrBedfordVan 0:b9164b348919 309 int whoAmI();
MrBedfordVan 0:b9164b348919 310
MrBedfordVan 0:b9164b348919 311 /**
MrBedfordVan 0:b9164b348919 312 * Reads the value of the X axis from the latest update retrieved from the magnetometer.
MrBedfordVan 0:b9164b348919 313 *
MrBedfordVan 0:b9164b348919 314 * @param system The coordinate system to use. By default, a simple cartesian system is provided.
MrBedfordVan 0:b9164b348919 315 *
MrBedfordVan 0:b9164b348919 316 * @return The magnetic force measured in the X axis, in nano teslas.
MrBedfordVan 0:b9164b348919 317 *
MrBedfordVan 0:b9164b348919 318 * @code
MrBedfordVan 0:b9164b348919 319 * compass.getX();
MrBedfordVan 0:b9164b348919 320 * @endcode
MrBedfordVan 0:b9164b348919 321 */
MrBedfordVan 0:b9164b348919 322 int getX(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 323
MrBedfordVan 0:b9164b348919 324 /**
MrBedfordVan 0:b9164b348919 325 * Reads the value of the Y axis from the latest update retrieved from the magnetometer.
MrBedfordVan 0:b9164b348919 326 *
MrBedfordVan 0:b9164b348919 327 * @param system The coordinate system to use. By default, a simple cartesian system is provided.
MrBedfordVan 0:b9164b348919 328 *
MrBedfordVan 0:b9164b348919 329 * @return The magnetic force measured in the Y axis, in nano teslas.
MrBedfordVan 0:b9164b348919 330 *
MrBedfordVan 0:b9164b348919 331 * @code
MrBedfordVan 0:b9164b348919 332 * compass.getY();
MrBedfordVan 0:b9164b348919 333 * @endcode
MrBedfordVan 0:b9164b348919 334 */
MrBedfordVan 0:b9164b348919 335 int getY(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 336
MrBedfordVan 0:b9164b348919 337 /**
MrBedfordVan 0:b9164b348919 338 * Reads the value of the Z axis from the latest update retrieved from the magnetometer.
MrBedfordVan 0:b9164b348919 339 *
MrBedfordVan 0:b9164b348919 340 * @param system The coordinate system to use. By default, a simple cartesian system is provided.
MrBedfordVan 0:b9164b348919 341 *
MrBedfordVan 0:b9164b348919 342 * @return The magnetic force measured in the Z axis, in nano teslas.
MrBedfordVan 0:b9164b348919 343 *
MrBedfordVan 0:b9164b348919 344 * @code
MrBedfordVan 0:b9164b348919 345 * compass.getZ();
MrBedfordVan 0:b9164b348919 346 * @endcode
MrBedfordVan 0:b9164b348919 347 */
MrBedfordVan 0:b9164b348919 348 int getZ(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 349
MrBedfordVan 0:b9164b348919 350 /**
MrBedfordVan 0:b9164b348919 351 * Determines the overall magnetic field strength based on the latest update from the magnetometer.
MrBedfordVan 0:b9164b348919 352 *
MrBedfordVan 0:b9164b348919 353 * @return The magnetic force measured across all axis, in nano teslas.
MrBedfordVan 0:b9164b348919 354 *
MrBedfordVan 0:b9164b348919 355 * @code
MrBedfordVan 0:b9164b348919 356 * compass.getFieldStrength();
MrBedfordVan 0:b9164b348919 357 * @endcode
MrBedfordVan 0:b9164b348919 358 */
MrBedfordVan 0:b9164b348919 359 int getFieldStrength();
MrBedfordVan 0:b9164b348919 360
MrBedfordVan 0:b9164b348919 361 /**
MrBedfordVan 0:b9164b348919 362 * Reads the current die temperature of the compass.
MrBedfordVan 0:b9164b348919 363 *
MrBedfordVan 0:b9164b348919 364 * @return the temperature in degrees celsius, or MICROBIT_I2C_ERROR if the temperature reading could not be retreived
MrBedfordVan 0:b9164b348919 365 * from the accelerometer.
MrBedfordVan 0:b9164b348919 366 */
MrBedfordVan 0:b9164b348919 367 int readTemperature();
MrBedfordVan 0:b9164b348919 368
MrBedfordVan 0:b9164b348919 369 /**
MrBedfordVan 0:b9164b348919 370 * Perform a calibration of the compass.
MrBedfordVan 0:b9164b348919 371 *
MrBedfordVan 0:b9164b348919 372 * This method will be called automatically if a user attempts to read a compass value when
MrBedfordVan 0:b9164b348919 373 * the compass is uncalibrated. It can also be called at any time by the user.
MrBedfordVan 0:b9164b348919 374 *
MrBedfordVan 0:b9164b348919 375 * The method will only return once the compass has been calibrated.
MrBedfordVan 0:b9164b348919 376 *
MrBedfordVan 0:b9164b348919 377 * @return MICROBIT_OK, MICROBIT_I2C_ERROR if the magnetometer could not be accessed,
MrBedfordVan 0:b9164b348919 378 * or MICROBIT_CALIBRATION_REQUIRED if the calibration algorithm failed to complete successfully.
MrBedfordVan 0:b9164b348919 379 *
MrBedfordVan 0:b9164b348919 380 * @note THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS
MrBedfordVan 0:b9164b348919 381 */
MrBedfordVan 0:b9164b348919 382 int calibrate();
MrBedfordVan 0:b9164b348919 383
MrBedfordVan 0:b9164b348919 384 /**
MrBedfordVan 0:b9164b348919 385 * Configure the compass to use the calibration data that is supplied to this call.
MrBedfordVan 0:b9164b348919 386 *
MrBedfordVan 0:b9164b348919 387 * Calibration data is comprised of the perceived zero offset of each axis of the compass.
MrBedfordVan 0:b9164b348919 388 *
MrBedfordVan 0:b9164b348919 389 * After calibration this should now take into account trimming errors in the magnetometer,
MrBedfordVan 0:b9164b348919 390 * and any "hard iron" offsets on the device.
MrBedfordVan 0:b9164b348919 391 *
MrBedfordVan 0:b9164b348919 392 * @param calibration A CompassSample containing the offsets for the x, y and z axis.
MrBedfordVan 0:b9164b348919 393 */
MrBedfordVan 0:b9164b348919 394 void setCalibration(CompassSample calibration);
MrBedfordVan 0:b9164b348919 395
MrBedfordVan 0:b9164b348919 396 /**
MrBedfordVan 0:b9164b348919 397 * Provides the calibration data currently in use by the compass.
MrBedfordVan 0:b9164b348919 398 *
MrBedfordVan 0:b9164b348919 399 * More specifically, the x, y and z zero offsets of the compass.
MrBedfordVan 0:b9164b348919 400 *
MrBedfordVan 0:b9164b348919 401 * @return calibration A CompassSample containing the offsets for the x, y and z axis.
MrBedfordVan 0:b9164b348919 402 */
MrBedfordVan 0:b9164b348919 403 CompassSample getCalibration();
MrBedfordVan 0:b9164b348919 404
MrBedfordVan 0:b9164b348919 405 /**
MrBedfordVan 0:b9164b348919 406 * Updates the local sample, only if the compass indicates that
MrBedfordVan 0:b9164b348919 407 * data is stale.
MrBedfordVan 0:b9164b348919 408 *
MrBedfordVan 0:b9164b348919 409 * @note Can be used to trigger manual updates, if the device is running without a scheduler.
MrBedfordVan 0:b9164b348919 410 * Also called internally by all get[X,Y,Z]() member functions.
MrBedfordVan 0:b9164b348919 411 */
MrBedfordVan 0:b9164b348919 412 int updateSample();
MrBedfordVan 0:b9164b348919 413
MrBedfordVan 0:b9164b348919 414 /**
MrBedfordVan 0:b9164b348919 415 * Periodic callback from MicroBit idle thread.
MrBedfordVan 0:b9164b348919 416 *
MrBedfordVan 0:b9164b348919 417 * Calls updateSample().
MrBedfordVan 0:b9164b348919 418 */
MrBedfordVan 0:b9164b348919 419 virtual void idleTick();
MrBedfordVan 0:b9164b348919 420
MrBedfordVan 0:b9164b348919 421 /**
MrBedfordVan 0:b9164b348919 422 * Returns 0 or 1. 1 indicates that the compass is calibrated, zero means the compass requires calibration.
MrBedfordVan 0:b9164b348919 423 */
MrBedfordVan 0:b9164b348919 424 int isCalibrated();
MrBedfordVan 0:b9164b348919 425
MrBedfordVan 0:b9164b348919 426 /**
MrBedfordVan 0:b9164b348919 427 * Returns 0 or 1. 1 indicates that the compass is calibrating, zero means the compass is not currently calibrating.
MrBedfordVan 0:b9164b348919 428 */
MrBedfordVan 0:b9164b348919 429 int isCalibrating();
MrBedfordVan 0:b9164b348919 430
MrBedfordVan 0:b9164b348919 431 /**
MrBedfordVan 0:b9164b348919 432 * Clears the calibration held in persistent storage, and sets the calibrated flag to zero.
MrBedfordVan 0:b9164b348919 433 */
MrBedfordVan 0:b9164b348919 434 void clearCalibration();
MrBedfordVan 0:b9164b348919 435
MrBedfordVan 0:b9164b348919 436 /**
MrBedfordVan 0:b9164b348919 437 * Destructor for MicroBitCompass, where we deregister this instance from the array of fiber components.
MrBedfordVan 0:b9164b348919 438 */
MrBedfordVan 0:b9164b348919 439 ~MicroBitCompass();
MrBedfordVan 0:b9164b348919 440
MrBedfordVan 0:b9164b348919 441 private:
MrBedfordVan 0:b9164b348919 442
MrBedfordVan 0:b9164b348919 443 /**
MrBedfordVan 0:b9164b348919 444 * Issues a standard, 2 byte I2C command write to the accelerometer.
MrBedfordVan 0:b9164b348919 445 *
MrBedfordVan 0:b9164b348919 446 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 447 *
MrBedfordVan 0:b9164b348919 448 * @param reg The address of the register to write to.
MrBedfordVan 0:b9164b348919 449 *
MrBedfordVan 0:b9164b348919 450 * @param value The value to write.
MrBedfordVan 0:b9164b348919 451 *
MrBedfordVan 0:b9164b348919 452 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the the write request failed.
MrBedfordVan 0:b9164b348919 453 */
MrBedfordVan 0:b9164b348919 454 int writeCommand(uint8_t reg, uint8_t value);
MrBedfordVan 0:b9164b348919 455
MrBedfordVan 0:b9164b348919 456 /**
MrBedfordVan 0:b9164b348919 457 * Issues a read command, copying data into the specified buffer.
MrBedfordVan 0:b9164b348919 458 *
MrBedfordVan 0:b9164b348919 459 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 460 *
MrBedfordVan 0:b9164b348919 461 * @param reg The address of the register to access.
MrBedfordVan 0:b9164b348919 462 *
MrBedfordVan 0:b9164b348919 463 * @param buffer Memory area to read the data into.
MrBedfordVan 0:b9164b348919 464 *
MrBedfordVan 0:b9164b348919 465 * @param length The number of bytes to read.
MrBedfordVan 0:b9164b348919 466 *
MrBedfordVan 0:b9164b348919 467 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the the read request failed.
MrBedfordVan 0:b9164b348919 468 */
MrBedfordVan 0:b9164b348919 469 int readCommand(uint8_t reg, uint8_t* buffer, int length);
MrBedfordVan 0:b9164b348919 470
MrBedfordVan 0:b9164b348919 471 /**
MrBedfordVan 0:b9164b348919 472 * Issues a read of a given address, and returns the value.
MrBedfordVan 0:b9164b348919 473 *
MrBedfordVan 0:b9164b348919 474 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 475 *
MrBedfordVan 0:b9164b348919 476 * @param reg The address of the 16 bit register to access.
MrBedfordVan 0:b9164b348919 477 *
MrBedfordVan 0:b9164b348919 478 * @return The register value, interpreted as a 16 but signed value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
MrBedfordVan 0:b9164b348919 479 */
MrBedfordVan 0:b9164b348919 480 int read16(uint8_t reg);
MrBedfordVan 0:b9164b348919 481
MrBedfordVan 0:b9164b348919 482 /**
MrBedfordVan 0:b9164b348919 483 * Issues a read of a given address, and returns the value.
MrBedfordVan 0:b9164b348919 484 *
MrBedfordVan 0:b9164b348919 485 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 486 *
MrBedfordVan 0:b9164b348919 487 * @param reg The address of the 16 bit register to access.
MrBedfordVan 0:b9164b348919 488 *
MrBedfordVan 0:b9164b348919 489 * @return The register value, interpreted as a 8 bit unsigned value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
MrBedfordVan 0:b9164b348919 490 */
MrBedfordVan 0:b9164b348919 491 int read8(uint8_t reg);
MrBedfordVan 0:b9164b348919 492
MrBedfordVan 0:b9164b348919 493 /**
MrBedfordVan 0:b9164b348919 494 * Calculates a tilt compensated bearing of the device, using the accelerometer.
MrBedfordVan 0:b9164b348919 495 */
MrBedfordVan 0:b9164b348919 496 int tiltCompensatedBearing();
MrBedfordVan 0:b9164b348919 497
MrBedfordVan 0:b9164b348919 498 /**
MrBedfordVan 0:b9164b348919 499 * Calculates a non-tilt compensated bearing of the device.
MrBedfordVan 0:b9164b348919 500 */
MrBedfordVan 0:b9164b348919 501 int basicBearing();
MrBedfordVan 0:b9164b348919 502
MrBedfordVan 0:b9164b348919 503 /**
MrBedfordVan 0:b9164b348919 504 * An initialisation member function used by the many constructors of MicroBitCompass.
MrBedfordVan 0:b9164b348919 505 *
MrBedfordVan 0:b9164b348919 506 * @param id the unique identifier for this compass instance.
MrBedfordVan 0:b9164b348919 507 *
MrBedfordVan 0:b9164b348919 508 * @param address the base address of the magnetometer on the i2c bus.
MrBedfordVan 0:b9164b348919 509 */
MrBedfordVan 0:b9164b348919 510 void init(uint16_t id, uint16_t address);
MrBedfordVan 0:b9164b348919 511 };
MrBedfordVan 0:b9164b348919 512
MrBedfordVan 0:b9164b348919 513 #endif