Paulo Roman / BLE_API

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of BLE_API by Bluetooth Low Energy

public/Gap.h@352:79d7cb60ae27, 2015-05-08 (annotated)

Committer:
rgrover1
Date:
Fri May 08 15:35:46 2015 +0100
Revision:
352:79d7cb60ae27
Parent:
349:b8b2b3973c47
Child:
353:5ed63cda3038
Synchronized with git rev 7559176d

Author: Rohit Grover

support getLinkStatus()

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 346:4a42f777161f 37 typedef uint8_t address_t[ADDR_LEN]; /* 48-bit address, LSB format. */
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 352:79d7cb60ae27 67 /**
rgrover1 352:79d7cb60ae27 68 * @brief Defines possible security status/states.
rgrover1 352:79d7cb60ae27 69 *
rgrover1 352:79d7cb60ae27 70 * @details Defines possible security status/states of a link when requested by getLinkSecurity().
rgrover1 352:79d7cb60ae27 71 */
rgrover1 352:79d7cb60ae27 72 enum LinkSecurityStatus_t {
rgrover1 352:79d7cb60ae27 73 NOT_ENCRYPTED, /**< The link is not secured. */
rgrover1 352:79d7cb60ae27 74 ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/
rgrover1 352:79d7cb60ae27 75 ENCRYPTED /**< The link is secure.*/
rgrover1 352:79d7cb60ae27 76 };
rgrover1 352:79d7cb60ae27 77
rgrover1 260:ea7f9f14cc15 78 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
rgrover1 260:ea7f9f14cc15 79 static const uint16_t UNIT_0_625_MS = 650; /**< Number of microseconds in 0.625 milliseconds. */
rgrover1 260:ea7f9f14cc15 80 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 81 return (durationInMillis * 1000) / UNIT_1_25_MS;
rgrover1 260:ea7f9f14cc15 82 }
rgrover1 260:ea7f9f14cc15 83 static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 84 return (durationInMillis * 1000) / UNIT_0_625_MS;
rgrover1 260:ea7f9f14cc15 85 }
rgrover1 325:501ad8b8bbe5 86 static uint16_t GAP_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
rgrover1 325:501ad8b8bbe5 87 return (gapUnits * UNIT_0_625_MS) / 1000;
rgrover1 325:501ad8b8bbe5 88 }
rgrover1 260:ea7f9f14cc15 89
rgrover1 260:ea7f9f14cc15 90 typedef void (*EventCallback_t)(void);
rgrover1 342:152bd9c825d6 91 typedef void (*ConnectionEventCallback_t)(Handle_t,
rgrover1 342:152bd9c825d6 92 addr_type_t peerAddrType, const address_t peerAddr,
rgrover1 342:152bd9c825d6 93 addr_type_t ownAddrType, const address_t ownAddr,
rgrover1 342:152bd9c825d6 94 const ConnectionParams_t *);
rgrover1 349:b8b2b3973c47 95 typedef void (*HandleSpecificEvent_t)(Handle_t handle);
rgrover1 260:ea7f9f14cc15 96 typedef void (*DisconnectionEventCallback_t)(Handle_t, DisconnectionReason_t);
rgrover1 341:8a104d9d80c1 97 typedef void (*RadioNotificationEventCallback_t) (bool radio_active); /* gets passed true for ACTIVE; false for INACTIVE. */
rgrover1 260:ea7f9f14cc15 98
rgrover1 260:ea7f9f14cc15 99 friend class BLEDevice;
rgrover1 260:ea7f9f14cc15 100 private:
rgrover1 260:ea7f9f14cc15 101 /* These functions must be defined in the sub-class */
rgrover1 260:ea7f9f14cc15 102 virtual ble_error_t setAddress(addr_type_t type, const address_t address) = 0;
rgrover1 260:ea7f9f14cc15 103 virtual ble_error_t getAddress(addr_type_t *typeP, address_t address) = 0;
rgrover1 260:ea7f9f14cc15 104 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &, const GapAdvertisingData &) = 0;
rgrover1 260:ea7f9f14cc15 105 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
rgrover1 260:ea7f9f14cc15 106 virtual ble_error_t stopAdvertising(void) = 0;
rgrover1 325:501ad8b8bbe5 107 virtual uint16_t getMinAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 108 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 109 virtual uint16_t getMaxAdvertisingInterval(void) const = 0;
rgrover1 260:ea7f9f14cc15 110 virtual ble_error_t disconnect(DisconnectionReason_t reason) = 0;
rgrover1 260:ea7f9f14cc15 111 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 112 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 113 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 114
rgrover1 352:79d7cb60ae27 115 virtual ble_error_t deleteAllBondedDevices(void) = 0;
rgrover1 352:79d7cb60ae27 116 virtual ble_error_t getLinkSecurity(Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) = 0;
rgrover1 352:79d7cb60ae27 117
rgrover1 260:ea7f9f14cc15 118 virtual ble_error_t setDeviceName(const uint8_t *deviceName) = 0;
rgrover1 260:ea7f9f14cc15 119 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) = 0;
rgrover1 260:ea7f9f14cc15 120 virtual ble_error_t setAppearance(uint16_t appearance) = 0;
rgrover1 260:ea7f9f14cc15 121 virtual ble_error_t getAppearance(uint16_t *appearanceP) = 0;
rgrover1 260:ea7f9f14cc15 122
rgrover1 337:e7c2eb38f5cc 123 protected:
rgrover1 260:ea7f9f14cc15 124 /* Event callback handlers */
rgrover1 260:ea7f9f14cc15 125 void setOnTimeout(EventCallback_t callback) {onTimeout = callback;}
rgrover1 260:ea7f9f14cc15 126 void setOnConnection(ConnectionEventCallback_t callback) {onConnection = callback;}
rgrover1 260:ea7f9f14cc15 127
rgrover1 260:ea7f9f14cc15 128 /**
rgrover1 260:ea7f9f14cc15 129 * Set the application callback for disconnection events.
rgrover1 260:ea7f9f14cc15 130 * @param callback
rgrover1 260:ea7f9f14cc15 131 * Pointer to the unique callback.
rgrover1 260:ea7f9f14cc15 132 */
rgrover1 260:ea7f9f14cc15 133 void setOnDisconnection(DisconnectionEventCallback_t callback) {onDisconnection = callback;}
rgrover1 260:ea7f9f14cc15 134
rgrover1 260:ea7f9f14cc15 135 /**
rgrover1 341:8a104d9d80c1 136 * Set the application callback for radio-notification events.
rgrover1 341:8a104d9d80c1 137 * @param callback
rgrover1 341:8a104d9d80c1 138 * Handler to be executed in resonse to a radio notification event.
rgrover1 341:8a104d9d80c1 139 */
rgrover1 341:8a104d9d80c1 140 virtual void setOnRadioNotification(RadioNotificationEventCallback_t callback) {onRadioNotification = callback;}
rgrover1 341:8a104d9d80c1 141
rgrover1 341:8a104d9d80c1 142 /**
rgrover1 349:b8b2b3973c47 143 * To indicate that security procedure for link has started.
rgrover1 349:b8b2b3973c47 144 */
rgrover1 349:b8b2b3973c47 145 virtual void setOnSecuritySetupStarted(HandleSpecificEvent_t callback) {onSecuritySetupStarted = callback;}
rgrover1 349:b8b2b3973c47 146
rgrover1 349:b8b2b3973c47 147 /**
rgrover1 349:b8b2b3973c47 148 * To indicate that security procedure for link has completed.
rgrover1 349:b8b2b3973c47 149 */
rgrover1 349:b8b2b3973c47 150 virtual void setOnSecuritySetupCompleted(HandleSpecificEvent_t callback) {onSecuritySetupCompleted = callback;}
rgrover1 349:b8b2b3973c47 151
rgrover1 349:b8b2b3973c47 152 /**
rgrover1 349:b8b2b3973c47 153 * To indicate that link with the peer is secured. For bonded devices,
rgrover1 349:b8b2b3973c47 154 * subsequent reconnections with bonded peer will result only in this callback
rgrover1 349:b8b2b3973c47 155 * when the link is secured and setup procedures will not occur unless the
rgrover1 349:b8b2b3973c47 156 * bonding information is either lost or deleted on either or both sides.
rgrover1 349:b8b2b3973c47 157 */
rgrover1 349:b8b2b3973c47 158 virtual void setOnLinkSecured(HandleSpecificEvent_t callback) {onLinkSecured = callback;}
rgrover1 349:b8b2b3973c47 159
rgrover1 349:b8b2b3973c47 160 /**
rgrover1 349:b8b2b3973c47 161 * To indicate that device context is stored persistently.
rgrover1 349:b8b2b3973c47 162 */
rgrover1 349:b8b2b3973c47 163 virtual void setOnSecurityContextStored(HandleSpecificEvent_t callback) {onSecurityContextStored = callback;}
rgrover1 349:b8b2b3973c47 164
rgrover1 349:b8b2b3973c47 165 /**
rgrover1 260:ea7f9f14cc15 166 * Append to a chain of callbacks to be invoked upon disconnection; these
rgrover1 260:ea7f9f14cc15 167 * callbacks receive no context and are therefore different from the
rgrover1 260:ea7f9f14cc15 168 * onDisconnection callback.
rgrover1 260:ea7f9f14cc15 169 * @param callback
rgrover1 260:ea7f9f14cc15 170 * function pointer to be invoked upon disconnection; receives no context.
rgrover1 260:ea7f9f14cc15 171 *
rgrover1 260:ea7f9f14cc15 172 * @note the disconnection CallChain should have been merged with
rgrover1 260:ea7f9f14cc15 173 * onDisconnctionCallback; but this was not possible because
rgrover1 260:ea7f9f14cc15 174 * FunctionPointer (which is a building block for CallChain) doesn't
rgrover1 260:ea7f9f14cc15 175 * accept variadic templates.
rgrover1 260:ea7f9f14cc15 176 */
rgrover1 260:ea7f9f14cc15 177 template<typename T>
rgrover1 260:ea7f9f14cc15 178 void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) {disconnectionCallChain.add(tptr, mptr);}
rgrover1 260:ea7f9f14cc15 179
rgrover1 337:e7c2eb38f5cc 180 private:
rgrover1 260:ea7f9f14cc15 181 GapState_t getState(void) const {
rgrover1 260:ea7f9f14cc15 182 return state;
rgrover1 260:ea7f9f14cc15 183 }
rgrover1 260:ea7f9f14cc15 184
rgrover1 260:ea7f9f14cc15 185 protected:
rgrover1 349:b8b2b3973c47 186 Gap() :
rgrover1 349:b8b2b3973c47 187 state(),
rgrover1 349:b8b2b3973c47 188 onTimeout(NULL),
rgrover1 349:b8b2b3973c47 189 onConnection(NULL),
rgrover1 349:b8b2b3973c47 190 onDisconnection(NULL),
rgrover1 349:b8b2b3973c47 191 onRadioNotification(),
rgrover1 349:b8b2b3973c47 192 onSecuritySetupStarted(),
rgrover1 349:b8b2b3973c47 193 onSecuritySetupCompleted(),
rgrover1 349:b8b2b3973c47 194 onLinkSecured(),
rgrover1 349:b8b2b3973c47 195 onSecurityContextStored(),
rgrover1 349:b8b2b3973c47 196 disconnectionCallChain() {
rgrover1 260:ea7f9f14cc15 197 /* empty */
rgrover1 260:ea7f9f14cc15 198 }
rgrover1 260:ea7f9f14cc15 199
rgrover1 260:ea7f9f14cc15 200 public:
rgrover1 342:152bd9c825d6 201 void processConnectionEvent(Handle_t handle, addr_type_t peerAddrType, const address_t peerAddr, addr_type_t ownAddrType, const address_t ownAddr, const ConnectionParams_t *params) {
rgrover1 260:ea7f9f14cc15 202 state.connected = 1;
rgrover1 260:ea7f9f14cc15 203 if (onConnection) {
rgrover1 342:152bd9c825d6 204 onConnection(handle, peerAddrType, peerAddr, ownAddrType, ownAddr, params);
rgrover1 260:ea7f9f14cc15 205 }
rgrover1 260:ea7f9f14cc15 206 }
rgrover1 260:ea7f9f14cc15 207
rgrover1 260:ea7f9f14cc15 208 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
rgrover1 260:ea7f9f14cc15 209 state.connected = 0;
rgrover1 260:ea7f9f14cc15 210 if (onDisconnection) {
rgrover1 260:ea7f9f14cc15 211 onDisconnection(handle, reason);
rgrover1 260:ea7f9f14cc15 212 }
rgrover1 260:ea7f9f14cc15 213 disconnectionCallChain.call();
rgrover1 260:ea7f9f14cc15 214 }
rgrover1 260:ea7f9f14cc15 215
rgrover1 349:b8b2b3973c47 216 void processSecuritySetupStartedEvent(Handle_t handle) {
rgrover1 349:b8b2b3973c47 217 if (onSecuritySetupStarted) {
rgrover1 349:b8b2b3973c47 218 onSecuritySetupStarted(handle);
rgrover1 349:b8b2b3973c47 219 }
rgrover1 349:b8b2b3973c47 220 }
rgrover1 349:b8b2b3973c47 221
rgrover1 349:b8b2b3973c47 222 void processSecuritySetupCompletedEvent(Handle_t handle) {
rgrover1 349:b8b2b3973c47 223 if (onSecuritySetupCompleted) {
rgrover1 349:b8b2b3973c47 224 onSecuritySetupCompleted(handle);
rgrover1 349:b8b2b3973c47 225 }
rgrover1 349:b8b2b3973c47 226 }
rgrover1 349:b8b2b3973c47 227
rgrover1 349:b8b2b3973c47 228 void processLinkSecuredEvent(Handle_t handle) {
rgrover1 349:b8b2b3973c47 229 if (onLinkSecured) {
rgrover1 349:b8b2b3973c47 230 onLinkSecured(handle);
rgrover1 349:b8b2b3973c47 231 }
rgrover1 349:b8b2b3973c47 232 }
rgrover1 349:b8b2b3973c47 233
rgrover1 349:b8b2b3973c47 234 void processSecurityContextStoredEvent(Handle_t handle) {
rgrover1 349:b8b2b3973c47 235 if (onSecurityContextStored) {
rgrover1 349:b8b2b3973c47 236 onSecurityContextStored(handle);
rgrover1 349:b8b2b3973c47 237 }
rgrover1 349:b8b2b3973c47 238 }
rgrover1 349:b8b2b3973c47 239
rgrover1 260:ea7f9f14cc15 240 void processEvent(GapEvents::gapEvent_e type) {
rgrover1 260:ea7f9f14cc15 241 switch (type) {
rgrover1 260:ea7f9f14cc15 242 case GapEvents::GAP_EVENT_TIMEOUT:
rgrover1 260:ea7f9f14cc15 243 state.advertising = 0;
rgrover1 260:ea7f9f14cc15 244 if (onTimeout) {
rgrover1 260:ea7f9f14cc15 245 onTimeout();
rgrover1 260:ea7f9f14cc15 246 }
rgrover1 260:ea7f9f14cc15 247 break;
rgrover1 267:ad6f6f40eb24 248 default:
rgrover1 267:ad6f6f40eb24 249 break;
rgrover1 260:ea7f9f14cc15 250 }
rgrover1 260:ea7f9f14cc15 251 }
rgrover1 260:ea7f9f14cc15 252
rgrover1 260:ea7f9f14cc15 253 protected:
rgrover1 260:ea7f9f14cc15 254 GapState_t state;
rgrover1 260:ea7f9f14cc15 255
rgrover1 337:e7c2eb38f5cc 256 protected:
rgrover1 260:ea7f9f14cc15 257 EventCallback_t onTimeout;
rgrover1 260:ea7f9f14cc15 258 ConnectionEventCallback_t onConnection;
rgrover1 260:ea7f9f14cc15 259 DisconnectionEventCallback_t onDisconnection;
rgrover1 341:8a104d9d80c1 260 RadioNotificationEventCallback_t onRadioNotification;
rgrover1 349:b8b2b3973c47 261 HandleSpecificEvent_t onSecuritySetupStarted;
rgrover1 349:b8b2b3973c47 262 HandleSpecificEvent_t onSecuritySetupCompleted;
rgrover1 349:b8b2b3973c47 263 HandleSpecificEvent_t onLinkSecured;
rgrover1 349:b8b2b3973c47 264 HandleSpecificEvent_t onSecurityContextStored;
rgrover1 260:ea7f9f14cc15 265 CallChain disconnectionCallChain;
rgrover1 260:ea7f9f14cc15 266
rgrover1 260:ea7f9f14cc15 267 private:
rgrover1 260:ea7f9f14cc15 268 /* disallow copy and assignment */
rgrover1 260:ea7f9f14cc15 269 Gap(const Gap &);
rgrover1 260:ea7f9f14cc15 270 Gap& operator=(const Gap &);
rgrover1 260:ea7f9f14cc15 271 };
rgrover1 260:ea7f9f14cc15 272
rgrover1 260:ea7f9f14cc15 273 #endif // ifndef __GAP_H__