Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1085:ab823cb9783f, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:47 2016 +0000
Revision:
1085:ab823cb9783f
Parent:
1084:40c1e518d6de
Child:
1086:75d4e8ce277d
Synchronized with git rev 2f527dbb

Author: Rohit Grover

transparenly support existing applications which may have used Gap::ADDR_TYPE_*.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 710:b2e1a2660ec2 1 /* mbed Microcontroller Library
rgrover1 710:b2e1a2660ec2 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 710:b2e1a2660ec2 3 *
rgrover1 710:b2e1a2660ec2 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 710:b2e1a2660ec2 5 * you may not use this file except in compliance with the License.
rgrover1 710:b2e1a2660ec2 6 * You may obtain a copy of the License at
rgrover1 710:b2e1a2660ec2 7 *
rgrover1 710:b2e1a2660ec2 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 710:b2e1a2660ec2 9 *
rgrover1 710:b2e1a2660ec2 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 710:b2e1a2660ec2 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 710:b2e1a2660ec2 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 710:b2e1a2660ec2 13 * See the License for the specific language governing permissions and
rgrover1 710:b2e1a2660ec2 14 * limitations under the License.
rgrover1 710:b2e1a2660ec2 15 */
rgrover1 710:b2e1a2660ec2 16
rgrover1 710:b2e1a2660ec2 17 #ifndef __GAP_H__
rgrover1 710:b2e1a2660ec2 18 #define __GAP_H__
rgrover1 710:b2e1a2660ec2 19
vcoubard 1078:79c089630b38 20 #include "ble/BLEProtocol.h"
rgrover1 710:b2e1a2660ec2 21 #include "GapAdvertisingData.h"
rgrover1 710:b2e1a2660ec2 22 #include "GapAdvertisingParams.h"
rgrover1 710:b2e1a2660ec2 23 #include "GapScanningParams.h"
rgrover1 710:b2e1a2660ec2 24 #include "GapEvents.h"
rgrover1 829:9072de50087b 25 #include "CallChainOfFunctionPointersWithContext.h"
rgrover1 710:b2e1a2660ec2 26 #include "FunctionPointerWithContext.h"
rgrover1 710:b2e1a2660ec2 27
vcoubard 1048:efb29faf12fc 28 /* Forward declarations for classes that will only be used for pointers or references in the following. */
rgrover1 710:b2e1a2660ec2 29 class GapAdvertisingParams;
rgrover1 710:b2e1a2660ec2 30 class GapScanningParams;
rgrover1 710:b2e1a2660ec2 31 class GapAdvertisingData;
rgrover1 710:b2e1a2660ec2 32
rgrover1 710:b2e1a2660ec2 33 class Gap {
vcoubard 1078:79c089630b38 34 /*
vcoubard 1078:79c089630b38 35 * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated.
vcoubard 1078:79c089630b38 36 * They have been relocated to the class BLEProtocol.
vcoubard 1078:79c089630b38 37 */
rgrover1 710:b2e1a2660ec2 38 public:
vcoubard 1078:79c089630b38 39 /**
vcoubard 1078:79c089630b38 40 * Address-type for BLEProtocol addresses.
vcoubard 1085:ab823cb9783f 41 *
vcoubard 1085:ab823cb9783f 42 * @note: deprecated. Use BLEProtocol::AddressType_t instead. This declaration will soon be changed to:
vcoubard 1085:ab823cb9783f 43 * typedef BLEProtocol::AddressType_t AddressType_t;
vcoubard 1085:ab823cb9783f 44 * It has been left in this current state to transparenly support existing applications which may have used Gap::ADDR_TYPE_*.
vcoubard 1078:79c089630b38 45 */
vcoubard 1085:ab823cb9783f 46 enum AddressType_t {
vcoubard 1085:ab823cb9783f 47 ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
vcoubard 1085:ab823cb9783f 48 ADDR_TYPE_RANDOM_STATIC,
vcoubard 1085:ab823cb9783f 49 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
vcoubard 1085:ab823cb9783f 50 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
vcoubard 1085:ab823cb9783f 51 };
rgrover1 710:b2e1a2660ec2 52
vcoubard 1078:79c089630b38 53 /**
vcoubard 1078:79c089630b38 54 * Address-type for BLEProtocol addresses.
vcoubard 1078:79c089630b38 55 * @note: deprecated. Use BLEProtocol::AddressType_t instead.
vcoubard 1078:79c089630b38 56 */
vcoubard 1078:79c089630b38 57 typedef BLEProtocol::AddressType_t addr_type_t;
rgrover1 710:b2e1a2660ec2 58
vcoubard 1078:79c089630b38 59 static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
vcoubard 1078:79c089630b38 60 typedef BLEProtocol::Address_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_t instead. */
vcoubard 1078:79c089630b38 61 typedef BLEProtocol::Address_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_t instead. */
vcoubard 1078:79c089630b38 62
vcoubard 1078:79c089630b38 63 public:
rgrover1 710:b2e1a2660ec2 64 enum TimeoutSource_t {
rgrover1 710:b2e1a2660ec2 65 TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
rgrover1 710:b2e1a2660ec2 66 TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
rgrover1 710:b2e1a2660ec2 67 TIMEOUT_SRC_SCAN = 0x02, /**< Scanning timeout. */
rgrover1 710:b2e1a2660ec2 68 TIMEOUT_SRC_CONN = 0x03, /**< Connection timeout. */
rgrover1 710:b2e1a2660ec2 69 };
rgrover1 710:b2e1a2660ec2 70
rgrover1 710:b2e1a2660ec2 71 /**
rgrover1 710:b2e1a2660ec2 72 * Enumeration for disconnection reasons. The values for these reasons are
vcoubard 1048:efb29faf12fc 73 * derived from Nordic's implementation, but the reasons are meant to be
vcoubard 1048:efb29faf12fc 74 * independent of the transport. If you are returned a reason that is not
vcoubard 1048:efb29faf12fc 75 * covered by this enumeration, please refer to the underlying
rgrover1 710:b2e1a2660ec2 76 * transport library.
rgrover1 710:b2e1a2660ec2 77 */
rgrover1 710:b2e1a2660ec2 78 enum DisconnectionReason_t {
rgrover1 710:b2e1a2660ec2 79 CONNECTION_TIMEOUT = 0x08,
rgrover1 710:b2e1a2660ec2 80 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
vcoubard 1048:efb29faf12fc 81 REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
vcoubard 1048:efb29faf12fc 82 REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
rgrover1 710:b2e1a2660ec2 83 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
rgrover1 710:b2e1a2660ec2 84 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
rgrover1 710:b2e1a2660ec2 85 };
rgrover1 710:b2e1a2660ec2 86
vcoubard 1048:efb29faf12fc 87 /* Describes the current state of the device (more than one bit can be set). */
rgrover1 710:b2e1a2660ec2 88 struct GapState_t {
vcoubard 1048:efb29faf12fc 89 unsigned advertising : 1; /**< Peripheral is currently advertising. */
vcoubard 1048:efb29faf12fc 90 unsigned connected : 1; /**< Peripheral is connected to a central. */
rgrover1 710:b2e1a2660ec2 91 };
rgrover1 710:b2e1a2660ec2 92
rgrover1 710:b2e1a2660ec2 93 typedef uint16_t Handle_t; /* Type for connection handle. */
rgrover1 710:b2e1a2660ec2 94
rgrover1 710:b2e1a2660ec2 95 typedef struct {
rgrover1 710:b2e1a2660ec2 96 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 97 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 98 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 99 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 100 } ConnectionParams_t;
rgrover1 710:b2e1a2660ec2 101
rgrover1 710:b2e1a2660ec2 102 enum Role_t {
rgrover1 710:b2e1a2660ec2 103 PERIPHERAL = 0x1, /**< Peripheral Role. */
rgrover1 710:b2e1a2660ec2 104 CENTRAL = 0x2, /**< Central Role. */
rgrover1 710:b2e1a2660ec2 105 };
rgrover1 710:b2e1a2660ec2 106
rgrover1 710:b2e1a2660ec2 107 struct AdvertisementCallbackParams_t {
vcoubard 1079:6e2d9514f3df 108 BLEProtocol::Address_t peerAddr;
vcoubard 1079:6e2d9514f3df 109 int8_t rssi;
vcoubard 1079:6e2d9514f3df 110 bool isScanResponse;
vcoubard 1079:6e2d9514f3df 111 GapAdvertisingParams::AdvertisingType_t type;
vcoubard 1079:6e2d9514f3df 112 uint8_t advertisingDataLen;
vcoubard 1079:6e2d9514f3df 113 const uint8_t *advertisingData;
rgrover1 710:b2e1a2660ec2 114 };
rgrover1 710:b2e1a2660ec2 115 typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
rgrover1 710:b2e1a2660ec2 116
rgrover1 710:b2e1a2660ec2 117 struct ConnectionCallbackParams_t {
vcoubard 1078:79c089630b38 118 Handle_t handle;
vcoubard 1078:79c089630b38 119 Role_t role;
vcoubard 1078:79c089630b38 120 BLEProtocol::AddressType_t peerAddrType;
vcoubard 1079:6e2d9514f3df 121 BLEProtocol::Address_t peerAddr;
vcoubard 1078:79c089630b38 122 BLEProtocol::AddressType_t ownAddrType;
vcoubard 1079:6e2d9514f3df 123 BLEProtocol::Address_t ownAddr;
vcoubard 1078:79c089630b38 124 const ConnectionParams_t *connectionParams;
rgrover1 710:b2e1a2660ec2 125
vcoubard 1078:79c089630b38 126 ConnectionCallbackParams_t(Handle_t handleIn,
vcoubard 1078:79c089630b38 127 Role_t roleIn,
vcoubard 1078:79c089630b38 128 BLEProtocol::AddressType_t peerAddrTypeIn,
vcoubard 1078:79c089630b38 129 const uint8_t *peerAddrIn,
vcoubard 1078:79c089630b38 130 BLEProtocol::AddressType_t ownAddrTypeIn,
vcoubard 1078:79c089630b38 131 const uint8_t *ownAddrIn,
vcoubard 1078:79c089630b38 132 const ConnectionParams_t *connectionParamsIn) :
rgrover1 710:b2e1a2660ec2 133 handle(handleIn),
rgrover1 710:b2e1a2660ec2 134 role(roleIn),
rgrover1 710:b2e1a2660ec2 135 peerAddrType(peerAddrTypeIn),
rgrover1 710:b2e1a2660ec2 136 peerAddr(),
rgrover1 710:b2e1a2660ec2 137 ownAddrType(ownAddrTypeIn),
rgrover1 710:b2e1a2660ec2 138 ownAddr(),
rgrover1 710:b2e1a2660ec2 139 connectionParams(connectionParamsIn) {
rgrover1 710:b2e1a2660ec2 140 memcpy(peerAddr, peerAddrIn, ADDR_LEN);
rgrover1 710:b2e1a2660ec2 141 memcpy(ownAddr, ownAddrIn, ADDR_LEN);
rgrover1 710:b2e1a2660ec2 142 }
rgrover1 710:b2e1a2660ec2 143 };
rgrover1 710:b2e1a2660ec2 144
rgrover1 829:9072de50087b 145 struct DisconnectionCallbackParams_t {
rgrover1 829:9072de50087b 146 Handle_t handle;
rgrover1 829:9072de50087b 147 DisconnectionReason_t reason;
rgrover1 829:9072de50087b 148
rgrover1 829:9072de50087b 149 DisconnectionCallbackParams_t(Handle_t handleIn,
rgrover1 829:9072de50087b 150 DisconnectionReason_t reasonIn) :
rgrover1 829:9072de50087b 151 handle(handleIn),
rgrover1 829:9072de50087b 152 reason(reasonIn)
rgrover1 829:9072de50087b 153 {}
rgrover1 829:9072de50087b 154 };
rgrover1 829:9072de50087b 155
rgrover1 710:b2e1a2660ec2 156 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
rgrover1 710:b2e1a2660ec2 157 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 710:b2e1a2660ec2 158 return (durationInMillis * 1000) / UNIT_1_25_MS;
rgrover1 710:b2e1a2660ec2 159 }
rgrover1 766:03f1a26f132f 160
vcoubard 1052:b55e1ad3e1b3 161 typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
vcoubard 1052:b55e1ad3e1b3 162 typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
rgrover1 710:b2e1a2660ec2 163
vcoubard 1052:b55e1ad3e1b3 164 typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
vcoubard 1052:b55e1ad3e1b3 165 typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
vcoubard 1052:b55e1ad3e1b3 166
vcoubard 1052:b55e1ad3e1b3 167 typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
vcoubard 1054:f59e5d9a992a 168 typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
vcoubard 1052:b55e1ad3e1b3 169
rgrover1 753:0f60274cd3ad 170 typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
rgrover1 710:b2e1a2660ec2 171
rgrover1 710:b2e1a2660ec2 172 /*
rgrover1 710:b2e1a2660ec2 173 * The following functions are meant to be overridden in the platform-specific sub-class.
rgrover1 710:b2e1a2660ec2 174 */
rgrover1 710:b2e1a2660ec2 175 public:
rgrover1 710:b2e1a2660ec2 176 /**
rgrover1 710:b2e1a2660ec2 177 * Set the BTLE MAC address and type. Please note that the address format is
vcoubard 1079:6e2d9514f3df 178 * least significant byte first (LSB). Please refer to BLEProtocol::Address_t.
rgrover1 710:b2e1a2660ec2 179 *
rgrover1 710:b2e1a2660ec2 180 * @return BLE_ERROR_NONE on success.
rgrover1 710:b2e1a2660ec2 181 */
vcoubard 1079:6e2d9514f3df 182 virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::Address_t address) {
rgrover1 734:4872b70437ce 183 /* avoid compiler warnings about unused variables */
rgrover1 734:4872b70437ce 184 (void)type;
rgrover1 734:4872b70437ce 185 (void)address;
rgrover1 734:4872b70437ce 186
rgrover1 728:997ba5e7b3b6 187 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 188 }
rgrover1 710:b2e1a2660ec2 189
rgrover1 710:b2e1a2660ec2 190 /**
rgrover1 710:b2e1a2660ec2 191 * Fetch the BTLE MAC address and type.
rgrover1 710:b2e1a2660ec2 192 *
rgrover1 710:b2e1a2660ec2 193 * @return BLE_ERROR_NONE on success.
rgrover1 710:b2e1a2660ec2 194 */
vcoubard 1079:6e2d9514f3df 195 virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::Address_t address) {
vcoubard 1048:efb29faf12fc 196 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 197 (void)typeP;
rgrover1 734:4872b70437ce 198 (void)address;
rgrover1 734:4872b70437ce 199
rgrover1 728:997ba5e7b3b6 200 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 201 }
rgrover1 710:b2e1a2660ec2 202
rgrover1 710:b2e1a2660ec2 203 /**
vcoubard 1056:ce2fb3d09929 204 * @return Minimum Advertising interval in milliseconds for connectable
vcoubard 1056:ce2fb3d09929 205 * undirected and connectable directed event types.
rgrover1 710:b2e1a2660ec2 206 */
rgrover1 710:b2e1a2660ec2 207 virtual uint16_t getMinAdvertisingInterval(void) const {
rgrover1 742:861ed7eb186d 208 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 209 }
rgrover1 710:b2e1a2660ec2 210
rgrover1 710:b2e1a2660ec2 211 /**
vcoubard 1056:ce2fb3d09929 212 * @return Minimum Advertising interval in milliseconds for scannable
vcoubard 1056:ce2fb3d09929 213 * undirected and non-connectable undirected event types.
rgrover1 710:b2e1a2660ec2 214 */
rgrover1 710:b2e1a2660ec2 215 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
rgrover1 742:861ed7eb186d 216 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 217 }
rgrover1 710:b2e1a2660ec2 218
rgrover1 710:b2e1a2660ec2 219 /**
rgrover1 710:b2e1a2660ec2 220 * @return Maximum Advertising interval in milliseconds.
rgrover1 710:b2e1a2660ec2 221 */
rgrover1 710:b2e1a2660ec2 222 virtual uint16_t getMaxAdvertisingInterval(void) const {
rgrover1 742:861ed7eb186d 223 return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 224 }
rgrover1 710:b2e1a2660ec2 225
rgrover1 710:b2e1a2660ec2 226 virtual ble_error_t stopAdvertising(void) {
rgrover1 728:997ba5e7b3b6 227 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 228 }
rgrover1 710:b2e1a2660ec2 229
rgrover1 710:b2e1a2660ec2 230 /**
rgrover1 710:b2e1a2660ec2 231 * Stop scanning. The current scanning parameters remain in effect.
rgrover1 710:b2e1a2660ec2 232 *
rgrover1 710:b2e1a2660ec2 233 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
rgrover1 710:b2e1a2660ec2 234 */
rgrover1 710:b2e1a2660ec2 235 virtual ble_error_t stopScan() {
rgrover1 728:997ba5e7b3b6 236 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 237 }
rgrover1 710:b2e1a2660ec2 238
rgrover1 710:b2e1a2660ec2 239 /**
rgrover1 710:b2e1a2660ec2 240 * Create a connection (GAP Link Establishment).
rgrover1 710:b2e1a2660ec2 241 *
rgrover1 710:b2e1a2660ec2 242 * @param peerAddr
rgrover1 710:b2e1a2660ec2 243 * 48-bit address, LSB format.
rgrover1 710:b2e1a2660ec2 244 * @param peerAddrType
rgrover1 710:b2e1a2660ec2 245 * Address type of the peer.
rgrover1 710:b2e1a2660ec2 246 * @param connectionParams
rgrover1 710:b2e1a2660ec2 247 * Connection parameters.
rgrover1 710:b2e1a2660ec2 248 * @param scanParams
rgrover1 710:b2e1a2660ec2 249 * Paramters to be used while scanning for the peer.
rgrover1 710:b2e1a2660ec2 250 * @return BLE_ERROR_NONE if connection establishment procedure is started
rgrover1 829:9072de50087b 251 * successfully. The connectionCallChain (if set) will be invoked upon
rgrover1 710:b2e1a2660ec2 252 * a connection event.
rgrover1 710:b2e1a2660ec2 253 */
vcoubard 1079:6e2d9514f3df 254 virtual ble_error_t connect(const BLEProtocol::Address_t peerAddr,
vcoubard 1079:6e2d9514f3df 255 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1079:6e2d9514f3df 256 const ConnectionParams_t *connectionParams,
vcoubard 1079:6e2d9514f3df 257 const GapScanningParams *scanParams) {
vcoubard 1048:efb29faf12fc 258 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 259 (void)peerAddr;
rgrover1 734:4872b70437ce 260 (void)peerAddrType;
rgrover1 734:4872b70437ce 261 (void)connectionParams;
rgrover1 734:4872b70437ce 262 (void)scanParams;
rgrover1 734:4872b70437ce 263
rgrover1 728:997ba5e7b3b6 264 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 265 }
rgrover1 710:b2e1a2660ec2 266
rgrover1 710:b2e1a2660ec2 267 /**
rgrover1 710:b2e1a2660ec2 268 * This call initiates the disconnection procedure, and its completion will
rgrover1 710:b2e1a2660ec2 269 * be communicated to the application with an invocation of the
rgrover1 710:b2e1a2660ec2 270 * disconnectionCallback.
rgrover1 710:b2e1a2660ec2 271 *
rgrover1 710:b2e1a2660ec2 272 * @param reason
vcoubard 1048:efb29faf12fc 273 * The reason for disconnection; to be sent back to the peer.
rgrover1 710:b2e1a2660ec2 274 */
rgrover1 710:b2e1a2660ec2 275 virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
rgrover1 734:4872b70437ce 276 /* avoid compiler warnings about unused variables */
rgrover1 734:4872b70437ce 277 (void)connectionHandle;
rgrover1 734:4872b70437ce 278 (void)reason;
rgrover1 734:4872b70437ce 279
rgrover1 728:997ba5e7b3b6 280 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 281 }
rgrover1 710:b2e1a2660ec2 282
rgrover1 710:b2e1a2660ec2 283 /**
rgrover1 710:b2e1a2660ec2 284 * This call initiates the disconnection procedure, and its completion will
rgrover1 710:b2e1a2660ec2 285 * be communicated to the application with an invocation of the
rgrover1 710:b2e1a2660ec2 286 * disconnectionCallback.
rgrover1 710:b2e1a2660ec2 287 *
rgrover1 710:b2e1a2660ec2 288 * @param reason
vcoubard 1048:efb29faf12fc 289 * The reason for disconnection; to be sent back to the peer.
rgrover1 710:b2e1a2660ec2 290 *
vcoubard 1048:efb29faf12fc 291 * @note: This version of disconnect() doesn't take a connection handle. It
vcoubard 1048:efb29faf12fc 292 * works reliably only for stacks that are limited to a single
rgrover1 710:b2e1a2660ec2 293 * connection. This API should be considered *deprecated* in favour of the
vcoubard 1048:efb29faf12fc 294 * alternative, which takes a connection handle. It will be dropped in the future.
rgrover1 710:b2e1a2660ec2 295 */
rgrover1 710:b2e1a2660ec2 296 virtual ble_error_t disconnect(DisconnectionReason_t reason) {
vcoubard 1048:efb29faf12fc 297 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 298 (void)reason;
rgrover1 734:4872b70437ce 299
rgrover1 728:997ba5e7b3b6 300 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 301 }
rgrover1 710:b2e1a2660ec2 302
rgrover1 710:b2e1a2660ec2 303 /**
rgrover1 710:b2e1a2660ec2 304 * Get the GAP peripheral preferred connection parameters. These are the
rgrover1 710:b2e1a2660ec2 305 * defaults that the peripheral would like to have in a connection. The
rgrover1 710:b2e1a2660ec2 306 * choice of the connection parameters is eventually up to the central.
rgrover1 710:b2e1a2660ec2 307 *
rgrover1 710:b2e1a2660ec2 308 * @param[out] params
rgrover1 710:b2e1a2660ec2 309 * The structure where the parameters will be stored. Memory
rgrover1 710:b2e1a2660ec2 310 * for this is owned by the caller.
rgrover1 710:b2e1a2660ec2 311 *
rgrover1 710:b2e1a2660ec2 312 * @return BLE_ERROR_NONE if the parameters were successfully filled into
rgrover1 710:b2e1a2660ec2 313 * the given structure pointed to by params.
rgrover1 710:b2e1a2660ec2 314 */
rgrover1 710:b2e1a2660ec2 315 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
vcoubard 1048:efb29faf12fc 316 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 317 (void)params;
rgrover1 734:4872b70437ce 318
rgrover1 728:997ba5e7b3b6 319 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 320 }
rgrover1 710:b2e1a2660ec2 321
rgrover1 710:b2e1a2660ec2 322 /**
rgrover1 710:b2e1a2660ec2 323 * Set the GAP peripheral preferred connection parameters. These are the
rgrover1 710:b2e1a2660ec2 324 * defaults that the peripheral would like to have in a connection. The
rgrover1 710:b2e1a2660ec2 325 * choice of the connection parameters is eventually up to the central.
rgrover1 710:b2e1a2660ec2 326 *
rgrover1 710:b2e1a2660ec2 327 * @param[in] params
rgrover1 710:b2e1a2660ec2 328 * The structure containing the desired parameters.
rgrover1 710:b2e1a2660ec2 329 */
rgrover1 710:b2e1a2660ec2 330 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
vcoubard 1048:efb29faf12fc 331 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 332 (void)params;
rgrover1 734:4872b70437ce 333
rgrover1 728:997ba5e7b3b6 334 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 335 }
rgrover1 710:b2e1a2660ec2 336
rgrover1 710:b2e1a2660ec2 337 /**
rgrover1 816:2b4f0ef8c06e 338 * Update connection parameters.
vcoubard 1048:efb29faf12fc 339 * In the central role this will initiate a Link Layer connection parameter update procedure.
vcoubard 1048:efb29faf12fc 340 * In the peripheral role, this will send the corresponding L2CAP request and wait for
rgrover1 816:2b4f0ef8c06e 341 * the central to perform the procedure.
rgrover1 816:2b4f0ef8c06e 342 *
rgrover1 710:b2e1a2660ec2 343 * @param[in] handle
vcoubard 1048:efb29faf12fc 344 * Connection Handle.
rgrover1 710:b2e1a2660ec2 345 * @param[in] params
rgrover1 710:b2e1a2660ec2 346 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
rgrover1 710:b2e1a2660ec2 347 * the parameters in the PPCP characteristic of the GAP service will be used instead.
rgrover1 710:b2e1a2660ec2 348 */
rgrover1 710:b2e1a2660ec2 349 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
rgrover1 734:4872b70437ce 350 /* avoid compiler warnings about unused variables */
rgrover1 734:4872b70437ce 351 (void)handle;
rgrover1 734:4872b70437ce 352 (void)params;
rgrover1 734:4872b70437ce 353
rgrover1 728:997ba5e7b3b6 354 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 355 }
rgrover1 710:b2e1a2660ec2 356
rgrover1 710:b2e1a2660ec2 357 /**
rgrover1 710:b2e1a2660ec2 358 * Set the device name characteristic in the GAP service.
rgrover1 710:b2e1a2660ec2 359 * @param[in] deviceName
rgrover1 710:b2e1a2660ec2 360 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
rgrover1 710:b2e1a2660ec2 361 */
rgrover1 710:b2e1a2660ec2 362 virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
vcoubard 1048:efb29faf12fc 363 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 364 (void)deviceName;
rgrover1 734:4872b70437ce 365
rgrover1 728:997ba5e7b3b6 366 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 367 }
rgrover1 710:b2e1a2660ec2 368
rgrover1 710:b2e1a2660ec2 369 /**
rgrover1 710:b2e1a2660ec2 370 * Get the value of the device name characteristic in the GAP service.
rgrover1 710:b2e1a2660ec2 371 * @param[out] deviceName
rgrover1 710:b2e1a2660ec2 372 * Pointer to an empty buffer where the UTF-8 *non NULL-
rgrover1 710:b2e1a2660ec2 373 * terminated* string will be placed. Set this
rgrover1 710:b2e1a2660ec2 374 * value to NULL in order to obtain the deviceName-length
rgrover1 710:b2e1a2660ec2 375 * from the 'length' parameter.
rgrover1 710:b2e1a2660ec2 376 *
rgrover1 710:b2e1a2660ec2 377 * @param[in/out] lengthP
rgrover1 710:b2e1a2660ec2 378 * (on input) Length of the buffer pointed to by deviceName;
rgrover1 710:b2e1a2660ec2 379 * (on output) the complete device name length (without the
rgrover1 710:b2e1a2660ec2 380 * null terminator).
rgrover1 710:b2e1a2660ec2 381 *
rgrover1 710:b2e1a2660ec2 382 * @note If the device name is longer than the size of the supplied buffer,
rgrover1 710:b2e1a2660ec2 383 * length will return the complete device name length, and not the
rgrover1 710:b2e1a2660ec2 384 * number of bytes actually returned in deviceName. The application may
rgrover1 710:b2e1a2660ec2 385 * use this information to retry with a suitable buffer size.
rgrover1 710:b2e1a2660ec2 386 */
rgrover1 710:b2e1a2660ec2 387 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
rgrover1 734:4872b70437ce 388 /* avoid compiler warnings about unused variables */
rgrover1 734:4872b70437ce 389 (void)deviceName;
rgrover1 734:4872b70437ce 390 (void)lengthP;
rgrover1 734:4872b70437ce 391
rgrover1 728:997ba5e7b3b6 392 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 393 }
rgrover1 710:b2e1a2660ec2 394
rgrover1 710:b2e1a2660ec2 395 /**
rgrover1 710:b2e1a2660ec2 396 * Set the appearance characteristic in the GAP service.
rgrover1 710:b2e1a2660ec2 397 * @param[in] appearance
rgrover1 710:b2e1a2660ec2 398 * The new value for the device-appearance.
rgrover1 710:b2e1a2660ec2 399 */
rgrover1 710:b2e1a2660ec2 400 virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
vcoubard 1048:efb29faf12fc 401 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 402 (void)appearance;
rgrover1 734:4872b70437ce 403
rgrover1 728:997ba5e7b3b6 404 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 405 }
rgrover1 710:b2e1a2660ec2 406
rgrover1 710:b2e1a2660ec2 407 /**
rgrover1 710:b2e1a2660ec2 408 * Get the appearance characteristic in the GAP service.
rgrover1 710:b2e1a2660ec2 409 * @param[out] appearance
rgrover1 710:b2e1a2660ec2 410 * The new value for the device-appearance.
rgrover1 710:b2e1a2660ec2 411 */
rgrover1 710:b2e1a2660ec2 412 virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
vcoubard 1048:efb29faf12fc 413 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 414 (void)appearanceP;
rgrover1 734:4872b70437ce 415
rgrover1 728:997ba5e7b3b6 416 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 417 }
rgrover1 710:b2e1a2660ec2 418
rgrover1 710:b2e1a2660ec2 419 /**
rgrover1 710:b2e1a2660ec2 420 * Set the radio's transmit power.
rgrover1 710:b2e1a2660ec2 421 * @param[in] txPower Radio transmit power in dBm.
rgrover1 710:b2e1a2660ec2 422 */
rgrover1 710:b2e1a2660ec2 423 virtual ble_error_t setTxPower(int8_t txPower) {
vcoubard 1048:efb29faf12fc 424 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 425 (void)txPower;
rgrover1 734:4872b70437ce 426
rgrover1 728:997ba5e7b3b6 427 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 428 }
rgrover1 710:b2e1a2660ec2 429
rgrover1 710:b2e1a2660ec2 430 /**
rgrover1 710:b2e1a2660ec2 431 * Query the underlying stack for permitted arguments for setTxPower().
rgrover1 710:b2e1a2660ec2 432 *
rgrover1 710:b2e1a2660ec2 433 * @param[out] valueArrayPP
rgrover1 710:b2e1a2660ec2 434 * Out parameter to receive the immutable array of Tx values.
rgrover1 710:b2e1a2660ec2 435 * @param[out] countP
rgrover1 710:b2e1a2660ec2 436 * Out parameter to receive the array's size.
rgrover1 710:b2e1a2660ec2 437 */
rgrover1 710:b2e1a2660ec2 438 virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
vcoubard 1048:efb29faf12fc 439 /* Avoid compiler warnings about unused variables. */
rgrover1 734:4872b70437ce 440 (void)valueArrayPP;
rgrover1 734:4872b70437ce 441 (void)countP;
rgrover1 734:4872b70437ce 442
rgrover1 742:861ed7eb186d 443 *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 444 }
rgrover1 710:b2e1a2660ec2 445
rgrover1 710:b2e1a2660ec2 446 protected:
rgrover1 710:b2e1a2660ec2 447 /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
rgrover1 710:b2e1a2660ec2 448 virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
rgrover1 772:b6d27ab66c94 449 (void)scanningParams;
rgrover1 728:997ba5e7b3b6 450 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 710:b2e1a2660ec2 451 }
rgrover1 710:b2e1a2660ec2 452
rgrover1 710:b2e1a2660ec2 453 /*
rgrover1 710:b2e1a2660ec2 454 * APIs with non-virtual implementations.
rgrover1 710:b2e1a2660ec2 455 */
rgrover1 710:b2e1a2660ec2 456 public:
rgrover1 710:b2e1a2660ec2 457 /**
vcoubard 1048:efb29faf12fc 458 * Returns the current GAP state of the device using a bitmask that
vcoubard 1048:efb29faf12fc 459 * describes whether the device is advertising or connected.
rgrover1 710:b2e1a2660ec2 460 */
rgrover1 710:b2e1a2660ec2 461 GapState_t getState(void) const {
rgrover1 710:b2e1a2660ec2 462 return state;
rgrover1 710:b2e1a2660ec2 463 }
rgrover1 710:b2e1a2660ec2 464
rgrover1 710:b2e1a2660ec2 465 /**
rgrover1 710:b2e1a2660ec2 466 * Set the GAP advertising mode to use for this device.
rgrover1 710:b2e1a2660ec2 467 */
rgrover1 710:b2e1a2660ec2 468 void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
rgrover1 710:b2e1a2660ec2 469 _advParams.setAdvertisingType(advType);
rgrover1 710:b2e1a2660ec2 470 }
rgrover1 710:b2e1a2660ec2 471
rgrover1 710:b2e1a2660ec2 472 /**
rgrover1 710:b2e1a2660ec2 473 * @param[in] interval
rgrover1 710:b2e1a2660ec2 474 * Advertising interval in units of milliseconds. Advertising
rgrover1 710:b2e1a2660ec2 475 * is disabled if interval is 0. If interval is smaller than
rgrover1 710:b2e1a2660ec2 476 * the minimum supported value, then the minimum supported
rgrover1 710:b2e1a2660ec2 477 * value is used instead. This minimum value can be discovered
rgrover1 710:b2e1a2660ec2 478 * using getMinAdvertisingInterval().
rgrover1 710:b2e1a2660ec2 479 *
rgrover1 710:b2e1a2660ec2 480 * This field must be set to 0 if connectionMode is equal
rgrover1 710:b2e1a2660ec2 481 * to ADV_CONNECTABLE_DIRECTED.
rgrover1 710:b2e1a2660ec2 482 *
rgrover1 710:b2e1a2660ec2 483 * @note: Decreasing this value will allow central devices to detect a
vcoubard 1048:efb29faf12fc 484 * peripheral faster, at the expense of more power being used by the radio
rgrover1 710:b2e1a2660ec2 485 * due to the higher data transmit rate.
rgrover1 710:b2e1a2660ec2 486 *
rgrover1 710:b2e1a2660ec2 487 * @Note: [WARNING] This API previously used 0.625ms as the unit for its
rgrover1 710:b2e1a2660ec2 488 * 'interval' argument. That required an explicit conversion from
rgrover1 710:b2e1a2660ec2 489 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
rgrover1 710:b2e1a2660ec2 490 * no longer required as the new units are milliseconds. Any application
vcoubard 1048:efb29faf12fc 491 * code depending on the old semantics needs to be updated accordingly.
rgrover1 710:b2e1a2660ec2 492 */
rgrover1 710:b2e1a2660ec2 493 void setAdvertisingInterval(uint16_t interval) {
rgrover1 710:b2e1a2660ec2 494 if (interval == 0) {
rgrover1 710:b2e1a2660ec2 495 stopAdvertising();
rgrover1 710:b2e1a2660ec2 496 } else if (interval < getMinAdvertisingInterval()) {
rgrover1 710:b2e1a2660ec2 497 interval = getMinAdvertisingInterval();
rgrover1 710:b2e1a2660ec2 498 }
rgrover1 786:d6d7087d8377 499 _advParams.setInterval(interval);
rgrover1 710:b2e1a2660ec2 500 }
rgrover1 710:b2e1a2660ec2 501
rgrover1 710:b2e1a2660ec2 502 /**
rgrover1 710:b2e1a2660ec2 503 * @param[in] timeout
rgrover1 710:b2e1a2660ec2 504 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
rgrover1 710:b2e1a2660ec2 505 * and 16383). Use 0 to disable the advertising timeout.
rgrover1 710:b2e1a2660ec2 506 */
rgrover1 710:b2e1a2660ec2 507 void setAdvertisingTimeout(uint16_t timeout) {
rgrover1 710:b2e1a2660ec2 508 _advParams.setTimeout(timeout);
rgrover1 710:b2e1a2660ec2 509 }
rgrover1 710:b2e1a2660ec2 510
rgrover1 710:b2e1a2660ec2 511 /**
rgrover1 710:b2e1a2660ec2 512 * Start advertising.
rgrover1 710:b2e1a2660ec2 513 */
rgrover1 710:b2e1a2660ec2 514 ble_error_t startAdvertising(void) {
vcoubard 1048:efb29faf12fc 515 setAdvertisingData(); /* Update the underlying stack. */
rgrover1 710:b2e1a2660ec2 516 return startAdvertising(_advParams);
rgrover1 710:b2e1a2660ec2 517 }
rgrover1 710:b2e1a2660ec2 518
rgrover1 710:b2e1a2660ec2 519 /**
rgrover1 710:b2e1a2660ec2 520 * Reset any advertising payload prepared from prior calls to
rgrover1 710:b2e1a2660ec2 521 * accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard 1048:efb29faf12fc 522 * initialized advertising payload to the underlying stack.
rgrover1 710:b2e1a2660ec2 523 */
rgrover1 710:b2e1a2660ec2 524 void clearAdvertisingPayload(void) {
rgrover1 710:b2e1a2660ec2 525 _advPayload.clear();
rgrover1 710:b2e1a2660ec2 526 setAdvertisingData();
rgrover1 710:b2e1a2660ec2 527 }
rgrover1 710:b2e1a2660ec2 528
rgrover1 710:b2e1a2660ec2 529 /**
rgrover1 710:b2e1a2660ec2 530 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 710:b2e1a2660ec2 531 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1048:efb29faf12fc 532 * as an additional 31 bytes if the advertising payload is too
rgrover1 710:b2e1a2660ec2 533 * small.
rgrover1 710:b2e1a2660ec2 534 *
rgrover1 710:b2e1a2660ec2 535 * @param[in] flags
rgrover1 710:b2e1a2660ec2 536 * The flags to be added. Please refer to
rgrover1 710:b2e1a2660ec2 537 * GapAdvertisingData::Flags for valid flags. Multiple
rgrover1 710:b2e1a2660ec2 538 * flags may be specified in combination.
rgrover1 710:b2e1a2660ec2 539 */
rgrover1 710:b2e1a2660ec2 540 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
rgrover1 710:b2e1a2660ec2 541 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 542 if ((rc = _advPayload.addFlags(flags)) != BLE_ERROR_NONE) {
rgrover1 710:b2e1a2660ec2 543 return rc;
rgrover1 710:b2e1a2660ec2 544 }
rgrover1 710:b2e1a2660ec2 545
rgrover1 710:b2e1a2660ec2 546 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 547 }
rgrover1 710:b2e1a2660ec2 548
rgrover1 710:b2e1a2660ec2 549 /**
rgrover1 710:b2e1a2660ec2 550 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 710:b2e1a2660ec2 551 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1048:efb29faf12fc 552 * as an additional 31 bytes if the advertising payload is too
rgrover1 710:b2e1a2660ec2 553 * small.
rgrover1 710:b2e1a2660ec2 554 *
rgrover1 710:b2e1a2660ec2 555 * @param app
rgrover1 710:b2e1a2660ec2 556 * The appearance of the peripheral.
rgrover1 710:b2e1a2660ec2 557 */
rgrover1 710:b2e1a2660ec2 558 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
rgrover1 710:b2e1a2660ec2 559 setAppearance(app);
rgrover1 710:b2e1a2660ec2 560
rgrover1 710:b2e1a2660ec2 561 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 562 if ((rc = _advPayload.addAppearance(app)) != BLE_ERROR_NONE) {
rgrover1 710:b2e1a2660ec2 563 return rc;
rgrover1 710:b2e1a2660ec2 564 }
rgrover1 710:b2e1a2660ec2 565
rgrover1 710:b2e1a2660ec2 566 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 567 }
rgrover1 710:b2e1a2660ec2 568
rgrover1 710:b2e1a2660ec2 569 /**
rgrover1 710:b2e1a2660ec2 570 * Accumulate an AD structure in the advertising payload. Please note that
rgrover1 710:b2e1a2660ec2 571 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1048:efb29faf12fc 572 * as an additional 31 bytes if the advertising payload is too
rgrover1 710:b2e1a2660ec2 573 * small.
rgrover1 710:b2e1a2660ec2 574 *
vcoubard 1048:efb29faf12fc 575 * @param power
rgrover1 764:1e560f0d45e1 576 * The max transmit power to be used by the controller (in dBm).
rgrover1 710:b2e1a2660ec2 577 */
rgrover1 710:b2e1a2660ec2 578 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
rgrover1 710:b2e1a2660ec2 579 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 580 if ((rc = _advPayload.addTxPower(power)) != BLE_ERROR_NONE) {
rgrover1 710:b2e1a2660ec2 581 return rc;
rgrover1 710:b2e1a2660ec2 582 }
rgrover1 710:b2e1a2660ec2 583
rgrover1 710:b2e1a2660ec2 584 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 585 }
rgrover1 710:b2e1a2660ec2 586
rgrover1 710:b2e1a2660ec2 587 /**
rgrover1 710:b2e1a2660ec2 588 * Accumulate a variable length byte-stream as an AD structure in the
rgrover1 710:b2e1a2660ec2 589 * advertising payload. Please note that the payload is limited to 31 bytes.
rgrover1 710:b2e1a2660ec2 590 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard 1048:efb29faf12fc 591 * advertising payload is too small.
rgrover1 710:b2e1a2660ec2 592 *
vcoubard 1048:efb29faf12fc 593 * @param type The type describing the variable length data.
vcoubard 1048:efb29faf12fc 594 * @param data Data bytes.
vcoubard 1048:efb29faf12fc 595 * @param len Length of data.
rgrover1 710:b2e1a2660ec2 596 */
rgrover1 710:b2e1a2660ec2 597 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
rgrover1 710:b2e1a2660ec2 598 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
rgrover1 710:b2e1a2660ec2 599 setDeviceName(data);
rgrover1 710:b2e1a2660ec2 600 }
rgrover1 710:b2e1a2660ec2 601
rgrover1 710:b2e1a2660ec2 602 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 603 if ((rc = _advPayload.addData(type, data, len)) != BLE_ERROR_NONE) {
rgrover1 710:b2e1a2660ec2 604 return rc;
rgrover1 710:b2e1a2660ec2 605 }
rgrover1 710:b2e1a2660ec2 606
rgrover1 710:b2e1a2660ec2 607 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 608 }
rgrover1 710:b2e1a2660ec2 609
rgrover1 710:b2e1a2660ec2 610 /**
rgrover1 765:4cd91998cd48 611 * Update a particular ADV field in the advertising payload (based on
rgrover1 765:4cd91998cd48 612 * matching type and length). Note: the length of the new data must be the
rgrover1 765:4cd91998cd48 613 * same as the old one.
rgrover1 763:36c3e2b1f1ae 614 *
vcoubard 1048:efb29faf12fc 615 * @param[in] type The ADV type field describing the variable length data.
vcoubard 1048:efb29faf12fc 616 * @param[in] data Data bytes.
vcoubard 1048:efb29faf12fc 617 * @param[in] len Length of data.
rgrover1 765:4cd91998cd48 618 *
rgrover1 765:4cd91998cd48 619 * @note: If advertisements are enabled, then the update will take effect immediately.
rgrover1 765:4cd91998cd48 620 *
rgrover1 765:4cd91998cd48 621 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1048:efb29faf12fc 622 * a <type, len> match; otherwise, an appropriate error.
rgrover1 763:36c3e2b1f1ae 623 */
rgrover1 763:36c3e2b1f1ae 624 ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
rgrover1 763:36c3e2b1f1ae 625 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
rgrover1 763:36c3e2b1f1ae 626 setDeviceName(data);
rgrover1 763:36c3e2b1f1ae 627 }
rgrover1 763:36c3e2b1f1ae 628
rgrover1 763:36c3e2b1f1ae 629 ble_error_t rc;
rgrover1 763:36c3e2b1f1ae 630 if ((rc = _advPayload.updateData(type, data, len)) != BLE_ERROR_NONE) {
rgrover1 763:36c3e2b1f1ae 631 return rc;
rgrover1 763:36c3e2b1f1ae 632 }
rgrover1 763:36c3e2b1f1ae 633
rgrover1 763:36c3e2b1f1ae 634 return setAdvertisingData();
rgrover1 763:36c3e2b1f1ae 635 }
rgrover1 763:36c3e2b1f1ae 636
rgrover1 763:36c3e2b1f1ae 637 /**
vcoubard 1048:efb29faf12fc 638 * Set up a particular, user-constructed advertisement payload for the
rgrover1 710:b2e1a2660ec2 639 * underlying stack. It would be uncommon for this API to be used directly;
rgrover1 710:b2e1a2660ec2 640 * there are other APIs to build an advertisement payload (see above).
rgrover1 710:b2e1a2660ec2 641 */
rgrover1 710:b2e1a2660ec2 642 ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
rgrover1 710:b2e1a2660ec2 643 _advPayload = payload;
rgrover1 710:b2e1a2660ec2 644 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 645 }
rgrover1 710:b2e1a2660ec2 646
rgrover1 710:b2e1a2660ec2 647 /**
rgrover1 710:b2e1a2660ec2 648 * @return Read back advertising data. Useful for storing and
rgrover1 710:b2e1a2660ec2 649 * restoring payload.
rgrover1 710:b2e1a2660ec2 650 */
rgrover1 710:b2e1a2660ec2 651 const GapAdvertisingData &getAdvertisingPayload(void) const {
rgrover1 710:b2e1a2660ec2 652 return _advPayload;
rgrover1 710:b2e1a2660ec2 653 }
rgrover1 710:b2e1a2660ec2 654
rgrover1 710:b2e1a2660ec2 655 /**
rgrover1 710:b2e1a2660ec2 656 * Accumulate a variable length byte-stream as an AD structure in the
rgrover1 710:b2e1a2660ec2 657 * scanResponse payload.
rgrover1 710:b2e1a2660ec2 658 *
vcoubard 1048:efb29faf12fc 659 * @param[in] type The type describing the variable length data.
vcoubard 1048:efb29faf12fc 660 * @param[in] data Data bytes.
vcoubard 1048:efb29faf12fc 661 * @param[in] len Length of data.
rgrover1 710:b2e1a2660ec2 662 */
rgrover1 710:b2e1a2660ec2 663 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
rgrover1 710:b2e1a2660ec2 664 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 665 if ((rc = _scanResponse.addData(type, data, len)) != BLE_ERROR_NONE) {
rgrover1 710:b2e1a2660ec2 666 return rc;
rgrover1 710:b2e1a2660ec2 667 }
rgrover1 710:b2e1a2660ec2 668
rgrover1 710:b2e1a2660ec2 669 return setAdvertisingData();
rgrover1 710:b2e1a2660ec2 670 }
rgrover1 710:b2e1a2660ec2 671
rgrover1 710:b2e1a2660ec2 672 /**
rgrover1 710:b2e1a2660ec2 673 * Reset any scan response prepared from prior calls to
rgrover1 710:b2e1a2660ec2 674 * accumulateScanResponse().
rgrover1 710:b2e1a2660ec2 675 *
rgrover1 710:b2e1a2660ec2 676 * Note: This should be followed by a call to setAdvertisingPayload() or
rgrover1 710:b2e1a2660ec2 677 * startAdvertising() before the update takes effect.
rgrover1 710:b2e1a2660ec2 678 */
rgrover1 710:b2e1a2660ec2 679 void clearScanResponse(void) {
rgrover1 710:b2e1a2660ec2 680 _scanResponse.clear();
rgrover1 710:b2e1a2660ec2 681 setAdvertisingData();
rgrover1 710:b2e1a2660ec2 682 }
rgrover1 710:b2e1a2660ec2 683
rgrover1 710:b2e1a2660ec2 684 /**
vcoubard 1048:efb29faf12fc 685 * Set up parameters for GAP scanning (observer mode).
rgrover1 710:b2e1a2660ec2 686 * @param[in] interval
rgrover1 710:b2e1a2660ec2 687 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 710:b2e1a2660ec2 688 * @param[in] window
rgrover1 710:b2e1a2660ec2 689 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 710:b2e1a2660ec2 690 * @param[in] timeout
vcoubard 1048:efb29faf12fc 691 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
rgrover1 710:b2e1a2660ec2 692 * @param[in] activeScanning
rgrover1 710:b2e1a2660ec2 693 * Set to True if active-scanning is required. This is used to fetch the
rgrover1 710:b2e1a2660ec2 694 * scan response from a peer if possible.
rgrover1 710:b2e1a2660ec2 695 *
rgrover1 710:b2e1a2660ec2 696 * The scanning window divided by the interval determines the duty cycle for
rgrover1 710:b2e1a2660ec2 697 * scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1 710:b2e1a2660ec2 698 * then the controller will scan for 10 percent of the time. It is possible
rgrover1 710:b2e1a2660ec2 699 * to have the interval and window set to the same value. In this case,
rgrover1 710:b2e1a2660ec2 700 * scanning is continuous, with a change of scanning frequency once every
rgrover1 710:b2e1a2660ec2 701 * interval.
rgrover1 710:b2e1a2660ec2 702 *
rgrover1 710:b2e1a2660ec2 703 * Once the scanning parameters have been configured, scanning can be
rgrover1 710:b2e1a2660ec2 704 * enabled by using startScan().
rgrover1 710:b2e1a2660ec2 705 *
rgrover1 710:b2e1a2660ec2 706 * @Note: The scan interval and window are recommendations to the BLE stack.
rgrover1 710:b2e1a2660ec2 707 */
rgrover1 710:b2e1a2660ec2 708 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
rgrover1 710:b2e1a2660ec2 709 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
rgrover1 710:b2e1a2660ec2 710 uint16_t timeout = 0,
rgrover1 710:b2e1a2660ec2 711 bool activeScanning = false) {
rgrover1 710:b2e1a2660ec2 712 ble_error_t rc;
rgrover1 710:b2e1a2660ec2 713 if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
rgrover1 710:b2e1a2660ec2 714 ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
rgrover1 710:b2e1a2660ec2 715 ((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
rgrover1 710:b2e1a2660ec2 716 _scanningParams.setActiveScanning(activeScanning);
rgrover1 710:b2e1a2660ec2 717 return BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 718 }
rgrover1 710:b2e1a2660ec2 719
rgrover1 710:b2e1a2660ec2 720 return rc;
rgrover1 710:b2e1a2660ec2 721 }
rgrover1 710:b2e1a2660ec2 722
rgrover1 710:b2e1a2660ec2 723 /**
vcoubard 1048:efb29faf12fc 724 * Set up the scanInterval parameter for GAP scanning (observer mode).
rgrover1 710:b2e1a2660ec2 725 * @param[in] interval
rgrover1 710:b2e1a2660ec2 726 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 710:b2e1a2660ec2 727 *
rgrover1 710:b2e1a2660ec2 728 * The scanning window divided by the interval determines the duty cycle for
rgrover1 710:b2e1a2660ec2 729 * scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1 710:b2e1a2660ec2 730 * then the controller will scan for 10 percent of the time. It is possible
rgrover1 710:b2e1a2660ec2 731 * to have the interval and window set to the same value. In this case,
rgrover1 710:b2e1a2660ec2 732 * scanning is continuous, with a change of scanning frequency once every
rgrover1 710:b2e1a2660ec2 733 * interval.
rgrover1 710:b2e1a2660ec2 734 *
rgrover1 710:b2e1a2660ec2 735 * Once the scanning parameters have been configured, scanning can be
rgrover1 710:b2e1a2660ec2 736 * enabled by using startScan().
rgrover1 710:b2e1a2660ec2 737 */
rgrover1 710:b2e1a2660ec2 738 ble_error_t setScanInterval(uint16_t interval) {
rgrover1 710:b2e1a2660ec2 739 return _scanningParams.setInterval(interval);
rgrover1 710:b2e1a2660ec2 740 }
rgrover1 710:b2e1a2660ec2 741
rgrover1 710:b2e1a2660ec2 742 /**
vcoubard 1048:efb29faf12fc 743 * Set up the scanWindow parameter for GAP scanning (observer mode).
rgrover1 710:b2e1a2660ec2 744 * @param[in] window
rgrover1 710:b2e1a2660ec2 745 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1 710:b2e1a2660ec2 746 *
rgrover1 710:b2e1a2660ec2 747 * The scanning window divided by the interval determines the duty cycle for
rgrover1 710:b2e1a2660ec2 748 * scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1 710:b2e1a2660ec2 749 * then the controller will scan for 10 percent of the time. It is possible
rgrover1 710:b2e1a2660ec2 750 * to have the interval and window set to the same value. In this case,
rgrover1 710:b2e1a2660ec2 751 * scanning is continuous, with a change of scanning frequency once every
rgrover1 710:b2e1a2660ec2 752 * interval.
rgrover1 710:b2e1a2660ec2 753 *
rgrover1 710:b2e1a2660ec2 754 * Once the scanning parameters have been configured, scanning can be
rgrover1 710:b2e1a2660ec2 755 * enabled by using startScan().
rgrover1 770:079b714e9c1a 756 *
rgrover1 770:079b714e9c1a 757 * If scanning is already active, the updated value of scanWindow will be
rgrover1 770:079b714e9c1a 758 * propagated to the underlying BLE stack.
rgrover1 710:b2e1a2660ec2 759 */
rgrover1 710:b2e1a2660ec2 760 ble_error_t setScanWindow(uint16_t window) {
rgrover1 770:079b714e9c1a 761 ble_error_t rc;
rgrover1 770:079b714e9c1a 762 if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
rgrover1 770:079b714e9c1a 763 return rc;
rgrover1 770:079b714e9c1a 764 }
rgrover1 770:079b714e9c1a 765
rgrover1 770:079b714e9c1a 766 /* If scanning is already active, propagate the new setting to the stack. */
rgrover1 770:079b714e9c1a 767 if (scanningActive) {
rgrover1 770:079b714e9c1a 768 return startRadioScan(_scanningParams);
rgrover1 770:079b714e9c1a 769 }
rgrover1 770:079b714e9c1a 770
rgrover1 770:079b714e9c1a 771 return BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 772 }
rgrover1 710:b2e1a2660ec2 773
rgrover1 710:b2e1a2660ec2 774 /**
vcoubard 1048:efb29faf12fc 775 * Set up parameters for GAP scanning (observer mode).
rgrover1 710:b2e1a2660ec2 776 * @param[in] timeout
vcoubard 1048:efb29faf12fc 777 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
rgrover1 710:b2e1a2660ec2 778 *
rgrover1 710:b2e1a2660ec2 779 * Once the scanning parameters have been configured, scanning can be
rgrover1 710:b2e1a2660ec2 780 * enabled by using startScan().
rgrover1 770:079b714e9c1a 781 *
rgrover1 770:079b714e9c1a 782 * If scanning is already active, the updated value of scanTimeout will be
rgrover1 770:079b714e9c1a 783 * propagated to the underlying BLE stack.
rgrover1 710:b2e1a2660ec2 784 */
rgrover1 710:b2e1a2660ec2 785 ble_error_t setScanTimeout(uint16_t timeout) {
rgrover1 770:079b714e9c1a 786 ble_error_t rc;
rgrover1 770:079b714e9c1a 787 if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
rgrover1 770:079b714e9c1a 788 return rc;
rgrover1 770:079b714e9c1a 789 }
rgrover1 770:079b714e9c1a 790
rgrover1 770:079b714e9c1a 791 /* If scanning is already active, propagate the new settings to the stack. */
rgrover1 770:079b714e9c1a 792 if (scanningActive) {
rgrover1 770:079b714e9c1a 793 return startRadioScan(_scanningParams);
rgrover1 770:079b714e9c1a 794 }
rgrover1 770:079b714e9c1a 795
rgrover1 770:079b714e9c1a 796 return BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 797 }
rgrover1 710:b2e1a2660ec2 798
rgrover1 710:b2e1a2660ec2 799 /**
vcoubard 1048:efb29faf12fc 800 * Set up parameters for GAP scanning (observer mode).
rgrover1 710:b2e1a2660ec2 801 * @param[in] activeScanning
rgrover1 710:b2e1a2660ec2 802 * Set to True if active-scanning is required. This is used to fetch the
rgrover1 710:b2e1a2660ec2 803 * scan response from a peer if possible.
rgrover1 710:b2e1a2660ec2 804 *
rgrover1 710:b2e1a2660ec2 805 * Once the scanning parameters have been configured, scanning can be
rgrover1 710:b2e1a2660ec2 806 * enabled by using startScan().
rgrover1 770:079b714e9c1a 807 *
rgrover1 770:079b714e9c1a 808 * If scanning is already in progress, then active-scanning will be enabled
rgrover1 770:079b714e9c1a 809 * for the underlying BLE stack.
rgrover1 710:b2e1a2660ec2 810 */
rgrover1 770:079b714e9c1a 811 ble_error_t setActiveScanning(bool activeScanning) {
rgrover1 710:b2e1a2660ec2 812 _scanningParams.setActiveScanning(activeScanning);
rgrover1 770:079b714e9c1a 813
rgrover1 770:079b714e9c1a 814 /* If scanning is already active, propagate the new settings to the stack. */
rgrover1 770:079b714e9c1a 815 if (scanningActive) {
rgrover1 770:079b714e9c1a 816 return startRadioScan(_scanningParams);
rgrover1 770:079b714e9c1a 817 }
rgrover1 770:079b714e9c1a 818
rgrover1 770:079b714e9c1a 819 return BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 820 }
rgrover1 710:b2e1a2660ec2 821
rgrover1 710:b2e1a2660ec2 822 /**
rgrover1 710:b2e1a2660ec2 823 * Start scanning (Observer Procedure) based on the parameters currently in
rgrover1 710:b2e1a2660ec2 824 * effect.
rgrover1 710:b2e1a2660ec2 825 *
rgrover1 710:b2e1a2660ec2 826 * @param[in] callback
vcoubard 1048:efb29faf12fc 827 * The application-specific callback to be invoked upon
rgrover1 710:b2e1a2660ec2 828 * receiving every advertisement report. This can be passed in
rgrover1 710:b2e1a2660ec2 829 * as NULL, in which case scanning may not be enabled at all.
rgrover1 710:b2e1a2660ec2 830 */
rgrover1 710:b2e1a2660ec2 831 ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
rgrover1 710:b2e1a2660ec2 832 ble_error_t err = BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 833 if (callback) {
rgrover1 710:b2e1a2660ec2 834 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
rgrover1 770:079b714e9c1a 835 scanningActive = true;
rgrover1 710:b2e1a2660ec2 836 onAdvertisementReport.attach(callback);
rgrover1 710:b2e1a2660ec2 837 }
rgrover1 710:b2e1a2660ec2 838 }
rgrover1 710:b2e1a2660ec2 839
rgrover1 710:b2e1a2660ec2 840 return err;
rgrover1 710:b2e1a2660ec2 841 }
rgrover1 710:b2e1a2660ec2 842
rgrover1 710:b2e1a2660ec2 843 /**
rgrover1 710:b2e1a2660ec2 844 * Same as above, but this takes an (object, method) pair for a callback.
rgrover1 710:b2e1a2660ec2 845 */
rgrover1 710:b2e1a2660ec2 846 template<typename T>
rgrover1 710:b2e1a2660ec2 847 ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
rgrover1 710:b2e1a2660ec2 848 ble_error_t err = BLE_ERROR_NONE;
rgrover1 710:b2e1a2660ec2 849 if (object && callbackMember) {
rgrover1 710:b2e1a2660ec2 850 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
rgrover1 770:079b714e9c1a 851 scanningActive = true;
rgrover1 710:b2e1a2660ec2 852 onAdvertisementReport.attach(object, callbackMember);
rgrover1 710:b2e1a2660ec2 853 }
rgrover1 710:b2e1a2660ec2 854 }
rgrover1 710:b2e1a2660ec2 855
rgrover1 710:b2e1a2660ec2 856 return err;
rgrover1 710:b2e1a2660ec2 857 }
rgrover1 710:b2e1a2660ec2 858
rgrover1 753:0f60274cd3ad 859 /**
rgrover1 753:0f60274cd3ad 860 * Initialize radio-notification events to be generated from the stack.
vcoubard 1048:efb29faf12fc 861 * This API doesn't need to be called directly.
rgrover1 753:0f60274cd3ad 862 *
rgrover1 753:0f60274cd3ad 863 * Radio Notification is a feature that enables ACTIVE and INACTIVE
rgrover1 753:0f60274cd3ad 864 * (nACTIVE) signals from the stack that notify the application when the
rgrover1 753:0f60274cd3ad 865 * radio is in use.
rgrover1 753:0f60274cd3ad 866 *
vcoubard 1048:efb29faf12fc 867 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1048:efb29faf12fc 868 * signal is sent at the end of the radio event. These signals can be used
rgrover1 753:0f60274cd3ad 869 * by the application programmer to synchronize application logic with radio
rgrover1 753:0f60274cd3ad 870 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1048:efb29faf12fc 871 * devices, to manage peak current drawn during periods when the radio is on,
rgrover1 753:0f60274cd3ad 872 * or to trigger sensor data collection for transmission in the Radio Event.
rgrover1 753:0f60274cd3ad 873 *
rgrover1 753:0f60274cd3ad 874 * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
rgrover1 753:0f60274cd3ad 875 */
rgrover1 753:0f60274cd3ad 876 virtual ble_error_t initRadioNotification(void) {
rgrover1 753:0f60274cd3ad 877 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
rgrover1 753:0f60274cd3ad 878 }
rgrover1 753:0f60274cd3ad 879
rgrover1 710:b2e1a2660ec2 880 private:
rgrover1 710:b2e1a2660ec2 881 ble_error_t setAdvertisingData(void) {
rgrover1 710:b2e1a2660ec2 882 return setAdvertisingData(_advPayload, _scanResponse);
rgrover1 710:b2e1a2660ec2 883 }
rgrover1 710:b2e1a2660ec2 884
rgrover1 710:b2e1a2660ec2 885 private:
rgrover1 896:791741895cd8 886 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
rgrover1 896:791741895cd8 887 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
rgrover1 710:b2e1a2660ec2 888
rgrover1 710:b2e1a2660ec2 889 public:
rgrover1 710:b2e1a2660ec2 890 /**
rgrover1 710:b2e1a2660ec2 891 * Accessors to read back currently active advertising params.
rgrover1 710:b2e1a2660ec2 892 */
rgrover1 710:b2e1a2660ec2 893 GapAdvertisingParams &getAdvertisingParams(void) {
rgrover1 710:b2e1a2660ec2 894 return _advParams;
rgrover1 710:b2e1a2660ec2 895 }
rgrover1 710:b2e1a2660ec2 896 const GapAdvertisingParams &getAdvertisingParams(void) const {
rgrover1 710:b2e1a2660ec2 897 return _advParams;
rgrover1 710:b2e1a2660ec2 898 }
rgrover1 710:b2e1a2660ec2 899
rgrover1 710:b2e1a2660ec2 900 /**
vcoubard 1048:efb29faf12fc 901 * Set up a particular, user-constructed set of advertisement parameters for
rgrover1 710:b2e1a2660ec2 902 * the underlying stack. It would be uncommon for this API to be used
rgrover1 710:b2e1a2660ec2 903 * directly; there are other APIs to tweak advertisement parameters
rgrover1 710:b2e1a2660ec2 904 * individually.
rgrover1 710:b2e1a2660ec2 905 */
rgrover1 710:b2e1a2660ec2 906 void setAdvertisingParams(const GapAdvertisingParams &newParams) {
rgrover1 710:b2e1a2660ec2 907 _advParams = newParams;
rgrover1 710:b2e1a2660ec2 908 }
rgrover1 710:b2e1a2660ec2 909
rgrover1 710:b2e1a2660ec2 910 /* Event callback handlers. */
rgrover1 710:b2e1a2660ec2 911 public:
rgrover1 710:b2e1a2660ec2 912 /**
vcoubard 1048:efb29faf12fc 913 * Set up a callback for timeout events. Refer to TimeoutSource_t for
rgrover1 710:b2e1a2660ec2 914 * possible event types.
vcoubard 1052:b55e1ad3e1b3 915 * @note It is possible to unregister callbacks using onTimeout().detach(callback)
rgrover1 710:b2e1a2660ec2 916 */
vcoubard 1052:b55e1ad3e1b3 917 void onTimeout(TimeoutEventCallback_t callback) {
vcoubard 1052:b55e1ad3e1b3 918 timeoutCallbackChain.add(callback);
vcoubard 1052:b55e1ad3e1b3 919 }
vcoubard 1052:b55e1ad3e1b3 920
vcoubard 1052:b55e1ad3e1b3 921 /**
vcoubard 1052:b55e1ad3e1b3 922 * @brief provide access to the callchain of timeout event callbacks
vcoubard 1052:b55e1ad3e1b3 923 * It is possible to register callbacks using onTimeout().add(callback);
vcoubard 1054:f59e5d9a992a 924 * It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1052:b55e1ad3e1b3 925 * @return The timeout event callbacks chain
vcoubard 1052:b55e1ad3e1b3 926 */
vcoubard 1052:b55e1ad3e1b3 927 TimeoutEventCallbackChain_t& onTimeout() {
vcoubard 1052:b55e1ad3e1b3 928 return timeoutCallbackChain;
vcoubard 1052:b55e1ad3e1b3 929 }
rgrover1 710:b2e1a2660ec2 930
rgrover1 710:b2e1a2660ec2 931 /**
rgrover1 829:9072de50087b 932 * Append to a chain of callbacks to be invoked upon GAP connection.
vcoubard 1052:b55e1ad3e1b3 933 * @note It is possible to unregister callbacks using onConnection().detach(callback)
rgrover1 710:b2e1a2660ec2 934 */
rgrover1 829:9072de50087b 935 void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
rgrover1 710:b2e1a2660ec2 936
rgrover1 829:9072de50087b 937 template<typename T>
rgrover1 829:9072de50087b 938 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
rgrover1 710:b2e1a2660ec2 939
rgrover1 710:b2e1a2660ec2 940 /**
vcoubard 1052:b55e1ad3e1b3 941 * @brief provide access to the callchain of connection event callbacks
vcoubard 1052:b55e1ad3e1b3 942 * It is possible to register callbacks using onConnection().add(callback);
vcoubard 1054:f59e5d9a992a 943 * It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1052:b55e1ad3e1b3 944 * @return The connection event callbacks chain
vcoubard 1052:b55e1ad3e1b3 945 */
vcoubard 1054:f59e5d9a992a 946 ConnectionEventCallbackChain_t& onConnection() {
vcoubard 1052:b55e1ad3e1b3 947 return connectionCallChain;
vcoubard 1052:b55e1ad3e1b3 948 }
vcoubard 1052:b55e1ad3e1b3 949
vcoubard 1052:b55e1ad3e1b3 950 /**
rgrover1 829:9072de50087b 951 * Append to a chain of callbacks to be invoked upon GAP disconnection.
vcoubard 1052:b55e1ad3e1b3 952 * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
rgrover1 816:2b4f0ef8c06e 953 */
rgrover1 829:9072de50087b 954 void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
rgrover1 816:2b4f0ef8c06e 955
rgrover1 710:b2e1a2660ec2 956 template<typename T>
rgrover1 829:9072de50087b 957 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
rgrover1 710:b2e1a2660ec2 958
rgrover1 710:b2e1a2660ec2 959 /**
vcoubard 1052:b55e1ad3e1b3 960 * @brief provide access to the callchain of disconnection event callbacks
vcoubard 1052:b55e1ad3e1b3 961 * It is possible to register callbacks using onDisconnection().add(callback);
vcoubard 1054:f59e5d9a992a 962 * It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1052:b55e1ad3e1b3 963 * @return The disconnection event callbacks chain
vcoubard 1052:b55e1ad3e1b3 964 */
vcoubard 1052:b55e1ad3e1b3 965 DisconnectionEventCallbackChain_t& onDisconnection() {
vcoubard 1052:b55e1ad3e1b3 966 return disconnectionCallChain;
vcoubard 1052:b55e1ad3e1b3 967 }
vcoubard 1052:b55e1ad3e1b3 968
vcoubard 1052:b55e1ad3e1b3 969 /**
rgrover1 710:b2e1a2660ec2 970 * Set the application callback for radio-notification events.
rgrover1 710:b2e1a2660ec2 971 *
rgrover1 710:b2e1a2660ec2 972 * Radio Notification is a feature that enables ACTIVE and INACTIVE
rgrover1 710:b2e1a2660ec2 973 * (nACTIVE) signals from the stack that notify the application when the
rgrover1 753:0f60274cd3ad 974 * radio is in use.
rgrover1 710:b2e1a2660ec2 975 *
vcoubard 1048:efb29faf12fc 976 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1048:efb29faf12fc 977 * signal is sent at the end of the radio event. These signals can be used
rgrover1 710:b2e1a2660ec2 978 * by the application programmer to synchronize application logic with radio
rgrover1 710:b2e1a2660ec2 979 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1048:efb29faf12fc 980 * devices, to manage peak current drawn during periods when the radio is on,
rgrover1 710:b2e1a2660ec2 981 * or to trigger sensor data collection for transmission in the Radio Event.
rgrover1 710:b2e1a2660ec2 982 *
rgrover1 710:b2e1a2660ec2 983 * @param callback
rgrover1 710:b2e1a2660ec2 984 * The application handler to be invoked in response to a radio
rgrover1 710:b2e1a2660ec2 985 * ACTIVE/INACTIVE event.
rgrover1 754:9b391fb5c5d7 986 *
vcoubard 1048:efb29faf12fc 987 * Or in the other version:
rgrover1 754:9b391fb5c5d7 988 *
rgrover1 754:9b391fb5c5d7 989 * @param tptr
rgrover1 754:9b391fb5c5d7 990 * Pointer to the object of a class defining the member callback
rgrover1 754:9b391fb5c5d7 991 * function (mptr).
rgrover1 754:9b391fb5c5d7 992 * @param mptr
rgrover1 754:9b391fb5c5d7 993 * The member callback (within the context of an object) to be
rgrover1 754:9b391fb5c5d7 994 * invoked in response to a radio ACTIVE/INACTIVE event.
rgrover1 710:b2e1a2660ec2 995 */
rgrover1 753:0f60274cd3ad 996 void onRadioNotification(void (*callback)(bool param)) {
rgrover1 753:0f60274cd3ad 997 radioNotificationCallback.attach(callback);
rgrover1 753:0f60274cd3ad 998 }
rgrover1 753:0f60274cd3ad 999 template <typename T>
rgrover1 753:0f60274cd3ad 1000 void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
rgrover1 753:0f60274cd3ad 1001 radioNotificationCallback.attach(tptr, mptr);
rgrover1 753:0f60274cd3ad 1002 }
rgrover1 710:b2e1a2660ec2 1003
vcoubard 1082:127667021827 1004 public:
vcoubard 1082:127667021827 1005 /**
vcoubard 1082:127667021827 1006 * Clear all Gap state of the associated object.
vcoubard 1082:127667021827 1007 *
vcoubard 1082:127667021827 1008 * This function is meant to be overridden in the platform-specific
vcoubard 1082:127667021827 1009 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1082:127667021827 1010 * state and not the data held in Gap members. This shall be achieved by a
vcoubard 1082:127667021827 1011 * call to Gap::reset() from the sub-class' reset() implementation.
vcoubard 1082:127667021827 1012 *
vcoubard 1082:127667021827 1013 * @return BLE_ERROR_NONE on success.
vcoubard 1082:127667021827 1014 *
vcoubard 1082:127667021827 1015 * @note: Currently a call to reset() does not reset the advertising and
vcoubard 1082:127667021827 1016 * scan parameters to default values.
vcoubard 1082:127667021827 1017 */
vcoubard 1082:127667021827 1018 virtual ble_error_t reset(void) {
vcoubard 1082:127667021827 1019 /* Clear Gap state */
vcoubard 1082:127667021827 1020 state.advertising = 0;
vcoubard 1084:40c1e518d6de 1021 state.connected = 0;
vcoubard 1082:127667021827 1022
vcoubard 1082:127667021827 1023 /* Clear scanning state */
vcoubard 1082:127667021827 1024 scanningActive = false;
vcoubard 1082:127667021827 1025
vcoubard 1082:127667021827 1026 /* Clear advertising and scanning data */
vcoubard 1082:127667021827 1027 _advPayload.clear();
vcoubard 1082:127667021827 1028 _scanResponse.clear();
vcoubard 1082:127667021827 1029
vcoubard 1082:127667021827 1030 /* Clear callbacks */
vcoubard 1082:127667021827 1031 timeoutCallbackChain.clear();
vcoubard 1082:127667021827 1032 connectionCallChain.clear();
vcoubard 1082:127667021827 1033 disconnectionCallChain.clear();
vcoubard 1082:127667021827 1034 radioNotificationCallback = NULL;
vcoubard 1084:40c1e518d6de 1035 onAdvertisementReport = NULL;
vcoubard 1082:127667021827 1036
vcoubard 1082:127667021827 1037 return BLE_ERROR_NONE;
vcoubard 1082:127667021827 1038 }
vcoubard 1082:127667021827 1039
rgrover1 710:b2e1a2660ec2 1040 protected:
rgrover1 710:b2e1a2660ec2 1041 Gap() :
rgrover1 710:b2e1a2660ec2 1042 _advParams(),
rgrover1 710:b2e1a2660ec2 1043 _advPayload(),
rgrover1 710:b2e1a2660ec2 1044 _scanningParams(),
rgrover1 710:b2e1a2660ec2 1045 _scanResponse(),
rgrover1 710:b2e1a2660ec2 1046 state(),
rgrover1 770:079b714e9c1a 1047 scanningActive(false),
vcoubard 1052:b55e1ad3e1b3 1048 timeoutCallbackChain(),
rgrover1 710:b2e1a2660ec2 1049 radioNotificationCallback(),
rgrover1 710:b2e1a2660ec2 1050 onAdvertisementReport(),
rgrover1 816:2b4f0ef8c06e 1051 connectionCallChain(),
rgrover1 710:b2e1a2660ec2 1052 disconnectionCallChain() {
rgrover1 710:b2e1a2660ec2 1053 _advPayload.clear();
rgrover1 710:b2e1a2660ec2 1054 _scanResponse.clear();
rgrover1 710:b2e1a2660ec2 1055 }
rgrover1 710:b2e1a2660ec2 1056
rgrover1 710:b2e1a2660ec2 1057 /* Entry points for the underlying stack to report events back to the user. */
rgrover1 710:b2e1a2660ec2 1058 public:
vcoubard 1079:6e2d9514f3df 1059 void processConnectionEvent(Handle_t handle,
vcoubard 1079:6e2d9514f3df 1060 Role_t role,
vcoubard 1079:6e2d9514f3df 1061 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1079:6e2d9514f3df 1062 const BLEProtocol::Address_t peerAddr,
vcoubard 1079:6e2d9514f3df 1063 BLEProtocol::AddressType_t ownAddrType,
vcoubard 1079:6e2d9514f3df 1064 const BLEProtocol::Address_t ownAddr,
vcoubard 1079:6e2d9514f3df 1065 const ConnectionParams_t *connectionParams) {
rgrover1 710:b2e1a2660ec2 1066 state.connected = 1;
rgrover1 829:9072de50087b 1067 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
rgrover1 829:9072de50087b 1068 connectionCallChain.call(&callbackParams);
rgrover1 710:b2e1a2660ec2 1069 }
rgrover1 710:b2e1a2660ec2 1070
rgrover1 710:b2e1a2660ec2 1071 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
rgrover1 710:b2e1a2660ec2 1072 state.connected = 0;
rgrover1 829:9072de50087b 1073 DisconnectionCallbackParams_t callbackParams(handle, reason);
rgrover1 829:9072de50087b 1074 disconnectionCallChain.call(&callbackParams);
rgrover1 710:b2e1a2660ec2 1075 }
rgrover1 710:b2e1a2660ec2 1076
vcoubard 1079:6e2d9514f3df 1077 void processAdvertisementReport(const BLEProtocol::Address_t peerAddr,
vcoubard 1079:6e2d9514f3df 1078 int8_t rssi,
vcoubard 1079:6e2d9514f3df 1079 bool isScanResponse,
rgrover1 710:b2e1a2660ec2 1080 GapAdvertisingParams::AdvertisingType_t type,
vcoubard 1079:6e2d9514f3df 1081 uint8_t advertisingDataLen,
vcoubard 1079:6e2d9514f3df 1082 const uint8_t *advertisingData) {
rgrover1 710:b2e1a2660ec2 1083 AdvertisementCallbackParams_t params;
rgrover1 710:b2e1a2660ec2 1084 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
rgrover1 710:b2e1a2660ec2 1085 params.rssi = rssi;
rgrover1 710:b2e1a2660ec2 1086 params.isScanResponse = isScanResponse;
rgrover1 710:b2e1a2660ec2 1087 params.type = type;
rgrover1 710:b2e1a2660ec2 1088 params.advertisingDataLen = advertisingDataLen;
rgrover1 710:b2e1a2660ec2 1089 params.advertisingData = advertisingData;
rgrover1 710:b2e1a2660ec2 1090 onAdvertisementReport.call(&params);
rgrover1 710:b2e1a2660ec2 1091 }
rgrover1 710:b2e1a2660ec2 1092
rgrover1 710:b2e1a2660ec2 1093 void processTimeoutEvent(TimeoutSource_t source) {
vcoubard 1052:b55e1ad3e1b3 1094 if (timeoutCallbackChain) {
vcoubard 1052:b55e1ad3e1b3 1095 timeoutCallbackChain(source);
rgrover1 710:b2e1a2660ec2 1096 }
rgrover1 710:b2e1a2660ec2 1097 }
rgrover1 710:b2e1a2660ec2 1098
rgrover1 710:b2e1a2660ec2 1099 protected:
rgrover1 710:b2e1a2660ec2 1100 GapAdvertisingParams _advParams;
rgrover1 710:b2e1a2660ec2 1101 GapAdvertisingData _advPayload;
rgrover1 710:b2e1a2660ec2 1102 GapScanningParams _scanningParams;
rgrover1 710:b2e1a2660ec2 1103 GapAdvertisingData _scanResponse;
rgrover1 710:b2e1a2660ec2 1104
rgrover1 710:b2e1a2660ec2 1105 GapState_t state;
rgrover1 770:079b714e9c1a 1106 bool scanningActive;
rgrover1 710:b2e1a2660ec2 1107
rgrover1 710:b2e1a2660ec2 1108 protected:
vcoubard 1052:b55e1ad3e1b3 1109 TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard 1052:b55e1ad3e1b3 1110 RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard 1052:b55e1ad3e1b3 1111 AdvertisementReportCallback_t onAdvertisementReport;
vcoubard 1052:b55e1ad3e1b3 1112 ConnectionEventCallbackChain_t connectionCallChain;
vcoubard 1052:b55e1ad3e1b3 1113 DisconnectionEventCallbackChain_t disconnectionCallChain;
rgrover1 710:b2e1a2660ec2 1114
rgrover1 710:b2e1a2660ec2 1115 private:
vcoubard 1048:efb29faf12fc 1116 /* Disallow copy and assignment. */
rgrover1 710:b2e1a2660ec2 1117 Gap(const Gap &);
rgrover1 710:b2e1a2660ec2 1118 Gap& operator=(const Gap &);
rgrover1 710:b2e1a2660ec2 1119 };
rgrover1 710:b2e1a2660ec2 1120
rgrover1 710:b2e1a2660ec2 1121 #endif // ifndef __GAP_H__