Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
Gap Class Reference
Ble » Gap

Define device discovery, connection and link management procedures. More...

#include <Gap.h>

Inheritance diagram for Gap:
Gap

Data Structures

struct  AdvertisementCallbackParams_t
 Representation of a scanned advertising packet. More...
 
struct  ConnectionCallbackParams_t
 Connection events. More...
 
struct  ConnectionParams_t
 Parameters of a BLE connection. More...
 
struct  DisconnectionCallbackParams_t
 Disconnection event. More...
 
struct  GapState_t
 Description of the states of the device. More...
 
struct  Whitelist_t
 Representation of a whitelist of addresses. More...
 

Public Types

typedef BLEProtocol::AddressType_t AddressType_t
 Address-type for BLEProtocol addresses. More...
 
typedef BLEProtocol::AddressType_t addr_type_t
 Address-type for BLEProtocol addresses. More...
 
typedef BLEProtocol::AddressBytes_t Address_t
 48-bit address, LSB format. More...
 
typedef BLEProtocol::AddressBytes_t address_t
 48-bit address, LSB format. More...
 
typedef ble::connection_handle_t Handle_t
 Opaque value type representing a connection handle. More...
 
typedef ble::random_address_type_t RandomAddressType_t
 Enumeration of random address types. More...
 
typedef ble::peer_address_type_t PeerAddressType_t
 Enumeration of peer address types. More...
 
typedef ble::phy_t Phy_t
 Enumeration of BLE PHY. More...
 
typedef ble::phy_set_t PhySet_t
 Set of BLE PHYs. More...
 
typedef ble::coded_symbol_per_bit_t CodedSymbolPerBit_t
 Enumeration of type of symbols that can be used with LE coded PHY. More...
 
typedef FunctionPointerWithContext< const AdvertisementCallbackParams_t * > AdvertisementReportCallback_t
 Type of the callback handling scanned advertisement packets. More...
 
typedef ble::peripheral_privacy_configuration_t PeripheralPrivacyConfiguration_t
 Privacy Configuration of the peripheral role. More...
 
typedef ble::central_privay_configuration_t CentralPrivacyConfiguration_t
 Privacy configuration of the central role. More...
 
typedef FunctionPointerWithContext< TimeoutSource_tTimeoutEventCallback_t
 Timeout event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< TimeoutSource_tTimeoutEventCallbackChain_t
 Callchain of timeout event handlers. More...
 
typedef FunctionPointerWithContext< const ConnectionCallbackParams_t * > ConnectionEventCallback_t
 Connection event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const ConnectionCallbackParams_t * > ConnectionEventCallbackChain_t
 Callchain of connection event handlers. More...
 
typedef FunctionPointerWithContext< const DisconnectionCallbackParams_t * > DisconnectionEventCallback_t
 Disconnection event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const DisconnectionCallbackParams_t * > DisconnectionEventCallbackChain_t
 Callchain of disconnection event handlers. More...
 
typedef FunctionPointerWithContext< bool > RadioNotificationEventCallback_t
 Radio notification event handler. More...
 
typedef FunctionPointerWithContext< const LegacyGap * > GapShutdownCallback_t
 Gap shutdown event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const LegacyGap * > GapShutdownCallbackChain_t
 Callchain of gap shutdown event handler. More...
 

Public Member Functions

ble_error_t setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
 Set the device MAC address and type. More...
 
ble_error_t getAddress (BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
 Fetch the current address and its type. More...
 
uint16_t getMinAdvertisingInterval (void) const
 Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types. More...
 
uint16_t getMinNonConnectableAdvertisingInterval (void) const
 Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type. More...
 
uint16_t getMaxAdvertisingInterval (void) const
 Get the maximum advertising interval in milliseconds. More...
 
ble_error_t stopAdvertising (void)
 Stop the ongoing advertising procedure. More...
 
ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, PeerAddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 Initiate a connection to a peer. More...
 
ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 Initiate a connection to a peer. More...
 
ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, DeprecatedAddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 Initiate a connection to a peer. More...
 
ble_error_t disconnect (Handle_t connectionHandle, DisconnectionReason_t reason)
 Initiate a disconnection procedure. More...
 
ble_error_t disconnect (DisconnectionReason_t reason)
 Initiate a disconnection procedure. More...
 
ble_error_t getPreferredConnectionParams (ConnectionParams_t *params)
 Returned the preferred connection parameters exposed in the GATT Generic Access Service. More...
 
ble_error_t setPreferredConnectionParams (const ConnectionParams_t *params)
 Set the value of the preferred connection parameters exposed in the GATT Generic Access Service. More...
 
ble_error_t updateConnectionParams (Handle_t handle, const ConnectionParams_t *params)
 Update connection parameters of an existing connection. More...
 
ble_error_t setDeviceName (const uint8_t *deviceName)
 Set the value of the device name characteristic in the Generic Access Service. More...
 
ble_error_t getDeviceName (uint8_t *deviceName, unsigned *lengthP)
 Get the value of the device name characteristic in the Generic Access Service. More...
 
ble_error_t setAppearance (GapAdvertisingData::Appearance appearance)
 Set the value of the appearance characteristic in the GAP service. More...
 
ble_error_t getAppearance (GapAdvertisingData::Appearance *appearanceP)
 Get the value of the appearance characteristic in the GAP service. More...
 
ble_error_t setTxPower (int8_t txPower)
 Set the radio's transmit power. More...
 
void getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP)
 Query the underlying stack for allowed Tx power values. More...
 
uint8_t getMaxWhitelistSize (void) const
 Get the maximum size of the whitelist. More...
 
ble_error_t getWhitelist (Whitelist_t &whitelist) const
 Get the Link Layer to use the internal whitelist when scanning, advertising or initiating a connection depending on the filter policies. More...
 
ble_error_t setWhitelist (const Whitelist_t &whitelist)
 Set the value of the whitelist to be used during GAP procedures. More...
 
ble_error_t setAdvertisingPolicyMode (AdvertisingPolicyMode_t mode)
 Set the advertising policy filter mode to be used during the next advertising procedure. More...
 
ble_error_t setScanningPolicyMode (ScanningPolicyMode_t mode)
 Set the scan policy filter mode to be used during the next scan procedure. More...
 
ble_error_t setInitiatorPolicyMode (InitiatorPolicyMode_t mode)
 Set the initiator policy filter mode to be used during the next connection initiation. More...
 
AdvertisingPolicyMode_t getAdvertisingPolicyMode (void) const
 Get the current advertising policy filter mode. More...
 
ScanningPolicyMode_t getScanningPolicyMode (void) const
 Get the current scan policy filter mode. More...
 
InitiatorPolicyMode_t getInitiatorPolicyMode (void) const
 Get the current initiator policy filter mode. More...
 
GapState_t getState (void) const
 Get the current advertising and connection states of the device. More...
 
void setAdvertisingType (GapAdvertisingParams::AdvertisingType_t advType)
 Set the advertising type to use during the advertising procedure. More...
 
void setAdvertisingInterval (uint16_t interval)
 Set the advertising interval. More...
 
void setAdvertisingTimeout (uint16_t timeout)
 Set the advertising duration. More...
 
ble_error_t startAdvertising (void)
 Start the advertising procedure. More...
 
void clearAdvertisingPayload (void)
 Reset the value of the advertising payload advertised. More...
 
ble_error_t accumulateAdvertisingPayload (uint8_t flags)
 Set gap flags in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::Appearance app)
 Set the appearance field in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayloadTxPower (int8_t power)
 Set the Tx Power field in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Add a new field in the advertising payload. More...
 
ble_error_t updateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Update a particular field in the advertising payload. More...
 
ble_error_t setAdvertisingPayload (const GapAdvertisingData &payload)
 Set the value of the payload advertised. More...
 
const GapAdvertisingDatagetAdvertisingPayload (void) const
 Get a reference to the current advertising payload. More...
 
ble_error_t accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Add a new field in the advertising payload. More...
 
void clearScanResponse (void)
 Reset the content of the scan response. More...
 
ble_error_t setScanParams (uint16_t interval=GapScanningParams::SCAN_INTERVAL_MAX, uint16_t window=GapScanningParams::SCAN_WINDOW_MAX, uint16_t timeout=0, bool activeScanning=false)
 Set the parameters used during a scan procedure. More...
 
ble_error_t setScanParams (const GapScanningParams &scanningParams)
 Set the parameters used during a scan procedure. More...
 
ble_error_t setScanInterval (uint16_t interval)
 Set the interval parameter used during scanning procedures. More...
 
ble_error_t setScanWindow (uint16_t window)
 Set the window parameter used during scanning procedures. More...
 
ble_error_t setScanTimeout (uint16_t timeout)
 Set the timeout parameter used during scanning procedures. More...
 
ble_error_t setActiveScanning (bool activeScanning)
 Enable or disable active scanning. More...
 
ble_error_t startScan (void(*callback)(const AdvertisementCallbackParams_t *params))
 Start the scanning procedure. More...
 
template<typename T >
ble_error_t startScan (T *object, void(T::*callbackMember)(const AdvertisementCallbackParams_t *params))
 Start the scanning procedure. More...
 
ble_error_t initRadioNotification (void)
 Enable radio-notification events. More...
 
GapAdvertisingParamsgetAdvertisingParams (void)
 Get the current advertising parameters. More...
 
const GapAdvertisingParamsgetAdvertisingParams (void) const
 Const alternative to Gap::getAdvertisingParams(). More...
 
void setAdvertisingParams (const GapAdvertisingParams &newParams)
 Set the advertising parameters. More...
 
void onTimeout (TimeoutEventCallback_t callback)
 Register a callback handling timeout events. More...
 
TimeoutEventCallbackChain_tonTimeout ()
 Get the callchain of registered timeout event handlers. More...
 
void onConnection (ConnectionEventCallback_t callback)
 Register a callback handling connection events. More...
 
template<typename T >
void onConnection (T *tptr, void(T::*mptr)(const ConnectionCallbackParams_t *))
 Register a callback handling connection events. More...
 
ConnectionEventCallbackChain_tonConnection ()
 Get the callchain of registered connection event handlers. More...
 
void onDisconnection (DisconnectionEventCallback_t callback)
 Register a callback handling disconnection events. More...
 
template<typename T >
void onDisconnection (T *tptr, void(T::*mptr)(const DisconnectionCallbackParams_t *))
 Register a callback handling disconnection events. More...
 
