Philip Holifield / microbit-dal

from bbc microbit library

Dependencies:   BLE_API mbed-dev-bin nRF51822

Dependents:   microbit

Fork of microbit-dal by Lancaster University

inc/core/MicroBitDevice.h@75:c700add33ba5, 2018-01-11 (annotated)

Committer:
euxton
Date:
Thu Jan 11 21:54:30 2018 +0000
Revision:
75:c700add33ba5
Parent:
47:69f452b1a5c9 
1st commit

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 /**
Jonathan Austin 1:8aa5cdb4ab67 27 * Device specific funcitons for the nrf51822 device.
Jonathan Austin 1:8aa5cdb4ab67 28 *
Jonathan Austin 1:8aa5cdb4ab67 29 * Provides a degree of platform independence for microbit-dal functionality.
Jonathan Austin 1:8aa5cdb4ab67 30 *
Jonathan Austin 1:8aa5cdb4ab67 31 * TODO: Determine if any of this belongs in an mbed target definition.
Jonathan Austin 1:8aa5cdb4ab67 32 * TODO: Review microbit-dal to place all such functions here.
Jonathan Austin 1:8aa5cdb4ab67 33 */
Jonathan Austin 1:8aa5cdb4ab67 34 #ifndef MICROBIT_DEVICE_H
Jonathan Austin 1:8aa5cdb4ab67 35 #define MICROBIT_DEVICE_H
Jonathan Austin 1:8aa5cdb4ab67 36
Jonathan Austin 1:8aa5cdb4ab67 37 #define MICROBIT_NAME_LENGTH 5
Jonathan Austin 1:8aa5cdb4ab67 38 #define MICROBIT_NAME_CODE_LETTERS 5
Jonathan Austin 1:8aa5cdb4ab67 39 #define MICROBIT_PANIC_ERROR_CHARS 4
Jonathan Austin 1:8aa5cdb4ab67 40
Jonathan Austin 1:8aa5cdb4ab67 41 #include "MicroBitConfig.h"
Jonathan Austin 1:8aa5cdb4ab67 42 #include "MicroBitMatrixMaps.h"
Jonathan Austin 1:8aa5cdb4ab67 43
Jonathan Austin 1:8aa5cdb4ab67 44 /**
Jonathan Austin 1:8aa5cdb4ab67 45 * Determines if a BLE stack is currently running.
Jonathan Austin 1:8aa5cdb4ab67 46 *
Jonathan Austin 1:8aa5cdb4ab67 47 * @return true is a bluetooth stack is operational, false otherwise.
Jonathan Austin 1:8aa5cdb4ab67 48 */
Jonathan Austin 1:8aa5cdb4ab67 49 bool ble_running();
Jonathan Austin 1:8aa5cdb4ab67 50
Jonathan Austin 1:8aa5cdb4ab67 51 /**
Jonathan Austin 1:8aa5cdb4ab67 52 * Derive a unique, consistent serial number of this device from internal data.
Jonathan Austin 1:8aa5cdb4ab67 53 *
Jonathan Austin 1:8aa5cdb4ab67 54 * @return the serial number of this device.
Jonathan Austin 1:8aa5cdb4ab67 55 */
Jonathan Austin 1:8aa5cdb4ab67 56 uint32_t microbit_serial_number();
Jonathan Austin 1:8aa5cdb4ab67 57
Jonathan Austin 1:8aa5cdb4ab67 58 /**
Jonathan Austin 1:8aa5cdb4ab67 59 * Derive the friendly name for this device, based on its serial number.
Jonathan Austin 1:8aa5cdb4ab67 60 *
Jonathan Austin 1:8aa5cdb4ab67 61 * @return the serial number of this device.
Jonathan Austin 1:8aa5cdb4ab67 62 */
Jonathan Austin 1:8aa5cdb4ab67 63 char* microbit_friendly_name();
Jonathan Austin 1:8aa5cdb4ab67 64
Jonathan Austin 1:8aa5cdb4ab67 65 /**
Jonathan Austin 1:8aa5cdb4ab67 66 * Perform a hard reset of the micro:bit.
Jonathan Austin 1:8aa5cdb4ab67 67 */
Jonathan Austin 1:8aa5cdb4ab67 68 void microbit_reset();
Jonathan Austin 1:8aa5cdb4ab67 69
Jonathan Austin 1:8aa5cdb4ab67 70 /**
Jonathan Austin 1:8aa5cdb4ab67 71 * Determine the version of microbit-dal currently running.
Jonathan Austin 1:8aa5cdb4ab67 72 * @return a pointer to a character buffer containing a representation of the semantic version number.
Jonathan Austin 1:8aa5cdb4ab67 73 */
Jonathan Austin 1:8aa5cdb4ab67 74 const char * microbit_dal_version();
Jonathan Austin 1:8aa5cdb4ab67 75
Jonathan Austin 1:8aa5cdb4ab67 76 /**
Jonathan Austin 1:8aa5cdb4ab67 77 * Disables all interrupts and user processing.
Jonathan Austin 1:8aa5cdb4ab67 78 * Displays "=(" and an accompanying status code on the default display.
LancasterUniversity 47:69f452b1a5c9 79 * @param statusCode the appropriate status code, must be in the range 0-999.
Jonathan Austin 1:8aa5cdb4ab67 80 *
Jonathan Austin 1:8aa5cdb4ab67 81 * @code
Jonathan Austin 1:8aa5cdb4ab67 82 * microbit_panic(20);
Jonathan Austin 1:8aa5cdb4ab67 83 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 84 */
Jonathan Austin 1:8aa5cdb4ab67 85 void microbit_panic(int statusCode);
Jonathan Austin 1:8aa5cdb4ab67 86
Jonathan Austin 1:8aa5cdb4ab67 87 /**
Jonathan Austin 1:8aa5cdb4ab67 88 * Defines the length of time that the device will remain in a error state before resetting.
Jonathan Austin 1:8aa5cdb4ab67 89 *
Jonathan Austin 1:8aa5cdb4ab67 90 * @param iteration The number of times the error code will be displayed before resetting. Set to zero to remain in error state forever.
Jonathan Austin 1:8aa5cdb4ab67 91 *
Jonathan Austin 1:8aa5cdb4ab67 92 * @code
Jonathan Austin 1:8aa5cdb4ab67 93 * microbit_panic_timeout(4);
Jonathan Austin 1:8aa5cdb4ab67 94 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 95 */
Jonathan Austin 1:8aa5cdb4ab67 96 void microbit_panic_timeout(int iterations);
Jonathan Austin 1:8aa5cdb4ab67 97
Jonathan Austin 1:8aa5cdb4ab67 98 /**
Jonathan Austin 1:8aa5cdb4ab67 99 * Generate a random number in the given range.
Jonathan Austin 1:8aa5cdb4ab67 100 * We use a simple Galois LFSR random number generator here,
Jonathan Austin 1:8aa5cdb4ab67 101 * as a Galois LFSR is sufficient for our applications, and much more lightweight
Jonathan Austin 1:8aa5cdb4ab67 102 * than the hardware random number generator built int the processor, which takes
Jonathan Austin 1:8aa5cdb4ab67 103 * a long time and uses a lot of energy.
Jonathan Austin 1:8aa5cdb4ab67 104 *
Jonathan Austin 1:8aa5cdb4ab67 105 * KIDS: You shouldn't use this is the real world to generte cryptographic keys though...
Jonathan Austin 1:8aa5cdb4ab67 106 * have a think why not. :-)
Jonathan Austin 1:8aa5cdb4ab67 107 *
Jonathan Austin 1:8aa5cdb4ab67 108 * @param max the upper range to generate a number for. This number cannot be negative.
Jonathan Austin 1:8aa5cdb4ab67 109 *
Jonathan Austin 1:8aa5cdb4ab67 110 * @return A random, natural number between 0 and the max-1. Or MICROBIT_INVALID_VALUE if max is <= 0.
Jonathan Austin 1:8aa5cdb4ab67 111 *
Jonathan Austin 1:8aa5cdb4ab67 112 * @code
Jonathan Austin 1:8aa5cdb4ab67 113 * microbit_random(200); //a number between 0 and 199
Jonathan Austin 1:8aa5cdb4ab67 114 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 115 */
Jonathan Austin 1:8aa5cdb4ab67 116 int microbit_random(int max);
Jonathan Austin 1:8aa5cdb4ab67 117
Jonathan Austin 1:8aa5cdb4ab67 118 /**
Jonathan Austin 1:8aa5cdb4ab67 119 * Seed the random number generator (RNG).
Jonathan Austin 1:8aa5cdb4ab67 120 *
Jonathan Austin 1:8aa5cdb4ab67 121 * This function uses the NRF51822's in built cryptographic random number generator to seed a Galois LFSR.
Jonathan Austin 1:8aa5cdb4ab67 122 * We do this as the hardware RNG is relatively high power, and is locked out by the BLE stack internally,
Jonathan Austin 1:8aa5cdb4ab67 123 * with a less than optimal application interface. A Galois LFSR is sufficient for our
Jonathan Austin 1:8aa5cdb4ab67 124 * applications, and much more lightweight.
Jonathan Austin 1:8aa5cdb4ab67 125 */
Jonathan Austin 1:8aa5cdb4ab67 126 void microbit_seed_random();
Jonathan Austin 1:8aa5cdb4ab67 127
Jonathan Austin 1:8aa5cdb4ab67 128 /**
Jonathan Austin 1:8aa5cdb4ab67 129 * Seed the pseudo random number generator (RNG) using the given 32-bit value.
Jonathan Austin 1:8aa5cdb4ab67 130 * This function does not use the NRF51822's in built cryptographic random number generator.
Jonathan Austin 1:8aa5cdb4ab67 131 *
Jonathan Austin 1:8aa5cdb4ab67 132 * @param seed The value to use as a seed.
Jonathan Austin 1:8aa5cdb4ab67 133 */
Jonathan Austin 1:8aa5cdb4ab67 134 void microbit_seed_random(uint32_t seed);
Jonathan Austin 1:8aa5cdb4ab67 135
LancasterUniversity 47:69f452b1a5c9 136 #endif