Rene Miedema / ble_test

abc

Fork of BLE_API by Bluetooth Low Energy

public/Gap.h@341:8a104d9d80c1, 2015-04-15 (annotated)

Committer:
rgrover1
Date:
Wed Apr 15 09:05:11 2015 +0100
Revision:
341:8a104d9d80c1
Parent:
337:e7c2eb38f5cc
Child:
342:152bd9c825d6
Synchronized with git rev 8b631fc0

Author: Rohit Grover

Release 0.3.2

=============



Enhancements

~~~~~~~~~~~~



* Add new API: onRadioNotification(). Radio Notification is a feature that

  enables ACTIVE and INACTIVE (nACTIVE) signals from the stack that notify the

  application when the radio is in use. The ACTIVE signal is sent before the

  Radio Event starts. The nACTIVE signal is sent at the end of the Radio

  Event. These signals can be used by the application programmer to

  synchronize application logic with radio activity. For example, the ACTIVE

  signal can be used to shut off external devices to manage peak current drawn

  during periods when the radio is on, or to trigger sensor data collection

  for transmission in the Radio Event.



* merge contents of several .cpp files under common/* into .h files under public/*.

  e.g. GattService, GapAdvertisingData, UUID.



* Add a note to the documentation for setAdvertisingInterval() to warn users

  about the new units for 'interval'.



* get rid of a few deprecated APIs: setAdvertisingData() and startAdvertising().



Bugfixes

~~~~~~~~



none.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 260:ea7f9f14cc15 1 /* mbed Microcontroller Library
rgrover1 260:ea7f9f14cc15 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 260:ea7f9f14cc15 3 *
rgrover1 260:ea7f9f14cc15 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 260:ea7f9f14cc15 5 * you may not use this file except in compliance with the License.
rgrover1 260:ea7f9f14cc15 6 * You may obtain a copy of the License at
rgrover1 260:ea7f9f14cc15 7 *
rgrover1 260:ea7f9f14cc15 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 260:ea7f9f14cc15 9 *
rgrover1 260:ea7f9f14cc15 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 260:ea7f9f14cc15 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 260:ea7f9f14cc15 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 260:ea7f9f14cc15 13 * See the License for the specific language governing permissions and
rgrover1 260:ea7f9f14cc15 14 * limitations under the License.
rgrover1 260:ea7f9f14cc15 15 */
rgrover1 260:ea7f9f14cc15 16
rgrover1 260:ea7f9f14cc15 17 #ifndef __GAP_H__
rgrover1 260:ea7f9f14cc15 18 #define __GAP_H__
rgrover1 260:ea7f9f14cc15 19
rgrover1 260:ea7f9f14cc15 20 #include "GapAdvertisingData.h"
rgrover1 260:ea7f9f14cc15 21 #include "GapAdvertisingParams.h"
rgrover1 260:ea7f9f14cc15 22 #include "GapEvents.h"
rgrover1 260:ea7f9f14cc15 23 #include "CallChain.h"
rgrover1 260:ea7f9f14cc15 24
rgrover1 260:ea7f9f14cc15 25 using namespace mbed;
rgrover1 260:ea7f9f14cc15 26
rgrover1 260:ea7f9f14cc15 27 class Gap {
rgrover1 260:ea7f9f14cc15 28 public:
rgrover1 260:ea7f9f14cc15 29 typedef enum addr_type_e {
rgrover1 260:ea7f9f14cc15 30 ADDR_TYPE_PUBLIC = 0,
rgrover1 260:ea7f9f14cc15 31 ADDR_TYPE_RANDOM_STATIC,
rgrover1 260:ea7f9f14cc15 32 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
rgrover1 260:ea7f9f14cc15 33 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
rgrover1 260:ea7f9f14cc15 34 } addr_type_t;
rgrover1 260:ea7f9f14cc15 35
rgrover1 260:ea7f9f14cc15 36 static const unsigned ADDR_LEN = 6;
rgrover1 260:ea7f9f14cc15 37 typedef uint8_t address_t[ADDR_LEN];
rgrover1 260:ea7f9f14cc15 38
rgrover1 260:ea7f9f14cc15 39 /**
rgrover1 260:ea7f9f14cc15 40 * Enumeration for disconnection reasons. The values for these reasons are
rgrover1 260:ea7f9f14cc15 41 * derived from Nordic's implementation; but the reasons are meant to be
rgrover1 260:ea7f9f14cc15 42 * independent of the transport. If you are returned a reason which is not
rgrover1 260:ea7f9f14cc15 43 * covered by this enumeration, then please refer to the underlying
rgrover1 260:ea7f9f14cc15 44 * transport library.
rgrover1 260:ea7f9f14cc15 45 */
rgrover1 260:ea7f9f14cc15 46 enum DisconnectionReason_t {
rgrover1 260:ea7f9f14cc15 47 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
rgrover1 260:ea7f9f14cc15 48 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
rgrover1 260:ea7f9f14cc15 49 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
rgrover1 260:ea7f9f14cc15 50 };
rgrover1 260:ea7f9f14cc15 51
rgrover1 260:ea7f9f14cc15 52 /* Describes the current state of the device (more than one bit can be set) */
rgrover1 260:ea7f9f14cc15 53 typedef struct GapState_s {
rgrover1 260:ea7f9f14cc15 54 unsigned advertising : 1; /**< peripheral is currently advertising */
rgrover1 260:ea7f9f14cc15 55 unsigned connected : 1; /**< peripheral is connected to a central */
rgrover1 260:ea7f9f14cc15 56 } GapState_t;
rgrover1 260:ea7f9f14cc15 57
rgrover1 260:ea7f9f14cc15 58 typedef uint16_t Handle_t;
rgrover1 260:ea7f9f14cc15 59
rgrover1 260:ea7f9f14cc15 60 typedef struct {
rgrover1 260:ea7f9f14cc15 61 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 62 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 63 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 64 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 65 } ConnectionParams_t;
rgrover1 260:ea7f9f14cc15 66
rgrover1 260:ea7f9f14cc15 67 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
rgrover1 260:ea7f9f14cc15 68 static const uint16_t UNIT_0_625_MS = 650; /**< Number of microseconds in 0.625 milliseconds. */
rgrover1 260:ea7f9f14cc15 69 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 70 return (durationInMillis * 1000) / UNIT_1_25_MS;
rgrover1 260:ea7f9f14cc15 71 }
rgrover1 260:ea7f9f14cc15 72 static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 73 return (durationInMillis * 1000) / UNIT_0_625_MS;
rgrover1 260:ea7f9f14cc15 74 }
rgrover1 325:501ad8b8bbe5 75 static uint16_t GAP_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
rgrover1 325:501ad8b8bbe5 76 return (gapUnits * UNIT_0_625_MS) / 1000;
rgrover1 325:501ad8b8bbe5 77 }
rgrover1 260:ea7f9f14cc15 78
rgrover1 260:ea7f9f14cc15 79 typedef void (*EventCallback_t)(void);
rgrover1 260:ea7f9f14cc15 80 typedef void (*ConnectionEventCallback_t)(Handle_t, addr_type_t peerAddrType, const address_t peerAddr, const ConnectionParams_t *);
rgrover1 260:ea7f9f14cc15 81 typedef void (*DisconnectionEventCallback_t)(Handle_t, DisconnectionReason_t);
rgrover1 341:8a104d9d80c1 82 typedef void (*RadioNotificationEventCallback_t) (bool radio_active); /* gets passed true for ACTIVE; false for INACTIVE. */
rgrover1 260:ea7f9f14cc15 83
rgrover1 260:ea7f9f14cc15 84 friend class BLEDevice;
rgrover1 260:ea7f9f14cc15 85 private:
rgrover1 260:ea7f9f14cc15 86 /* These functions must be defined in the sub-class */
rgrover1 260:ea7f9f14cc15 87 virtual ble_error_t setAddress(addr_type_t type, const address_t address) = 0;
rgrover1 260:ea7f9f14cc15 88 virtual ble_error_t getAddress(addr_type_t *typeP, address_t address) = 0;
rgrover1 260:ea7f9f14cc15 89 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &, const GapAdvertisingData &) = 0;
rgrover1 260:ea7f9f14cc15 90 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
rgrover1 260:ea7f9f14cc15 91 virtual ble_error_t stopAdvertising(void) = 0;
rgrover1 325:501ad8b8bbe5 92 virtual uint16_t getMinAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 93 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 94 virtual uint16_t getMaxAdvertisingInterval(void) const = 0;
rgrover1 260:ea7f9f14cc15 95 virtual ble_error_t disconnect(DisconnectionReason_t reason) = 0;
rgrover1 260:ea7f9f14cc15 96 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 97 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 98 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 99
rgrover1 260:ea7f9f14cc15 100 virtual ble_error_t setDeviceName(const uint8_t *deviceName) = 0;
rgrover1 260:ea7f9f14cc15 101 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) = 0;
rgrover1 260:ea7f9f14cc15 102 virtual ble_error_t setAppearance(uint16_t appearance) = 0;
rgrover1 260:ea7f9f14cc15 103 virtual ble_error_t getAppearance(uint16_t *appearanceP) = 0;
rgrover1 260:ea7f9f14cc15 104
rgrover1 337:e7c2eb38f5cc 105 protected:
rgrover1 260:ea7f9f14cc15 106 /* Event callback handlers */
rgrover1 260:ea7f9f14cc15 107 void setOnTimeout(EventCallback_t callback) {onTimeout = callback;}
rgrover1 260:ea7f9f14cc15 108 void setOnConnection(ConnectionEventCallback_t callback) {onConnection = callback;}
rgrover1 260:ea7f9f14cc15 109
rgrover1 260:ea7f9f14cc15 110 /**
rgrover1 260:ea7f9f14cc15 111 * Set the application callback for disconnection events.
rgrover1 260:ea7f9f14cc15 112 * @param callback
rgrover1 260:ea7f9f14cc15 113 * Pointer to the unique callback.
rgrover1 260:ea7f9f14cc15 114 */
rgrover1 260:ea7f9f14cc15 115 void setOnDisconnection(DisconnectionEventCallback_t callback) {onDisconnection = callback;}
rgrover1 260:ea7f9f14cc15 116
rgrover1 260:ea7f9f14cc15 117 /**
rgrover1 341:8a104d9d80c1 118 * Set the application callback for radio-notification events.
rgrover1 341:8a104d9d80c1 119 * @param callback
rgrover1 341:8a104d9d80c1 120 * Handler to be executed in resonse to a radio notification event.
rgrover1 341:8a104d9d80c1 121 */
rgrover1 341:8a104d9d80c1 122 virtual void setOnRadioNotification(RadioNotificationEventCallback_t callback) {onRadioNotification = callback;}
rgrover1 341:8a104d9d80c1 123
rgrover1 341:8a104d9d80c1 124 /**
rgrover1 260:ea7f9f14cc15 125 * Append to a chain of callbacks to be invoked upon disconnection; these
rgrover1 260:ea7f9f14cc15 126 * callbacks receive no context and are therefore different from the
rgrover1 260:ea7f9f14cc15 127 * onDisconnection callback.
rgrover1 260:ea7f9f14cc15 128 * @param callback
rgrover1 260:ea7f9f14cc15 129 * function pointer to be invoked upon disconnection; receives no context.
rgrover1 260:ea7f9f14cc15 130 *
rgrover1 260:ea7f9f14cc15 131 * @note the disconnection CallChain should have been merged with
rgrover1 260:ea7f9f14cc15 132 * onDisconnctionCallback; but this was not possible because
rgrover1 260:ea7f9f14cc15 133 * FunctionPointer (which is a building block for CallChain) doesn't
rgrover1 260:ea7f9f14cc15 134 * accept variadic templates.
rgrover1 260:ea7f9f14cc15 135 */
rgrover1 260:ea7f9f14cc15 136 template<typename T>
rgrover1 260:ea7f9f14cc15 137 void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) {disconnectionCallChain.add(tptr, mptr);}
rgrover1 260:ea7f9f14cc15 138
rgrover1 337:e7c2eb38f5cc 139 private:
rgrover1 260:ea7f9f14cc15 140 GapState_t getState(void) const {
rgrover1 260:ea7f9f14cc15 141 return state;
rgrover1 260:ea7f9f14cc15 142 }
rgrover1 260:ea7f9f14cc15 143
rgrover1 260:ea7f9f14cc15 144 protected:
rgrover1 260:ea7f9f14cc15 145 /* Default constructor. */
rgrover1 341:8a104d9d80c1 146 Gap() : state(), onTimeout(NULL), onConnection(NULL), onDisconnection(NULL), onRadioNotification(), disconnectionCallChain() {
rgrover1 260:ea7f9f14cc15 147 /* empty */
rgrover1 260:ea7f9f14cc15 148 }
rgrover1 260:ea7f9f14cc15 149
rgrover1 260:ea7f9f14cc15 150 public:
rgrover1 260:ea7f9f14cc15 151 void processConnectionEvent(Handle_t handle, addr_type_t type, const address_t addr, const ConnectionParams_t *params) {
rgrover1 260:ea7f9f14cc15 152 state.connected = 1;
rgrover1 260:ea7f9f14cc15 153 if (onConnection) {
rgrover1 260:ea7f9f14cc15 154 onConnection(handle, type, addr, params);
rgrover1 260:ea7f9f14cc15 155 }
rgrover1 260:ea7f9f14cc15 156 }
rgrover1 260:ea7f9f14cc15 157
rgrover1 260:ea7f9f14cc15 158 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
rgrover1 260:ea7f9f14cc15 159 state.connected = 0;
rgrover1 260:ea7f9f14cc15 160 if (onDisconnection) {
rgrover1 260:ea7f9f14cc15 161 onDisconnection(handle, reason);
rgrover1 260:ea7f9f14cc15 162 }
rgrover1 260:ea7f9f14cc15 163 disconnectionCallChain.call();
rgrover1 260:ea7f9f14cc15 164 }
rgrover1 260:ea7f9f14cc15 165
rgrover1 260:ea7f9f14cc15 166 void processEvent(GapEvents::gapEvent_e type) {
rgrover1 260:ea7f9f14cc15 167 switch (type) {
rgrover1 260:ea7f9f14cc15 168 case GapEvents::GAP_EVENT_TIMEOUT:
rgrover1 260:ea7f9f14cc15 169 state.advertising = 0;
rgrover1 260:ea7f9f14cc15 170 if (onTimeout) {
rgrover1 260:ea7f9f14cc15 171 onTimeout();
rgrover1 260:ea7f9f14cc15 172 }
rgrover1 260:ea7f9f14cc15 173 break;
rgrover1 267:ad6f6f40eb24 174 default:
rgrover1 267:ad6f6f40eb24 175 break;
rgrover1 260:ea7f9f14cc15 176 }
rgrover1 260:ea7f9f14cc15 177 }
rgrover1 260:ea7f9f14cc15 178
rgrover1 260:ea7f9f14cc15 179 protected:
rgrover1 260:ea7f9f14cc15 180 GapState_t state;
rgrover1 260:ea7f9f14cc15 181
rgrover1 337:e7c2eb38f5cc 182 protected:
rgrover1 260:ea7f9f14cc15 183 EventCallback_t onTimeout;
rgrover1 260:ea7f9f14cc15 184 ConnectionEventCallback_t onConnection;
rgrover1 260:ea7f9f14cc15 185 DisconnectionEventCallback_t onDisconnection;
rgrover1 341:8a104d9d80c1 186 RadioNotificationEventCallback_t onRadioNotification;
rgrover1 260:ea7f9f14cc15 187 CallChain disconnectionCallChain;
rgrover1 260:ea7f9f14cc15 188
rgrover1 260:ea7f9f14cc15 189 private:
rgrover1 260:ea7f9f14cc15 190 /* disallow copy and assignment */
rgrover1 260:ea7f9f14cc15 191 Gap(const Gap &);
rgrover1 260:ea7f9f14cc15 192 Gap& operator=(const Gap &);
rgrover1 260:ea7f9f14cc15 193 };
rgrover1 260:ea7f9f14cc15 194
rgrover1 260:ea7f9f14cc15 195 #endif // ifndef __GAP_H__