DisconnectionEventCallbackChain_tonDisconnection ()
 Get the callchain of registered disconnection event handlers. More...
 
void onRadioNotification (void(*callback)(bool param))
 Set the radio-notification events handler. More...
 
template<typename T >
void onRadioNotification (T *tptr, void(T::*mptr)(bool))
 Set the radio-notification events handler. More...
 
void onShutdown (const GapShutdownCallback_t &callback)
 Register a Gap shutdown event handler. More...
 
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const LegacyGap *))
 Register a Gap shutdown event handler. More...
 
GapShutdownCallbackChain_tonShutdown ()
 Access the callchain of shutdown event handler. More...
 
ble_error_t reset (void)
 Reset the Gap instance. More...
 
void processConnectionEvent (Handle_t handle, Role_t role, PeerAddressType_t peerAddrType, const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t ownAddrType, const BLEProtocol::AddressBytes_t ownAddr, const ConnectionParams_t *connectionParams, const uint8_t *peerResolvableAddr=NULL, const uint8_t *localResolvableAddr=NULL)
 Notify all registered connection event handlers of a connection event. More...
 
void processConnectionEvent (Handle_t handle, Role_t role, BLEProtocol::AddressType_t peerAddrType, const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t ownAddrType, const BLEProtocol::AddressBytes_t ownAddr, const ConnectionParams_t *connectionParams, const uint8_t *peerResolvableAddr=NULL, const uint8_t *localResolvableAddr=NULL)
 Notify all registered connection event handlers of a connection event. More...
 
void processDisconnectionEvent (Handle_t handle, DisconnectionReason_t reason)
 Notify all registered disconnection event handlers of a disconnection event. More...
 
void processAdvertisementReport (const BLEProtocol::AddressBytes_t peerAddr, int8_t rssi, bool isScanResponse, GapAdvertisingParams::AdvertisingType_t type, uint8_t advertisingDataLen, const uint8_t *advertisingData, PeerAddressType_t addressType)
 Forward a received advertising packet to all registered event handlers listening for scanned packet events. More...
 
void processAdvertisementReport (const BLEProtocol::AddressBytes_t peerAddr, int8_t rssi, bool isScanResponse, GapAdvertisingParams::AdvertisingType_t type, uint8_t advertisingDataLen, const uint8_t *advertisingData, BLEProtocol::AddressType_t addressType=BLEProtocol::AddressType::RANDOM_STATIC)
 Forward a received advertising packet to all registered event handlers listening for scanned packet events. More...
 
void processTimeoutEvent (TimeoutSource_t source)
 Notify the occurrence of a timeout event to all registered timeout events handler. More...
 
void setEventHandler (EventHandler *handler)
 Assign the event handler implementation that will be used by the gap module to signal events back to the application. More...
 
bool isFeatureSupported (controller_supported_features_t feature)
 Check controller support for a specific feature. More...
 
uint8_t getMaxAdvertisingSetNumber ()
 Return currently available number of supported advertising sets. More...
 
uint16_t getMaxAdvertisingDataLength ()
 Return maximum advertising data length supported. More...
 
uint16_t getMaxConnectableAdvertisingDataLength ()
 Return maximum advertising data length supported for connectable advertising. More...
 
uint16_t getMaxActiveSetAdvertisingDataLength ()
 Return maximum advertising data length you may set if advertising set is active. More...
 
ble_error_t createAdvertisingSet (advertising_handle_t *handle, const AdvertisingParameters &parameters)
 Create an advertising set and apply the passed in parameters. More...
 
ble_error_t destroyAdvertisingSet (advertising_handle_t handle)
 Remove the advertising set (resets its set parameters). More...
 
ble_error_t setAdvertisingParameters (advertising_handle_t handle, const AdvertisingParameters &params)
 Set advertising parameters of an existing set. More...
 
ble_error_t setAdvertisingPayload (advertising_handle_t handle, mbed::Span< const uint8_t > payload)
 Set new advertising payload for a given advertising set. More...
 
ble_error_t setAdvertisingScanResponse (advertising_handle_t handle, mbed::Span< const uint8_t > response)
 Set new advertising scan response for a given advertising set. More...
 
ble_error_t startAdvertising (advertising_handle_t handle, adv_duration_t maxDuration=adv_duration_t::forever(), uint8_t maxEvents=0)
 Start advertising using the given advertising set. More...
 
ble_error_t stopAdvertising (advertising_handle_t handle)
 Stop advertising given advertising set. More...
 
bool isAdvertisingActive (advertising_handle_t handle)
 Check if advertising is active for a given advertising set. More...
 
ble_error_t setPeriodicAdvertisingParameters (advertising_handle_t handle, periodic_interval_t periodicAdvertisingIntervalMin, periodic_interval_t periodicAdvertisingIntervalMax, bool advertiseTxPower=true)
 Set periodic advertising parameters for a given advertising set. More...
 
ble_error_t setPeriodicAdvertisingPayload (advertising_handle_t handle, mbed::Span< const uint8_t > payload)
 Set new periodic advertising payload for a given advertising set. More...
 
ble_error_t startPeriodicAdvertising (advertising_handle_t handle)
 Start periodic advertising for a given set. More...
 
ble_error_t stopPeriodicAdvertising (advertising_handle_t handle)
 Stop periodic advertising for a given set. More...
 
bool isPeriodicAdvertisingActive (advertising_handle_t handle)
 Check if periodic advertising is active for a given advertising set. More...
 
ble_error_t setScanParameters (const ScanParameters &params)
 Set new scan parameters. More...
 
ble_error_t startScan (scan_duration_t duration=scan_duration_t::forever(), duplicates_filter_t filtering=duplicates_filter_t::DISABLE, scan_period_t period=scan_period_t(0))
 Start scanning. More...
 
ble_error_t stopScan ()
 Stop the ongoing scanning procedure. More...
 
ble_error_t createSync (peer_address_type_t peerAddressType, const address_t &peerAddress, uint8_t sid, slave_latency_t maxPacketSkip, sync_timeout_t timeout)
 Synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. More...
 
ble_error_t createSync (slave_latency_t maxPacketSkip, sync_timeout_t timeout)
 Synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. More...
 
ble_error_t cancelCreateSync ()
 Cancel sync attempt. More...
 
ble_error_t terminateSync (periodic_sync_handle_t handle)
 Stop reception of the periodic advertising identified by the handle. More...
 
ble_error_t addDeviceToPeriodicAdvertiserList (peer_address_type_t peerAddressType, const address_t &peerAddress, advertising_sid_t sid)
 Add device to the periodic advertiser list. More...
 
ble_error_t removeDeviceFromPeriodicAdvertiserList (peer_address_type_t peerAddressType, const address_t &peerAddress, advertising_sid_t sid)
 Remove device from the periodic advertiser list. More...
 
ble_error_t clearPeriodicAdvertiserList ()
 Remove all devices from periodic advertiser list. More...
 
uint8_t getMaxPeriodicAdvertiserListSize ()
 Get number of devices that can be added to the periodic advertiser list. More...
 
ble_error_t connect (peer_address_type_t peerAddressType, const address_t &peerAddress, const ConnectionParameters &connectionParams)
 Initiate a connection to a peer. More...
 
ble_error_t cancelConnect ()
 Cancel the connection attempt. More...
 
ble_error_t readPhy (connection_handle_t connection)
 Read the PHY used by the transmitter and the receiver on a connection. More...
 
ble_error_t setPreferredPhys (const phy_set_t *txPhys, const phy_set_t *rxPhys)
 Set the preferred PHYs to use in a connection. More...
 
ble_error_t setPhy (connection_handle_t connection, const phy_set_t *txPhys, const phy_set_t *rxPhys, coded_symbol_per_bit_t codedSymbol)
 Update the PHY used by a connection. More...
 
ble_error_t enablePrivacy (bool enable)
 Enable or disable privacy mode of the local device. More...
 
ble_error_t setPeripheralPrivacyConfiguration (const peripheral_privacy_configuration_t *configuration)
 Set the privacy configuration used by the peripheral role. More...
 
ble_error_t getPeripheralPrivacyConfiguration (peripheral_privacy_configuration_t *configuration)
 Get the privacy configuration used by the peripheral role. More...
 
ble_error_t setCentralPrivacyConfiguration (const central_privay_configuration_t *configuration)
 Set the privacy configuration used by the central role. More...
 
ble_error_t getCentralPrivacyConfiguration (central_privay_configuration_t *configuration)
 Get the privacy configuration used by the central role. More...
 

Static Public Member Functions

static uint16_t MSEC_TO_GAP_DURATION_UNITS (uint32_t durationInMillis)
 Convert milliseconds into 1.25ms units. More...
 
static ble_error_t getRandomAddressType (const BLEProtocol::AddressBytes_t address, RandomAddressType_t *addressType)
 Return the type of a random address. More...
 

Static Public Attributes

static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN
 Length (in octets) of the BLE MAC address. More...
 
static const uint16_t UNIT_1_25_MS = 1250
 Number of microseconds in 1.25 milliseconds. More...
 
static const peripheral_privacy_configuration_t default_peripheral_privacy_configuration
 Default peripheral privacy configuration. More...
 
static const central_privay_configuration_t default_central_privacy_configuration
 Default peripheral privacy configuration. More...
 

Protected Member Functions

ble_error_t startRadioScan (const GapScanningParams &scanningParams)
 Start scanning procedure in the underlying BLE stack. More...
 
 LegacyGap ()
 Construct a Gap instance. More...
 

Protected Attributes

GapAdvertisingParams _advParams
 Current advertising parameters. More...
 
GapAdvertisingData _advPayload
 Current advertising data. More...
 
GapScanningParams _scanningParams
 Current scanning parameters. More...
 
GapAdvertisingData _scanResponse
 Current scan response. More...
 
uint8_t connectionCount
 Number of open connections. More...
 
GapState_t state
 Current GAP state. More...
 
bool scanningActive
 Active scanning flag. More...
 
TimeoutEventCallbackChain_t timeoutCallbackChain
 Callchain containing all registered callback handlers for timeout events. More...
 
RadioNotificationEventCallback_t radioNotificationCallback
 The registered callback handler for radio notification events. More...
 
AdvertisementReportCallback_t onAdvertisementReport
 The registered callback handler for scanned advertisement packet notifications. More...
 
ConnectionEventCallbackChain_t connectionCallChain
 Callchain containing all registered callback handlers for connection events. More...
 
