Martin Woolley / microbit-dal-bluetooth-mdw_starter

My fork

Dependencies:   BLE_API mbed-dev-bin nRF51822-bluetooth-mdw

Fork of microbit-dal-bluetooth-mdw by Martin Woolley

inc/drivers/MicroBitAccelerometer.h@38:1a9e8e5e23f2, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 12:18:17 2016 +0100
Revision:
38:1a9e8e5e23f2
Parent:
1:8aa5cdb4ab67
Child:
39:112df23f039f
Synchronized with git rev b5846f06

Author: Joe Finney

microbit: Fixed unreachable High-G gesture events [issue #109]



Ammended basic gesture recogniser to correclty generate threshold events for

high G forces (3G, 6G and 8G threshold events).



Also refined semantics such that events for any given impulse will be

generated for ALL thresholds below that below. e.g a 7G impulse will now raise

both the 3G and 6G threshold events.

Who changed what in which revision?

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