Jan Cumps / microbit

microbit

Dependencies:   microbit-dal

Fork of microbit by Lancaster University

inc/MicroBit.h@12:a62ca1ee7b52, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 13:00:25 2016 +0100
Revision:
12:a62ca1ee7b52
Parent:
1:af427e419320
Child:
13:802a76669499
Synchronized with git rev ef758346

Author: James Devine

microbit: minor spelling corrections



Courtesy of @gbaman

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:af427e419320 1 /*
Jonathan Austin 1:af427e419320 2 The MIT License (MIT)
Jonathan Austin 1:af427e419320 3
Jonathan Austin 1:af427e419320 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:af427e419320 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:af427e419320 6
Jonathan Austin 1:af427e419320 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:af427e419320 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:af427e419320 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:af427e419320 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:af427e419320 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:af427e419320 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:af427e419320 13
Jonathan Austin 1:af427e419320 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:af427e419320 15 all copies or substantial portions of the Software.
Jonathan Austin 1:af427e419320 16
Jonathan Austin 1:af427e419320 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:af427e419320 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:af427e419320 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:af427e419320 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:af427e419320 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:af427e419320 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:af427e419320 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:af427e419320 24 */
Jonathan Austin 1:af427e419320 25
Jonathan Austin 1:af427e419320 26 #ifndef MICROBIT_H
Jonathan Austin 1:af427e419320 27 #define MICROBIT_H
Jonathan Austin 1:af427e419320 28
Jonathan Austin 1:af427e419320 29 #include "mbed.h"
Jonathan Austin 1:af427e419320 30
Jonathan Austin 1:af427e419320 31 #include "MicroBitConfig.h"
Jonathan Austin 1:af427e419320 32 #include "MicroBitHeapAllocator.h"
Jonathan Austin 1:af427e419320 33 #include "MicroBitDevice.h"
Jonathan Austin 1:af427e419320 34 #include "ErrorNo.h"
Jonathan Austin 1:af427e419320 35 #include "MicroBitSystemTimer.h"
Jonathan Austin 1:af427e419320 36 #include "Matrix4.h"
Jonathan Austin 1:af427e419320 37 #include "MicroBitCompat.h"
Jonathan Austin 1:af427e419320 38 #include "MicroBitComponent.h"
Jonathan Austin 1:af427e419320 39 #include "ManagedType.h"
Jonathan Austin 1:af427e419320 40 #include "ManagedString.h"
Jonathan Austin 1:af427e419320 41 #include "MicroBitImage.h"
Jonathan Austin 1:af427e419320 42 #include "MicroBitFont.h"
Jonathan Austin 1:af427e419320 43 #include "MicroBitEvent.h"
Jonathan Austin 1:af427e419320 44 #include "DynamicPwm.h"
Jonathan Austin 1:af427e419320 45 #include "MicroBitI2C.h"
Jonathan Austin 1:af427e419320 46 #include "NotifyEvents.h"
Jonathan Austin 1:af427e419320 47
Jonathan Austin 1:af427e419320 48 #include "MicroBitButton.h"
Jonathan Austin 1:af427e419320 49 #include "MicroBitPin.h"
Jonathan Austin 1:af427e419320 50 #include "MicroBitCompass.h"
Jonathan Austin 1:af427e419320 51 #include "MicroBitCompassCalibrator.h"
Jonathan Austin 1:af427e419320 52 #include "MicroBitAccelerometer.h"
Jonathan Austin 1:af427e419320 53 #include "MicroBitThermometer.h"
Jonathan Austin 1:af427e419320 54 #include "MicroBitLightSensor.h"
Jonathan Austin 1:af427e419320 55 #include "MicroBitMultiButton.h"
Jonathan Austin 1:af427e419320 56
Jonathan Austin 1:af427e419320 57 #include "MicroBitSerial.h"
Jonathan Austin 1:af427e419320 58 #include "MicroBitIO.h"
Jonathan Austin 1:af427e419320 59 #include "MicroBitMatrixMaps.h"
Jonathan Austin 1:af427e419320 60 #include "MicroBitDisplay.h"
Jonathan Austin 1:af427e419320 61
Jonathan Austin 1:af427e419320 62 #include "MicroBitFiber.h"
Jonathan Austin 1:af427e419320 63 #include "MicroBitMessageBus.h"
Jonathan Austin 1:af427e419320 64
Jonathan Austin 1:af427e419320 65 #include "MicroBitBLEManager.h"
Jonathan Austin 1:af427e419320 66 #include "MicroBitRadio.h"
Jonathan Austin 1:af427e419320 67 #include "MicroBitStorage.h"
Jonathan Austin 1:af427e419320 68
Jonathan Austin 1:af427e419320 69 // MicroBit::flags values
Jonathan Austin 1:af427e419320 70 #define MICROBIT_INITIALIZED 0x01
Jonathan Austin 1:af427e419320 71
Jonathan Austin 1:af427e419320 72 /**
Jonathan Austin 1:af427e419320 73 * Class definition for a MicroBit device.
Jonathan Austin 1:af427e419320 74 *
Jonathan Austin 1:af427e419320 75 * Represents the device as a whole, and includes member variables that represent various device drivers
Jonathan Austin 1:af427e419320 76 * used to control aspects of the micro:bit.
Jonathan Austin 1:af427e419320 77 */
Jonathan Austin 1:af427e419320 78 class MicroBit
Jonathan Austin 1:af427e419320 79 {
Jonathan Austin 1:af427e419320 80 private:
Jonathan Austin 1:af427e419320 81
Jonathan Austin 1:af427e419320 82 /**
Jonathan Austin 1:af427e419320 83 * A listener to perform actions as a result of Message Bus reflection.
Jonathan Austin 1:af427e419320 84 *
Jonathan Austin 1:af427e419320 85 * In some cases we want to perform lazy instantiation of components, such as
Jonathan Austin 1:af427e419320 86 * the compass and the accelerometer, where we only want to add them to the idle
Jonathan Austin 1:af427e419320 87 * fiber when someone has the intention of using these components.
Jonathan Austin 1:af427e419320 88 */
Jonathan Austin 1:af427e419320 89 void onListenerRegisteredEvent(MicroBitEvent evt);
Jonathan Austin 1:af427e419320 90
Jonathan Austin 1:af427e419320 91 uint8_t status;
Jonathan Austin 1:af427e419320 92
Jonathan Austin 1:af427e419320 93 public:
Jonathan Austin 1:af427e419320 94
Jonathan Austin 1:af427e419320 95 // Serial Interface
Jonathan Austin 1:af427e419320 96 MicroBitSerial serial;
Jonathan Austin 1:af427e419320 97
Jonathan Austin 1:af427e419320 98 // Reset Button
Jonathan Austin 1:af427e419320 99 InterruptIn resetButton;
Jonathan Austin 1:af427e419320 100
Jonathan Austin 1:af427e419320 101 // Persistent key value store
Jonathan Austin 1:af427e419320 102 MicroBitStorage storage;
Jonathan Austin 1:af427e419320 103
Jonathan Austin 1:af427e419320 104 // I2C Interface
Jonathan Austin 1:af427e419320 105 MicroBitI2C i2c;
Jonathan Austin 1:af427e419320 106
Jonathan Austin 1:af427e419320 107 // Device level Message Bus abstraction
Jonathan Austin 1:af427e419320 108 MicroBitMessageBus messageBus;
Jonathan Austin 1:af427e419320 109
Jonathan Austin 1:af427e419320 110 // Member variables to represent each of the core components on the device.
Jonathan Austin 1:af427e419320 111 MicroBitDisplay display;
Jonathan Austin 1:af427e419320 112 MicroBitButton buttonA;
Jonathan Austin 1:af427e419320 113 MicroBitButton buttonB;
Jonathan Austin 1:af427e419320 114 MicroBitMultiButton buttonAB;
Jonathan Austin 1:af427e419320 115 MicroBitAccelerometer accelerometer;
Jonathan Austin 1:af427e419320 116 MicroBitCompass compass;
Jonathan Austin 1:af427e419320 117 MicroBitCompassCalibrator compassCalibrator;
Jonathan Austin 1:af427e419320 118 MicroBitThermometer thermometer;
Jonathan Austin 1:af427e419320 119
Jonathan Austin 1:af427e419320 120 //An object of available IO pins on the device
Jonathan Austin 1:af427e419320 121 MicroBitIO io;
Jonathan Austin 1:af427e419320 122
Jonathan Austin 1:af427e419320 123 // Bluetooth related member variables.
Jonathan Austin 1:af427e419320 124 MicroBitBLEManager bleManager;
Jonathan Austin 1:af427e419320 125 MicroBitRadio radio;
Jonathan Austin 1:af427e419320 126 BLEDevice *ble;
Jonathan Austin 1:af427e419320 127
Jonathan Austin 1:af427e419320 128 /**
Jonathan Austin 1:af427e419320 129 * Constructor.
Jonathan Austin 1:af427e419320 130 *
Jonathan Austin 1:af427e419320 131 * Create a representation of a MicroBit device, which includes member variables
Jonathan Austin 1:af427e419320 132 * that represent various device drivers used to control aspects of the micro:bit.
Jonathan Austin 1:af427e419320 133 */
Jonathan Austin 1:af427e419320 134 MicroBit();
Jonathan Austin 1:af427e419320 135
Jonathan Austin 1:af427e419320 136 /**
Jonathan Austin 1:af427e419320 137 * Post constructor initialisation method.
Jonathan Austin 1:af427e419320 138 *
Jonathan Austin 1:af427e419320 139 * This call will initialised the scheduler, memory allocator and Bluetooth stack.
Jonathan Austin 1:af427e419320 140 *
Jonathan Austin 1:af427e419320 141 * This is required as the Bluetooth stack can't be brought up in a
Jonathan Austin 1:af427e419320 142 * static context i.e. in a constructor.
Jonathan Austin 1:af427e419320 143 *
Jonathan Austin 1:af427e419320 144 * @code
Jonathan Austin 1:af427e419320 145 * uBit.init();
Jonathan Austin 1:af427e419320 146 * @endcode
Jonathan Austin 1:af427e419320 147 *
Jonathan Austin 1:af427e419320 148 * @note This method must be called before user code utilises any functionality
Jonathan Austin 1:af427e419320 149 * contained by uBit.
Jonathan Austin 1:af427e419320 150 */
Jonathan Austin 1:af427e419320 151 void init();
Jonathan Austin 1:af427e419320 152
Jonathan Austin 1:af427e419320 153 /**
Jonathan Austin 1:af427e419320 154 * Return the friendly name for this device.
Jonathan Austin 1:af427e419320 155 *
Jonathan Austin 1:af427e419320 156 * @return A ManagedString representing the friendly name of this device.
Jonathan Austin 1:af427e419320 157 *
Jonathan Austin 1:af427e419320 158 * @code
Jonathan Austin 1:af427e419320 159 * ManagedString name = uBit.getName();
Jonathan Austin 1:af427e419320 160 * @endcode
Jonathan Austin 1:af427e419320 161 */
Jonathan Austin 1:af427e419320 162 static ManagedString getName();
Jonathan Austin 1:af427e419320 163
Jonathan Austin 1:af427e419320 164 /**
Jonathan Austin 1:af427e419320 165 * Return the serial number of this device.
Jonathan Austin 1:af427e419320 166 *
Jonathan Austin 1:af427e419320 167 * @return A ManagedString representing the serial number of this device.
Jonathan Austin 1:af427e419320 168 *
Jonathan Austin 1:af427e419320 169 * @code
Jonathan Austin 1:af427e419320 170 * ManagedString serialNumber = uBit.getSerial();
Jonathan Austin 1:af427e419320 171 * @endcode
Jonathan Austin 1:af427e419320 172 */
Jonathan Austin 1:af427e419320 173 static ManagedString getSerial();
Jonathan Austin 1:af427e419320 174
Jonathan Austin 1:af427e419320 175 /**
Jonathan Austin 1:af427e419320 176 * Will reset the micro:bit when called.
Jonathan Austin 1:af427e419320 177 *
Jonathan Austin 1:af427e419320 178 * @code
Jonathan Austin 1:af427e419320 179 * uBit.reset();
Jonathan Austin 1:af427e419320 180 * @endcode
Jonathan Austin 1:af427e419320 181 */
Jonathan Austin 1:af427e419320 182 void reset();
Jonathan Austin 1:af427e419320 183
Jonathan Austin 1:af427e419320 184 /**
Jonathan Austin 1:af427e419320 185 * Delay execution for the given amount of time.
Jonathan Austin 1:af427e419320 186 *
Jonathan Austin 1:af427e419320 187 * If the scheduler is running, this will deschedule the current fiber and perform
LancasterUniversity 12:a62ca1ee7b52 188 * a power efficient, concurrent sleep operation.
Jonathan Austin 1:af427e419320 189 *
Jonathan Austin 1:af427e419320 190 * If the scheduler is disabled or we're running in an interrupt context, this
Jonathan Austin 1:af427e419320 191 * will revert to a busy wait.
Jonathan Austin 1:af427e419320 192 *
Jonathan Austin 1:af427e419320 193 * Alternatively: wait, wait_ms, wait_us can be used which will perform a blocking sleep
Jonathan Austin 1:af427e419320 194 * operation.
Jonathan Austin 1:af427e419320 195 *
Jonathan Austin 1:af427e419320 196 * @param milliseconds the amount of time, in ms, to wait for. This number cannot be negative.
Jonathan Austin 1:af427e419320 197 *
Jonathan Austin 1:af427e419320 198 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER milliseconds is less than zero.
Jonathan Austin 1:af427e419320 199 *
Jonathan Austin 1:af427e419320 200 * @code
Jonathan Austin 1:af427e419320 201 * uBit.sleep(20); //sleep for 20ms
Jonathan Austin 1:af427e419320 202 * @endcode
Jonathan Austin 1:af427e419320 203 *
Jonathan Austin 1:af427e419320 204 * @note This operation is currently limited by the rate of the system timer, therefore
Jonathan Austin 1:af427e419320 205 * the granularity of the sleep operation is limited to 6 ms unless the rate of
Jonathan Austin 1:af427e419320 206 * the system timer is modified.
Jonathan Austin 1:af427e419320 207 */
Jonathan Austin 1:af427e419320 208 void sleep(uint32_t milliseconds);
Jonathan Austin 1:af427e419320 209
Jonathan Austin 1:af427e419320 210 /**
Jonathan Austin 1:af427e419320 211 * Seed the pseudo random number generator using the hardware random number generator.
Jonathan Austin 1:af427e419320 212 *
Jonathan Austin 1:af427e419320 213 * @code
Jonathan Austin 1:af427e419320 214 * uBit.seedRandom();
Jonathan Austin 1:af427e419320 215 * @endcode
Jonathan Austin 1:af427e419320 216 */
Jonathan Austin 1:af427e419320 217 void seedRandom();
Jonathan Austin 1:af427e419320 218
Jonathan Austin 1:af427e419320 219 /**
Jonathan Austin 1:af427e419320 220 * Seed the pseudo random number generator using the given value.
Jonathan Austin 1:af427e419320 221 *
Jonathan Austin 1:af427e419320 222 * @param seed The 32-bit value to seed the generator with.
Jonathan Austin 1:af427e419320 223 *
Jonathan Austin 1:af427e419320 224 * @code
Jonathan Austin 1:af427e419320 225 * uBit.seedRandom(0xBB5EED);
Jonathan Austin 1:af427e419320 226 * @endcode
Jonathan Austin 1:af427e419320 227 */
Jonathan Austin 1:af427e419320 228 void seedRandom(uint32_t seed);
Jonathan Austin 1:af427e419320 229
Jonathan Austin 1:af427e419320 230
Jonathan Austin 1:af427e419320 231 /**
Jonathan Austin 1:af427e419320 232 * Generate a random number in the given range.
Jonathan Austin 1:af427e419320 233 * We use a simple Galois LFSR random number generator here,
Jonathan Austin 1:af427e419320 234 * as a Galois LFSR is sufficient for our applications, and much more lightweight
Jonathan Austin 1:af427e419320 235 * than the hardware random number generator built int the processor, which takes
Jonathan Austin 1:af427e419320 236 * a long time and uses a lot of energy.
Jonathan Austin 1:af427e419320 237 *
Jonathan Austin 1:af427e419320 238 * KIDS: You shouldn't use this is the real world to generte cryptographic keys though...
Jonathan Austin 1:af427e419320 239 * have a think why not. :-)
Jonathan Austin 1:af427e419320 240 *
Jonathan Austin 1:af427e419320 241 * @param max the upper range to generate a number for. This number cannot be negative.
Jonathan Austin 1:af427e419320 242 *
Jonathan Austin 1:af427e419320 243 * @return A random, natural number between 0 and the max-1. Or MICROBIT_INVALID_VALUE if max is <= 0.
Jonathan Austin 1:af427e419320 244 *
Jonathan Austin 1:af427e419320 245 * @code
Jonathan Austin 1:af427e419320 246 * uBit.random(200); //a number between 0 and 199
Jonathan Austin 1:af427e419320 247 * @endcode
Jonathan Austin 1:af427e419320 248 */
Jonathan Austin 1:af427e419320 249 int random(int max);
Jonathan Austin 1:af427e419320 250
Jonathan Austin 1:af427e419320 251 /**
Jonathan Austin 1:af427e419320 252 * Determine the time since this MicroBit was last reset.
Jonathan Austin 1:af427e419320 253 *
Jonathan Austin 1:af427e419320 254 * @return The time since the last reset, in milliseconds.
Jonathan Austin 1:af427e419320 255 *
Jonathan Austin 1:af427e419320 256 * @note This will value overflow after 1.6 months.
Jonathan Austin 1:af427e419320 257 */
Jonathan Austin 1:af427e419320 258 //TODO: handle overflow case.
Jonathan Austin 1:af427e419320 259 unsigned long systemTime();
Jonathan Austin 1:af427e419320 260
Jonathan Austin 1:af427e419320 261 /**
Jonathan Austin 1:af427e419320 262 * Determine the version of the micro:bit runtime currently in use.
Jonathan Austin 1:af427e419320 263 *
Jonathan Austin 1:af427e419320 264 * @return A textual description of the version of the micro:bit runtime that
Jonathan Austin 1:af427e419320 265 * is currently running on this device.
Jonathan Austin 1:af427e419320 266 */
Jonathan Austin 1:af427e419320 267 const char *systemVersion();
Jonathan Austin 1:af427e419320 268
Jonathan Austin 1:af427e419320 269 /**
Jonathan Austin 1:af427e419320 270 * Triggers a microbit panic where an loop will display a panic face
Jonathan Austin 1:af427e419320 271 * and the status code, if provided.
Jonathan Austin 1:af427e419320 272 *
Jonathan Austin 1:af427e419320 273 * This loop will continue for panic_timeout iterations, defaults to 0 (infinite).
Jonathan Austin 1:af427e419320 274 *
Jonathan Austin 1:af427e419320 275 * panic_timeout can be configured via a call to microbit_panic_timeout.
Jonathan Austin 1:af427e419320 276 *
Jonathan Austin 1:af427e419320 277 * @param statusCode the status code of the associated error.
Jonathan Austin 1:af427e419320 278 *
Jonathan Austin 1:af427e419320 279 * @code
Jonathan Austin 1:af427e419320 280 * microbit_panic_timeout(4);
Jonathan Austin 1:af427e419320 281 *
Jonathan Austin 1:af427e419320 282 * // will display loop for 4 iterations.
Jonathan Austin 1:af427e419320 283 * uBit.panic(10);
Jonathan Austin 1:af427e419320 284 * @endcode
Jonathan Austin 1:af427e419320 285 */
Jonathan Austin 1:af427e419320 286 void panic(int statusCode = 0);
Jonathan Austin 1:af427e419320 287
Jonathan Austin 1:af427e419320 288 /**
Jonathan Austin 1:af427e419320 289 * Add a component to the array of system components. This component will then receive
Jonathan Austin 1:af427e419320 290 * periodic callbacks, once every tick period in interrupt context.
Jonathan Austin 1:af427e419320 291 *
Jonathan Austin 1:af427e419320 292 * @param component The component to add.
Jonathan Austin 1:af427e419320 293 *
Jonathan Austin 1:af427e419320 294 * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the component array is full.
Jonathan Austin 1:af427e419320 295 *
Jonathan Austin 1:af427e419320 296 * @code
Jonathan Austin 1:af427e419320 297 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 298 * MicroBitDisplay* display = new MicroBitDisplay();
Jonathan Austin 1:af427e419320 299 *
Jonathan Austin 1:af427e419320 300 * uBit.addSystemComponent(display);
Jonathan Austin 1:af427e419320 301 * @endcode
Jonathan Austin 1:af427e419320 302 *
Jonathan Austin 1:af427e419320 303 * @note This interface is now deprecated, and will be removed in the next major release. Please use system_timer_add_component().
Jonathan Austin 1:af427e419320 304 */
Jonathan Austin 1:af427e419320 305 int addSystemComponent(MicroBitComponent *component);
Jonathan Austin 1:af427e419320 306
Jonathan Austin 1:af427e419320 307 /**
Jonathan Austin 1:af427e419320 308 * Remove a component from the array of system components. This component will no longer receive
Jonathan Austin 1:af427e419320 309 * periodic callbacks.
Jonathan Austin 1:af427e419320 310 *
Jonathan Austin 1:af427e419320 311 * @param component The component to remove.
Jonathan Austin 1:af427e419320 312 *
Jonathan Austin 1:af427e419320 313 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
Jonathan Austin 1:af427e419320 314 *
Jonathan Austin 1:af427e419320 315 * @code
Jonathan Austin 1:af427e419320 316 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 317 * MicroBitDisplay* display = new MicroBitDisplay();
Jonathan Austin 1:af427e419320 318 *
Jonathan Austin 1:af427e419320 319 * uBit.addSystemComponent(display);
Jonathan Austin 1:af427e419320 320 *
Jonathan Austin 1:af427e419320 321 * uBit.removeSystemComponent(display);
Jonathan Austin 1:af427e419320 322 * @endcode
Jonathan Austin 1:af427e419320 323 *
Jonathan Austin 1:af427e419320 324 * @note This interface is now deprecated, and will be removed in the next major release. Please use system_timer_remove_component().
Jonathan Austin 1:af427e419320 325 */
Jonathan Austin 1:af427e419320 326 int removeSystemComponent(MicroBitComponent *component);
Jonathan Austin 1:af427e419320 327
Jonathan Austin 1:af427e419320 328 /**
Jonathan Austin 1:af427e419320 329 * Adds a component to the array of idle thread components, which are processed
Jonathan Austin 1:af427e419320 330 * when the run queue is empty.
Jonathan Austin 1:af427e419320 331 *
Jonathan Austin 1:af427e419320 332 * The system timer will poll isIdleCallbackNeeded on each component to determine
Jonathan Austin 1:af427e419320 333 * if the scheduler should schedule the idle_task imminently.
Jonathan Austin 1:af427e419320 334 *
Jonathan Austin 1:af427e419320 335 * @param component The component to add to the array.
Jonathan Austin 1:af427e419320 336 *
Jonathan Austin 1:af427e419320 337 * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the fiber components array is full.
Jonathan Austin 1:af427e419320 338 *
Jonathan Austin 1:af427e419320 339 * @code
Jonathan Austin 1:af427e419320 340 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
Jonathan Austin 1:af427e419320 341 *
Jonathan Austin 1:af427e419320 342 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 343 * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
Jonathan Austin 1:af427e419320 344 *
Jonathan Austin 1:af427e419320 345 * fiber_add_idle_component(accelerometer);
Jonathan Austin 1:af427e419320 346 * @endcode
Jonathan Austin 1:af427e419320 347 *
Jonathan Austin 1:af427e419320 348 * @note This interface is now deprecated, and will be removed in the next major release. Please use fiber_add_idle_component().
Jonathan Austin 1:af427e419320 349 */
Jonathan Austin 1:af427e419320 350 int addIdleComponent(MicroBitComponent *component);
Jonathan Austin 1:af427e419320 351
Jonathan Austin 1:af427e419320 352 /**
Jonathan Austin 1:af427e419320 353 * Remove a component from the array of idle thread components
Jonathan Austin 1:af427e419320 354 *
Jonathan Austin 1:af427e419320 355 * @param component The component to remove from the idle component array.
Jonathan Austin 1:af427e419320 356 *
Jonathan Austin 1:af427e419320 357 * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
Jonathan Austin 1:af427e419320 358 *
Jonathan Austin 1:af427e419320 359 * @code
Jonathan Austin 1:af427e419320 360 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
Jonathan Austin 1:af427e419320 361 *
Jonathan Austin 1:af427e419320 362 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 363 * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
Jonathan Austin 1:af427e419320 364 *
Jonathan Austin 1:af427e419320 365 * uBit.addIdleComponent(accelerometer);
Jonathan Austin 1:af427e419320 366 *
Jonathan Austin 1:af427e419320 367 * uBit.removeIdleComponent(accelerometer);
Jonathan Austin 1:af427e419320 368 * @endcode
Jonathan Austin 1:af427e419320 369 *
Jonathan Austin 1:af427e419320 370 * @note This interface is now deprecated, and will be removed in the next major release. Please use fiber_remove_idle_component().
Jonathan Austin 1:af427e419320 371 */
Jonathan Austin 1:af427e419320 372 int removeIdleComponent(MicroBitComponent *component);
Jonathan Austin 1:af427e419320 373 };
Jonathan Austin 1:af427e419320 374
Jonathan Austin 1:af427e419320 375 /**
Jonathan Austin 1:af427e419320 376 * Return the friendly name for this device.
Jonathan Austin 1:af427e419320 377 *
Jonathan Austin 1:af427e419320 378 * @return A ManagedString representing the friendly name of this device.
Jonathan Austin 1:af427e419320 379 *
Jonathan Austin 1:af427e419320 380 * @code
Jonathan Austin 1:af427e419320 381 * ManagedString name = uBit.getName();
Jonathan Austin 1:af427e419320 382 * @endcode
Jonathan Austin 1:af427e419320 383 */
Jonathan Austin 1:af427e419320 384 inline ManagedString MicroBit::getName()
Jonathan Austin 1:af427e419320 385 {
Jonathan Austin 1:af427e419320 386 return ManagedString(microbit_friendly_name());
Jonathan Austin 1:af427e419320 387 }
Jonathan Austin 1:af427e419320 388
Jonathan Austin 1:af427e419320 389 /**
Jonathan Austin 1:af427e419320 390 * Return the serial number of this device.
Jonathan Austin 1:af427e419320 391 *
Jonathan Austin 1:af427e419320 392 * @return A ManagedString representing the serial number of this device.
Jonathan Austin 1:af427e419320 393 *
Jonathan Austin 1:af427e419320 394 * @code
Jonathan Austin 1:af427e419320 395 * ManagedString serialNumber = uBit.getSerial();
Jonathan Austin 1:af427e419320 396 * @endcode
Jonathan Austin 1:af427e419320 397 */
Jonathan Austin 1:af427e419320 398 inline ManagedString MicroBit::getSerial()
Jonathan Austin 1:af427e419320 399 {
Jonathan Austin 1:af427e419320 400 // We take to 16 bit numbers here, as we want the full range of ID bits, but don't want negative numbers...
Jonathan Austin 1:af427e419320 401 int n1 = microbit_serial_number() & 0xffff;
Jonathan Austin 1:af427e419320 402 int n2 = (microbit_serial_number() >> 16) & 0xffff;
Jonathan Austin 1:af427e419320 403
Jonathan Austin 1:af427e419320 404 // Simply concat the two numbers.
Jonathan Austin 1:af427e419320 405 ManagedString s1(n1);
Jonathan Austin 1:af427e419320 406 ManagedString s2(n2);
Jonathan Austin 1:af427e419320 407
Jonathan Austin 1:af427e419320 408 return s1 + s2;
Jonathan Austin 1:af427e419320 409 }
Jonathan Austin 1:af427e419320 410
Jonathan Austin 1:af427e419320 411 /**
Jonathan Austin 1:af427e419320 412 * Will reset the micro:bit when called.
Jonathan Austin 1:af427e419320 413 *
Jonathan Austin 1:af427e419320 414 * @code
Jonathan Austin 1:af427e419320 415 * uBit.reset();
Jonathan Austin 1:af427e419320 416 * @endcode
Jonathan Austin 1:af427e419320 417 */
Jonathan Austin 1:af427e419320 418 inline void MicroBit::reset()
Jonathan Austin 1:af427e419320 419 {
Jonathan Austin 1:af427e419320 420 if(ble && ble->getGapState().connected) {
Jonathan Austin 1:af427e419320 421
Jonathan Austin 1:af427e419320 422 // We have a connected BLE peer. Disconnect the BLE session.
Jonathan Austin 1:af427e419320 423 ble->gap().disconnect(Gap::REMOTE_USER_TERMINATED_CONNECTION);
Jonathan Austin 1:af427e419320 424
Jonathan Austin 1:af427e419320 425 // Wait a little while for the connection to drop.
Jonathan Austin 1:af427e419320 426 wait_ms(100);
Jonathan Austin 1:af427e419320 427 }
Jonathan Austin 1:af427e419320 428
Jonathan Austin 1:af427e419320 429 microbit_reset();
Jonathan Austin 1:af427e419320 430 }
Jonathan Austin 1:af427e419320 431
Jonathan Austin 1:af427e419320 432 /**
Jonathan Austin 1:af427e419320 433 * Delay execution for the given amount of time.
Jonathan Austin 1:af427e419320 434 *
Jonathan Austin 1:af427e419320 435 * If the scheduler is running, this will deschedule the current fiber and perform
LancasterUniversity 12:a62ca1ee7b52 436 * a power efficient, concurrent sleep operation.
Jonathan Austin 1:af427e419320 437 *
Jonathan Austin 1:af427e419320 438 * If the scheduler is disabled or we're running in an interrupt context, this
Jonathan Austin 1:af427e419320 439 * will revert to a busy wait.
Jonathan Austin 1:af427e419320 440 *
Jonathan Austin 1:af427e419320 441 * Alternatively: wait, wait_ms, wait_us can be used which will perform a blocking sleep
Jonathan Austin 1:af427e419320 442 * operation.
Jonathan Austin 1:af427e419320 443 *
Jonathan Austin 1:af427e419320 444 * @param milliseconds the amount of time, in ms, to wait for. This number cannot be negative.
Jonathan Austin 1:af427e419320 445 *
Jonathan Austin 1:af427e419320 446 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER milliseconds is less than zero.
Jonathan Austin 1:af427e419320 447 *
Jonathan Austin 1:af427e419320 448 * @code
Jonathan Austin 1:af427e419320 449 * uBit.sleep(20); //sleep for 20ms
Jonathan Austin 1:af427e419320 450 * @endcode
Jonathan Austin 1:af427e419320 451 *
Jonathan Austin 1:af427e419320 452 * @note This operation is currently limited by the rate of the system timer, therefore
Jonathan Austin 1:af427e419320 453 * the granularity of the sleep operation is limited to 6 ms unless the rate of
Jonathan Austin 1:af427e419320 454 * the system timer is modified.
Jonathan Austin 1:af427e419320 455 */
Jonathan Austin 1:af427e419320 456 inline void MicroBit::sleep(uint32_t milliseconds)
Jonathan Austin 1:af427e419320 457 {
Jonathan Austin 1:af427e419320 458 fiber_sleep(milliseconds);
Jonathan Austin 1:af427e419320 459 }
Jonathan Austin 1:af427e419320 460
Jonathan Austin 1:af427e419320 461 /**
Jonathan Austin 1:af427e419320 462 * Generate a random number in the given range.
Jonathan Austin 1:af427e419320 463 * We use a simple Galois LFSR random number generator here,
Jonathan Austin 1:af427e419320 464 * as a Galois LFSR is sufficient for our applications, and much more lightweight
Jonathan Austin 1:af427e419320 465 * than the hardware random number generator built int the processor, which takes
Jonathan Austin 1:af427e419320 466 * a long time and uses a lot of energy.
Jonathan Austin 1:af427e419320 467 *
Jonathan Austin 1:af427e419320 468 * KIDS: You shouldn't use this is the real world to generte cryptographic keys though...
Jonathan Austin 1:af427e419320 469 * have a think why not. :-)
Jonathan Austin 1:af427e419320 470 *
Jonathan Austin 1:af427e419320 471 * @param max the upper range to generate a number for. This number cannot be negative.
Jonathan Austin 1:af427e419320 472 *
Jonathan Austin 1:af427e419320 473 * @return A random, natural number between 0 and the max-1. Or MICROBIT_INVALID_VALUE if max is <= 0.
Jonathan Austin 1:af427e419320 474 *
Jonathan Austin 1:af427e419320 475 * @code
Jonathan Austin 1:af427e419320 476 * uBit.random(200); //a number between 0 and 199
Jonathan Austin 1:af427e419320 477 * @endcode
Jonathan Austin 1:af427e419320 478 */
Jonathan Austin 1:af427e419320 479 inline int MicroBit::random(int max)
Jonathan Austin 1:af427e419320 480 {
Jonathan Austin 1:af427e419320 481 return microbit_random(max);
Jonathan Austin 1:af427e419320 482 }
Jonathan Austin 1:af427e419320 483
Jonathan Austin 1:af427e419320 484 /**
Jonathan Austin 1:af427e419320 485 * Seed the pseudo random number generator using the hardware random number generator.
Jonathan Austin 1:af427e419320 486 *
Jonathan Austin 1:af427e419320 487 * @code
Jonathan Austin 1:af427e419320 488 * uBit.seedRandom();
Jonathan Austin 1:af427e419320 489 * @endcode
Jonathan Austin 1:af427e419320 490 */
Jonathan Austin 1:af427e419320 491 inline void MicroBit::seedRandom()
Jonathan Austin 1:af427e419320 492 {
Jonathan Austin 1:af427e419320 493 microbit_seed_random();
Jonathan Austin 1:af427e419320 494 }
Jonathan Austin 1:af427e419320 495
Jonathan Austin 1:af427e419320 496
Jonathan Austin 1:af427e419320 497 /**
Jonathan Austin 1:af427e419320 498 * Seed the pseudo random number generator using the given value.
Jonathan Austin 1:af427e419320 499 *
Jonathan Austin 1:af427e419320 500 * @param seed The 32-bit value to seed the generator with.
Jonathan Austin 1:af427e419320 501 *
Jonathan Austin 1:af427e419320 502 * @code
Jonathan Austin 1:af427e419320 503 * uBit.seedRandom(0xBB5EED);
Jonathan Austin 1:af427e419320 504 * @endcode
Jonathan Austin 1:af427e419320 505 */
Jonathan Austin 1:af427e419320 506 inline void MicroBit::seedRandom(uint32_t seed)
Jonathan Austin 1:af427e419320 507 {
Jonathan Austin 1:af427e419320 508 microbit_seed_random(seed);
Jonathan Austin 1:af427e419320 509 }
Jonathan Austin 1:af427e419320 510
Jonathan Austin 1:af427e419320 511
Jonathan Austin 1:af427e419320 512 /**
Jonathan Austin 1:af427e419320 513 * Add a component to the array of system components. This component will then receive
Jonathan Austin 1:af427e419320 514 * periodic callbacks, once every tick period in interrupt context.
Jonathan Austin 1:af427e419320 515 *
Jonathan Austin 1:af427e419320 516 * @param component The component to add.
Jonathan Austin 1:af427e419320 517 *
Jonathan Austin 1:af427e419320 518 * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the component array is full.
Jonathan Austin 1:af427e419320 519 *
Jonathan Austin 1:af427e419320 520 * @code
Jonathan Austin 1:af427e419320 521 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 522 * MicroBitDisplay* display = new MicroBitDisplay();
Jonathan Austin 1:af427e419320 523 *
Jonathan Austin 1:af427e419320 524 * uBit.addSystemComponent(display);
Jonathan Austin 1:af427e419320 525 * @endcode
Jonathan Austin 1:af427e419320 526 *
Jonathan Austin 1:af427e419320 527 * @note This interface is now deprecated, and will be removed in the next major release. Please use system_timer_add_component().
Jonathan Austin 1:af427e419320 528 */
Jonathan Austin 1:af427e419320 529 inline int MicroBit::addSystemComponent(MicroBitComponent *component)
Jonathan Austin 1:af427e419320 530 {
Jonathan Austin 1:af427e419320 531 return system_timer_add_component(component);
Jonathan Austin 1:af427e419320 532 }
Jonathan Austin 1:af427e419320 533
Jonathan Austin 1:af427e419320 534 /**
Jonathan Austin 1:af427e419320 535 * Remove a component from the array of system components. This component will no longer receive
Jonathan Austin 1:af427e419320 536 * periodic callbacks.
Jonathan Austin 1:af427e419320 537 *
Jonathan Austin 1:af427e419320 538 * @param component The component to remove.
Jonathan Austin 1:af427e419320 539 *
Jonathan Austin 1:af427e419320 540 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
Jonathan Austin 1:af427e419320 541 *
Jonathan Austin 1:af427e419320 542 * @code
Jonathan Austin 1:af427e419320 543 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 544 * MicroBitDisplay* display = new MicroBitDisplay();
Jonathan Austin 1:af427e419320 545 *
Jonathan Austin 1:af427e419320 546 * uBit.addSystemComponent(display);
Jonathan Austin 1:af427e419320 547 *
Jonathan Austin 1:af427e419320 548 * uBit.removeSystemComponent(display);
Jonathan Austin 1:af427e419320 549 * @endcode
Jonathan Austin 1:af427e419320 550 *
Jonathan Austin 1:af427e419320 551 * @note This interface is now deprecated, and will be removed in the next major release. Please use system_timer_remove_component().
Jonathan Austin 1:af427e419320 552 */
Jonathan Austin 1:af427e419320 553 inline int MicroBit::removeSystemComponent(MicroBitComponent *component)
Jonathan Austin 1:af427e419320 554 {
Jonathan Austin 1:af427e419320 555 return system_timer_remove_component(component);
Jonathan Austin 1:af427e419320 556 }
Jonathan Austin 1:af427e419320 557
Jonathan Austin 1:af427e419320 558 /**
Jonathan Austin 1:af427e419320 559 * Adds a component to the array of idle thread components, which are processed
Jonathan Austin 1:af427e419320 560 * when the run queue is empty.
Jonathan Austin 1:af427e419320 561 *
Jonathan Austin 1:af427e419320 562 * The system timer will poll isIdleCallbackNeeded on each component to determine
Jonathan Austin 1:af427e419320 563 * if the scheduler should schedule the idle_task imminently.
Jonathan Austin 1:af427e419320 564 *
Jonathan Austin 1:af427e419320 565 * @param component The component to add to the array.
Jonathan Austin 1:af427e419320 566 *
Jonathan Austin 1:af427e419320 567 * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the fiber components array is full.
Jonathan Austin 1:af427e419320 568 *
Jonathan Austin 1:af427e419320 569 * @code
Jonathan Austin 1:af427e419320 570 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
Jonathan Austin 1:af427e419320 571 *
Jonathan Austin 1:af427e419320 572 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 573 * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
Jonathan Austin 1:af427e419320 574 *
Jonathan Austin 1:af427e419320 575 * fiber_add_idle_component(accelerometer);
Jonathan Austin 1:af427e419320 576 * @endcode
Jonathan Austin 1:af427e419320 577 *
Jonathan Austin 1:af427e419320 578 * @note This interface is now deprecated, and will be removed in the next major release. Please use fiber_add_idle_component().
Jonathan Austin 1:af427e419320 579 */
Jonathan Austin 1:af427e419320 580 inline int MicroBit::addIdleComponent(MicroBitComponent *component)
Jonathan Austin 1:af427e419320 581 {
Jonathan Austin 1:af427e419320 582 return fiber_add_idle_component(component);
Jonathan Austin 1:af427e419320 583 }
Jonathan Austin 1:af427e419320 584
Jonathan Austin 1:af427e419320 585 /**
Jonathan Austin 1:af427e419320 586 * Remove a component from the array of idle thread components
Jonathan Austin 1:af427e419320 587 *
Jonathan Austin 1:af427e419320 588 * @param component The component to remove from the idle component array.
Jonathan Austin 1:af427e419320 589 *
Jonathan Austin 1:af427e419320 590 * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
Jonathan Austin 1:af427e419320 591 *
Jonathan Austin 1:af427e419320 592 * @code
Jonathan Austin 1:af427e419320 593 * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
Jonathan Austin 1:af427e419320 594 *
Jonathan Austin 1:af427e419320 595 * // heap allocated - otherwise it will be paged out!
Jonathan Austin 1:af427e419320 596 * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
Jonathan Austin 1:af427e419320 597 *
Jonathan Austin 1:af427e419320 598 * uBit.addIdleComponent(accelerometer);
Jonathan Austin 1:af427e419320 599 *
Jonathan Austin 1:af427e419320 600 * uBit.removeIdleComponent(accelerometer);
Jonathan Austin 1:af427e419320 601 * @endcode
Jonathan Austin 1:af427e419320 602 *
Jonathan Austin 1:af427e419320 603 * @note This interface is now deprecated, and will be removed in the next major release. Please use fiber_remove_idle_component().
Jonathan Austin 1:af427e419320 604 */
Jonathan Austin 1:af427e419320 605 inline int MicroBit::removeIdleComponent(MicroBitComponent *component)
Jonathan Austin 1:af427e419320 606 {
Jonathan Austin 1:af427e419320 607 return fiber_remove_idle_component(component);
Jonathan Austin 1:af427e419320 608 }
Jonathan Austin 1:af427e419320 609
Jonathan Austin 1:af427e419320 610
Jonathan Austin 1:af427e419320 611 /**
Jonathan Austin 1:af427e419320 612 * Determine the time since this MicroBit was last reset.
Jonathan Austin 1:af427e419320 613 *
Jonathan Austin 1:af427e419320 614 * @return The time since the last reset, in milliseconds.
Jonathan Austin 1:af427e419320 615 *
Jonathan Austin 1:af427e419320 616 * @note This will value overflow after 1.6 months.
Jonathan Austin 1:af427e419320 617 */
Jonathan Austin 1:af427e419320 618 inline unsigned long MicroBit::systemTime()
Jonathan Austin 1:af427e419320 619 {
Jonathan Austin 1:af427e419320 620 return system_timer_current_time();
Jonathan Austin 1:af427e419320 621 }
Jonathan Austin 1:af427e419320 622
Jonathan Austin 1:af427e419320 623
Jonathan Austin 1:af427e419320 624 /**
Jonathan Austin 1:af427e419320 625 * Determine the version of the micro:bit runtime currently in use.
Jonathan Austin 1:af427e419320 626 *
Jonathan Austin 1:af427e419320 627 * @return A textual description of the version of the micro:bit runtime that
Jonathan Austin 1:af427e419320 628 * is currently running on this device.
Jonathan Austin 1:af427e419320 629 */
Jonathan Austin 1:af427e419320 630 inline const char *MicroBit::systemVersion()
Jonathan Austin 1:af427e419320 631 {
Jonathan Austin 1:af427e419320 632 return microbit_dal_version();
Jonathan Austin 1:af427e419320 633 }
Jonathan Austin 1:af427e419320 634
Jonathan Austin 1:af427e419320 635 /**
Jonathan Austin 1:af427e419320 636 * Triggers a microbit panic where an loop will display a panic face
Jonathan Austin 1:af427e419320 637 * and the status code, if provided.
Jonathan Austin 1:af427e419320 638 *
Jonathan Austin 1:af427e419320 639 * This loop will continue for panic_timeout iterations, defaults to 0 (infinite).
Jonathan Austin 1:af427e419320 640 *
Jonathan Austin 1:af427e419320 641 * panic_timeout can be configured via a call to microbit_panic_timeout.
Jonathan Austin 1:af427e419320 642 *
Jonathan Austin 1:af427e419320 643 * @param statusCode the status code of the associated error.
Jonathan Austin 1:af427e419320 644 *
Jonathan Austin 1:af427e419320 645 * @code
Jonathan Austin 1:af427e419320 646 * microbit_panic_timeout(4);
Jonathan Austin 1:af427e419320 647 *
Jonathan Austin 1:af427e419320 648 * // will display loop for 4 iterations.
Jonathan Austin 1:af427e419320 649 * uBit.panic(10);
Jonathan Austin 1:af427e419320 650 * @endcode
Jonathan Austin 1:af427e419320 651 */
Jonathan Austin 1:af427e419320 652 inline void MicroBit::panic(int statusCode)
Jonathan Austin 1:af427e419320 653 {
Jonathan Austin 1:af427e419320 654 //show error and enter infinite while
Jonathan Austin 1:af427e419320 655 microbit_panic(statusCode);
Jonathan Austin 1:af427e419320 656 }
Jonathan Austin 1:af427e419320 657
LancasterUniversity 12:a62ca1ee7b52 658 #endif