DisconnectionEventCallbackChain_t disconnectionCallChain
 Callchain containing all registered callback handlers for disconnection events. More...
 

Detailed Description

Define device discovery, connection and link management procedures.

Accessing gap

Instance of a Gap class for a given BLE device should be accessed using BLE::gap(). The reference returned remains valid until the BLE instance shut down (see BLE::shutdown()).

// assuming ble_device has been initialized
BLE& ble_device;
ble::Gap& gap = ble_device.gap();
Advertising

Advertising consists of broadcasting at a regular interval a small amount of data containing valuable information about the device. These packets may be scanned by peer devices listening on BLE advertising channels.

Scanners may also request additional information from a device advertising by sending a scan request. If the broadcaster accepts scan requests, it can reply with a scan response packet containing additional information.

Advertising parameters are updated using setAdvertisingParams(). The main advertising payload is updated using setAdvertisingPayload(), and the scan response is updated using setAdvertisingScanResponse(). If the advertising is already updated, the data will take effect from the next advertising event.

To create a valid advertising payload and scan response, you may use AdvertisingDataBuilder. You must first allocate memory and create an mbed::Span and pass that into the AdvertisingDataBuilder, which will only be able to add as much data as fits in the provided buffer. The builder accepts any size of the buffer, but for the created data to be usable, it must be smaller than the maximum data length returned from getMaxAdvertisingDataLength().

Another option is to use AdvertisingDataSimpleBuilder, which allocates memory on the stack and offers a fluent interface at the expense of a reduced set of APIs and error management options.

Note
Prior to Bluetooth 5, advertising and scanning payload size were limited to LEGACY_ADVERTISING_MAX_SIZE. It changed with Bluetooth 5, and now the maximum size of data that can be advertised depends on the controller. If you wish to be compatible with older devices, you may wish to advertise with the LEGACY_ADVERTISING_HANDLE. This uses payloads no larger than LEGACY_ADVERTISING_MAX_SIZE with that advertising set.
Extended advertising

Extended advertising allows for a wider choice of options than legacy advertising. You can send bigger payloads and use different PHYs. This allows for bigger throughput or longer range.

Extended advertising may be split across many packets and takes place on both the regular advertising channels and the rest of the 37 channels normally used by connected devices.

The 3 channels used in legacy advertising are called primary advertisement channels. The remaining 37 channels are used for secondary advertising. Unlike sending data during a connection, this allows the device to broadcast data to multiple devices.

The advertising starts on the primary channels (which you may select) and continues on the secondary channels as indicated in the packet sent on the primary channel. This way, the advertising can send large payloads without saturating the advertising channels. Primary channels are limited to 1M and coded PHYs, but secondary channels may use the increased throughput 2M PHY.

Periodic advertising

Similarly, you can use periodic advertising to transfer regular data to multiple devices.

The advertiser uses primary channels to advertise the information needed to listen to the periodic advertisements on secondary channels. This sync information will be used by the scanner who can now optimize for power consumption and only listen for the periodic advertisements at specified times.

Like extended advertising, periodic advertising offers extra PHY options of 2M and coded. The payload may be updated at any time and will be updated on the next advertisement event when the periodic advertising is active.

Advertising sets

Advertisers may advertise multiple payloads at the same time. The configuration and identification of these is done through advertising sets. Use a handle obtained from createAvertisingSet() for advertising operations. After ending all advertising operations, remove the handle from the system using destroyAdvertisingHandle().

Extended advertising and periodic advertising is an optional feature, and not all devices support it. Some will only be able to see the now-called legacy advertising.

Legacy advertising is available through a special handle, LEGACY_ADVERTISING_HANDLE. This handle is always available, doesn't need to be created and can't be destroyed.

There is a limited number of advertising sets available because they require support from the controller. Their availability is dynamic and may be queried at any time using getMaxAdvertisingSetNumber(). Advertising sets take up resources even if they are not actively advertising right now, so it's important to destroy the set when you're done with it (or reuse it in the next advertisement).

Periodic advertising and extended advertising share the same set but not the same data. Extended advertising carries out periodic advertising synchronization information. Therefore, to let other devices be aware that your device exposes periodic advertising, you should start extended advertising of the set. Subsequently, you may disable extended advertising, and the periodic advertising will continue. If you start periodic advertising while extended advertising is inactive, periodic advertising won't start until you start extended advertising at a later time.

Privacy

Privacy is a feature that allows a device to avoid being tracked by other (untrusted) devices. The device achieves it by periodically generating a new random address. The random address may be a resolvable random address, enabling trusted devices to recognize it as belonging to the same device. These trusted devices receive an Identity Resolution Key (IRK) during pairing. This is handled by the SecurityManager and relies on the other device accepting and storing the IRK.

You need to enable privacy by calling enablePrivacy() after having initialized the SecurityManager because privacy requires SecurityManager to handle IRKs. The behavior of privacy enabled devices is set by using setCentralPrivacyConfiguration(), which specifies what the device should be with devices using random addresses. Random addresses generated by privacy enabled devices can be of two types: resolvable (by devices who have the IRK) and unresolvable. Unresolvable addresses can't be used for connecting and connectable advertising. Therefore, a resolvable one will be used for these regardless of the privacy configuration.

Scanning

Scanning consists of listening for peer advertising packets. From a scan, a device can identify devices available in its environment.

If the device scans actively, then it will send scan request to scannable advertisers and collect their scan responses.

Scanning is done by creating ScanParameters and applying them with setScanParameters(). One configured, you may call startScan().

When a scanning device receives an advertising packet, it will call onAdvertisingReport() in the registered event handler. A whitelist may be used to limit the advertising reports by setting the correct policy in the scan parameters.

Connection event handling

A peer may connect device advertising connectable packets. The advertising procedure ends as soon as the device is connected. If an advertising timeout has been set in the advertising parameters then onAdvertisingEnd will be called in the registered eventHandler when it runs out.

A device accepting a connection request from a peer is named a peripheral, and the device initiating the connection is named a central.

Connection is initiated by central devices. A call to connect() will result in the device scanning on any PHYs set in ConectionParamters passed in.

Peripheral and central receive a connection event when the connection is effective. If successful will result in a call to onConnectionComplete in the EventHandler registered with the Gap.

It the connection attempt fails it will result in onConnectionComplete called on the central device with the event carrying the error flag.

Changing the PHYsical transport of a connection

Once a connection has been established, it is possible to change the physical transport used between the local and the distant device. Changing the transport can either increase the bandwidth or increase the communication range. An increased bandwidth equals a better power consumption but also a loss in sensibility and therefore a degraded range.

Symmetrically an increased range means a lowered bandwidth and a degraded power consumption.

Applications can change the PHY used by calling the function setPhy. Once the update has been made the result is forwarded to the application by calling the function onPhyUpdateComplete of the event handler registered.

disconnection

The application code initiates a disconnection when it calls the disconnect(Handle_t, DisconnectionReason_t) function.

Disconnection may also be initiated by the remote peer or the local controller/stack. To catch all disconnection events, application code may set up an handler taking care of disconnection events by calling onDisconnection().

Modulation Schemes

When supported by the host and controller you can select different modulation schemes (

See also
BLUETOOTH SPECIFICATION Version 5.0 | Vol 1, Part A - 1.2):
  • LE 1M PHY
  • LE 2M PHY
  • LE coded PHY

You may set preferred PHYs (separately for RX and TX) using setPreferredPhys(). You may also set the currently used PHYs on a selected connection using setPhy(). Both of these settings are only advisory and the controller is allowed to make its own decision on the best PHY to use based on your request, the peer's supported features and the connection's physical conditions.

You may query the currently used PHY using readPhy() which will return the result through a call to the registered event handler. You may register the handler with setEventHandler(). The events inform about the currently used PHY and of any changes to PHYs which may be triggered autonomously by the controller or by the peer.

Definition at line 52 of file Gap.h.

Member Typedef Documentation

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead.

Definition at line 92 of file Gap.h.

48-bit address, LSB format.

Deprecated:
Use BLEProtocol::AddressBytes_t instead.

Definition at line 118 of file Gap.h.

48-bit address, LSB format.

Deprecated:
Use BLEProtocol::AddressBytes_t instead.

Definition at line 125 of file Gap.h.

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead.

Definition at line 85 of file Gap.h.

Type of the callback handling scanned advertisement packets.

See also
Gap::startScan().

Definition at line 485 of file Gap.h.

Privacy configuration of the central role.

Note
This configuration is also used when the local device operates as an observer.

Definition at line 686 of file Gap.h.

Enumeration of type of symbols that can be used with LE coded PHY.

Definition at line 334 of file Gap.h.

Connection event handler.

See also
Gap::onConnection().

Definition at line 729 of file Gap.h.

Callchain of connection event handlers.

See also
Gap::onConnection().

Definition at line 737 of file Gap.h.

Disconnection event handler.

See also
Gap::onDisconnection().

Definition at line 745 of file Gap.h.

Callchain of disconnection event handlers.

See also
Gap::onDisconnection().

Definition at line 753 of file Gap.h.

Gap shutdown event handler.

See also
Gap::onShutdown().

Definition at line 767 of file Gap.h.

Callchain of gap shutdown event handler.

See also
Gap::onShutdown().

Definition at line 775 of file Gap.h.

Opaque value type representing a connection handle.

It is used to identify to refer to a specific connection across Gap, GattClient and GattEvent API.

Note
instances are generated by in the connection callback.

Definition at line 309 of file Gap.h.

Enumeration of peer address types.

Definition at line 319 of file Gap.h.

Privacy Configuration of the peripheral role.

Note
This configuration also applies to the broadcaster role configuration.

Definition at line 681 of file Gap.h.

typedef ble::phy_t Phy_t

Enumeration of BLE PHY.

Definition at line 324 of file Gap.h.

Set of BLE PHYs.

Definition at line 329 of file Gap.h.

Radio notification event handler.

See also
Gap::onRadioNotification().

Definition at line 760 of file Gap.h.

Enumeration of random address types.

Definition at line 314 of file Gap.h.

Timeout event handler.

See also
Gap::onTimeout().

Definition at line 713 of file Gap.h.

Callchain of timeout event handlers.

See also
Gap::onTimeout().

Definition at line 721 of file Gap.h.

Member Enumeration Documentation

Advertising policy filter modes.

See also
Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.2.
Enumerator
ADV_POLICY_IGNORE_WHITELIST 

