Wendy Warne / microbit-dal

updates

Dependencies:   BLE_API mbed-dev-bin nRF51822

Fork of microbit-dal-eddystone by Martin Woolley

inc/bluetooth/MicroBitBLEManager.h@36:6837feb07da4, 2016-07-13 (annotated)

Committer:
LancasterUniversity
Date:
Wed Jul 13 12:18:15 2016 +0100
Revision:
36:6837feb07da4
Parent:
3:d86a4ddc1867
Child:
74:a8f5674a0079
Synchronized with git rev 4e71d613

Author: James Devine

microbit-dal: Added setPull to MicroBitPin



This new member function allows the configuration of the pull currently

applied to the MicroBitPin instance. This member function only has

affect when the MicroBitPin instance is in a digital input mode.

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_BLE_MANAGER_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MICROBIT_BLE_MANAGER_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
Jonathan Austin 1:8aa5cdb4ab67 32 /*
Jonathan Austin 1:8aa5cdb4ab67 33 * The underlying Nordic libraries that support BLE do not compile cleanly with the stringent GCC settings we employ
Jonathan Austin 1:8aa5cdb4ab67 34 * If we're compiling under GCC, then we suppress any warnings generated from this code (but not the rest of the DAL)
Jonathan Austin 1:8aa5cdb4ab67 35 * The ARM cc compiler is more tolerant. We don't test __GNUC__ here to detect GCC as ARMCC also typically sets this
Jonathan Austin 1:8aa5cdb4ab67 36 * as a compatability option, but does not support the options used...
Jonathan Austin 1:8aa5cdb4ab67 37 */
Jonathan Austin 1:8aa5cdb4ab67 38 #if !defined (__arm)
Jonathan Austin 1:8aa5cdb4ab67 39 #pragma GCC diagnostic push
Jonathan Austin 1:8aa5cdb4ab67 40 #pragma GCC diagnostic ignored "-Wunused-parameter"
Jonathan Austin 1:8aa5cdb4ab67 41 #endif
Jonathan Austin 1:8aa5cdb4ab67 42 #include "ble/BLE.h"
Jonathan Austin 1:8aa5cdb4ab67 43
Jonathan Austin 1:8aa5cdb4ab67 44 /*
Jonathan Austin 1:8aa5cdb4ab67 45 * Return to our predefined compiler settings.
Jonathan Austin 1:8aa5cdb4ab67 46 */
Jonathan Austin 1:8aa5cdb4ab67 47 #if !defined (__arm)
Jonathan Austin 1:8aa5cdb4ab67 48 #pragma GCC diagnostic pop
Jonathan Austin 1:8aa5cdb4ab67 49 #endif
Jonathan Austin 1:8aa5cdb4ab67 50
Jonathan Austin 1:8aa5cdb4ab67 51 #include "ble/services/DeviceInformationService.h"
Jonathan Austin 1:8aa5cdb4ab67 52 #include "MicroBitDFUService.h"
Jonathan Austin 1:8aa5cdb4ab67 53 #include "MicroBitEventService.h"
Jonathan Austin 1:8aa5cdb4ab67 54 #include "MicroBitLEDService.h"
Jonathan Austin 1:8aa5cdb4ab67 55 #include "MicroBitAccelerometerService.h"
Jonathan Austin 1:8aa5cdb4ab67 56 #include "MicroBitMagnetometerService.h"
Jonathan Austin 1:8aa5cdb4ab67 57 #include "MicroBitButtonService.h"
Jonathan Austin 1:8aa5cdb4ab67 58 #include "MicroBitIOPinService.h"
Jonathan Austin 1:8aa5cdb4ab67 59 #include "MicroBitTemperatureService.h"
Jonathan Austin 1:8aa5cdb4ab67 60 #include "ExternalEvents.h"
Jonathan Austin 1:8aa5cdb4ab67 61 #include "MicroBitButton.h"
Jonathan Austin 1:8aa5cdb4ab67 62 #include "MicroBitStorage.h"
Jonathan Austin 1:8aa5cdb4ab67 63
Jonathan Austin 1:8aa5cdb4ab67 64 #define MICROBIT_BLE_PAIR_REQUEST 0x01
Jonathan Austin 1:8aa5cdb4ab67 65 #define MICROBIT_BLE_PAIR_COMPLETE 0x02
Jonathan Austin 1:8aa5cdb4ab67 66 #define MICROBIT_BLE_PAIR_PASSCODE 0x04
Jonathan Austin 1:8aa5cdb4ab67 67 #define MICROBIT_BLE_PAIR_SUCCESSFUL 0x08
Jonathan Austin 1:8aa5cdb4ab67 68
Jonathan Austin 1:8aa5cdb4ab67 69 #define MICROBIT_BLE_PAIRING_TIMEOUT 90
Jonathan Austin 1:8aa5cdb4ab67 70 #define MICROBIT_BLE_POWER_LEVELS 8
Jonathan Austin 1:8aa5cdb4ab67 71 #define MICROBIT_BLE_MAXIMUM_BONDS 4
Jonathan Austin 1:8aa5cdb4ab67 72 #define MICROBIT_BLE_ENABLE_BONDING true
Jonathan Austin 1:8aa5cdb4ab67 73
Jonathan Austin 1:8aa5cdb4ab67 74 extern const int8_t MICROBIT_BLE_POWER_LEVEL[];
Jonathan Austin 1:8aa5cdb4ab67 75
Jonathan Austin 1:8aa5cdb4ab67 76 struct BLESysAttribute
Jonathan Austin 1:8aa5cdb4ab67 77 {
LancasterUniversity 3:d86a4ddc1867 78 uint8_t sys_attr[8];
Jonathan Austin 1:8aa5cdb4ab67 79 };
Jonathan Austin 1:8aa5cdb4ab67 80
Jonathan Austin 1:8aa5cdb4ab67 81 struct BLESysAttributeStore
Jonathan Austin 1:8aa5cdb4ab67 82 {
Jonathan Austin 1:8aa5cdb4ab67 83 BLESysAttribute sys_attrs[MICROBIT_BLE_MAXIMUM_BONDS];
Jonathan Austin 1:8aa5cdb4ab67 84 };
Jonathan Austin 1:8aa5cdb4ab67 85
Jonathan Austin 1:8aa5cdb4ab67 86 /**
Jonathan Austin 1:8aa5cdb4ab67 87 * Class definition for the MicroBitBLEManager.
Jonathan Austin 1:8aa5cdb4ab67 88 *
Jonathan Austin 1:8aa5cdb4ab67 89 */
Jonathan Austin 1:8aa5cdb4ab67 90 class MicroBitBLEManager : MicroBitComponent
Jonathan Austin 1:8aa5cdb4ab67 91 {
Jonathan Austin 1:8aa5cdb4ab67 92 public:
Jonathan Austin 1:8aa5cdb4ab67 93
Jonathan Austin 1:8aa5cdb4ab67 94 // The mbed abstraction of the BlueTooth Low Energy (BLE) hardware
Jonathan Austin 1:8aa5cdb4ab67 95 BLEDevice *ble;
Jonathan Austin 1:8aa5cdb4ab67 96
Jonathan Austin 1:8aa5cdb4ab67 97 //an instance of MicroBitStorage used to store sysAttrs from softdevice
Jonathan Austin 1:8aa5cdb4ab67 98 MicroBitStorage* storage;
Jonathan Austin 1:8aa5cdb4ab67 99
Jonathan Austin 1:8aa5cdb4ab67 100 /**
Jonathan Austin 1:8aa5cdb4ab67 101 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 102 *
Jonathan Austin 1:8aa5cdb4ab67 103 * Configure and manage the micro:bit's Bluetooth Low Energy (BLE) stack.
Jonathan Austin 1:8aa5cdb4ab67 104 *
Jonathan Austin 1:8aa5cdb4ab67 105 * @param _storage an instance of MicroBitStorage used to persist sys attribute information. (This is required for compatability with iOS).
Jonathan Austin 1:8aa5cdb4ab67 106 *
Jonathan Austin 1:8aa5cdb4ab67 107 * @note The BLE stack *cannot* be brought up in a static context (the software simply hangs or corrupts itself).
Jonathan Austin 1:8aa5cdb4ab67 108 * Hence, the init() member function should be used to initialise the BLE stack.
Jonathan Austin 1:8aa5cdb4ab67 109 */
Jonathan Austin 1:8aa5cdb4ab67 110 MicroBitBLEManager(MicroBitStorage& _storage);
Jonathan Austin 1:8aa5cdb4ab67 111
Jonathan Austin 1:8aa5cdb4ab67 112 /**
Jonathan Austin 1:8aa5cdb4ab67 113 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 114 *
Jonathan Austin 1:8aa5cdb4ab67 115 * Configure and manage the micro:bit's Bluetooth Low Energy (BLE) stack.
Jonathan Austin 1:8aa5cdb4ab67 116 *
Jonathan Austin 1:8aa5cdb4ab67 117 * @note The BLE stack *cannot* be brought up in a static context (the software simply hangs or corrupts itself).
Jonathan Austin 1:8aa5cdb4ab67 118 * Hence, the init() member function should be used to initialise the BLE stack.
Jonathan Austin 1:8aa5cdb4ab67 119 */
Jonathan Austin 1:8aa5cdb4ab67 120 MicroBitBLEManager();
Jonathan Austin 1:8aa5cdb4ab67 121
Jonathan Austin 1:8aa5cdb4ab67 122 /**
Jonathan Austin 1:8aa5cdb4ab67 123 * Post constructor initialisation method as the BLE stack cannot be brought
Jonathan Austin 1:8aa5cdb4ab67 124 * up in a static context.
Jonathan Austin 1:8aa5cdb4ab67 125 *
Jonathan Austin 1:8aa5cdb4ab67 126 * @param deviceName The name used when advertising
Jonathan Austin 1:8aa5cdb4ab67 127 * @param serialNumber The serial number exposed by the device information service
Jonathan Austin 1:8aa5cdb4ab67 128 * @param messageBus An instance of an EventModel, used during pairing.
Jonathan Austin 1:8aa5cdb4ab67 129 * @param enableBonding If true, the security manager enabled bonding.
Jonathan Austin 1:8aa5cdb4ab67 130 *
Jonathan Austin 1:8aa5cdb4ab67 131 * @code
Jonathan Austin 1:8aa5cdb4ab67 132 * bleManager.init(uBit.getName(), uBit.getSerial(), uBit.messageBus, true);
Jonathan Austin 1:8aa5cdb4ab67 133 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 134 */
Jonathan Austin 1:8aa5cdb4ab67 135 void init(ManagedString deviceName, ManagedString serialNumber, EventModel& messageBus, bool enableBonding);
Jonathan Austin 1:8aa5cdb4ab67 136
Jonathan Austin 1:8aa5cdb4ab67 137 /**
Jonathan Austin 1:8aa5cdb4ab67 138 * Change the output power level of the transmitter to the given value.
Jonathan Austin 1:8aa5cdb4ab67 139 *
Jonathan Austin 1:8aa5cdb4ab67 140 * @param power a value in the range 0..7, where 0 is the lowest power and 7 is the highest.
Jonathan Austin 1:8aa5cdb4ab67 141 *
Jonathan Austin 1:8aa5cdb4ab67 142 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range.
Jonathan Austin 1:8aa5cdb4ab67 143 *
Jonathan Austin 1:8aa5cdb4ab67 144 * @code
Jonathan Austin 1:8aa5cdb4ab67 145 * // maximum transmission power.
Jonathan Austin 1:8aa5cdb4ab67 146 * bleManager.setTransmitPower(7);
Jonathan Austin 1:8aa5cdb4ab67 147 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 148 */
Jonathan Austin 1:8aa5cdb4ab67 149 int setTransmitPower(int power);
Jonathan Austin 1:8aa5cdb4ab67 150
Jonathan Austin 1:8aa5cdb4ab67 151 /**
Jonathan Austin 1:8aa5cdb4ab67 152 * Enter pairing mode. This is mode is called to initiate pairing, and to enable FOTA programming
Jonathan Austin 1:8aa5cdb4ab67 153 * of the micro:bit in cases where BLE is disabled during normal operation.
Jonathan Austin 1:8aa5cdb4ab67 154 *
Jonathan Austin 1:8aa5cdb4ab67 155 * @param display An instance of MicroBitDisplay used when displaying pairing information.
Jonathan Austin 1:8aa5cdb4ab67 156 * @param authorizationButton The button to use to authorise a pairing request.
Jonathan Austin 1:8aa5cdb4ab67 157 *
Jonathan Austin 1:8aa5cdb4ab67 158 * @code
Jonathan Austin 1:8aa5cdb4ab67 159 * // initiate pairing mode
Jonathan Austin 1:8aa5cdb4ab67 160 * bleManager.pairingMode(uBit.display, uBit.buttonA);
Jonathan Austin 1:8aa5cdb4ab67 161 * @endcode
Jonathan Austin 1:8aa5cdb4ab67 162 */
Jonathan Austin 1:8aa5cdb4ab67 163 void pairingMode(MicroBitDisplay &display, MicroBitButton &authorisationButton);
Jonathan Austin 1:8aa5cdb4ab67 164
Jonathan Austin 1:8aa5cdb4ab67 165 /**
Jonathan Austin 1:8aa5cdb4ab67 166 * When called, the micro:bit will begin advertising for a predefined period,
Jonathan Austin 1:8aa5cdb4ab67 167 * MICROBIT_BLE_ADVERTISING_TIMEOUT seconds to bonded devices.
Jonathan Austin 1:8aa5cdb4ab67 168 */
Jonathan Austin 1:8aa5cdb4ab67 169 void advertise();
Jonathan Austin 1:8aa5cdb4ab67 170
Jonathan Austin 1:8aa5cdb4ab67 171 /**
Jonathan Austin 1:8aa5cdb4ab67 172 * Determines the number of devices currently bonded with this micro:bit.
Jonathan Austin 1:8aa5cdb4ab67 173 * @return The number of active bonds.
Jonathan Austin 1:8aa5cdb4ab67 174 */
Jonathan Austin 1:8aa5cdb4ab67 175 int getBondCount();
Jonathan Austin 1:8aa5cdb4ab67 176
Jonathan Austin 1:8aa5cdb4ab67 177 /**
Jonathan Austin 1:8aa5cdb4ab67 178 * A request to pair has been received from a BLE device.
Jonathan Austin 1:8aa5cdb4ab67 179 * If we're in pairing mode, display the passkey to the user.
Jonathan Austin 1:8aa5cdb4ab67 180 * Also, purge the bonding table if it has reached capacity.
Jonathan Austin 1:8aa5cdb4ab67 181 *
Jonathan Austin 1:8aa5cdb4ab67 182 * @note for internal use only.
Jonathan Austin 1:8aa5cdb4ab67 183 */
Jonathan Austin 1:8aa5cdb4ab67 184 void pairingRequested(ManagedString passKey);
Jonathan Austin 1:8aa5cdb4ab67 185
Jonathan Austin 1:8aa5cdb4ab67 186 /**
Jonathan Austin 1:8aa5cdb4ab67 187 * A pairing request has been sucessfully completed.
Jonathan Austin 1:8aa5cdb4ab67 188 * If we're in pairing mode, display a success or failure message.
Jonathan Austin 1:8aa5cdb4ab67 189 *
Jonathan Austin 1:8aa5cdb4ab67 190 * @note for internal use only.
Jonathan Austin 1:8aa5cdb4ab67 191 */
Jonathan Austin 1:8aa5cdb4ab67 192 void pairingComplete(bool success);
Jonathan Austin 1:8aa5cdb4ab67 193
Jonathan Austin 1:8aa5cdb4ab67 194 /**
Jonathan Austin 1:8aa5cdb4ab67 195 * Periodic callback in thread context.
Jonathan Austin 1:8aa5cdb4ab67 196 * We use this here purely to safely issue a disconnect operation after a pairing operation is complete.
Jonathan Austin 1:8aa5cdb4ab67 197 */
Jonathan Austin 1:8aa5cdb4ab67 198 void idleTick();
Jonathan Austin 1:8aa5cdb4ab67 199
Jonathan Austin 1:8aa5cdb4ab67 200 private:
Jonathan Austin 1:8aa5cdb4ab67 201
Jonathan Austin 1:8aa5cdb4ab67 202 /**
Jonathan Austin 1:8aa5cdb4ab67 203 * Displays the device's ID code as a histogram on the provided MicroBitDisplay instance.
Jonathan Austin 1:8aa5cdb4ab67 204 *
Jonathan Austin 1:8aa5cdb4ab67 205 * @param display The display instance used for displaying the histogram.
Jonathan Austin 1:8aa5cdb4ab67 206 */
Jonathan Austin 1:8aa5cdb4ab67 207 void showNameHistogram(MicroBitDisplay &display);
Jonathan Austin 1:8aa5cdb4ab67 208
Jonathan Austin 1:8aa5cdb4ab67 209 int pairingStatus;
Jonathan Austin 1:8aa5cdb4ab67 210 ManagedString passKey;
Jonathan Austin 1:8aa5cdb4ab67 211 ManagedString deviceName;
Jonathan Austin 1:8aa5cdb4ab67 212
Jonathan Austin 1:8aa5cdb4ab67 213 };
Jonathan Austin 1:8aa5cdb4ab67 214
LancasterUniversity 3:d86a4ddc1867 215 #endif