Owen Brotherwood / microbitmpr121

Start of a microbit mpr121 library

Dependents:   microbitmpr121-example

MicroBitMpr121.h@5:4a8384331ca7, 2017-01-16 (annotated)

Committer:
owenbrotherwood
Date:
Mon Jan 16 19:43:18 2017 +0000
Revision:
5:4a8384331ca7
Parent:
4:f63476855239
Child:
6:103a5a2ca571
Next: functionality

Who changed what in which revision?

UserRevisionLine numberNew contents of line
owenbrotherwood 4:f63476855239 1 /*
owenbrotherwood 4:f63476855239 2 The MIT License (MIT)
owenbrotherwood 1:f6fed00a3ff2 3
owenbrotherwood 4:f63476855239 4 Copyright (c) 2016 British Broadcasting Corporation.
owenbrotherwood 4:f63476855239 5 This software is provided by Lancaster University by arrangement with the BBC.
owenbrotherwood 4:f63476855239 6
owenbrotherwood 4:f63476855239 7 Permission is hereby granted, free of charge, to any person obtaining a
owenbrotherwood 4:f63476855239 8 copy of this software and associated documentation files (the "Software"),
owenbrotherwood 4:f63476855239 9 to deal in the Software without restriction, including without limitation
owenbrotherwood 4:f63476855239 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
owenbrotherwood 4:f63476855239 11 and/or sell copies of the Software, and to permit persons to whom the
owenbrotherwood 4:f63476855239 12 Software is furnished to do so, subject to the following conditions:
owenbrotherwood 4:f63476855239 13
owenbrotherwood 4:f63476855239 14 The above copyright notice and this permission notice shall be included in
owenbrotherwood 4:f63476855239 15 all copies or substantial portions of the Software.
owenbrotherwood 0:fb4572fc4901 16
owenbrotherwood 4:f63476855239 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
owenbrotherwood 4:f63476855239 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
owenbrotherwood 4:f63476855239 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
owenbrotherwood 4:f63476855239 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
owenbrotherwood 4:f63476855239 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
owenbrotherwood 4:f63476855239 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
owenbrotherwood 4:f63476855239 23 DEALINGS IN THE SOFTWARE.
owenbrotherwood 4:f63476855239 24 */
owenbrotherwood 4:f63476855239 25
owenbrotherwood 4:f63476855239 26 #ifndef MICROBIT_MPR121_H
owenbrotherwood 4:f63476855239 27 #define MICROBIT_MPR121_H
owenbrotherwood 4:f63476855239 28
owenbrotherwood 4:f63476855239 29 #include "mbed.h"
owenbrotherwood 4:f63476855239 30 #include "MicroBitConfig.h"
owenbrotherwood 4:f63476855239 31 #include "MicroBitPin.h"
owenbrotherwood 4:f63476855239 32 #include "MicroBitComponent.h"
owenbrotherwood 4:f63476855239 33 #include "MicroBitI2C.h"
owenbrotherwood 1:f6fed00a3ff2 34
owenbrotherwood 4:f63476855239 35 /**
owenbrotherwood 4:f63476855239 36 * Relevant pin assignments
owenbrotherwood 4:f63476855239 37 */
owenbrotherwood 4:f63476855239 38 #define MPR121_DEFAULT_INT MICROBIT_PIN_P16
owenbrotherwood 4:f63476855239 39
owenbrotherwood 4:f63476855239 40 /**
owenbrotherwood 4:f63476855239 41 * I2C constants
owenbrotherwood 4:f63476855239 42 */
owenbrotherwood 5:4a8384331ca7 43 #define MPR121_DEFAULT_ADDR 0x5A
owenbrotherwood 4:f63476855239 44
owenbrotherwood 4:f63476855239 45
owenbrotherwood 4:f63476855239 46 /**
owenbrotherwood 4:f63476855239 47 * Status Bits
owenbrotherwood 4:f63476855239 48 */
owenbrotherwood 4:f63476855239 49
owenbrotherwood 1:f6fed00a3ff2 50
owenbrotherwood 4:f63476855239 51 /**
owenbrotherwood 4:f63476855239 52 * MPR121 MAGIC ID value
owenbrotherwood 4:f63476855239 53 * Returned from the MPR121_WHO_AM_I register for ID purposes.
owenbrotherwood 4:f63476855239 54 */
owenbrotherwood 5:4a8384331ca7 55 #define MPR121_WHOAMI_VAL 0X9A //TODO
owenbrotherwood 4:f63476855239 56
owenbrotherwood 4:f63476855239 57 /**
owenbrotherwood 4:f63476855239 58 * Class definition for MicroBit Mpr121.
owenbrotherwood 4:f63476855239 59 *
owenbrotherwood 4:f63476855239 60 * Represents an implementation of the Mpr121.
owenbrotherwood 4:f63476855239 61 * Also includes ...
owenbrotherwood 4:f63476855239 62 */
owenbrotherwood 4:f63476855239 63 class MicroBitMpr121 : public MicroBitComponent
owenbrotherwood 4:f63476855239 64 {
owenbrotherwood 4:f63476855239 65 uint16_t address; // I2C address of the magnetmometer.
owenbrotherwood 4:f63476855239 66
owenbrotherwood 4:f63476855239 67 DigitalIn int1; // Data ready interrupt.
owenbrotherwood 4:f63476855239 68 MicroBitI2C& i2c; // The I2C interface the sensor is connected to.
owenbrotherwood 0:fb4572fc4901 69
owenbrotherwood 0:fb4572fc4901 70 public:
owenbrotherwood 1:f6fed00a3ff2 71
owenbrotherwood 0:fb4572fc4901 72 /**
owenbrotherwood 4:f63476855239 73 * Constructor.
owenbrotherwood 4:f63476855239 74 * Create a software representation of a mpr121.
owenbrotherwood 4:f63476855239 75 *
owenbrotherwood 4:f63476855239 76 * @param _i2c an instance of i2c, which the mpr121 is accessible from.
owenbrotherwood 4:f63476855239 77 *
owenbrotherwood 4:f63476855239 78 * @param address the address for the mpr121 register on the i2c bus. Defaults to MPR121_DEFAULT_ADDR.
owenbrotherwood 4:f63476855239 79 *
owenbrotherwood 4:f63476855239 80 * @param id the ID of the new MicroBitMpr121 object. Defaults to MPR121_DEFAULT_ADDR.
owenbrotherwood 4:f63476855239 81 *
owenbrotherwood 4:f63476855239 82 * @code
owenbrotherwood 4:f63476855239 83 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
owenbrotherwood 4:f63476855239 84 *
owenbrotherwood 4:f63476855239 85 * MicroBitMpr121 mpr121(i2c);
owenbrotherwood 4:f63476855239 86 * @endcode
owenbrotherwood 4:f63476855239 87 */
owenbrotherwood 5:4a8384331ca7 88 MicroBitMpr121(MicroBitI2C& _i2c, uint16_t address = MPR121_DEFAULT_ADDR, DigitalIn interupt = MICROBIT_PIN_P16, uint16_t id = MPR121_DEFAULT_ADDR);
owenbrotherwood 4:f63476855239 89
owenbrotherwood 4:f63476855239 90 /**
owenbrotherwood 4:f63476855239 91 * Configures the compass for the sample rate defined in this object.
owenbrotherwood 4:f63476855239 92 * The nearest values are chosen to those defined that are supported by the hardware.
owenbrotherwood 4:f63476855239 93 * The instance variables are then updated to reflect reality.
owenbrotherwood 4:f63476855239 94 *
owenbrotherwood 4:f63476855239 95 * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be configured.
owenbrotherwood 4:f63476855239 96 */
owenbrotherwood 4:f63476855239 97 int configure();
owenbrotherwood 4:f63476855239 98
owenbrotherwood 4:f63476855239 99 /**
owenbrotherwood 4:f63476855239 100 * Attempts to set the sample rate of the compass to the specified value (in ms).
owenbrotherwood 4:f63476855239 101 *
owenbrotherwood 4:f63476855239 102 * @param period the requested time between samples, in milliseconds.
owenbrotherwood 4:f63476855239 103 *
owenbrotherwood 4:f63476855239 104 * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
owenbrotherwood 4:f63476855239 105 *
owenbrotherwood 4:f63476855239 106 * @code
owenbrotherwood 4:f63476855239 107 * // sample rate is now 20 ms.
owenbrotherwood 4:f63476855239 108 * compass.setPeriod(20);
owenbrotherwood 4:f63476855239 109 * @endcode
owenbrotherwood 4:f63476855239 110 *
owenbrotherwood 4:f63476855239 111 * @note The requested rate may not be possible on the hardware. In this case, the
owenbrotherwood 4:f63476855239 112 * nearest lower rate is chosen.
owenbrotherwood 4:f63476855239 113 */
owenbrotherwood 4:f63476855239 114 int setPeriod(int period);
owenbrotherwood 4:f63476855239 115
owenbrotherwood 4:f63476855239 116 /**
owenbrotherwood 4:f63476855239 117 * Reads the currently configured sample rate of the compass.
owenbrotherwood 4:f63476855239 118 *
owenbrotherwood 4:f63476855239 119 * @return The time between samples, in milliseconds.
owenbrotherwood 4:f63476855239 120 */
owenbrotherwood 4:f63476855239 121 int getPeriod();
owenbrotherwood 4:f63476855239 122
owenbrotherwood 4:f63476855239 123 /**
owenbrotherwood 4:f63476855239 124 * Gets the current heading of the device, relative to magnetic north.
owenbrotherwood 4:f63476855239 125 *
owenbrotherwood 4:f63476855239 126 * If the compass is not calibrated, it will raise the MICROBIT_COMPASS_EVT_CALIBRATE event.
owenbrotherwood 4:f63476855239 127 *
owenbrotherwood 4:f63476855239 128 * Users wishing to implement their own calibration algorithms should listen for this event,
owenbrotherwood 4:f63476855239 129 * using MESSAGE_BUS_LISTENER_IMMEDIATE model. This ensures that calibration is complete before
owenbrotherwood 4:f63476855239 130 * the user program continues.
owenbrotherwood 4:f63476855239 131 *
owenbrotherwood 4:f63476855239 132 * @return the current heading, in degrees. Or MICROBIT_CALIBRATION_IN_PROGRESS if the compass is calibrating.
owenbrotherwood 4:f63476855239 133 *
owenbrotherwood 4:f63476855239 134 * @code
owenbrotherwood 4:f63476855239 135 * compass.heading();
owenbrotherwood 4:f63476855239 136 * @endcode
owenbrotherwood 4:f63476855239 137 */
owenbrotherwood 4:f63476855239 138 int heading();
owenbrotherwood 4:f63476855239 139
owenbrotherwood 4:f63476855239 140 /**
owenbrotherwood 4:f63476855239 141 * Attempts to read the 8 bit ID from the magnetometer, this can be used for
owenbrotherwood 4:f63476855239 142 * validation purposes.
owenbrotherwood 4:f63476855239 143 *
owenbrotherwood 4:f63476855239 144 * @return the 8 bit ID returned by the magnetometer, or MICROBIT_I2C_ERROR if the request fails.
owenbrotherwood 4:f63476855239 145 *
owenbrotherwood 4:f63476855239 146 * @code
owenbrotherwood 4:f63476855239 147 * compass.whoAmI();
owenbrotherwood 4:f63476855239 148 * @endcode
owenbrotherwood 4:f63476855239 149 */
owenbrotherwood 4:f63476855239 150 int whoAmI();
owenbrotherwood 4:f63476855239 151
owenbrotherwood 4:f63476855239 152 /**
owenbrotherwood 4:f63476855239 153 * Determines the overall magnetic field strength based on the latest update from the magnetometer.
owenbrotherwood 4:f63476855239 154 *
owenbrotherwood 4:f63476855239 155 * @return The magnetic force measured across all axis, in nano teslas.
owenbrotherwood 4:f63476855239 156 *
owenbrotherwood 4:f63476855239 157 * @code
owenbrotherwood 4:f63476855239 158 * compass.getFieldStrength();
owenbrotherwood 4:f63476855239 159 * @endcode
owenbrotherwood 4:f63476855239 160 */
owenbrotherwood 4:f63476855239 161 int getFieldStrength();
owenbrotherwood 4:f63476855239 162
owenbrotherwood 4:f63476855239 163 /**
owenbrotherwood 4:f63476855239 164 * Reads the current die temperature of the compass.
owenbrotherwood 4:f63476855239 165 *
owenbrotherwood 4:f63476855239 166 * @return the temperature in degrees celsius, or MICROBIT_I2C_ERROR if the temperature reading could not be retreived
owenbrotherwood 4:f63476855239 167 * from the accelerometer.
owenbrotherwood 4:f63476855239 168 */
owenbrotherwood 4:f63476855239 169 int readTemperature();
owenbrotherwood 1:f6fed00a3ff2 170
owenbrotherwood 0:fb4572fc4901 171 /**
owenbrotherwood 4:f63476855239 172 * Perform a calibration of the compass.
owenbrotherwood 4:f63476855239 173 *
owenbrotherwood 4:f63476855239 174 * This method will be called automatically if a user attempts to read a compass value when
owenbrotherwood 4:f63476855239 175 * the compass is uncalibrated. It can also be called at any time by the user.
owenbrotherwood 4:f63476855239 176 *
owenbrotherwood 4:f63476855239 177 * The method will only return once the compass has been calibrated.
owenbrotherwood 4:f63476855239 178 *
owenbrotherwood 4:f63476855239 179 * @return MICROBIT_OK, MICROBIT_I2C_ERROR if the magnetometer could not be accessed,
owenbrotherwood 4:f63476855239 180 * or MICROBIT_CALIBRATION_REQUIRED if the calibration algorithm failed to complete successfully.
owenbrotherwood 4:f63476855239 181 *
owenbrotherwood 4:f63476855239 182 * @note THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS
owenbrotherwood 4:f63476855239 183 */
owenbrotherwood 4:f63476855239 184 int calibrate();
owenbrotherwood 1:f6fed00a3ff2 185
owenbrotherwood 1:f6fed00a3ff2 186
owenbrotherwood 4:f63476855239 187 /**
owenbrotherwood 4:f63476855239 188 * Updates the local sample, only if the compass indicates that
owenbrotherwood 4:f63476855239 189 * data is stale.
owenbrotherwood 4:f63476855239 190 *
owenbrotherwood 4:f63476855239 191 * @note Can be used to trigger manual updates, if the device is running without a scheduler.
owenbrotherwood 4:f63476855239 192 * Also called internally by all get[X,Y,Z]() member functions.
owenbrotherwood 4:f63476855239 193 */
owenbrotherwood 4:f63476855239 194 int updateSample();
owenbrotherwood 1:f6fed00a3ff2 195
owenbrotherwood 4:f63476855239 196 /**
owenbrotherwood 4:f63476855239 197 * Periodic callback from MicroBit idle thread.
owenbrotherwood 4:f63476855239 198 *
owenbrotherwood 4:f63476855239 199 * Calls updateSample().
owenbrotherwood 4:f63476855239 200 */
owenbrotherwood 4:f63476855239 201 virtual void idleTick();
owenbrotherwood 1:f6fed00a3ff2 202
owenbrotherwood 4:f63476855239 203 /**
owenbrotherwood 4:f63476855239 204 * Returns 0 or 1. 1 indicates that the compass is calibrated, zero means the compass requires calibration.
owenbrotherwood 4:f63476855239 205 */
owenbrotherwood 4:f63476855239 206 int isCalibrated();
owenbrotherwood 1:f6fed00a3ff2 207
owenbrotherwood 4:f63476855239 208 /**
owenbrotherwood 4:f63476855239 209 * Returns 0 or 1. 1 indicates that the compass is calibrating, zero means the compass is not currently calibrating.
owenbrotherwood 4:f63476855239 210 */
owenbrotherwood 4:f63476855239 211 int isCalibrating();
owenbrotherwood 1:f6fed00a3ff2 212
owenbrotherwood 4:f63476855239 213 /**
owenbrotherwood 4:f63476855239 214 * Clears the calibration held in persistent storage, and sets the calibrated flag to zero.
owenbrotherwood 4:f63476855239 215 */
owenbrotherwood 4:f63476855239 216 void clearCalibration();
owenbrotherwood 1:f6fed00a3ff2 217
owenbrotherwood 4:f63476855239 218 /**
owenbrotherwood 4:f63476855239 219 * Destructor for MicroBitMpr121, where we deregister this instance from the array of fiber components.
owenbrotherwood 4:f63476855239 220 */
owenbrotherwood 4:f63476855239 221 ~MicroBitMpr121();
owenbrotherwood 1:f6fed00a3ff2 222
owenbrotherwood 4:f63476855239 223 private:
owenbrotherwood 2:4e130924a398 224
owenbrotherwood 4:f63476855239 225 /**
owenbrotherwood 4:f63476855239 226 * Issues a standard, 2 byte I2C command write to the accelerometer.
owenbrotherwood 4:f63476855239 227 *
owenbrotherwood 4:f63476855239 228 * Blocks the calling thread until complete.
owenbrotherwood 4:f63476855239 229 *
owenbrotherwood 4:f63476855239 230 * @param reg The address of the register to write to.
owenbrotherwood 4:f63476855239 231 *
owenbrotherwood 4:f63476855239 232 * @param value The value to write.
owenbrotherwood 4:f63476855239 233 *
owenbrotherwood 4:f63476855239 234 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the the write request failed.
owenbrotherwood 4:f63476855239 235 */
owenbrotherwood 4:f63476855239 236 int writeCommand(uint8_t reg, uint8_t value);
owenbrotherwood 2:4e130924a398 237
owenbrotherwood 4:f63476855239 238 /**
owenbrotherwood 4:f63476855239 239 * Issues a read command, copying data into the specified buffer.
owenbrotherwood 4:f63476855239 240 *
owenbrotherwood 4:f63476855239 241 * Blocks the calling thread until complete.
owenbrotherwood 4:f63476855239 242 *
owenbrotherwood 4:f63476855239 243 * @param reg The address of the register to access.
owenbrotherwood 4:f63476855239 244 *
owenbrotherwood 4:f63476855239 245 * @param buffer Memory area to read the data into.
owenbrotherwood 4:f63476855239 246 *
owenbrotherwood 4:f63476855239 247 * @param length The number of bytes to read.
owenbrotherwood 4:f63476855239 248 *
owenbrotherwood 4:f63476855239 249 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the the read request failed.
owenbrotherwood 4:f63476855239 250 */
owenbrotherwood 4:f63476855239 251 int readCommand(uint8_t reg, uint8_t* buffer, int length);
owenbrotherwood 1:f6fed00a3ff2 252
owenbrotherwood 4:f63476855239 253 /**
owenbrotherwood 4:f63476855239 254 * Issues a read of a given address, and returns the value.
owenbrotherwood 4:f63476855239 255 *
owenbrotherwood 4:f63476855239 256 * Blocks the calling thread until complete.
owenbrotherwood 4:f63476855239 257 *
owenbrotherwood 4:f63476855239 258 * @param reg The address of the 16 bit register to access.
owenbrotherwood 4:f63476855239 259 *
owenbrotherwood 4:f63476855239 260 * @return The register value, interpreted as a 16 but signed value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
owenbrotherwood 4:f63476855239 261 */
owenbrotherwood 4:f63476855239 262 int read16(uint8_t reg);
owenbrotherwood 1:f6fed00a3ff2 263
owenbrotherwood 4:f63476855239 264 /**
owenbrotherwood 4:f63476855239 265 * Issues a read of a given address, and returns the value.
owenbrotherwood 4:f63476855239 266 *
owenbrotherwood 4:f63476855239 267 * Blocks the calling thread until complete.
owenbrotherwood 4:f63476855239 268 *
owenbrotherwood 4:f63476855239 269 * @param reg The address of the 16 bit register to access.
owenbrotherwood 4:f63476855239 270 *
owenbrotherwood 4:f63476855239 271 * @return The register value, interpreted as a 8 bit unsigned value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
owenbrotherwood 4:f63476855239 272 */
owenbrotherwood 4:f63476855239 273 int read8(uint8_t reg);
owenbrotherwood 1:f6fed00a3ff2 274
owenbrotherwood 4:f63476855239 275 /**
owenbrotherwood 4:f63476855239 276 * Calculates a tilt compensated bearing of the device, using the accelerometer.
owenbrotherwood 4:f63476855239 277 */
owenbrotherwood 4:f63476855239 278 int tiltCompensatedBearing();
owenbrotherwood 1:f6fed00a3ff2 279
owenbrotherwood 4:f63476855239 280 /**
owenbrotherwood 4:f63476855239 281 * Calculates a non-tilt compensated bearing of the device.
owenbrotherwood 4:f63476855239 282 */
owenbrotherwood 4:f63476855239 283 int basicBearing();
owenbrotherwood 1:f6fed00a3ff2 284
owenbrotherwood 4:f63476855239 285 /**
owenbrotherwood 4:f63476855239 286 * An initialisation member function used by the many constructors of MicroBitMpr121.
owenbrotherwood 4:f63476855239 287 *
owenbrotherwood 4:f63476855239 288 * @param id the unique identifier for this compass instance.
owenbrotherwood 4:f63476855239 289 *
owenbrotherwood 4:f63476855239 290 * @param address the base address of the magnetometer on the i2c bus.
owenbrotherwood 4:f63476855239 291 */
owenbrotherwood 4:f63476855239 292 void init(uint16_t id, uint16_t address);
owenbrotherwood 0:fb4572fc4901 293 };
owenbrotherwood 0:fb4572fc4901 294
owenbrotherwood 4:f63476855239 295 #endif