The whitelist is not used to filter peer request during advertising.

ADV_POLICY_FILTER_SCAN_REQS 

The whitelist is used to filter peer scan requests.

ADV_POLICY_FILTER_CONN_REQS 

The whitelist is used to filter peer connection requests.

ADV_POLICY_FILTER_ALL_REQS 

The whitelist is used to filter peer scan and connection requests.

Definition at line 209 of file Gap.h.

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead. The following constants have been left in their deprecated state to transparently support existing applications that may have used Gap::ADDR_TYPE_*.

Definition at line 101 of file Gap.h.

Enumeration of disconnection reasons.

Attention
There might be a mismatch between the disconnection reason passed to disconnect() and the disconnection event generated locally because the disconnection reason passed to disconnect() is the disconnection reason to be transmitted to the peer.
Enumerator
AUTHENTICATION_FAILURE 

GAP or GATT failed to authenticate the peer.

CONNECTION_TIMEOUT 

The connection timed out.

Attention
shall not be used as a reason in disconnect().
REMOTE_USER_TERMINATED_CONNECTION 

Connection terminated by the user.

REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES 

Remote device terminated connection due to low resources.

REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF 

Remote device terminated connection due to power off.

LOCAL_HOST_TERMINATED_CONNECTION 

Indicate that the local user or the internal Bluetooth subsystem terminated the connection.

Attention
shall not be used as a reason in disconnect().
CONN_INTERVAL_UNACCEPTABLE 

Connection parameters were unacceptable.

Definition at line 161 of file Gap.h.

Connection initiation policy filter mode.

See also
Bluetooth Core Specification 4.2 (vol. 6), Part B, Section 4.4.4.
Enumerator
INIT_POLICY_IGNORE_WHITELIST 

Connection can be initiated to any device.

INIT_POLICY_FILTER_ALL_ADV 

Connection initiation is restricted to the devices present in the whitelist.

Definition at line 253 of file Gap.h.

enum Role_t

Enumeration of GAP roles.

Note
The BLE API does not express the broadcaster and scanner roles.
Attention
A device can fulfill different roles concurrently.
Enumerator
PERIPHERAL 

Peripheral Role.

The device can advertise and it can be connected by a central. It acts as a slave when connected.

Note
A peripheral is a broadcaster.
CENTRAL 

Central Role.

The device can scan and initiate connection to peripherals. It acts as the master when a connection is established.

Note
A central is a scanner.

Definition at line 390 of file Gap.h.

Scanning policy filter mode.

See also
Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.3.
Enumerator
SCAN_POLICY_IGNORE_WHITELIST 

The whitelist is not used for scanning operations.

SCAN_POLICY_FILTER_ALL_ADV 

The whitelist is used to filter incoming advertising.

Definition at line 236 of file Gap.h.

Enumeration of possible timeout sources.

Enumerator
TIMEOUT_SRC_ADVERTISING 

Advertising timeout.

TIMEOUT_SRC_SECURITY_REQUEST 

Security request timeout.

TIMEOUT_SRC_SCAN 

Scanning timeout.

TIMEOUT_SRC_CONN 

Connection timeout.

Definition at line 131 of file Gap.h.

Member Function Documentation

ble_error_t accumulateAdvertisingPayload ( uint8_t  flags)

Set gap flags in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addFlags(flags);
gap.setAdvertisingPayload(payload);
Parameters
[in]flagsThe flags to be added.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder.
ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::Appearance  app)

Set the appearance field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addAppearance(app);
gap.setAdvertisingPayload(payload);
Parameters
[in]appThe appearance to advertise.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder instead.
ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)

Add a new field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addData(type, data, len);
gap.setAdvertisingPayload(payload);
Parameters
[in]typeIdentity of the field being added.
[in]dataBuffer containing the value of the field.
[in]lenLength of the data buffer.
Returns
BLE_ERROR_NONE if the advertisement payload was updated based on matching AD type; otherwise, an appropriate error.
Note
When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the supplied value is appended to the values previously added to the payload.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder instead.
ble_error_t accumulateAdvertisingPayloadTxPower ( int8_t  power)

Set the Tx Power field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addTxPower(power);
gap.setAdvertisingPayload(payload);
Parameters
[in]powerTransmit power in dBm used by the controller to advertise.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder instead.
ble_error_t accumulateScanResponse ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)

Add a new field in the advertising payload.

Parameters
[in]typeAD type identifier.
[in]databuffer containing AD data.
[in]lenLength of the data buffer.
Returns
BLE_ERROR_NONE if the data was successfully added to the scan response payload.
Deprecated:
Deprecated since addition of extended advertising support. Use createAdvertisingSet().
ble_error_t addDeviceToPeriodicAdvertiserList ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
advertising_sid_t  sid 
)
inherited

Add device to the periodic advertiser list.

Cannot be called when sync is ongoing.

Parameters
peerAddressTypePeer address type.
peerAddressPeer address.
sidAdvertiser set identifier.
Returns
BLE_ERROR_NONE on success.
ble_error_t cancelConnect ( )
inherited

Cancel the connection attempt.

This is not guaranteed to succeed. As a result onConnectionComplete in the event handler will be called. Check the success parameter to see if the connection was created.

Returns
BLE_ERROR_NONE if the connection attempt has been requested to be cancelled.
ble_error_t cancelCreateSync ( )
inherited

Cancel sync attempt.

Returns
BLE_ERROR_NONE on success.
void clearAdvertisingPayload ( void  )

Reset the value of the advertising payload advertised.

Deprecated:
Deprecated since addition of extended advertising support. Use setAdvertisingPayload(ble::advertising_handle_t, mbed::Span<uint8_t>, bool).
ble_error_t clearPeriodicAdvertiserList ( )
inherited

Remove all devices from periodic advertiser list.

Returns
BLE_ERROR_NONE on success.
void clearScanResponse ( void  )

Reset the content of the scan response.

Note
This should be followed by a call to Gap::setAdvertisingPayload() or Gap::startAdvertising() before the update takes effect.
Deprecated:
Deprecated since addition of extended advertising support. Use setAdvertisingScanResponse().
ble_error_t connect ( const BLEProtocol::AddressBytes_t  peerAddr,
PeerAddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)

Initiate a connection to a peer.

Once the connection is established, a ConnectionCallbackParams_t event is emitted to handlers that have been registered with onConnection().

Parameters
[in]peerAddrMAC address of the peer. It must be in LSB format.
[in]peerAddrTypeAddress type of the peer. It is usually obtained from advertising frames.
[in]connectionParamsConnection parameters to use.
[in]scanParamsScan parameters used to find the peer.
Returns
BLE_ERROR_NONE if connection establishment procedure is started successfully. The connectionCallChain (if set) is invoked upon a connection event.
Deprecated:
Deprecated since addition of extended advertising support. Use connect(target_peer_address_type_t, address_t, ConnectionParameters).
ble_error_t connect ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
const ConnectionParameters connectionParams 
)
inherited

Initiate a connection to a peer.

Once the connection is established an onConnectionComplete in the event handler will be called.

Parameters
peerAddressType
peerAddress
connectionParams
Returns
BLE_ERROR_NONE if connection establishment procedure is started successfully. The connectionCallChain (if set) is invoked upon a connection event.
See also
EventHandler::onConnectionComplete will be called whether the connection process succeed or fail.
EventHandler::onDisconnectionComplete is called when the connection ends.
ble_error_t connect ( const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)

Initiate a connection to a peer.

Once the connection is established, a ConnectionCallbackParams_t event is emitted to handlers that have been registered with onConnection().

Parameters
[in]peerAddrMAC address of the peer. It must be in LSB format.
[in]peerAddrTypeAddress type of the peer.
[in]connectionParamsConnection parameters to use.
[in]scanParamsScan parameters used to find the peer.
Deprecated:
BLEProtocol::AddressType_t is not able to to carry accurate meaning when privacy is in use. Please Uses the connect overload that accept a PeerAddressType_t as the peer address type.
Returns
BLE_ERROR_NONE if connection establishment procedure is started successfully. The connectionCallChain (if set) is invoked upon a connection event.
ble_error_t connect ( const BLEProtocol::AddressBytes_t  peerAddr,
DeprecatedAddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)

Initiate a connection to a peer.

See also
connect()
Deprecated:
This funtion overloads Gap::connect( const BLEProtocol::Address_t peerAddr, BLEProtocol::AddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams ) to maintain backward compatibility for changes from Gap::AddressType_t to BLEProtocol::AddressType_t.
ble_error_t createAdvertisingSet ( advertising_handle_t handle,
const AdvertisingParameters parameters 
)
inherited

Create an advertising set and apply the passed in parameters.

The handle returned by this function must be used for all other calls that accept an advertising handle. When done with advertising, remove from the system using destroyAdvertisingSet().

Note
The exception is the LEGACY_ADVERTISING_HANDLE which may be used at any time.
Parameters
[out]handleAdvertising handle returned, valid only if function returned success.
parametersAdvertising parameters for the newly created set.
Returns
BLE_ERROR_NONE on success.
Version
5+
ble_error_t createSync ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
uint8_t  sid,
slave_latency_t  maxPacketSkip,
sync_timeout_t  timeout 
)
inherited

Synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Parameters
peerAddressTypePeer address type.
peerAddressPeer address.
sidAdvertiser set identifier.
maxPacketSkipNumber of consecutive periodic advertising packets that the receiver may skip after successfully receiving a periodic advertising packet.
timeoutMaximum permitted time between successful receptions. If this time is exceeded, synchronisation is lost.
Returns
BLE_ERROR_NONE on success.
See also
EventHandler::onPeriodicAdvertisingSyncEstablished when the sync is effective.
EventHandler::onPeriodicAdvertisingReport when data are issued by the peer.
EventHandler::onPeriodicAdvertisingSyncLoss when the sync has been loss.
Version
5+
ble_error_t createSync ( slave_latency_t  maxPacketSkip,
sync_timeout_t  timeout 
)
inherited

Synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Use periodic advertising sync list to determine who to sync with.

Parameters
maxPacketSkipNumber of consecutive periodic advertising packets that the receiver may skip after successfully receiving a periodic advertising packet.
timeoutMaximum permitted time between successful receives. If this time is exceeded, synchronisation is lost.
Returns
BLE_ERROR_NONE on success.
See also
EventHandler::onPeriodicAdvertisingSyncEstablished when the sync is effective.
EventHandler::onPeriodicAdvertisingReport when data are issued by the peer.
EventHandler::onPeriodicAdvertisingSyncLoss when the sync has been loss.
Version
5+
ble_error_t destroyAdvertisingSet ( advertising_handle_t  handle)
inherited

