Define device discovery, connection and link management procedures. More...
#include <Gap.h>
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 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 GapAdvertisingData & | getAdvertisingPayload (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... | |
| GapAdvertisingParams & | getAdvertisingParams (void) |
| Get the current advertising parameters. More... | |
| const GapAdvertisingParams & | getAdvertisingParams (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_t & | onTimeout () |
| 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_t & | onConnection () |
| 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_t & | onDisconnection () |
| 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_t & | onShutdown () |
| 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 ¶meters) |
| 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 ¶ms) |
| 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 ¶ms) |
| 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... | |
Define device discovery, connection and link management procedures.
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()).
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.
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.
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.
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 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 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.
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.
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.
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().
When supported by the host and controller you can select different modulation schemes (
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.
Address-type for BLEProtocol addresses.
| typedef BLEProtocol::AddressBytes_t Address_t |
48-bit address, LSB format.
| typedef BLEProtocol::AddressBytes_t address_t |
48-bit address, LSB format.
Address-type for BLEProtocol addresses.
| typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t |
Type of the callback handling scanned advertisement packets.
| typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t |
Callchain of connection event handlers.
| typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t *> DisconnectionEventCallbackChain_t |
Callchain of disconnection event handlers.
| typedef FunctionPointerWithContext<const LegacyGap *> GapShutdownCallback_t |
| typedef CallChainOfFunctionPointersWithContext<const LegacyGap *> GapShutdownCallbackChain_t |
Callchain of gap shutdown event handler.
| typedef ble::connection_handle_t Handle_t |
Opaque value type representing a connection handle.
It is used to identify to refer to a specific connection across Gap, GattClient and GattEvent API.
| typedef ble::phy_t Phy_t |
| typedef ble::phy_set_t PhySet_t |
| typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t |
Radio notification event handler.
Callchain of timeout event handlers.
Advertising policy filter modes.
Address-type for BLEProtocol addresses.
Enumeration of disconnection reasons.
| Enumerator | |
|---|---|
| AUTHENTICATION_FAILURE |
GAP or GATT failed to authenticate the peer. |
| CONNECTION_TIMEOUT |
The connection timed out.
|
| 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.
|
| CONN_INTERVAL_UNACCEPTABLE |
Connection parameters were unacceptable. |
Connection initiation policy filter mode.
| 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. |
| enum Role_t |
Enumeration of GAP roles.
| enum ScanningPolicyMode_t |
| enum TimeoutSource_t |
| ble_error_t accumulateAdvertisingPayload | ( | uint8_t | flags | ) |
Set gap flags in the advertising payload.
A call to this function is equivalent to:
| [in] | flags | The flags to be added. |
| ble_error_t accumulateAdvertisingPayload | ( | GapAdvertisingData::Appearance | app | ) |
Set the appearance field in the advertising payload.
A call to this function is equivalent to:
| [in] | app | The appearance to advertise. |
| 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:
| [in] | type | Identity of the field being added. |
| [in] | data | Buffer containing the value of the field. |
| [in] | len | Length of the data buffer. |
| ble_error_t accumulateAdvertisingPayloadTxPower | ( | int8_t | power | ) |
Set the Tx Power field in the advertising payload.
A call to this function is equivalent to:
| [in] | power | Transmit power in dBm used by the controller to advertise. |
| ble_error_t accumulateScanResponse | ( | GapAdvertisingData::DataType | type, |
| const uint8_t * | data, | ||
| uint8_t | len | ||
| ) |
Add a new field in the advertising payload.
| [in] | type | AD type identifier. |
| [in] | data | buffer containing AD data. |
| [in] | len | Length of the data buffer. |
|
inherited |
Add device to the periodic advertiser list.
Cannot be called when sync is ongoing.
| peerAddressType | Peer address type. |
| peerAddress | Peer address. |
| sid | Advertiser set identifier. |
|
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.
|
inherited |
Cancel sync attempt.
| void clearAdvertisingPayload | ( | void | ) |
Reset the value of the advertising payload advertised.
|
inherited |
Remove all devices from periodic advertiser list.
| void clearScanResponse | ( | void | ) |
Reset the content of the scan response.
| 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().
| [in] | peerAddr | MAC address of the peer. It must be in LSB format. |
| [in] | peerAddrType | Address type of the peer. It is usually obtained from advertising frames. |
| [in] | connectionParams | Connection parameters to use. |
| [in] | scanParams | Scan parameters used to find the peer. |
|
inherited |
Initiate a connection to a peer.
Once the connection is established an onConnectionComplete in the event handler will be called.
| peerAddressType | |
| peerAddress | |
| connectionParams |
| 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().
| [in] | peerAddr | MAC address of the peer. It must be in LSB format. |
| [in] | peerAddrType | Address type of the peer. |
| [in] | connectionParams | Connection parameters to use. |
| [in] | scanParams | Scan parameters used to find the peer. |
| 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.
|
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().
| [out] | handle | Advertising handle returned, valid only if function returned success. |
| parameters | Advertising parameters for the newly created set. |
|
inherited |
Synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.
| peerAddressType | Peer address type. |
| peerAddress | Peer address. |
| sid | Advertiser set identifier. |
| maxPacketSkip | Number of consecutive periodic advertising packets that the receiver may skip after successfully receiving a periodic advertising packet. |
| timeout | Maximum permitted time between successful receptions. If this time is exceeded, synchronisation is lost. |
|
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.
| maxPacketSkip | Number of consecutive periodic advertising packets that the receiver may skip after successfully receiving a periodic advertising packet. |
| timeout | Maximum permitted time between successful receives. If this time is exceeded, synchronisation is lost. |
|
inherited |
Remove the advertising set (resets its set parameters).
The advertising set must not be active.
| handle | Advertising set handle. |
| 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().
| [in] | reason | Reason of the disconnection transmitted to the peer. |
| [in] | connectionHandle | Handle of the connection to end. |
| ble_error_t disconnect | ( | DisconnectionReason_t | reason | ) |
Initiate a disconnection procedure.
| [in] | reason | The reason for disconnection; to be sent back to the peer. |
|
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.
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.
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.
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.
| [in] | enable | Should be set to true to enable the privacy mode and false to disable it. |
| ble_error_t getAddress | ( | BLEProtocol::AddressType_t * | typeP, |
| BLEProtocol::AddressBytes_t | address | ||
| ) |
Fetch the current address and its type.
| [out] | typeP | Type of the current address set. |
| [out] | address | Value of the current address. |
| GapAdvertisingParams& getAdvertisingParams | ( | void | ) |
Get the current advertising parameters.
| const GapAdvertisingParams& getAdvertisingParams | ( | void | ) | const |
Const alternative to Gap::getAdvertisingParams().
| const GapAdvertisingData& getAdvertisingPayload | ( | void | ) | const |
Get a reference to the current advertising payload.
| AdvertisingPolicyMode_t getAdvertisingPolicyMode | ( | void | ) | const |
Get the current advertising policy filter mode.
| ble_error_t getAppearance | ( | GapAdvertisingData::Appearance * | appearanceP | ) |
Get the value of the appearance characteristic in the GAP service.
| [out] | appearanceP | The current device-appearance value. |
|
inherited |
Get the privacy configuration used by the central role.
| [out] | configuration | The variable filled with the current configuration. |
| 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.
| [out] | deviceName | Pointer to an empty buffer where the UTF-8 non NULL-terminated string is placed. |
| [in,out] | lengthP | Length 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. |
| InitiatorPolicyMode_t getInitiatorPolicyMode | ( | void | ) | const |
Get the current initiator policy filter mode.
|
inherited |
Return maximum advertising data length you may set if advertising set is active.
|
inherited |
Return maximum advertising data length supported.
| uint16_t getMaxAdvertisingInterval | ( | void | ) | const |
Get the maximum advertising interval in milliseconds.
|
inherited |
Return currently available number of supported advertising sets.
This may change at runtime.
|
inherited |
Return maximum advertising data length supported for connectable advertising.
|
inherited |
Get number of devices that can be added to the periodic advertiser list.
| uint8_t getMaxWhitelistSize | ( | void | ) | const |
Get the maximum size of the whitelist.
| uint16_t getMinAdvertisingInterval | ( | void | ) | const |
Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types.
| uint16_t getMinNonConnectableAdvertisingInterval | ( | void | ) | const |
Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type.
|
inherited |
Get the privacy configuration used by the peripheral role.
| [out] | configuration | The variable filled with the current configuration. |
| void getPermittedTxPowerValues | ( | const int8_t ** | valueArrayPP, |
| size_t * | countP | ||
| ) |
Query the underlying stack for allowed Tx power values.
| [out] | valueArrayPP | Receive the immutable array of Tx values. |
| [out] | countP | Receive the array's size. |
| ble_error_t getPreferredConnectionParams | ( | ConnectionParams_t * | params | ) |
Returned the preferred connection parameters exposed in the GATT Generic Access Service.
| [out] | params | Structure where the parameters are stored. |
params.
|
static |
Return the type of a random address.
| [in] | address | The random address to retrieve the type from. The address must be ordered in little endian. |
| [out] | addressType | Type of the address to fill. |
| ScanningPolicyMode_t getScanningPolicyMode | ( | void | ) | const |
Get the current scan policy filter mode.
| GapState_t getState | ( | void | ) | const |
Get the current advertising and connection states of the device.
| 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.
| [in,out] | whitelist | Define the whitelist instance which is used to store the whitelist requested. In input, the caller provisions memory. |
| 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.
|
inherited |
Check if advertising is active for a given advertising set.
| handle | Advertising set handle. |
|
inherited |
Check controller support for a specific feature.
| feature | Feature to check. |
|
inherited |
Check if periodic advertising is active for a given advertising set.
| handle | Advertising set handle. |
|
protected |
Construct a Gap instance.
|
static |
| void onConnection | ( | ConnectionEventCallback_t | callback | ) |
Register a callback handling connection events.
| [in] | callback | Event handler being registered. |
| void onConnection | ( | T * | tptr, |
| void(T::*)(const ConnectionCallbackParams_t *) | mptr | ||
| ) |
Register a callback handling connection events.
| [in] | tptr | Instance used to invoke mptr. |
| [in] | mptr | Event handler being registered. |
| ConnectionEventCallbackChain_t& onConnection | ( | ) |
Get the callchain of registered connection event handlers.
| void onDisconnection | ( | DisconnectionEventCallback_t | callback | ) |
Register a callback handling disconnection events.
| [in] | callback | Event handler being registered. |
| void onDisconnection | ( | T * | tptr, |
| void(T::*)(const DisconnectionCallbackParams_t *) | mptr | ||
| ) |
Register a callback handling disconnection events.
| [in] | tptr | Instance used to invoke mptr. |
| [in] | mptr | Event handler being registered. |
| DisconnectionEventCallbackChain_t& onDisconnection | ( | ) |
Get the callchain of registered disconnection event handlers.
| 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.
| [in] | callback | Application handler to be invoked in response to a radio ACTIVE/INACTIVE event. |
| void onRadioNotification | ( | T * | tptr, |
| void(T::*)(bool) | mptr | ||
| ) |
Set the radio-notification events handler.
| [in] | tptr | Instance to be used to invoke mptr. |
| [in] | mptr | Application handler to be invoked in response to a radio ACTIVE/INACTIVE event. |
| 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().
| [in] | callback | Shutdown event handler to register. |
| void onShutdown | ( | T * | objPtr, |
| void(T::*)(const LegacyGap *) | memberPtr | ||
| ) |
| GapShutdownCallbackChain_t& onShutdown | ( | ) |
Access the callchain of shutdown event handler.
| void onTimeout | ( | TimeoutEventCallback_t | callback | ) |
Register a callback handling timeout events.
| [in] | callback | Event handler being registered. |
| TimeoutEventCallbackChain_t& onTimeout | ( | ) |
Get the callchain of registered timeout event handlers.
| 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.
| [in] | peerAddr | Address of the peer that has emitted the packet. |
| [in] | rssi | Value of the RSSI measured for the received packet. |
| [in] | isScanResponse | If true, then the packet is a response to a scan request. |
| [in] | type | Advertising type of the packet. |
| [in] | advertisingDataLen | Length of the advertisement data received. |
| [in] | advertisingData | Pointer to the advertisement packet's data. |
| [in] | addressType | Type of the address of the peer that has emitted the packet. |
| 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.
| [in] | peerAddr | Address of the peer that has emitted the packet. |
| [in] | rssi | Value of the RSSI measured for the received packet. |
| [in] | isScanResponse | If true, then the packet is a response to a scan request. |
| [in] | type | Advertising type of the packet. |
| [in] | advertisingDataLen | Length of the advertisement data received. |
| [in] | advertisingData | Pointer to the advertisement packet's data. |
| [in] | addressType | Type of the address of the peer that has emitted the packet. |
| 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.
| [in] | handle | Handle of the new connection. |
| [in] | role | Role of this BLE device in the connection. |
| [in] | peerAddrType | Address type of the connected peer. |
| [in] | peerAddr | Address of the connected peer. |
| [in] | ownAddrType | Address type this device uses for this connection. |
| [in] | ownAddr | Address this device uses for this connection. This parameter may be NULL if the local address is not available. |
| [in] | connectionParams | Parameters of the connection. |
| [in] | peerResolvableAddr | Resolvable address used by the peer. |
| [in] | localResolvableAddr | resolvable address used by the local device. |
| 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.
| [in] | handle | Handle of the new connection. |
| [in] | role | Role of this BLE device in the connection. |
| [in] | peerAddrType | Address type of the connected peer. |
| [in] | peerAddr | Address of the connected peer. |
| [in] | ownAddrType | Address type this device uses for this connection. |
| [in] | ownAddr | Address this device uses for this connection. |
| [in] | connectionParams | Parameters of the connection. |
| [in] | peerResolvableAddr | Resolvable address used by the peer. |
| [in] | localResolvableAddr | resolvable address used by the local device. |
| void processDisconnectionEvent | ( | Handle_t | handle, |
| DisconnectionReason_t | reason | ||
| ) |
Notify all registered disconnection event handlers of a disconnection event.
| [in] | handle | Handle of the terminated connection. |
| [in] | reason | Reason of the disconnection. |
| void processTimeoutEvent | ( | TimeoutSource_t | source | ) |
Notify the occurrence of a timeout event to all registered timeout events handler.
| [in] | source | Source of the timout event. |
|
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.
| connection | Handle of the connection for which the PHY being used is queried. |
|
inherited |
Remove device from the periodic advertiser list.
Cannot be called when sync is ongoing.
| peerAddressType | Peer address type. |
| peerAddress | Peer address. |
| sid | Advertiser set identifier. |
| 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.
| ble_error_t setActiveScanning | ( | bool | activeScanning | ) |
Enable or disable active scanning.
| [in] | activeScanning | If 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. |
| 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.
| [in] | type | Type of the address to set. |
| [in] | address | Value 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. |
| void setAdvertisingInterval | ( | uint16_t | interval | ) |
Set the advertising interval.
| [in] | interval | Advertising 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.
|
inherited |
Set advertising parameters of an existing set.
| handle | Advertising set handle. |
| params | New advertising parameters. |
| void setAdvertisingParams | ( | const GapAdvertisingParams & | newParams | ) |
Set the advertising parameters.
| [in] | newParams | The new advertising parameters. |
|
inherited |
Set new advertising payload for a given advertising set.
| handle | Advertising set handle. |
| payload | Advertising payload. |
| ble_error_t setAdvertisingPayload | ( | const GapAdvertisingData & | payload | ) |
Set the value of the payload advertised.
| [in] | payload | A reference to a user constructed advertisement payload to set. |
| ble_error_t setAdvertisingPolicyMode | ( | AdvertisingPolicyMode_t | mode | ) |
Set the advertising policy filter mode to be used during the next advertising procedure.
| [in] | mode | New advertising policy filter mode. |
|
inherited |
Set new advertising scan response for a given advertising set.
This will be sent to device who perform active scanning.
| handle | Advertising set handle. |
| response | Advertising scan response. |
| void setAdvertisingTimeout | ( | uint16_t | timeout | ) |
Set the advertising duration.
A timeout event is genenerated once the advertising period expired.
| [in] | timeout | Advertising timeout (in seconds) between 0x1 and 0x3FFF. The special value 0 may be used to disable the advertising timeout. |
| void setAdvertisingType | ( | GapAdvertisingParams::AdvertisingType_t | advType | ) |
Set the advertising type to use during the advertising procedure.
| [in] | advType | New type of advertising to use. |
| ble_error_t setAppearance | ( | GapAdvertisingData::Appearance | appearance | ) |
Set the value of the appearance characteristic in the GAP service.
| [in] | appearance | The new value for the device-appearance. |
|
inherited |
Set the privacy configuration used by the central role.
| [in] | configuration | The configuration to set. |
| ble_error_t setDeviceName | ( | const uint8_t * | deviceName | ) |
Set the value of the device name characteristic in the Generic Access Service.
| [in] | deviceName | The new value for the device-name. This is a UTF-8 encoded, NULL-terminated string. |
|
inherited |
Assign the event handler implementation that will be used by the gap module to signal events back to the application.
| handler | Application implementation of an EventHandler. |
| ble_error_t setInitiatorPolicyMode | ( | InitiatorPolicyMode_t | mode | ) |
Set the initiator policy filter mode to be used during the next connection initiation.
| [in] | mode | New initiator policy filter mode. |
|
inherited |
Set periodic advertising parameters for a given advertising set.
| handle | Advertising set handle. |
| periodicAdvertisingIntervalMin | Minimum interval for periodic advertising. |
| periodicAdvertisingIntervalMax | Maximum interval for periodic advertising. |
| advertiseTxPower | Include transmission power in the advertisements. |
|
inherited |
Set new periodic advertising payload for a given advertising set.
| handle | Advertising set handle. |
| payload | Advertising payload. |
|
inherited |
Set the privacy configuration used by the peripheral role.
| [in] | configuration | The configuration to set. |
|
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.
| connection | Handle of the connection to update. |
| txPhys | Set of PHYs preferred for tx operations. If NULL then the choice is up to the Bluetooth subsystem. |
| rxPhys | Set of PHYs preferred for rx operations. If NULL then the choice is up to the Bluetooth subsystem. |
| codedSymbol | Number 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. |
| 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.
| [in] | params | Value of the preferred connection parameters. |
|
inherited |
Set the preferred PHYs to use in a connection.
| txPhys | Set of PHYs preferred for tx operations. If NULL then no preferred PHYs are set and the default value of the subsystem is used. |
| rxPhys | Set of PHYs preferred for rx operations. If NULL then no preferred PHYs are set and the default value of the subsystem is used. |
| ble_error_t setScanInterval | ( | uint16_t | interval | ) |
Set the interval parameter used during scanning procedures.
| [in] | interval | Interval 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. |
| ble_error_t setScanningPolicyMode | ( | ScanningPolicyMode_t | mode | ) |
Set the scan policy filter mode to be used during the next scan procedure.
| [in] | mode | New scan policy filter mode. |
|
inherited |
Set new scan parameters.
| params | Scan parameters, |
| 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.
| [in] | interval | 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. |
| [in] | window | Period in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s. |
| [in] | timeout | Duration in seconds of the scan procedure if any. The special value 0 disable specific duration of the scan procedure. |
| [in] | activeScanning | If 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. |
| ble_error_t setScanParams | ( | const GapScanningParams & | scanningParams | ) |
Set the parameters used during a scan procedure.
| [in] | scanningParams | Parameter struct containing the interval, period, timeout and active scanning toggle. |
| ble_error_t setScanTimeout | ( | uint16_t | timeout | ) |
Set the timeout parameter used during scanning procedures.
| [in] | timeout | Duration in seconds of the scan procedure if any. The special value 0 disables specific duration of the scan procedure. |
| ble_error_t setScanWindow | ( | uint16_t | window | ) |
Set the window parameter used during scanning procedures.
| [in] | window | Period in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s. |
| ble_error_t setTxPower | ( | int8_t | txPower | ) |
Set the radio's transmit power.
| [in] | txPower | Radio's transmit power in dBm. |
| ble_error_t setWhitelist | ( | const Whitelist_t & | whitelist | ) |
Set the value of the whitelist to be used during GAP procedures.
| [in] | whitelist | A reference to a whitelist containing the addresses to be copied to the internal whitelist. |
|
inherited |
Start advertising using the given advertising set.
| handle | Advertising set handle. |
| maxDuration | Max duration for advertising (in units of 10ms) - 0 means no limit. |
| maxEvents | Max number of events produced during advertising - 0 means no limit. |
| ble_error_t startAdvertising | ( | void | ) |
Start the advertising procedure.
|
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.
| handle | Advertising set handle. |
|
protected |
Start scanning procedure in the underlying BLE stack.
| [in] | scanningParams | Parameters of the scan procedure. |
|
inherited |
Start scanning.
| duration | How long to scan for. Special value 0 means scan forever. |
| filtering | Filtering policy. |
| period | How long to scan for in single period. If the period is 0 and duration is nonzero the scan will last for single duration. |
| 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.
| [in] | callback | Advertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback. |
| 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.
| [in] | object | Instance used to invoke callbackMember. |
| [in] | callbackMember | Advertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback invoked from object. |
|
inherited |
Stop advertising given advertising set.
This is separate from periodic advertising which will not be affected.
| handle | Advertising set handle. |
| ble_error_t stopAdvertising | ( | void | ) |
Stop the ongoing advertising procedure.
| BLE_ERROR_NONE | if the advertising procedure has been successfully stopped. |
|
inherited |
Stop periodic advertising for a given set.
| handle | Advertising set handle. |
|
inherited |
Stop the ongoing scanning procedure.
The current scanning parameters remain in effect.
| BLE_ERROR_NONE | if successfully stopped scanning procedure. |
|
inherited |
Stop reception of the periodic advertising identified by the handle.
| handle | Periodic advertising synchronisation handle. |
| 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:
| [in] | type | Id of the field to update. |
| [in] | data | data buffer containing the new value of the field. |
| [in] | len | Length of the data buffer. |
| 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.
| [in] | handle | Connection Handle. |
| [in] | params | Pointer to desired connection parameters. |
|
protected |
|
protected |
|
protected |
|
protected |
|
static |
|
protected |
|
protected |
|
staticinherited |
|
staticinherited |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |