MicroBitBLEManager.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 #ifndef MICROBIT_BLE_MANAGER_H
00027 #define MICROBIT_BLE_MANAGER_H
00028 
00029 #include "mbed.h"
00030 #include "MicroBitConfig.h"
00031 
00032 /*
00033  * The underlying Nordic libraries that support BLE do not compile cleanly with the stringent GCC settings we employ
00034  * If we're compiling under GCC, then we suppress any warnings generated from this code (but not the rest of the DAL)
00035  * The ARM cc compiler is more tolerant. We don't test __GNUC__ here to detect GCC as ARMCC also typically sets this
00036  * as a compatability option, but does not support the options used...
00037  */
00038 #if !defined(__arm)
00039 #pragma GCC diagnostic push
00040 #pragma GCC diagnostic ignored "-Wunused-parameter"
00041 #endif
00042 #include "ble/BLE.h"
00043 
00044 /*
00045  * Return to our predefined compiler settings.
00046  */
00047 #if !defined(__arm)
00048 #pragma GCC diagnostic pop
00049 #endif
00050 
00051 #include "ble/services/DeviceInformationService.h"
00052 #include "MicroBitDFUService.h"
00053 #include "MicroBitEventService.h"
00054 #include "MicroBitLEDService.h"
00055 #include "MicroBitAccelerometerService.h"
00056 #include "MicroBitMagnetometerService.h"
00057 #include "MicroBitButtonService.h"
00058 #include "MicroBitIOPinService.h"
00059 #include "MicroBitTemperatureService.h"
00060 #include "ExternalEvents.h"
00061 #include "MicroBitButton.h"
00062 #include "MicroBitStorage.h"
00063 
00064 #define MICROBIT_BLE_PAIR_REQUEST 0x01
00065 #define MICROBIT_BLE_PAIR_COMPLETE 0x02
00066 #define MICROBIT_BLE_PAIR_PASSCODE 0x04
00067 #define MICROBIT_BLE_PAIR_SUCCESSFUL 0x08
00068 
00069 #define MICROBIT_BLE_PAIRING_TIMEOUT 90
00070 #define MICROBIT_BLE_POWER_LEVELS 8
00071 #define MICROBIT_BLE_MAXIMUM_BONDS 4
00072 #define MICROBIT_BLE_ENABLE_BONDING true
00073 
00074 #define MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL     400
00075 #define MICROBIT_BLE_EDDYSTONE_DEFAULT_POWER    0xF0
00076 
00077 extern const int8_t MICROBIT_BLE_POWER_LEVEL[];
00078 
00079 struct BLESysAttribute
00080 {
00081     uint8_t sys_attr[8];
00082 };
00083 
00084 struct BLESysAttributeStore
00085 {
00086     BLESysAttribute sys_attrs[MICROBIT_BLE_MAXIMUM_BONDS];
00087 };
00088 
00089 typedef enum
00090 {
00091     BEACON_TYPE_NONE,
00092     BEACON_TYPE_EDDYSTONE,
00093     BEACON_TYPE_IBEACON
00094 }BLE_BEACON_TYPE;
00095 
00096 /**
00097   * Class definition for the MicroBitBLEManager.
00098   *
00099   */
00100 class MicroBitBLEManager : MicroBitComponent
00101 {
00102   public:
00103     static MicroBitBLEManager *manager;
00104 
00105     // The mbed abstraction of the BlueTooth Low Energy (BLE) hardware
00106     BLEDevice *ble;
00107 
00108     //an instance of MicroBitStorage used to store sysAttrs from softdevice
00109     MicroBitStorage *storage;
00110 
00111     /**
00112      * Constructor.
00113      *
00114      * Configure and manage the micro:bit's Bluetooth Low Energy (BLE) stack.
00115      *
00116      * @param _storage an instance of MicroBitStorage used to persist sys attribute information. (This is required for compatability with iOS).
00117      *
00118      * @note The BLE stack *cannot*  be brought up in a static context (the software simply hangs or corrupts itself).
00119      * Hence, the init() member function should be used to initialise the BLE stack.
00120      */
00121     MicroBitBLEManager(MicroBitStorage &_storage);
00122 
00123     /**
00124      * Constructor.
00125      *
00126      * Configure and manage the micro:bit's Bluetooth Low Energy (BLE) stack.
00127      *
00128      * @note The BLE stack *cannot*  be brought up in a static context (the software simply hangs or corrupts itself).
00129      * Hence, the init() member function should be used to initialise the BLE stack.
00130      */
00131     MicroBitBLEManager();
00132 
00133     /**
00134      * getInstance
00135      *
00136      * Allows other objects to easily obtain a pointer to the single instance of this object. By rights the constructor should be made
00137      * private to properly implement the singleton pattern.
00138      *
00139      */
00140     static MicroBitBLEManager *getInstance();
00141 
00142     /**
00143       * Post constructor initialisation method as the BLE stack cannot be brought
00144       * up in a static context.
00145       *
00146       * @param deviceName The name used when advertising
00147       * @param serialNumber The serial number exposed by the device information service
00148       * @param messageBus An instance of an EventModel, used during pairing.
00149       * @param enableBonding If true, the security manager enabled bonding.
00150       *
00151       * @code
00152       * bleManager.init(uBit.getName(), uBit.getSerial(), uBit.messageBus, true);
00153       * @endcode
00154       */
00155     void init(ManagedString deviceName, ManagedString serialNumber, EventModel &messageBus, bool enableBonding);
00156 
00157     /**
00158      * Change the output power level of the transmitter to the given value.
00159      *
00160      * @param power a value in the range 0..7, where 0 is the lowest power and 7 is the highest.
00161      *
00162      * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the value is out of range.
00163      *
00164      * @code
00165      * // maximum transmission power.
00166      * bleManager.setTransmitPower(7);
00167      * @endcode
00168      */
00169     int setTransmitPower(int power);
00170 
00171     /**
00172      * Enter pairing mode. This is mode is called to initiate pairing, and to enable FOTA programming
00173      * of the micro:bit in cases where BLE is disabled during normal operation.
00174      *
00175      * @param display An instance of MicroBitDisplay used when displaying pairing information.
00176      * @param authorizationButton The button to use to authorise a pairing request.
00177      *
00178      * @code
00179      * // initiate pairing mode
00180      * bleManager.pairingMode(uBit.display, uBit.buttonA);
00181      * @endcode
00182      */
00183     void pairingMode(MicroBitDisplay &display, MicroBitButton &authorisationButton);
00184 
00185     /**
00186      * When called, the micro:bit will begin advertising for a predefined period,
00187      * MICROBIT_BLE_ADVERTISING_TIMEOUT seconds to bonded devices.
00188      */
00189     void advertise();
00190 
00191     /**
00192      * Determines the number of devices currently bonded with this micro:bit.
00193      * @return The number of active bonds.
00194      */
00195     int getBondCount();
00196 
00197     /**
00198      * A request to pair has been received from a BLE device.
00199      * If we're in pairing mode, display the passkey to the user.
00200      * Also, purge the bonding table if it has reached capacity.
00201      *
00202      * @note for internal use only.
00203      */
00204     void pairingRequested(ManagedString passKey);
00205 
00206     /**
00207      * A pairing request has been sucessfully completed.
00208      * If we're in pairing mode, display a success or failure message.
00209      *
00210      * @note for internal use only.
00211      */
00212     void pairingComplete(bool success);
00213 
00214     /**
00215      * Periodic callback in thread context.
00216      * We use this here purely to safely issue a disconnect operation after a pairing operation is complete.
00217      */
00218     void idleTick();
00219 
00220     /**
00221     * Stops any currently running BLE advertisements
00222     */
00223     void stopAdvertising();
00224 #if CONFIG_ENABLED(MICROBIT_BLE_EDDYSTONE_URL)
00225 
00226     /**
00227       * Set the content of Eddystone URL frames
00228       *
00229       * @param url The url to broadcast
00230       *
00231       * @param calibratedPower the transmission range of the beacon (Defaults to: 0xF0 ~10m).
00232       *
00233       * @param connectable true to keep bluetooth connectable for other services, false otherwise. (Defaults to true)
00234       *
00235       * @param interval the rate at which the micro:bit will advertise url frames. (Defaults to MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL)
00236       *
00237       * @note The calibratedPower value ranges from -100 to +20 to a resolution of 1. The calibrated power should be binary encoded.
00238       * More information can be found at https://github.com/google/eddystone/tree/master/eddystone-uid#tx-power
00239       */
00240     int advertiseEddystoneUrl(const char *url, int8_t calibratedPower = MICROBIT_BLE_EDDYSTONE_DEFAULT_POWER, bool connectable = true, uint16_t interval = MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL);
00241 
00242     /**
00243       * Set the content of Eddystone URL frames, but accepts a ManagedString as a url.
00244       *
00245       * @param url The url to broadcast
00246       *
00247       * @param calibratedPower the transmission range of the beacon (Defaults to: 0xF0 ~10m).
00248       *
00249       * @param connectable true to keep bluetooth connectable for other services, false otherwise. (Defaults to true)
00250       *
00251       * @param interval the rate at which the micro:bit will advertise url frames. (Defaults to MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL)
00252       *
00253       * @note The calibratedPower value ranges from -100 to +20 to a resolution of 1. The calibrated power should be binary encoded.
00254       * More information can be found at https://github.com/google/eddystone/tree/master/eddystone-uid#tx-power
00255       */
00256     int advertiseEddystoneUrl(ManagedString url, int8_t calibratedPower = MICROBIT_BLE_EDDYSTONE_DEFAULT_POWER, bool connectable = true, uint16_t interval = MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL);
00257 #endif
00258 
00259 #if CONFIG_ENABLED(MICROBIT_BLE_EDDYSTONE_UID)
00260     /**
00261       * Set the content of Eddystone UID frames
00262       *
00263       * @param uid_namespace: the uid namespace. Must 10 bytes long.
00264       *
00265       * @param uid_instance:  the uid instance value. Must 6 bytes long.
00266       *
00267       * @param calibratedPower the transmission range of the beacon (Defaults to: 0xF0 ~10m).
00268       *
00269       * @param connectable true to keep bluetooth connectable for other services, false otherwise. (Defaults to true)
00270       *
00271       * @param interval the rate at which the micro:bit will advertise url frames. (Defaults to MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL)
00272       *
00273       * @note The calibratedPower value ranges from -100 to +20 to a resolution of 1. The calibrated power should be binary encoded.
00274       * More information can be found at https://github.com/google/eddystone/tree/master/eddystone-uid#tx-power
00275       */
00276     int advertiseEddystoneUid(const char* uid_namespace, const char* uid_instance, int8_t calibratedPower = MICROBIT_BLE_EDDYSTONE_DEFAULT_POWER, bool connectable = true, uint16_t interval = MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL);
00277 #endif
00278 
00279     /**
00280       * Set the content of Eddystone URL frames
00281       *
00282       * @param proximityUUID 16-byte proximity UUID
00283       *
00284       * @param major 2-byte major value
00285       *
00286       * @param minor 2-byte minor value
00287       *
00288       * @param calibratedPower the transmission range of the beacon (Defaults to: 0xF0 ~10m).
00289       *
00290       * @param interval the rate at which the micro:bit will advertise url frames. (Defaults to MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL)
00291       *
00292       * @note The calibratedPower value ranges from -100 to +20 to a resolution of 1. The calibrated power should be binary encoded.
00293       * More information can be found at https://github.com/google/eddystone/tree/master/eddystone-uid#tx-power
00294       */
00295     int advertiseIBeacon(const UUID &proximityUUID, int16_t major, int16_t minor, int8_t calibratedPower, uint16_t interval = MICROBIT_BLE_EDDYSTONE_ADV_INTERVAL);
00296 
00297   private:
00298     /**
00299     * Displays the device's ID code as a histogram on the provided MicroBitDisplay instance.
00300     *
00301     * @param display The display instance used for displaying the histogram.
00302     */
00303     void showNameHistogram(MicroBitDisplay &display);
00304 
00305     #define MICROBIT_BLE_DISCONNECT_AFTER_PAIRING_DELAY  500
00306     unsigned long pairing_completed_at_time;   
00307 
00308     int pairingStatus;
00309     ManagedString passKey;
00310     ManagedString deviceName;
00311 };
00312 
00313 #endif