Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/inc/drivers/MicroBitAccelerometer.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_ACCELEROMETER_H
MrBedfordVan 0:b9164b348919 27 #define MICROBIT_ACCELEROMETER_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 "MicroBitI2C.h"
MrBedfordVan 0:b9164b348919 34
MrBedfordVan 0:b9164b348919 35 /**
MrBedfordVan 0:b9164b348919 36 * Relevant pin assignments
MrBedfordVan 0:b9164b348919 37 */
MrBedfordVan 0:b9164b348919 38 #define MICROBIT_PIN_ACCEL_DATA_READY P0_28
MrBedfordVan 0:b9164b348919 39
MrBedfordVan 0:b9164b348919 40 /**
MrBedfordVan 0:b9164b348919 41 * Status flags
MrBedfordVan 0:b9164b348919 42 */
MrBedfordVan 0:b9164b348919 43 #define MICROBIT_ACCEL_PITCH_ROLL_VALID 0x02
MrBedfordVan 0:b9164b348919 44 #define MICROBIT_ACCEL_ADDED_TO_IDLE 0x04
MrBedfordVan 0:b9164b348919 45
MrBedfordVan 0:b9164b348919 46 /**
MrBedfordVan 0:b9164b348919 47 * I2C constants
MrBedfordVan 0:b9164b348919 48 */
MrBedfordVan 0:b9164b348919 49 #define MMA8653_DEFAULT_ADDR 0x3A
MrBedfordVan 0:b9164b348919 50
MrBedfordVan 0:b9164b348919 51 /**
MrBedfordVan 0:b9164b348919 52 * MMA8653 Register map (partial)
MrBedfordVan 0:b9164b348919 53 */
MrBedfordVan 0:b9164b348919 54 #define MMA8653_STATUS 0x00
MrBedfordVan 0:b9164b348919 55 #define MMA8653_OUT_X_MSB 0x01
MrBedfordVan 0:b9164b348919 56 #define MMA8653_WHOAMI 0x0D
MrBedfordVan 0:b9164b348919 57 #define MMA8653_XYZ_DATA_CFG 0x0E
MrBedfordVan 0:b9164b348919 58 #define MMA8653_CTRL_REG1 0x2A
MrBedfordVan 0:b9164b348919 59 #define MMA8653_CTRL_REG2 0x2B
MrBedfordVan 0:b9164b348919 60 #define MMA8653_CTRL_REG3 0x2C
MrBedfordVan 0:b9164b348919 61 #define MMA8653_CTRL_REG4 0x2D
MrBedfordVan 0:b9164b348919 62 #define MMA8653_CTRL_REG5 0x2E
MrBedfordVan 0:b9164b348919 63
MrBedfordVan 0:b9164b348919 64
MrBedfordVan 0:b9164b348919 65 /**
MrBedfordVan 0:b9164b348919 66 * MMA8653 constants
MrBedfordVan 0:b9164b348919 67 */
MrBedfordVan 0:b9164b348919 68 #define MMA8653_WHOAMI_VAL 0x5A
MrBedfordVan 0:b9164b348919 69
MrBedfordVan 0:b9164b348919 70 #define MMA8653_SAMPLE_RANGES 3
MrBedfordVan 0:b9164b348919 71 #define MMA8653_SAMPLE_RATES 8
MrBedfordVan 0:b9164b348919 72
MrBedfordVan 0:b9164b348919 73 /**
MrBedfordVan 0:b9164b348919 74 * Accelerometer events
MrBedfordVan 0:b9164b348919 75 */
MrBedfordVan 0:b9164b348919 76 #define MICROBIT_ACCELEROMETER_EVT_DATA_UPDATE 1
MrBedfordVan 0:b9164b348919 77
MrBedfordVan 0:b9164b348919 78 /**
MrBedfordVan 0:b9164b348919 79 * Gesture events
MrBedfordVan 0:b9164b348919 80 */
MrBedfordVan 0:b9164b348919 81 #define MICROBIT_ACCELEROMETER_EVT_NONE 0
MrBedfordVan 0:b9164b348919 82 #define MICROBIT_ACCELEROMETER_EVT_TILT_UP 1
MrBedfordVan 0:b9164b348919 83 #define MICROBIT_ACCELEROMETER_EVT_TILT_DOWN 2
MrBedfordVan 0:b9164b348919 84 #define MICROBIT_ACCELEROMETER_EVT_TILT_LEFT 3
MrBedfordVan 0:b9164b348919 85 #define MICROBIT_ACCELEROMETER_EVT_TILT_RIGHT 4
MrBedfordVan 0:b9164b348919 86 #define MICROBIT_ACCELEROMETER_EVT_FACE_UP 5
MrBedfordVan 0:b9164b348919 87 #define MICROBIT_ACCELEROMETER_EVT_FACE_DOWN 6
MrBedfordVan 0:b9164b348919 88 #define MICROBIT_ACCELEROMETER_EVT_FREEFALL 7
MrBedfordVan 0:b9164b348919 89 #define MICROBIT_ACCELEROMETER_EVT_3G 8
MrBedfordVan 0:b9164b348919 90 #define MICROBIT_ACCELEROMETER_EVT_6G 9
MrBedfordVan 0:b9164b348919 91 #define MICROBIT_ACCELEROMETER_EVT_8G 10
MrBedfordVan 0:b9164b348919 92 #define MICROBIT_ACCELEROMETER_EVT_SHAKE 11
MrBedfordVan 0:b9164b348919 93
MrBedfordVan 0:b9164b348919 94 /**
MrBedfordVan 0:b9164b348919 95 * Gesture recogniser constants
MrBedfordVan 0:b9164b348919 96 */
MrBedfordVan 0:b9164b348919 97 #define MICROBIT_ACCELEROMETER_REST_TOLERANCE 200
MrBedfordVan 0:b9164b348919 98 #define MICROBIT_ACCELEROMETER_TILT_TOLERANCE 200
MrBedfordVan 0:b9164b348919 99 #define MICROBIT_ACCELEROMETER_FREEFALL_TOLERANCE 400
MrBedfordVan 0:b9164b348919 100 #define MICROBIT_ACCELEROMETER_SHAKE_TOLERANCE 400
MrBedfordVan 0:b9164b348919 101 #define MICROBIT_ACCELEROMETER_3G_TOLERANCE 3072
MrBedfordVan 0:b9164b348919 102 #define MICROBIT_ACCELEROMETER_6G_TOLERANCE 6144
MrBedfordVan 0:b9164b348919 103 #define MICROBIT_ACCELEROMETER_8G_TOLERANCE 8192
MrBedfordVan 0:b9164b348919 104 #define MICROBIT_ACCELEROMETER_GESTURE_DAMPING 5
MrBedfordVan 0:b9164b348919 105 #define MICROBIT_ACCELEROMETER_SHAKE_DAMPING 10
MrBedfordVan 0:b9164b348919 106 #define MICROBIT_ACCELEROMETER_SHAKE_RTX 30
MrBedfordVan 0:b9164b348919 107
MrBedfordVan 0:b9164b348919 108 #define MICROBIT_ACCELEROMETER_REST_THRESHOLD (MICROBIT_ACCELEROMETER_REST_TOLERANCE * MICROBIT_ACCELEROMETER_REST_TOLERANCE)
MrBedfordVan 0:b9164b348919 109 #define MICROBIT_ACCELEROMETER_FREEFALL_THRESHOLD (MICROBIT_ACCELEROMETER_FREEFALL_TOLERANCE * MICROBIT_ACCELEROMETER_FREEFALL_TOLERANCE)
MrBedfordVan 0:b9164b348919 110 #define MICROBIT_ACCELEROMETER_3G_THRESHOLD (MICROBIT_ACCELEROMETER_3G_TOLERANCE * MICROBIT_ACCELEROMETER_3G_TOLERANCE)
MrBedfordVan 0:b9164b348919 111 #define MICROBIT_ACCELEROMETER_6G_THRESHOLD (MICROBIT_ACCELEROMETER_6G_TOLERANCE * MICROBIT_ACCELEROMETER_6G_TOLERANCE)
MrBedfordVan 0:b9164b348919 112 #define MICROBIT_ACCELEROMETER_8G_THRESHOLD (MICROBIT_ACCELEROMETER_8G_TOLERANCE * MICROBIT_ACCELEROMETER_8G_TOLERANCE)
MrBedfordVan 0:b9164b348919 113 #define MICROBIT_ACCELEROMETER_SHAKE_COUNT_THRESHOLD 4
MrBedfordVan 0:b9164b348919 114
MrBedfordVan 0:b9164b348919 115 struct MMA8653Sample
MrBedfordVan 0:b9164b348919 116 {
MrBedfordVan 0:b9164b348919 117 int16_t x;
MrBedfordVan 0:b9164b348919 118 int16_t y;
MrBedfordVan 0:b9164b348919 119 int16_t z;
MrBedfordVan 0:b9164b348919 120 };
MrBedfordVan 0:b9164b348919 121
MrBedfordVan 0:b9164b348919 122 struct MMA8653SampleRateConfig
MrBedfordVan 0:b9164b348919 123 {
MrBedfordVan 0:b9164b348919 124 uint32_t sample_period;
MrBedfordVan 0:b9164b348919 125 uint8_t ctrl_reg1;
MrBedfordVan 0:b9164b348919 126 };
MrBedfordVan 0:b9164b348919 127
MrBedfordVan 0:b9164b348919 128 struct MMA8653SampleRangeConfig
MrBedfordVan 0:b9164b348919 129 {
MrBedfordVan 0:b9164b348919 130 uint8_t sample_range;
MrBedfordVan 0:b9164b348919 131 uint8_t xyz_data_cfg;
MrBedfordVan 0:b9164b348919 132 };
MrBedfordVan 0:b9164b348919 133
MrBedfordVan 0:b9164b348919 134
MrBedfordVan 0:b9164b348919 135 extern const MMA8653SampleRangeConfig MMA8653SampleRange[];
MrBedfordVan 0:b9164b348919 136 extern const MMA8653SampleRateConfig MMA8653SampleRate[];
MrBedfordVan 0:b9164b348919 137
MrBedfordVan 0:b9164b348919 138 struct ShakeHistory
MrBedfordVan 0:b9164b348919 139 {
MrBedfordVan 0:b9164b348919 140 uint16_t shaken:1,
MrBedfordVan 0:b9164b348919 141 x:1,
MrBedfordVan 0:b9164b348919 142 y:1,
MrBedfordVan 0:b9164b348919 143 z:1,
MrBedfordVan 0:b9164b348919 144 unused,
MrBedfordVan 0:b9164b348919 145 impulse_3,
MrBedfordVan 0:b9164b348919 146 impulse_6,
MrBedfordVan 0:b9164b348919 147 impulse_8,
MrBedfordVan 0:b9164b348919 148 count:8;
MrBedfordVan 0:b9164b348919 149
MrBedfordVan 0:b9164b348919 150 uint16_t timer;
MrBedfordVan 0:b9164b348919 151 };
MrBedfordVan 0:b9164b348919 152
MrBedfordVan 0:b9164b348919 153 /**
MrBedfordVan 0:b9164b348919 154 * Class definition for MicroBit Accelerometer.
MrBedfordVan 0:b9164b348919 155 *
MrBedfordVan 0:b9164b348919 156 * Represents an implementation of the Freescale MMA8653 3 axis accelerometer
MrBedfordVan 0:b9164b348919 157 * Also includes basic data caching and on demand activation.
MrBedfordVan 0:b9164b348919 158 */
MrBedfordVan 0:b9164b348919 159 class MicroBitAccelerometer : public MicroBitComponent
MrBedfordVan 0:b9164b348919 160 {
MrBedfordVan 0:b9164b348919 161 uint16_t address; // I2C address of this accelerometer.
MrBedfordVan 0:b9164b348919 162 uint16_t samplePeriod; // The time between samples, in milliseconds.
MrBedfordVan 0:b9164b348919 163 uint8_t sampleRange; // The sample range of the accelerometer in g.
MrBedfordVan 0:b9164b348919 164 MMA8653Sample sample; // The last sample read.
MrBedfordVan 0:b9164b348919 165 DigitalIn int1; // Data ready interrupt.
MrBedfordVan 0:b9164b348919 166 float pitch; // Pitch of the device, in radians.
MrBedfordVan 0:b9164b348919 167 MicroBitI2C& i2c; // The I2C interface to use.
MrBedfordVan 0:b9164b348919 168 float roll; // Roll of the device, in radians.
MrBedfordVan 0:b9164b348919 169 uint8_t sigma; // the number of ticks that the instantaneous gesture has been stable.
MrBedfordVan 0:b9164b348919 170 uint8_t impulseSigma; // the number of ticks since an impulse event has been generated.
MrBedfordVan 0:b9164b348919 171 uint16_t lastGesture; // the last, stable gesture recorded.
MrBedfordVan 0:b9164b348919 172 uint16_t currentGesture; // the instantaneous, unfiltered gesture detected.
MrBedfordVan 0:b9164b348919 173 ShakeHistory shake; // State information needed to detect shake events.
MrBedfordVan 0:b9164b348919 174
MrBedfordVan 0:b9164b348919 175 public:
MrBedfordVan 0:b9164b348919 176
MrBedfordVan 0:b9164b348919 177 /**
MrBedfordVan 0:b9164b348919 178 * Constructor.
MrBedfordVan 0:b9164b348919 179 * Create a software abstraction of an accelerometer.
MrBedfordVan 0:b9164b348919 180 *
MrBedfordVan 0:b9164b348919 181 * @param _i2c an instance of MicroBitI2C used to communicate with the onboard accelerometer.
MrBedfordVan 0:b9164b348919 182 *
MrBedfordVan 0:b9164b348919 183 * @param address the default I2C address of the accelerometer. Defaults to: MMA8653_DEFAULT_ADDR.
MrBedfordVan 0:b9164b348919 184 *
MrBedfordVan 0:b9164b348919 185 * @param id the unique EventModel id of this component. Defaults to: MICROBIT_ID_ACCELEROMETER
MrBedfordVan 0:b9164b348919 186 *
MrBedfordVan 0:b9164b348919 187 * @code
MrBedfordVan 0:b9164b348919 188 * MicroBitI2C i2c = MicroBitI2C(I2C_SDA0, I2C_SCL0);
MrBedfordVan 0:b9164b348919 189 *
MrBedfordVan 0:b9164b348919 190 * MicroBitAccelerometer accelerometer = MicroBitAccelerometer(i2c);
MrBedfordVan 0:b9164b348919 191 * @endcode
MrBedfordVan 0:b9164b348919 192 */
MrBedfordVan 0:b9164b348919 193 MicroBitAccelerometer(MicroBitI2C &_i2c, uint16_t address = MMA8653_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_ACCELEROMETER);
MrBedfordVan 0:b9164b348919 194
MrBedfordVan 0:b9164b348919 195 /**
MrBedfordVan 0:b9164b348919 196 * Configures the accelerometer for G range and sample rate defined
MrBedfordVan 0:b9164b348919 197 * in this object. The nearest values are chosen to those defined
MrBedfordVan 0:b9164b348919 198 * that are supported by the hardware. The instance variables are then
MrBedfordVan 0:b9164b348919 199 * updated to reflect reality.
MrBedfordVan 0:b9164b348919 200 *
MrBedfordVan 0:b9164b348919 201 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the accelerometer could not be configured.
MrBedfordVan 0:b9164b348919 202 */
MrBedfordVan 0:b9164b348919 203 int configure();
MrBedfordVan 0:b9164b348919 204
MrBedfordVan 0:b9164b348919 205 /**
MrBedfordVan 0:b9164b348919 206 * Reads the acceleration data from the accelerometer, and stores it in our buffer.
MrBedfordVan 0:b9164b348919 207 * This only happens if the accelerometer indicates that it has new data via int1.
MrBedfordVan 0:b9164b348919 208 *
MrBedfordVan 0:b9164b348919 209 * On first use, this member function will attempt to add this component to the
MrBedfordVan 0:b9164b348919 210 * list of fiber components in order to constantly update the values stored
MrBedfordVan 0:b9164b348919 211 * by this object.
MrBedfordVan 0:b9164b348919 212 *
MrBedfordVan 0:b9164b348919 213 * This technique is called lazy instantiation, and it means that we do not
MrBedfordVan 0:b9164b348919 214 * obtain the overhead from non-chalantly adding this component to fiber components.
MrBedfordVan 0:b9164b348919 215 *
MrBedfordVan 0:b9164b348919 216 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the read request fails.
MrBedfordVan 0:b9164b348919 217 */
MrBedfordVan 0:b9164b348919 218 int updateSample();
MrBedfordVan 0:b9164b348919 219
MrBedfordVan 0:b9164b348919 220 /**
MrBedfordVan 0:b9164b348919 221 * Attempts to set the sample rate of the accelerometer to the specified value (in ms).
MrBedfordVan 0:b9164b348919 222 *
MrBedfordVan 0:b9164b348919 223 * @param period the requested time between samples, in milliseconds.
MrBedfordVan 0:b9164b348919 224 *
MrBedfordVan 0:b9164b348919 225 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.
MrBedfordVan 0:b9164b348919 226 *
MrBedfordVan 0:b9164b348919 227 * @code
MrBedfordVan 0:b9164b348919 228 * // sample rate is now 20 ms.
MrBedfordVan 0:b9164b348919 229 * accelerometer.setPeriod(20);
MrBedfordVan 0:b9164b348919 230 * @endcode
MrBedfordVan 0:b9164b348919 231 *
MrBedfordVan 0:b9164b348919 232 * @note The requested rate may not be possible on the hardware. In this case, the
MrBedfordVan 0:b9164b348919 233 * nearest lower rate is chosen.
MrBedfordVan 0:b9164b348919 234 */
MrBedfordVan 0:b9164b348919 235 int setPeriod(int period);
MrBedfordVan 0:b9164b348919 236
MrBedfordVan 0:b9164b348919 237 /**
MrBedfordVan 0:b9164b348919 238 * Reads the currently configured sample rate of the accelerometer.
MrBedfordVan 0:b9164b348919 239 *
MrBedfordVan 0:b9164b348919 240 * @return The time between samples, in milliseconds.
MrBedfordVan 0:b9164b348919 241 */
MrBedfordVan 0:b9164b348919 242 int getPeriod();
MrBedfordVan 0:b9164b348919 243
MrBedfordVan 0:b9164b348919 244 /**
MrBedfordVan 0:b9164b348919 245 * Attempts to set the sample range of the accelerometer to the specified value (in g).
MrBedfordVan 0:b9164b348919 246 *
MrBedfordVan 0:b9164b348919 247 * @param range The requested sample range of samples, in g.
MrBedfordVan 0:b9164b348919 248 *
MrBedfordVan 0:b9164b348919 249 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.
MrBedfordVan 0:b9164b348919 250 *
MrBedfordVan 0:b9164b348919 251 * @code
MrBedfordVan 0:b9164b348919 252 * // the sample range of the accelerometer is now 8G.
MrBedfordVan 0:b9164b348919 253 * accelerometer.setRange(8);
MrBedfordVan 0:b9164b348919 254 * @endcode
MrBedfordVan 0:b9164b348919 255 *
MrBedfordVan 0:b9164b348919 256 * @note The requested range may not be possible on the hardware. In this case, the
MrBedfordVan 0:b9164b348919 257 * nearest lower range is chosen.
MrBedfordVan 0:b9164b348919 258 */
MrBedfordVan 0:b9164b348919 259 int setRange(int range);
MrBedfordVan 0:b9164b348919 260
MrBedfordVan 0:b9164b348919 261 /**
MrBedfordVan 0:b9164b348919 262 * Reads the currently configured sample range of the accelerometer.
MrBedfordVan 0:b9164b348919 263 *
MrBedfordVan 0:b9164b348919 264 * @return The sample range, in g.
MrBedfordVan 0:b9164b348919 265 */
MrBedfordVan 0:b9164b348919 266 int getRange();
MrBedfordVan 0:b9164b348919 267
MrBedfordVan 0:b9164b348919 268 /**
MrBedfordVan 0:b9164b348919 269 * Attempts to read the 8 bit ID from the accelerometer, this can be used for
MrBedfordVan 0:b9164b348919 270 * validation purposes.
MrBedfordVan 0:b9164b348919 271 *
MrBedfordVan 0:b9164b348919 272 * @return the 8 bit ID returned by the accelerometer, or MICROBIT_I2C_ERROR if the request fails.
MrBedfordVan 0:b9164b348919 273 *
MrBedfordVan 0:b9164b348919 274 * @code
MrBedfordVan 0:b9164b348919 275 * accelerometer.whoAmI();
MrBedfordVan 0:b9164b348919 276 * @endcode
MrBedfordVan 0:b9164b348919 277 */
MrBedfordVan 0:b9164b348919 278 int whoAmI();
MrBedfordVan 0:b9164b348919 279
MrBedfordVan 0:b9164b348919 280 /**
MrBedfordVan 0:b9164b348919 281 * Reads the value of the X axis from the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 282 *
MrBedfordVan 0:b9164b348919 283 * @param system The coordinate system to use. By default, a simple cartesian system is provided.
MrBedfordVan 0:b9164b348919 284 *
MrBedfordVan 0:b9164b348919 285 * @return The force measured in the X axis, in milli-g.
MrBedfordVan 0:b9164b348919 286 *
MrBedfordVan 0:b9164b348919 287 * @code
MrBedfordVan 0:b9164b348919 288 * accelerometer.getX();
MrBedfordVan 0:b9164b348919 289 * @endcode
MrBedfordVan 0:b9164b348919 290 */
MrBedfordVan 0:b9164b348919 291 int getX(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 292
MrBedfordVan 0:b9164b348919 293 /**
MrBedfordVan 0:b9164b348919 294 * Reads the value of the Y axis from the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 295 *
MrBedfordVan 0:b9164b348919 296 * @return The force measured in the Y axis, in milli-g.
MrBedfordVan 0:b9164b348919 297 *
MrBedfordVan 0:b9164b348919 298 * @code
MrBedfordVan 0:b9164b348919 299 * accelerometer.getY();
MrBedfordVan 0:b9164b348919 300 * @endcode
MrBedfordVan 0:b9164b348919 301 */
MrBedfordVan 0:b9164b348919 302 int getY(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 303
MrBedfordVan 0:b9164b348919 304 /**
MrBedfordVan 0:b9164b348919 305 * Reads the value of the Z axis from the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 306 *
MrBedfordVan 0:b9164b348919 307 * @return The force measured in the Z axis, in milli-g.
MrBedfordVan 0:b9164b348919 308 *
MrBedfordVan 0:b9164b348919 309 * @code
MrBedfordVan 0:b9164b348919 310 * accelerometer.getZ();
MrBedfordVan 0:b9164b348919 311 * @endcode
MrBedfordVan 0:b9164b348919 312 */
MrBedfordVan 0:b9164b348919 313 int getZ(MicroBitCoordinateSystem system = SIMPLE_CARTESIAN);
MrBedfordVan 0:b9164b348919 314
MrBedfordVan 0:b9164b348919 315 /**
MrBedfordVan 0:b9164b348919 316 * Provides a rotation compensated pitch of the device, based on the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 317 *
MrBedfordVan 0:b9164b348919 318 * @return The pitch of the device, in degrees.
MrBedfordVan 0:b9164b348919 319 *
MrBedfordVan 0:b9164b348919 320 * @code
MrBedfordVan 0:b9164b348919 321 * accelerometer.getPitch();
MrBedfordVan 0:b9164b348919 322 * @endcode
MrBedfordVan 0:b9164b348919 323 */
MrBedfordVan 0:b9164b348919 324 int getPitch();
MrBedfordVan 0:b9164b348919 325
MrBedfordVan 0:b9164b348919 326 /**
MrBedfordVan 0:b9164b348919 327 * Provides a rotation compensated pitch of the device, based on the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 328 *
MrBedfordVan 0:b9164b348919 329 * @return The pitch of the device, in radians.
MrBedfordVan 0:b9164b348919 330 *
MrBedfordVan 0:b9164b348919 331 * @code
MrBedfordVan 0:b9164b348919 332 * accelerometer.getPitchRadians();
MrBedfordVan 0:b9164b348919 333 * @endcode
MrBedfordVan 0:b9164b348919 334 */
MrBedfordVan 0:b9164b348919 335 float getPitchRadians();
MrBedfordVan 0:b9164b348919 336
MrBedfordVan 0:b9164b348919 337 /**
MrBedfordVan 0:b9164b348919 338 * Provides a rotation compensated roll of the device, based on the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 339 *
MrBedfordVan 0:b9164b348919 340 * @return The roll of the device, in degrees.
MrBedfordVan 0:b9164b348919 341 *
MrBedfordVan 0:b9164b348919 342 * @code
MrBedfordVan 0:b9164b348919 343 * accelerometer.getRoll();
MrBedfordVan 0:b9164b348919 344 * @endcode
MrBedfordVan 0:b9164b348919 345 */
MrBedfordVan 0:b9164b348919 346 int getRoll();
MrBedfordVan 0:b9164b348919 347
MrBedfordVan 0:b9164b348919 348 /**
MrBedfordVan 0:b9164b348919 349 * Provides a rotation compensated roll of the device, based on the latest update retrieved from the accelerometer.
MrBedfordVan 0:b9164b348919 350 *
MrBedfordVan 0:b9164b348919 351 * @return The roll of the device, in radians.
MrBedfordVan 0:b9164b348919 352 *
MrBedfordVan 0:b9164b348919 353 * @code
MrBedfordVan 0:b9164b348919 354 * accelerometer.getRollRadians();
MrBedfordVan 0:b9164b348919 355 * @endcode
MrBedfordVan 0:b9164b348919 356 */
MrBedfordVan 0:b9164b348919 357 float getRollRadians();
MrBedfordVan 0:b9164b348919 358
MrBedfordVan 0:b9164b348919 359 /**
MrBedfordVan 0:b9164b348919 360 * Retrieves the last recorded gesture.
MrBedfordVan 0:b9164b348919 361 *
MrBedfordVan 0:b9164b348919 362 * @return The last gesture that was detected.
MrBedfordVan 0:b9164b348919 363 *
MrBedfordVan 0:b9164b348919 364 * Example:
MrBedfordVan 0:b9164b348919 365 * @code
MrBedfordVan 0:b9164b348919 366 * MicroBitDisplay display;
MrBedfordVan 0:b9164b348919 367 *
MrBedfordVan 0:b9164b348919 368 * if (accelerometer.getGesture() == SHAKE)
MrBedfordVan 0:b9164b348919 369 * display.scroll("SHAKE!");
MrBedfordVan 0:b9164b348919 370 * @endcode
MrBedfordVan 0:b9164b348919 371 */
MrBedfordVan 0:b9164b348919 372 uint16_t getGesture();
MrBedfordVan 0:b9164b348919 373
MrBedfordVan 0:b9164b348919 374 /**
MrBedfordVan 0:b9164b348919 375 * A periodic callback invoked by the fiber scheduler idle thread.
MrBedfordVan 0:b9164b348919 376 *
MrBedfordVan 0:b9164b348919 377 * Internally calls updateSample().
MrBedfordVan 0:b9164b348919 378 */
MrBedfordVan 0:b9164b348919 379 virtual void idleTick();
MrBedfordVan 0:b9164b348919 380
MrBedfordVan 0:b9164b348919 381 /**
MrBedfordVan 0:b9164b348919 382 * Destructor for MicroBitButton, where we deregister this instance from the array of fiber components.
MrBedfordVan 0:b9164b348919 383 */
MrBedfordVan 0:b9164b348919 384 ~MicroBitAccelerometer();
MrBedfordVan 0:b9164b348919 385
MrBedfordVan 0:b9164b348919 386 private:
MrBedfordVan 0:b9164b348919 387
MrBedfordVan 0:b9164b348919 388 /**
MrBedfordVan 0:b9164b348919 389 * Issues a standard, 2 byte I2C command write to the accelerometer.
MrBedfordVan 0:b9164b348919 390 *
MrBedfordVan 0:b9164b348919 391 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 392 *
MrBedfordVan 0:b9164b348919 393 * @param reg The address of the register to write to.
MrBedfordVan 0:b9164b348919 394 *
MrBedfordVan 0:b9164b348919 395 * @param value The value to write.
MrBedfordVan 0:b9164b348919 396 *
MrBedfordVan 0:b9164b348919 397 * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the the write request failed.
MrBedfordVan 0:b9164b348919 398 */
MrBedfordVan 0:b9164b348919 399 int writeCommand(uint8_t reg, uint8_t value);
MrBedfordVan 0:b9164b348919 400
MrBedfordVan 0:b9164b348919 401 /**
MrBedfordVan 0:b9164b348919 402 * Issues a read command, copying data into the specified buffer.
MrBedfordVan 0:b9164b348919 403 *
MrBedfordVan 0:b9164b348919 404 * Blocks the calling thread until complete.
MrBedfordVan 0:b9164b348919 405 *
MrBedfordVan 0:b9164b348919 406 * @param reg The address of the register to access.
MrBedfordVan 0:b9164b348919 407 *
MrBedfordVan 0:b9164b348919 408 * @param buffer Memory area to read the data into.
MrBedfordVan 0:b9164b348919 409 *
MrBedfordVan 0:b9164b348919 410 * @param length The number of bytes to read.
MrBedfordVan 0:b9164b348919 411 *
MrBedfordVan 0:b9164b348919 412 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the the read request failed.
MrBedfordVan 0:b9164b348919 413 */
MrBedfordVan 0:b9164b348919 414 int readCommand(uint8_t reg, uint8_t* buffer, int length);
MrBedfordVan 0:b9164b348919 415
MrBedfordVan 0:b9164b348919 416 /**
MrBedfordVan 0:b9164b348919 417 * Recalculate roll and pitch values for the current sample.
MrBedfordVan 0:b9164b348919 418 *
MrBedfordVan 0:b9164b348919 419 * @note We only do this at most once per sample, as the necessary trigonemteric functions are rather
MrBedfordVan 0:b9164b348919 420 * heavyweight for a CPU without a floating point unit.
MrBedfordVan 0:b9164b348919 421 */
MrBedfordVan 0:b9164b348919 422 void recalculatePitchRoll();
MrBedfordVan 0:b9164b348919 423
MrBedfordVan 0:b9164b348919 424 /**
MrBedfordVan 0:b9164b348919 425 * Updates the basic gesture recognizer. This performs instantaneous pose recognition, and also some low pass filtering to promote
MrBedfordVan 0:b9164b348919 426 * stability.
MrBedfordVan 0:b9164b348919 427 */
MrBedfordVan 0:b9164b348919 428 void updateGesture();
MrBedfordVan 0:b9164b348919 429
MrBedfordVan 0:b9164b348919 430 /**
MrBedfordVan 0:b9164b348919 431 * A service function.
MrBedfordVan 0:b9164b348919 432 * It calculates the current scalar acceleration of the device (x^2 + y^2 + z^2).
MrBedfordVan 0:b9164b348919 433 * It does not, however, square root the result, as this is a relatively high cost operation.
MrBedfordVan 0:b9164b348919 434 *
MrBedfordVan 0:b9164b348919 435 * This is left to application code should it be needed.
MrBedfordVan 0:b9164b348919 436 *
MrBedfordVan 0:b9164b348919 437 * @return the sum of the square of the acceleration of the device across all axes.
MrBedfordVan 0:b9164b348919 438 */
MrBedfordVan 0:b9164b348919 439 int instantaneousAccelerationSquared();
MrBedfordVan 0:b9164b348919 440
MrBedfordVan 0:b9164b348919 441 /**
MrBedfordVan 0:b9164b348919 442 * Service function.
MrBedfordVan 0:b9164b348919 443 * Determines a 'best guess' posture of the device based on instantaneous data.
MrBedfordVan 0:b9164b348919 444 *
MrBedfordVan 0:b9164b348919 445 * This makes no use of historic data, and forms this input to the filter implemented in updateGesture().
MrBedfordVan 0:b9164b348919 446 *
MrBedfordVan 0:b9164b348919 447 * @return A 'best guess' of the current posture of the device, based on instanataneous data.
MrBedfordVan 0:b9164b348919 448 */
MrBedfordVan 0:b9164b348919 449 uint16_t instantaneousPosture();
MrBedfordVan 0:b9164b348919 450 };
MrBedfordVan 0:b9164b348919 451
MrBedfordVan 0:b9164b348919 452 #endif