Remove the advertising set (resets its set parameters).

The advertising set must not be active.

Note
LEGACY_ADVERTISING_HANDLE may not be destroyed.
Parameters
handleAdvertising set handle.
Returns
BLE_ERROR_NONE on success.
Version
5+
ble_error_t disconnect ( Handle_t  connectionHandle,
DisconnectionReason_t  reason 
)

Initiate a disconnection procedure.

Once the disconnection procedure has completed a DisconnectionCallbackParams_t, the event is emitted to handlers that have been registered with onDisconnection().

Parameters
[in]reasonReason of the disconnection transmitted to the peer.
[in]connectionHandleHandle of the connection to end.
Returns
BLE_ERROR_NONE if the disconnection procedure successfully started.
Deprecated:
Deprecated since addition of extended advertising support. Use disconnect(connection_handle_t, local_disconnection_reason_t) instead.
ble_error_t disconnect ( DisconnectionReason_t  reason)

Initiate a disconnection procedure.

Deprecated:
This version of disconnect() doesn't take a connection handle. It works reliably only for stacks that are limited to a single connection. Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) instead.
Parameters
[in]reasonThe reason for disconnection; to be sent back to the peer.
Returns
BLE_ERROR_NONE if disconnection was successful.
ble_error_t enablePrivacy ( bool  enable)
inherited

Enable or disable privacy mode of the local device.

When privacy is enabled, the system use private addresses while it scans, advertises or initiate a connection. The device private address is renewed every 15 minutes.

Configuration

The privacy feature can be configured with the help of the functions setPeripheralPrivacyConfiguration and setCentralPrivacyConfiguration which respectively set the privacy configuration of the peripheral and central role.

Default configuration of peripheral role

By default private resolvable addresses are used for all procedures; including advertisement of nonconnectable packets. Connection request from an unknown initiator with a private resolvable address triggers the pairing procedure.

Default configuration of central role

By default private resolvable addresses are used for all procedures; including active scanning. Addresses present in advertisement packet are resolved and advertisement packets are forwarded to the application even if the advertiser private address is unknown.

Parameters
[in]enableShould be set to true to enable the privacy mode and false to disable it.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.

Fetch the current address and its type.

Parameters
[out]typePType of the current address set.
[out]addressValue of the current address.
Note
If privacy is enabled the device address may be unavailable to application code.
Returns
BLE_ERROR_NONE on success.
GapAdvertisingParams& getAdvertisingParams ( void  )

Get the current advertising parameters.

Returns
A reference to the current advertising parameters.
Deprecated:
Deprecated since addition of extended advertising support.
const GapAdvertisingParams& getAdvertisingParams ( void  ) const

Const alternative to Gap::getAdvertisingParams().

Returns
A const reference to the current advertising parameters.
Deprecated:
Deprecated since addition of extended advertising support.
const GapAdvertisingData& getAdvertisingPayload ( void  ) const

Get a reference to the current advertising payload.

Returns
A reference to the current advertising payload.
Deprecated:
Deprecated since addition of extended advertising support.
AdvertisingPolicyMode_t getAdvertisingPolicyMode ( void  ) const

Get the current advertising policy filter mode.

Returns
The current advertising policy filter mode.
Deprecated:
Deprecated since addition of extended advertising support.
ble_error_t getAppearance ( GapAdvertisingData::Appearance appearanceP)

Get the value of the appearance characteristic in the GAP service.

Parameters
[out]appearancePThe current device-appearance value.
Returns
BLE_ERROR_NONE if the device-appearance was fetched correctly from the underlying BLE stack.
ble_error_t getCentralPrivacyConfiguration ( central_privay_configuration_t configuration)
inherited

Get the privacy configuration used by the central role.

Parameters
[out]configurationThe variable filled with the current configuration.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
ble_error_t getDeviceName ( uint8_t *  deviceName,
unsigned *  lengthP 
)

Get the value of the device name characteristic in the Generic Access Service.

To obtain the length of the deviceName value, this function is invoked with the deviceName parameter set to NULL.

Parameters
[out]deviceNamePointer to an empty buffer where the UTF-8 non NULL-terminated string is placed.
[in,out]lengthPLength of the deviceName buffer. If the device name is successfully copied, then the length of the device name string (excluding the null terminator) replaces this value.
Returns
BLE_ERROR_NONE if the device name was fetched correctly from the underlying BLE stack.
Note
If the device name is longer than the size of the supplied buffer, length returns the complete device name length and not the number of bytes actually returned in deviceName. The application may use this information to retry with a suitable buffer size.
InitiatorPolicyMode_t getInitiatorPolicyMode ( void  ) const

Get the current initiator policy filter mode.

Returns
The current scan policy filter mode.
Deprecated:
Deprecated since addition of extended advertising support.
uint16_t getMaxActiveSetAdvertisingDataLength ( )
inherited

Return maximum advertising data length you may set if advertising set is active.

Returns
Maximum advertising data length you may set if advertising set is active.
uint16_t getMaxAdvertisingDataLength ( )
inherited

Return maximum advertising data length supported.

Returns
Maximum advertising data length supported.
uint16_t getMaxAdvertisingInterval ( void  ) const

Get the maximum advertising interval in milliseconds.

Returns
Maximum Advertising interval in milliseconds.
uint8_t getMaxAdvertisingSetNumber ( )
inherited

Return currently available number of supported advertising sets.

This may change at runtime.

Note
Devices that do not support Bluetooth 5 still offers one advertising set that has the handle LEGACY_ADVERTISING_HANDLE.
Returns
Number of advertising sets that may be created at the same time.
uint16_t getMaxConnectableAdvertisingDataLength ( )
inherited

Return maximum advertising data length supported for connectable advertising.

Returns
Maximum advertising data length supported for connectable advertising.
uint8_t getMaxPeriodicAdvertiserListSize ( )
inherited

Get number of devices that can be added to the periodic advertiser list.

Returns
Number of devices that can be added to the periodic advertiser list.
uint8_t getMaxWhitelistSize ( void  ) const

Get the maximum size of the whitelist.

Returns
Maximum size of the whitelist.
Note
If using Mbed OS, you can configure the size of the whitelist by setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file.
uint16_t getMinAdvertisingInterval ( void  ) const

Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types.

Returns
Minimum Advertising interval in milliseconds for connectable undirected and connectable directed advertising types.
uint16_t getMinNonConnectableAdvertisingInterval ( void  ) const

Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type.

Returns
Minimum Advertising interval in milliseconds for scannable undirected and nonconnectable undirected event types.
ble_error_t getPeripheralPrivacyConfiguration ( peripheral_privacy_configuration_t configuration)
inherited

Get the privacy configuration used by the peripheral role.

Parameters
[out]configurationThe variable filled with the current configuration.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
void getPermittedTxPowerValues ( const int8_t **  valueArrayPP,
size_t *  countP 
)

Query the underlying stack for allowed Tx power values.

Parameters
[out]valueArrayPPReceive the immutable array of Tx values.
[out]countPReceive the array's size.
Deprecated:
Deprecated since addition of extended advertising support.
ble_error_t getPreferredConnectionParams ( ConnectionParams_t params)

Returned the preferred connection parameters exposed in the GATT Generic Access Service.

Parameters
[out]paramsStructure where the parameters are stored.
Returns
BLE_ERROR_NONE if the parameters were successfully filled into params.
static ble_error_t getRandomAddressType ( const BLEProtocol::AddressBytes_t  address,
RandomAddressType_t addressType 
)
static

Return the type of a random address.

Parameters
[in]addressThe random address to retrieve the type from. The address must be ordered in little endian.
[out]addressTypeType of the address to fill.
Returns
BLE_ERROR_NONE in case of success or BLE_ERROR_INVALID_PARAM if the address in input was not identifiable as a random address.
ScanningPolicyMode_t getScanningPolicyMode ( void  ) const

Get the current scan policy filter mode.

Returns
The current scan policy filter mode.
Deprecated:
Deprecated since addition of extended advertising support.
GapState_t getState ( void  ) const

Get the current advertising and connection states of the device.

Returns
The current GAP state of the device.
Deprecated:
Deprecated since addition of extended advertising support. This is not meaningful when you use extended advertising; please use isAdvertisingActive() and getConnectionCount().
ble_error_t getWhitelist ( Whitelist_t whitelist) const

Get the Link Layer to use the internal whitelist when scanning, advertising or initiating a connection depending on the filter policies.

Parameters
[in,out]whitelistDefine the whitelist instance which is used to store the whitelist requested. In input, the caller provisions memory.
Returns
BLE_ERROR_NONE if the implementation's whitelist was successfully copied into the supplied reference.
ble_error_t initRadioNotification ( void  )

Enable radio-notification events.

Radio Notification is a feature that notifies the application when the radio is in use.

The ACTIVE signal is sent before the radio event starts. The nACTIVE signal is sent at the end of the radio event. The application programmer can use these signals to synchronize application logic with radio activity. For example, the ACTIVE signal can be used to shut off external devices, to manage peak current drawn during periods when the radio is on or to trigger sensor data collection for transmission in the Radio Event.

Returns
BLE_ERROR_NONE on successful initialization, otherwise an error code.
Deprecated:
Deprecated since addition of extended advertising support.
bool isAdvertisingActive ( advertising_handle_t  handle)
inherited

Check if advertising is active for a given advertising set.

Parameters
handleAdvertising set handle.
Returns
True if advertising is active on this set.
bool isFeatureSupported ( controller_supported_features_t  feature)
inherited

Check controller support for a specific feature.

Parameters
featureFeature to check.
Returns
True if feature is supported.
bool isPeriodicAdvertisingActive ( advertising_handle_t  handle)
inherited

Check if periodic advertising is active for a given advertising set.

Parameters
handleAdvertising set handle.
Returns
True if periodic advertising is active on this set.
Version
5+
LegacyGap ( )
protected

Construct a Gap instance.

static uint16_t MSEC_TO_GAP_DURATION_UNITS ( uint32_t  durationInMillis)
static

Convert milliseconds into 1.25ms units.

This function may be used to convert ms time of connection intervals into the format expected for connection parameters.

Parameters
[in]durationInMillisThe duration in milliseconds.
Returns
The duration in unit of 1.25ms.

