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@766:03f1a26f132f, 2015-08-07 (annotated)

Committer:
rgrover1
Date:
Fri Aug 07 15:53:50 2015 +0100
Revision:
766:03f1a26f132f
Parent:
765:4cd91998cd48
Child:
767:d6a79c77d1c3
Synchronized with git rev 0f2ba674

Author: Joshua Slater

Conversion from advertisement duration units to ms moved from Gap to GapAdvertisingParams. getInterval converts to ms. Added conversion in GapScanningParams

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