Mbed OS Reference
Loading...
Searching...
No Matches
Gap Class Reference

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

#include <Gap.h>

Data Structures

struct  EventHandler
 Definition of the general handler of Gap related events. More...
 
struct  PreferredConnectionParams_t
 Preferred connection parameter display in Generic Access Service. More...
 

Public Types

typedef FunctionPointerWithContext< const Gap * > GapShutdownCallback_t
 Gap shutdown event handler. More...
 
typedef CallChainOfFunctionPointersWithContext< const Gap * > GapShutdownCallbackChain_t
 Callchain of gap shutdown event handler. More...
 

Public Member Functions

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_privacy_configuration_t *configuration)
 Set the privacy configuration used by the central role. More...
 
ble_error_t getCentralPrivacyConfiguration (central_privacy_configuration_t *configuration)
 Get the privacy configuration used by the central role. More...
 
uint8_t getMaxWhitelistSize () 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 getAddress (own_address_type_t &typeP, address_t &address)
 Fetch the current address and its type. More...
 
ble_error_t reset ()
 Reset the Gap instance. 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 Gap *))
 Register a Gap shutdown event handler. More...
 
GapShutdownCallbackChain_tonShutdown ()
 Access the callchain of shutdown event handler. More...
 

Static Public Member Functions

static ble_error_t getRandomAddressType (ble::address_t address, ble::random_address_type_t *addressType)
 Return the type of a random address. More...
 

Detailed Description

Define device discovery, connection and link management procedures.

  • Device discovery: A device can advertise to nearby peers its existence, identity and capabilities. Similarly, a device can scan its environment to find advertising peers. The information acquired during the scan helps to identify peers and understand their use. A scanner may acquire more information about an advertising peer by sending a scan request. If the peer accepts scan requests, it may reply with additional information about its state.
  • Connection: A bluetooth device can establish a connection to a connectable advertising peer. Once the connection is established, both devices can communicate using the GATT protocol. The GATT protocol allows connected devices to expose a set of states that the other peer can discover, read and write.
  • Link Management: Connected devices may drop the connection and may adjust connection parameters according to the power envelop needed for their application.
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();
Abstract away BLE-capable radio transceivers or SOCs.
Definition: BLE.h:137
ble::Gap & gap()
Accessor to Gap.
Define device discovery, connection and link management procedures.
Definition: Gap.h:282
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 282 of file Gap.h.

Member Typedef Documentation

◆ GapShutdownCallback_t

Gap shutdown event handler.

See also
Gap::onShutdown().

Definition at line 289 of file Gap.h.

◆ GapShutdownCallbackChain_t

Callchain of gap shutdown event handler.

See also
Gap::onShutdown().

Definition at line 297 of file Gap.h.

Member Function Documentation

◆ setEventHandler()

void setEventHandler ( EventHandler handler)

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.
Note
Multiple discrete EventHandler instances may be used by adding them to a ChainableGapEventHandler and then setting the chain as the primary Gap EventHandler using this function.
See also
ChainableGapEventHandler

◆ isFeatureSupported()

bool isFeatureSupported ( controller_supported_features_t  feature)

Check controller support for a specific feature.

Parameters
featureFeature to check.
Returns
True if feature is supported.

◆ getMaxAdvertisingSetNumber()

uint8_t getMaxAdvertisingSetNumber ( )

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.

◆ getMaxAdvertisingDataLength()

uint16_t getMaxAdvertisingDataLength ( )

Return maximum advertising data length supported.

Returns
Maximum advertising data length supported.

◆ getMaxConnectableAdvertisingDataLength()

uint16_t getMaxConnectableAdvertisingDataLength ( )

Return maximum advertising data length supported for connectable advertising.

Returns
Maximum advertising data length supported for connectable advertising.

◆ getMaxActiveSetAdvertisingDataLength()

uint16_t getMaxActiveSetAdvertisingDataLength ( )

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.

◆ createAdvertisingSet()

ble_error_t createAdvertisingSet ( advertising_handle_t *  handle,
const AdvertisingParameters parameters 
)

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+

◆ destroyAdvertisingSet()

ble_error_t destroyAdvertisingSet ( advertising_handle_t  handle)

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+

◆ setAdvertisingParameters()

ble_error_t setAdvertisingParameters ( advertising_handle_t  handle,
const AdvertisingParameters params 
)

Set advertising parameters of an existing set.

Parameters
handleAdvertising set handle.
paramsNew advertising parameters.
Returns
BLE_ERROR_NONE on success.

◆ setAdvertisingPayload()

ble_error_t setAdvertisingPayload ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  payload 
)

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.

◆ setAdvertisingScanResponse()

ble_error_t setAdvertisingScanResponse ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  response 
)

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.

◆ startAdvertising()

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.

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. This does not guarantee the set has started if extended advertising is enabled. Register an event handler and wait for onAdvertisingStart event. An (unlikely) failed start the status of the event will contain an error.
See also
EventHandler::onAdvertisingStart when the advertising starts.
EventHandler::onScanRequestReceived when a scan request is received.
EventHandler::onAdvertisingEnd when the advertising ends.
EventHandler::onConnectionComplete when the device gets connected by a peer.

◆ stopAdvertising()

ble_error_t stopAdvertising ( advertising_handle_t  handle)

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. For extented advertising this does not guarantee the set is stopped if. Register an event handler and wait for onAdvertisingEnd event. An (unlikely) failed stop the event status will contain the error code.