Definition at line 703 of file Gap.h.

void onConnection ( ConnectionEventCallback_t  callback)

Register a callback handling connection events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onConnection().detach(callback).
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void onConnection ( T *  tptr,
void(T::*)(const ConnectionCallbackParams_t *)  mptr 
)

Register a callback handling connection events.

Parameters
[in]tptrInstance used to invoke mptr.
[in]mptrEvent handler being registered.
Note
A callback may be unregistered using onConnection().detach(callback).
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
ConnectionEventCallbackChain_t& onConnection ( )

Get the callchain of registered connection event handlers.

Note
To register callbacks, use onConnection().add(callback).
To unregister callbacks, use onConnection().detach(callback).
Returns
A reference to the connection event callbacks chain.
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void onDisconnection ( DisconnectionEventCallback_t  callback)

Register a callback handling disconnection events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onDisconnection().detach(callback).
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void onDisconnection ( T *  tptr,
void(T::*)(const DisconnectionCallbackParams_t *)  mptr 
)

Register a callback handling disconnection events.

Parameters
[in]tptrInstance used to invoke mptr.
[in]mptrEvent handler being registered.
Note
A callback may be unregistered using onDisconnection().detach(callback).
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
DisconnectionEventCallbackChain_t& onDisconnection ( )

Get the callchain of registered disconnection event handlers.

Note
To register callbacks use onDisconnection().add(callback).
To unregister callbacks use onDisconnection().detach(callback).
Returns
A reference to the disconnection event callbacks chain.
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void onRadioNotification ( void(*)(bool param)  callback)

Set the radio-notification events handler.

Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack that notify the application when the radio is in use.

The ACTIVE signal is sent before the radio event starts. The nACTIVE signal is sent at the end of the radio event. The application programmer can use these signals to synchronize application logic with radio activity. For example, the ACTIVE signal can be used to shut off external devices, to manage peak current drawn during periods when the radio is on or to trigger sensor data collection for transmission in the Radio Event.

Parameters
[in]callbackApplication handler to be invoked in response to a radio ACTIVE/INACTIVE event.
Deprecated:
Deprecated since addition of extended advertising support.
void onRadioNotification ( T *  tptr,
void(T::*)(bool)  mptr 
)

Set the radio-notification events handler.

Parameters
[in]tptrInstance to be used to invoke mptr.
[in]mptrApplication handler to be invoked in response to a radio ACTIVE/INACTIVE event.
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void onShutdown ( const GapShutdownCallback_t callback)

Register a Gap shutdown event handler.

The handler is called when the Gap instance is about to shut down. It is usually issued after a call to BLE::shutdown().

Parameters
[in]callbackShutdown event handler to register.
Note
To unregister a shutdown event handler, use onShutdown().detach(callback).
void onShutdown ( T *  objPtr,
void(T::*)(const LegacyGap *)  memberPtr 
)

Register a Gap shutdown event handler.

Parameters
[in]objPtrInstance used to invoke memberPtr.
[in]memberPtrShutdown event handler to register.

Definition at line 2216 of file Gap.h.

GapShutdownCallbackChain_t& onShutdown ( )

Access the callchain of shutdown event handler.

Note
To register callbacks, use onShutdown().add(callback).
To unregister callbacks, use onShutdown().detach(callback).
Returns
A reference to the shutdown event callback chain.
void onTimeout ( TimeoutEventCallback_t  callback)

Register a callback handling timeout events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onTimeout().detach(callback).
See also
TimeoutSource_t
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.

Get the callchain of registered timeout event handlers.

Note
To register callbacks, use onTimeout().add(callback).
To unregister callbacks, use onTimeout().detach(callback).
Returns
A reference to the timeout event callbacks chain.
Deprecated:
Deprecated since addition of extended advertising support. Use setEventHandler() instead.
void processAdvertisementReport ( const BLEProtocol::AddressBytes_t  peerAddr,
int8_t  rssi,
bool  isScanResponse,
GapAdvertisingParams::AdvertisingType_t  type,
uint8_t  advertisingDataLen,
const uint8_t *  advertisingData,
PeerAddressType_t  addressType 
)

Forward a received advertising packet to all registered event handlers listening for scanned packet events.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]peerAddrAddress of the peer that has emitted the packet.
[in]rssiValue of the RSSI measured for the received packet.
[in]isScanResponseIf true, then the packet is a response to a scan request.
[in]typeAdvertising type of the packet.
[in]advertisingDataLenLength of the advertisement data received.
[in]advertisingDataPointer to the advertisement packet's data.
[in]addressTypeType of the address of the peer that has emitted the packet.
Deprecated:
Deprecated since addition of extended advertising support. Use EventHandler::onAdvertisingReport() instead.
void processAdvertisementReport ( const BLEProtocol::AddressBytes_t  peerAddr,
int8_t  rssi,
bool  isScanResponse,
GapAdvertisingParams::AdvertisingType_t  type,
uint8_t  advertisingDataLen,
const uint8_t *  advertisingData,
BLEProtocol::AddressType_t  addressType = BLEProtocol::AddressType::RANDOM_STATIC 
)

Forward a received advertising packet to all registered event handlers listening for scanned packet events.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]peerAddrAddress of the peer that has emitted the packet.
[in]rssiValue of the RSSI measured for the received packet.
[in]isScanResponseIf true, then the packet is a response to a scan request.
[in]typeAdvertising type of the packet.
[in]advertisingDataLenLength of the advertisement data received.
[in]advertisingDataPointer to the advertisement packet's data.
[in]addressTypeType of the address of the peer that has emitted the packet.
Deprecated:
The type BLEProtocol::AddressType_t is not suitable when privacy is enabled. Use the overload that accepts a PeerAddressType_t instead.
void processConnectionEvent ( Handle_t  handle,
Role_t  role,
PeerAddressType_t  peerAddrType,
const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  ownAddrType,
const BLEProtocol::AddressBytes_t  ownAddr,
const ConnectionParams_t connectionParams,
const uint8_t *  peerResolvableAddr = NULL,
const uint8_t *  localResolvableAddr = NULL 
)

Notify all registered connection event handlers of a connection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a connection event occurs.
Parameters
[in]handleHandle of the new connection.
[in]roleRole of this BLE device in the connection.
[in]peerAddrTypeAddress type of the connected peer.
[in]peerAddrAddress of the connected peer.
[in]ownAddrTypeAddress type this device uses for this connection.
[in]ownAddrAddress this device uses for this connection. This parameter may be NULL if the local address is not available.
[in]connectionParamsParameters of the connection.
[in]peerResolvableAddrResolvable address used by the peer.
[in]localResolvableAddrresolvable address used by the local device.
Deprecated:
Deprecated since addition of extended advertising support. Use EventHandler::onConnectionComplete() instead.
void processConnectionEvent ( Handle_t  handle,
Role_t  role,
BLEProtocol::AddressType_t  peerAddrType,
const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  ownAddrType,
const BLEProtocol::AddressBytes_t  ownAddr,
const ConnectionParams_t connectionParams,
const uint8_t *  peerResolvableAddr = NULL,
const uint8_t *  localResolvableAddr = NULL 
)

Notify all registered connection event handlers of a connection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a connection event occurs.
Parameters
[in]handleHandle of the new connection.
[in]roleRole of this BLE device in the connection.
[in]peerAddrTypeAddress type of the connected peer.
[in]peerAddrAddress of the connected peer.
[in]ownAddrTypeAddress type this device uses for this connection.
[in]ownAddrAddress this device uses for this connection.
[in]connectionParamsParameters of the connection.
[in]peerResolvableAddrResolvable address used by the peer.
[in]localResolvableAddrresolvable address used by the local device.
Deprecated:
The type BLEProtocol::AddressType_t is not suitable when privacy is enabled. Use the overload that accepts a PeerAddressType_t instead.
void processDisconnectionEvent ( Handle_t  handle,
DisconnectionReason_t  reason 
)

Notify all registered disconnection event handlers of a disconnection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]handleHandle of the terminated connection.
[in]reasonReason of the disconnection.
Deprecated:
Deprecated since addition of extended advertising support. Use EventHandler::onDisconnection() instead.
void processTimeoutEvent ( TimeoutSource_t  source)

Notify the occurrence of a timeout event to all registered timeout events handler.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]sourceSource of the timout event.
Deprecated:
Deprecated since addition of extended advertising support. Use EventHandler instead.
ble_error_t readPhy ( connection_handle_t  connection)
inherited

Read the PHY used by the transmitter and the receiver on a connection.

Once the PHY has been read, it is reported back via the function onPhyRead of the event handler registered by the application.

Parameters
connectionHandle of the connection for which the PHY being used is queried.
Returns
BLE_ERROR_NONE if the read PHY procedure has been started or an appropriate error code.
Version
5+
See also
EventHandler::onReadPhy is called when the phy has been read.
ble_error_t removeDeviceFromPeriodicAdvertiserList ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
advertising_sid_t  sid 
)
inherited

Remove device from the periodic advertiser list.

Cannot be called when sync is ongoing.

Parameters
peerAddressTypePeer address type.
peerAddressPeer address.
sidAdvertiser set identifier.
Returns
BLE_ERROR_NONE on success.
ble_error_t reset ( void  )

Reset the Gap instance.

Reset process starts by notifying all registered shutdown event handlers that the Gap instance is about to be shut down. Then, it clears all Gap state of the associated object and then cleans the state present in the vendor implementation.

This function is meant to be overridden in the platform-specific subclass. Nevertheless, the subclass only resets its state and not the data held in Gap members. This is achieved by a call to Gap::reset() from the subclass' reset() implementation.

Returns
BLE_ERROR_NONE on success.
Note
Currently, a call to reset() does not reset the advertising and scan parameters to default values.
ble_error_t setActiveScanning ( bool  activeScanning)

Enable or disable active scanning.

Parameters
[in]activeScanningIf set to true, then the scanner sends scan requests to a scannable or connectable advertiser. If set to false then the scanner does not send any request during the scan procedure.
Returns
BLE_ERROR_NONE if active scanning was successfully set.
Note
If scanning is already in progress, then active scanning is enabled for the underlying BLE stack.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setAddress ( BLEProtocol::AddressType_t  type,
const BLEProtocol::AddressBytes_t  address 
)

Set the device MAC address and type.

The address set is used in subsequent GAP operations: scanning, advertising and connection initiation.

Parameters
[in]typeType of the address to set.
[in]addressValue of the address to set. It is ordered in little endian. This parameter is not considered if the address type is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those types of address, the BLE API itself generates the address.
Note
Some implementation may refuse to set a new PUBLIC address.
Random static address set does not change.
Deprecated:
Starting with mbed-os-5.9.0 this function is deprecated and address management is delegated to implementation. Implementations may or may not continue to support this function. Compliance with the Bluetooth specification and unification of behaviour between implementations are the key reasons behind this change:
  • Many implementations do not allow changing of the public address. Therefore programs relying on this function are not portable across BLE implementations.
  • The Bluetooth specification forbid replacement of the random static address; this address can be set once and only once: at startup. Depending on the underlying implementation the random address may or may not have been set automatically at startup; therefore update of the Random Static address after ble initialisation may be a fault. As a result calls to this function were not portable. Furthermore replacement of the random static address silently invalidates the bond stored in the secure database.
Returns
BLE_ERROR_NONE on success.
void setAdvertisingInterval ( uint16_t  interval)

Set the advertising interval.

Parameters
[in]intervalAdvertising interval in units of milliseconds. Advertising is disabled if interval is 0. If interval is smaller than the minimum supported value, then the minimum supported value is used instead. This minimum value can be discovered using getMinAdvertisingInterval().

This field must be set to 0 if connectionMode is equal to ADV_CONNECTABLE_DIRECTED.

Note
Decreasing this value allows central devices to detect a peripheral faster, at the expense of the radio using more power due to the higher data transmit rate.
Deprecated:
Deprecated since addition of extended advertising support. This option is now part of ble::AdvertisingParameters.
ble_error_t setAdvertisingParameters ( advertising_handle_t  handle,
const AdvertisingParameters params 
)
inherited

Set advertising parameters of an existing set.

Parameters
handleAdvertising set handle.
paramsNew advertising parameters.
Returns
BLE_ERROR_NONE on success.
void setAdvertisingParams ( const GapAdvertisingParams newParams)

Set the advertising parameters.

Parameters
[in]newParamsThe new advertising parameters.
Deprecated:
Deprecated since addition of extended advertising support. Use setAdvertisingParameters() instead.
ble_error_t setAdvertisingPayload ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  payload 
)
inherited

Set new advertising payload for a given advertising set.

Parameters
handleAdvertising set handle.
payloadAdvertising payload.
Note
If advertising set is active you may only set payload of length equal or less than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must stop the advertising set, set the payload and restart the set.
Returns
BLE_ERROR_NONE on success.
See also
ble::AdvertisingDataBuilder to build a payload.
ble_error_t setAdvertisingPayload ( const GapAdvertisingData payload)

Set the value of the payload advertised.

Parameters
[in]payloadA reference to a user constructed advertisement payload to set.
Returns
BLE_ERROR_NONE if the advertisement payload was successfully set.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder instead.
ble_error_t setAdvertisingPolicyMode ( AdvertisingPolicyMode_t  mode)

Set the advertising policy filter mode to be used during the next advertising procedure.

Parameters
[in]modeNew advertising policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
Deprecated:
Deprecated since addition of extended advertising support. This setting is now part of ble::AdvertisingParameters.
ble_error_t setAdvertisingScanResponse ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  response 
)
inherited

Set new advertising scan response for a given advertising set.

This will be sent to device who perform active scanning.

Parameters
handleAdvertising set handle.
responseAdvertising scan response.
Note
If advertising set is active you may only set payload of length equal or less than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must stop the advertising set, set the payload and restart the set.
Returns
BLE_ERROR_NONE on success.
See also
ble::AdvertisingDataBuilder to build a payload.
void setAdvertisingTimeout ( uint16_t  timeout)

Set the advertising duration.

A timeout event is genenerated once the advertising period expired.

Parameters
[in]timeoutAdvertising timeout (in seconds) between 0x1 and 0x3FFF. The special value 0 may be used to disable the advertising timeout.
Deprecated:
Deprecated since addition of extended advertising support. This option is now part of ble::AdvertisingParameters.
void setAdvertisingType ( GapAdvertisingParams::AdvertisingType_t  advType)

Set the advertising type to use during the advertising procedure.

Parameters
[in]advTypeNew type of advertising to use.
Deprecated:
Deprecated since addition of extended advertising support. This option is now part of ble::AdvertisingParameters.
ble_error_t setAppearance ( GapAdvertisingData::Appearance  appearance)

Set the value of the appearance characteristic in the GAP service.

Parameters
[in]appearanceThe new value for the device-appearance.
Returns
BLE_ERROR_NONE if the new appearance was set correctly.
ble_error_t setCentralPrivacyConfiguration ( const central_privay_configuration_t configuration)
inherited

Set the privacy configuration used by the central role.

Parameters
[in]configurationThe configuration to set.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
ble_error_t setDeviceName ( const uint8_t *  deviceName)

Set the value of the device name characteristic in the Generic Access Service.

Parameters
[in]deviceNameThe new value for the device-name. This is a UTF-8 encoded, NULL-terminated string.
Returns
BLE_ERROR_NONE if the device name was set correctly.
void setEventHandler ( EventHandler handler)
inherited

Assign the event handler implementation that will be used by the gap module to signal events back to the application.

Parameters
handlerApplication implementation of an EventHandler.

Definition at line 541 of file gap/Gap.h.

ble_error_t setInitiatorPolicyMode ( InitiatorPolicyMode_t  mode)

Set the initiator policy filter mode to be used during the next connection initiation.

Parameters
[in]modeNew initiator policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
Deprecated:
Deprecated since addition of extended advertising support. This setting is now part of ble::ConnectionParameters.
ble_error_t setPeriodicAdvertisingParameters ( advertising_handle_t  handle,
periodic_interval_t  periodicAdvertisingIntervalMin,
periodic_interval_t  periodicAdvertisingIntervalMax,
bool  advertiseTxPower = true 
)
inherited

Set periodic advertising parameters for a given advertising set.

Parameters
handleAdvertising set handle.
periodicAdvertisingIntervalMinMinimum interval for periodic advertising.
periodicAdvertisingIntervalMaxMaximum interval for periodic advertising.
advertiseTxPowerInclude transmission power in the advertisements.
Returns
BLE_ERROR_NONE on success.
Version
5+
ble_error_t setPeriodicAdvertisingPayload ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  payload 
)
inherited

Set new periodic advertising payload for a given advertising set.

Parameters
handleAdvertising set handle.
payloadAdvertising payload.
Returns
BLE_ERROR_NONE on success.
Note
If advertising set is active you may only set payload of length equal or less than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must stop the advertising set, set the payload and restart the set. Stopping the set will cause peers to lose sync on the periodic set.
See also
ble::AdvertisingDataBuilder to build a payload.
Version
5+
ble_error_t setPeripheralPrivacyConfiguration ( const peripheral_privacy_configuration_t configuration)
inherited

Set the privacy configuration used by the peripheral role.

Parameters
[in]configurationThe configuration to set.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
ble_error_t setPhy ( connection_handle_t  connection,
const phy_set_t txPhys,
const phy_set_t rxPhys,
coded_symbol_per_bit_t  codedSymbol 
)
inherited

Update the PHY used by a connection.

Once the update process has been completed, it is reported back to the application via the function onPhyUpdateComplete of the event handler registered by the application.

Parameters
connectionHandle of the connection to update.
txPhysSet of PHYs preferred for tx operations. If NULL then the choice is up to the Bluetooth subsystem.
rxPhysSet of PHYs preferred for rx operations. If NULL then the choice is up to the Bluetooth subsystem.
codedSymbolNumber of symbols used to code a bit when le coded is used. If the value is UNDEFINED then the choice is up to the Bluetooth subsystem.
Returns
BLE_ERROR_NONE if the update PHY procedure has been successfully started or an error code.
See also
EventHandler::onPhyUpdateComplete is called when the phy used by the connection has been updated.
ble_error_t setPreferredConnectionParams ( const ConnectionParams_t params)

Set the value of the preferred connection parameters exposed in the GATT Generic Access Service.

A connected peer may read the characteristic exposing these parameters and request an update of the connection parameters to accommodate the local device.

Parameters
[in]paramsValue of the preferred connection parameters.
Returns
BLE_ERROR_NONE if the preferred connection params were set correctly.
ble_error_t setPreferredPhys ( const phy_set_t txPhys,
const phy_set_t rxPhys 
)
inherited

Set the preferred PHYs to use in a connection.

Parameters
txPhysSet of PHYs preferred for tx operations. If NULL then no preferred PHYs are set and the default value of the subsystem is used.
rxPhysSet of PHYs preferred for rx operations. If NULL then no preferred PHYs are set and the default value of the subsystem is used.
Returns
BLE_ERROR_NONE if the preferences have been set or an appropriate error code.
Version
5+
ble_error_t setScanInterval ( uint16_t  interval)

Set the interval parameter used during scanning procedures.

Parameters
[in]intervalInterval in ms between the start of two consecutive scan windows. That value is greater or equal to the scan window value. The maximum allowed value is 10.24ms.
Returns
BLE_ERROR_NONE if the scan interval was correctly set.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setScanningPolicyMode ( ScanningPolicyMode_t  mode)

Set the scan policy filter mode to be used during the next scan procedure.

Parameters
[in]modeNew scan policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
Deprecated:
Deprecated since addition of extended advertising support. This setting is now part of ble::ScanParameters.
ble_error_t setScanParameters ( const ScanParameters params)
inherited

Set new scan parameters.

Parameters
paramsScan parameters,
See also
GapScanParameters for details.
Returns
BLE_ERROR_NONE on success.
ble_error_t setScanParams ( uint16_t  interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t  window = GapScanningParams::SCAN_WINDOW_MAX,
uint16_t  timeout = 0,
bool  activeScanning = false 
)

Set the parameters used during a scan procedure.

Parameters
[in]intervalin ms between the start of two consecutive scan windows. That value is greater or equal to the scan window value. The maximum allowed value is 10.24ms.
[in]windowPeriod in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s.
[in]timeoutDuration in seconds of the scan procedure if any. The special value 0 disable specific duration of the scan procedure.
[in]activeScanningIf set to true, then the scanner sends scan requests to a scannable or connectable advertiser. If set to false, then the scanner does not send any request during the scan procedure.
Returns
BLE_ERROR_NONE if the scan parameters were correctly set.
Note
The scanning window divided by the interval determines the duty cycle for scanning. For example, if the interval is 100ms and the window is 10ms, then the controller scans for 10 percent of the time.
If the interval and the window are set to the same value, then the device scans continuously during the scan procedure. The scanning frequency changes at every interval.
Once the scanning parameters have been configured, scanning can be enabled by using startScan().
The scan interval and window are recommendations to the BLE stack.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setScanParams ( const GapScanningParams scanningParams)