◆ isAdvertisingActive()

bool isAdvertisingActive ( advertising_handle_t  handle)

Check if advertising is active for a given advertising set.

Parameters
handleAdvertising set handle.
Returns
True if advertising is active on this set.

◆ setPeriodicAdvertisingParameters()

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.

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+

◆ setPeriodicAdvertisingPayload()

ble_error_t setPeriodicAdvertisingPayload ( advertising_handle_t  handle,
mbed::Span< const uint8_t >  payload 
)

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+

◆ startPeriodicAdvertising()

ble_error_t startPeriodicAdvertising ( advertising_handle_t  handle)

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+

◆ stopPeriodicAdvertising()

ble_error_t stopPeriodicAdvertising ( advertising_handle_t  handle)

Stop periodic advertising for a given set.

Parameters
handleAdvertising set handle.
Returns
BLE_ERROR_NONE on success.
Version
5+

◆ isPeriodicAdvertisingActive()

bool isPeriodicAdvertisingActive ( advertising_handle_t  handle)

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+

◆ setScanParameters()

ble_error_t setScanParameters ( const ScanParameters params)

Set new scan parameters.

Parameters
paramsScan parameters,
See also
GapScanParameters for details.
Returns
BLE_ERROR_NONE on success.

◆ startScan()

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.

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.

◆ stopScan()

ble_error_t stopScan ( )

Stop the ongoing scanning procedure.

The current scanning parameters remain in effect.

Return values
BLE_ERROR_NONEif successfully stopped scanning procedure.

◆ createSync() [1/2]

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.

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+

◆ createSync() [2/2]

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.

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+

◆ cancelCreateSync()

ble_error_t cancelCreateSync ( )

Cancel sync attempt.

Returns
BLE_ERROR_NONE on success.

◆ terminateSync()

ble_error_t terminateSync ( periodic_sync_handle_t  handle)

Stop reception of the periodic advertising identified by the handle.

Parameters
handlePeriodic advertising synchronisation handle.
Returns
BLE_ERROR_NONE on success.

◆ addDeviceToPeriodicAdvertiserList()

ble_error_t addDeviceToPeriodicAdvertiserList ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
advertising_sid_t  sid 
)

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.

◆ removeDeviceFromPeriodicAdvertiserList()

ble_error_t removeDeviceFromPeriodicAdvertiserList ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
advertising_sid_t  sid 
)

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.

◆ clearPeriodicAdvertiserList()

ble_error_t clearPeriodicAdvertiserList ( )

Remove all devices from periodic advertiser list.

Returns
BLE_ERROR_NONE on success.

◆ getMaxPeriodicAdvertiserListSize()

uint8_t getMaxPeriodicAdvertiserListSize ( )

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.

◆ connect()

ble_error_t connect ( peer_address_type_t  peerAddressType,
const address_t peerAddress,
const ConnectionParameters connectionParams 
)

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.

◆ cancelConnect()

ble_error_t cancelConnect ( )

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. Returns BLE_ERROR_OPERATION_NOT_PERMITTED if no ongoing connection for last used address found.

◆ readPhy()

ble_error_t readPhy ( connection_handle_t  connection)

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.

◆ setPreferredPhys()

ble_error_t setPreferredPhys ( const phy_set_t txPhys,
const phy_set_t rxPhys 
)

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+

◆ setPhy()

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.

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.

◆ enablePrivacy()

ble_error_t enablePrivacy ( bool  enable)

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.

Initialization of the privacy subsystem

When privacy is enabled, the system generates new resolvable and non resolvable private addresses. Scan, Advertising and Connecting to a peer won't be available until the generation process completes. When addresses have been generated, the application is notified that privacy initialisation as completed with a call to EventHandler::onPrivacyEnabled .

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.
See also
EventHandler::onPrivacyEnabled()

◆ setPeripheralPrivacyConfiguration()

ble_error_t setPeripheralPrivacyConfiguration ( const peripheral_privacy_configuration_t *  configuration)

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.

◆ getPeripheralPrivacyConfiguration()

ble_error_t getPeripheralPrivacyConfiguration ( peripheral_privacy_configuration_t *  configuration)

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.

◆ setCentralPrivacyConfiguration()

ble_error_t setCentralPrivacyConfiguration ( const central_privacy_configuration_t *  configuration)

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.

◆ getCentralPrivacyConfiguration()

ble_error_t getCentralPrivacyConfiguration ( central_privacy_configuration_t *  configuration)

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.

◆ getMaxWhitelistSize()

uint8_t getMaxWhitelistSize ( ) const

Get the maximum size of the whitelist.

Returns
Maximum size of the whitelist.

◆ getWhitelist()

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.

◆ setWhitelist()

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 non-resolvable addresses. 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.

◆ getAddress()

ble_error_t getAddress ( own_address_type_t &  typeP,
address_t address 
)

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.

◆ getRandomAddressType()

static ble_error_t getRandomAddressType ( ble::address_t  address,
ble::random_address_type_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.

◆ reset()

ble_error_t reset ( )

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.

◆ onShutdown() [1/3]

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).

◆ onShutdown() [2/3]

void onShutdown ( T *  objPtr,
void(T::*)(const Gap *)  memberPtr 
)

Register a Gap shutdown event handler.

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

Definition at line 1465 of file Gap.h.

◆ onShutdown() [3/3]

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.