Set the parameters used during a scan procedure.

Parameters
[in]scanningParamsParameter struct containing the interval, period, timeout and active scanning toggle.
Returns
BLE_ERROR_NONE if the scan parameters were correctly set.
Note
All restrictions from setScanParams(uint16_t, uint16_t, uint16_t, bool) apply.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setScanTimeout ( uint16_t  timeout)

Set the timeout parameter used during scanning procedures.

Parameters
[in]timeoutDuration in seconds of the scan procedure if any. The special value 0 disables specific duration of the scan procedure.
Returns
BLE_ERROR_NONE if the scan timeout was correctly set.
Note
If scanning is already active, the updated value of scanTimeout is propagated to the underlying BLE stack.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setScanWindow ( uint16_t  window)

Set the window parameter used during scanning procedures.

Parameters
[in]windowPeriod in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s.
Returns
BLE_ERROR_NONE if the scan window was correctly set.
Note
If scanning is already active, the updated value of scanWindow is propagated to the underlying BLE stack.
Deprecated:
Deprecated since addition of extended advertising support. Use setScanParameters(const ScanParameters &) instead.
ble_error_t setTxPower ( int8_t  txPower)

Set the radio's transmit power.

Parameters
[in]txPowerRadio's transmit power in dBm.
Returns
BLE_ERROR_NONE if the new radio's transmit power was set correctly.
Deprecated:
Deprecated since addition of extended advertising support. See ble::AdvertisingParameters and setAdvertisingParameters.
ble_error_t setWhitelist ( const Whitelist_t whitelist)

Set the value of the whitelist to be used during GAP procedures.

Parameters
[in]whitelistA reference to a whitelist containing the addresses to be copied to the internal whitelist.
Returns
BLE_ERROR_NONE if the implementation's whitelist was successfully populated with the addresses in the given whitelist.
Note
The whitelist must not contain addresses of type BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This results in a BLE_ERROR_INVALID_PARAM because the remote peer might change its private address at any time, and it is not possible to resolve it.
If the input whitelist is larger than getMaxWhitelistSize(), then BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
ble_error_t startAdvertising ( advertising_handle_t  handle,
adv_duration_t  maxDuration = adv_duration_t::forever(),
uint8_t  maxEvents = 0 
)
inherited

Start advertising using the given advertising set.

Parameters
handleAdvertising set handle.
maxDurationMax duration for advertising (in units of 10ms) - 0 means no limit.
maxEventsMax number of events produced during advertising - 0 means no limit.
Returns
BLE_ERROR_NONE on success.
See also
EventHandler::onScanRequestReceived when a scan request is received.
EventHandler::onAdvertisingEnd when the advertising ends.
EventHandler::onConnectionComplete when the device gets connected by a peer.
ble_error_t startAdvertising ( void  )

Start the advertising procedure.

Returns
BLE_ERROR_NONE if the device started advertising successfully.
Deprecated:
Deprecated since addition of extended advertising support. Use startAdvertising(advertising_handle_t, adv_duration_t, uint8_t) instead.
ble_error_t startPeriodicAdvertising ( advertising_handle_t  handle)
inherited

Start periodic advertising for a given set.

Periodic advertising will not start until normal advertising is running but will continue to run after normal advertising has stopped.

Parameters
handleAdvertising set handle.
Returns
BLE_ERROR_NONE on success.
Version
5+
ble_error_t startRadioScan ( const GapScanningParams scanningParams)
protected

Start scanning procedure in the underlying BLE stack.

Parameters
[in]scanningParamsParameters of the scan procedure.
Returns
BLE_ERROR_NONE if the scan procedure was successfully started.
Deprecated:
Deprecated since addition of extended advertising support. Vendors should use the Cordio HCI interface or the ble::pal or implement startScan(duplicates_filter_t, scan_duration_t, period)

Start scanning.

Parameters
durationHow long to scan for. Special value 0 means scan forever.
filteringFiltering policy.
periodHow long to scan for in single period. If the period is 0 and duration is nonzero the scan will last for single duration.
Note
When the duration and period parameters are non-zero scanning will last for the duration within the period. After the scan period has expired a new scan period will begin and scanning. This will repeat until stopScan() is called.
Returns
BLE_ERROR_NONE on success.
See also
EventHandler::onAdvertisingReport to collect advertising reports.
EventHandler::onScanTimeout when scanning timeout.
ble_error_t startScan ( void(*)(const AdvertisementCallbackParams_t *params)  callback)

Start the scanning procedure.

Packets received during the scan procedure are forwarded to the scan packet handler passed as argument to this function.

Parameters
[in]callbackAdvertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Note
The parameters used by the procedure are defined by setScanParams().
Deprecated:
Deprecated since addition of extended advertising support. Use startScan(duplicates_filter_t, scan_duration_t, scan_period_t) instead.
ble_error_t startScan ( T *  object,
void(T::*)(const AdvertisementCallbackParams_t *params)  callbackMember 
)

Start the scanning procedure.

Packets received during the scan procedure are forwarded to the scan packet handler passed as argument to this function.

Parameters
[in]objectInstance used to invoke callbackMember.
[in]callbackMemberAdvertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback invoked from object.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Note
The parameters used by the procedure are defined by setScanParams().
Deprecated:
Deprecated since addition of extended advertising support. Use createAdvertisingSet().
Deprecated:
Deprecated since addition of extended advertising support. Use startScan(duplicates_filter_t, scan_duration_t, scan_period_t) instead.
ble_error_t stopAdvertising ( advertising_handle_t  handle)
inherited

Stop advertising given advertising set.

This is separate from periodic advertising which will not be affected.

Parameters
handleAdvertising set handle.
Returns
BLE_ERROR_NONE on success.
ble_error_t stopAdvertising ( void  )

Stop the ongoing advertising procedure.

Note
The current advertising parameters remain in effect.
Return values
BLE_ERROR_NONEif the advertising procedure has been successfully stopped.
Deprecated:
Deprecated since addition of extended advertising support. Use stopAdvertising(advertising_handle_t).
ble_error_t stopPeriodicAdvertising ( advertising_handle_t  handle)
inherited

Stop periodic advertising for a given set.

Parameters
handleAdvertising set handle.
Returns
BLE_ERROR_NONE on success.
Version
5+
ble_error_t stopScan ( )
inherited

Stop the ongoing scanning procedure.

The current scanning parameters remain in effect.

Return values
BLE_ERROR_NONEif successfully stopped scanning procedure.
ble_error_t terminateSync ( periodic_sync_handle_t  handle)
inherited

Stop reception of the periodic advertising identified by the handle.

Parameters
handlePeriodic advertising synchronisation handle.
Returns
BLE_ERROR_NONE on success.
ble_error_t updateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)

Update a particular field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.updateData(type, data, len);
gap.setAdvertisingPayload(payload);
Parameters
[in]typeId of the field to update.
[in]datadata buffer containing the new value of the field.
[in]lenLength of the data buffer.
Note
If advertisements are enabled, then the update takes effect immediately.
Returns
BLE_ERROR_NONE if the advertisement payload was updated based on matching AD type; otherwise, an appropriate error.
Deprecated:
Deprecated since addition of extended advertising support. Use ble::AdvertisingDataBuilder instead.
ble_error_t updateConnectionParams ( Handle_t  handle,
const ConnectionParams_t params 
)

Update connection parameters of an existing connection.

In the central role, this initiates a Link Layer connection parameter update procedure. In the peripheral role, this sends the corresponding L2CAP request and waits for the central to perform the procedure.

Parameters
[in]handleConnection Handle.
[in]paramsPointer to desired connection parameters.
Returns
BLE_ERROR_NONE if the connection parameters were updated correctly.
Deprecated:
Deprecated since addition of extended advertising support. Use updateConnectionParameters(connection_handle_t, conn_interval_t, conn_interval_t, slave_latency_t, supervision_timeout_t, conn_event_length_t, conn_event_length_t) instead.

Field Documentation

GapAdvertisingParams _advParams
protected

Current advertising parameters.

Definition at line 2449 of file Gap.h.

GapAdvertisingData _advPayload
protected

Current advertising data.

Definition at line 2454 of file Gap.h.

GapScanningParams _scanningParams
protected

Current scanning parameters.

Definition at line 2459 of file Gap.h.

GapAdvertisingData _scanResponse
protected

Current scan response.

Definition at line 2464 of file Gap.h.

const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN
static

Length (in octets) of the BLE MAC address.

Definition at line 111 of file Gap.h.

ConnectionEventCallbackChain_t connectionCallChain
protected

Callchain containing all registered callback handlers for connection events.

Definition at line 2503 of file Gap.h.

uint8_t connectionCount
protected

Number of open connections.

Definition at line 2469 of file Gap.h.

const central_privay_configuration_t default_central_privacy_configuration
staticinherited

Default peripheral privacy configuration.

Definition at line 1169 of file gap/Gap.h.

const peripheral_privacy_configuration_t default_peripheral_privacy_configuration
staticinherited

Default peripheral privacy configuration.

Definition at line 1163 of file gap/Gap.h.

DisconnectionEventCallbackChain_t disconnectionCallChain
protected

Callchain containing all registered callback handlers for disconnection events.

Definition at line 2509 of file Gap.h.

AdvertisementReportCallback_t onAdvertisementReport
protected

The registered callback handler for scanned advertisement packet notifications.

Definition at line 2497 of file Gap.h.

RadioNotificationEventCallback_t radioNotificationCallback
protected

The registered callback handler for radio notification events.

Definition at line 2491 of file Gap.h.

bool scanningActive
protected

Active scanning flag.

Definition at line 2479 of file Gap.h.

GapState_t state
protected

Current GAP state.

Definition at line 2474 of file Gap.h.

TimeoutEventCallbackChain_t timeoutCallbackChain
protected

Callchain containing all registered callback handlers for timeout events.

Definition at line 2486 of file Gap.h.

const uint16_t UNIT_1_25_MS = 1250
static

Number of microseconds in 1.25 milliseconds.

Definition at line 691 of file Gap.h.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.