Mistake on this page?
Report an issue in GitHub or email us

GAP

Note: Some functions, variables or types have been deprecated. Please see the class reference linked below for details.

The Generic Access Profile is the layer of the stack that handles connectivity tasks. This includes link establishment and termination, advertising and scanning.

Devices with data to publish can use GAP to advertise. They can include the data in the advertisement itself, inside the scan response, or leave a peer device to query it after the connection has been established.

The other side of the process is the act of scanning, which listens for advertisements, allows you to query the advertisers for more data through a scan request or connect in order to query the peer device for the data you want.

Advertising, scanning and connection all have parameters that let you find a compromise between desired power consumption levels, latency and efficiency of these processes.

Advertising

Advertising consists of broadcasting at a regular interval a small amount of data containing valuable information about the device. Peer devices listening on BLE advertising channels may scan these packets.

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

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, it sends scan request to scannable advertisers and collects their scan responses.

Extended and periodic advertising

BLE controllers supporting Bluetooth 5.0 may offer additional advertising and scanning options. Use isFeatureSupported() to check feature availability.

Extended advertising may use multiple PHYs and spread the payload across many packets. This allows for much larger payloads. In this scenario, advertising is split across primary advertising on the advertising channels and secondary advertising using channels normally used for sending data to connected devices.

Similarly, if the controller supports periodic advertising, you may use periodic advertising to send changing data to many peers. Each peer needs to scan the advertisements on the primary channels and create a sync with a periodic advertisement it's interested in.

There may be many advertising sets active at one time on a single advertiser. This allows it to advertise different data at the same time, possibly to different peers.

Devices that do not support extended and periodic advertising will not see these advertisements. You may use legacy advertising alongside extended advertising, running at the same time, to support older devices in the environment.

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. The SecurityManager handles this and relies on the other device accepting and storing the IRK.

You need to enable privacy by calling enablePrivacy() after initializing the SecurityManager because privacy requires SecurityManager to handle IRKs. Set the behavior of privacy enabled devices by using setCentralPrivacyConfiguration(), which specifies what the device should be with devices using random addresses, and setPeripheralPrivacyConfiguration. Random addresses that privacy enabled devices generate can be of two types: resolvable (by devices who have the IRK) and unresolvable. You can't use unresolvable addresses for connecting and connectable advertising; therefore, use a resolvable one for these, regardless of the privacy configuration.

Modulation schemes

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

  • LE 1M PHY.
  • LE 2M PHY.
  • LE coded PHY.

These provide different compromises between bandwidth, power usage and error resiliency (see BLUETOOTH SPECIFICATION Version 5.0 Vol 1, Part A - 1.2).

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. 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 returns 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 the controller or the peer may trigger autonomously.

Data length (over-the-air MTU)

In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.

There are two separate MTUs to consider: the ATT_MTU (maximum attribute size) and data length. GattServer and GattClient affect ATT_MTU. Gap only deals with data length, which is the maximum size of the packet that carries attributes that are fragmented across many such packets.

The default value of data length supported by all controllers is 23 octets. If both controllers support data length extension and a higher value is negotiated, the BLE stack will call onDataLengthChange in the Gap::EventHandler registered by the user.

ATT_MTU and data length are independent of each other.

GAP class reference

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

GAP example

Here is an example demonstrating how to use the GAP API to advertise, scan, connect and disconnect and how parameters influence efficiency of these actions.

/* mbed Microcontroller Library
 * Copyright (c) 2006-2018 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include <events/mbed_events.h>
#include "ble/BLE.h"
#include "pretty_printer.h"
#include "mbed-trace/mbed_trace.h"

/** This example demonstrates all the basic setup required
 *  to advertise and scan.
 *
 *  It contains a single class that performs both scans and advertisements.
 *
 *  The demonstrations happens in sequence, after each "mode" ends
 *  the demo jumps to the next mode to continue.
 *
 *  You may connect to the device during advertising and if you advertise
 *  this demo will try to connect during the scanning phase. Connection
 *  will terminate the phase early. At the end of the phase some stats
 *  will be shown about the phase.
 */

/* demo config */
/* you can adjust these parameters and see the effect on the performance */

/* Advertising parameters are mainly defined by an advertising type and
 * and an interval between advertisements. Lower interval increases the
 * chances of being seen at the cost of increased power usage.
 *
 * The Bluetooth controller may run concurrent operations with the radio;
 * to help it, a minimum and maximum advertising interval should be
 * provided.
 *
 * Most bluetooth time units are specific to each operation. For example
 * adv_interval_t is expressed in multiples of 625 microseconds. If precision
 * is not require you may use a conversion from milliseconds.
 */
static const ble::AdvertisingParameters advertising_params(
    ble::advertising_type_t::CONNECTABLE_UNDIRECTED,
    ble::adv_interval_t(ble::millisecond_t(25)), /* this could also be expressed as ble::adv_interval_t(40) */
    ble::adv_interval_t(ble::millisecond_t(50)) /* this could also be expressed as ble::adv_interval_t(80) */
);

/* if the controller support it we can advertise multiple sets */
static const ble::AdvertisingParameters extended_advertising_params(
    ble::advertising_type_t::NON_CONNECTABLE_UNDIRECTED,
    ble::adv_interval_t(600),
    ble::adv_interval_t(800)
);

static const std::chrono::milliseconds advertising_duration = 10000ms;

/* Scanning happens repeatedly and is defined by:
 *  - The scan interval which is the time (in 0.625us) between each scan cycle.
 *  - The scan window which is the scanning time (in 0.625us) during a cycle.
 * If the scanning process is active, the local device sends scan requests
 * to discovered peer to get additional data.
 */
static const ble::ScanParameters scan_params(
    ble::phy_t::LE_1M,
    ble::scan_interval_t(80),
    ble::scan_window_t(60),
    false /* active scanning */
);

static const ble::scan_duration_t scan_duration(ble::millisecond_t(10000));

/* config end */

events::EventQueue event_queue;

using namespace std::chrono;
using std::milli;
using namespace std::literals::chrono_literals;

/* Delay between steps */
static const std::chrono::milliseconds delay = 3000ms;

/** Demonstrate advertising, scanning and connecting */
class GapDemo : private mbed::NonCopyable<GapDemo>, public ble::Gap::EventHandler
{
public:
    GapDemo(BLE& ble, events::EventQueue& event_queue) :
        _ble(ble),
        _gap(ble.gap()),
        _event_queue(event_queue)
    {
    }

    ~GapDemo()
    {
        if (_ble.hasInitialized()) {
            _ble.shutdown();
        }
    }

    /** Start BLE interface initialisation */
    void run()
    {
        /* handle gap events */
        _gap.setEventHandler(this);

        ble_error_t error = _ble.init(this, &GapDemo::on_init_complete);
        if (error) {
            print_error(error, "Error returned by BLE::init");
            return;
        }

        /* this will not return until shutdown */
        _event_queue.dispatch_forever();
    }

private:
    /** This is called when BLE interface is initialised and starts the first mode */
    void on_init_complete(BLE::InitializationCompleteCallbackContext *event)
    {
        if (event->error) {
            print_error(event->error, "Error during the initialisation");
            return;
        }

        print_mac_address();

        /* setup the default phy used in connection to 2M to reduce power consumption */
        if (_gap.isFeatureSupported(ble::controller_supported_features_t::LE_2M_PHY)) {
            ble::phy_set_t phys(/* 1M */ false, /* 2M */ true, /* coded */ false);

            ble_error_t error = _gap.setPreferredPhys(/* tx */&phys, /* rx */&phys);

            /* PHY 2M communication will only take place if both peers support it */
            if (error) {
                print_error(error, "GAP::setPreferedPhys failed");
            }
        } else {
            /* otherwise it will use 1M by default */
        }

        /* all calls are serialised on the user thread through the event queue */
        _event_queue.call(this, &GapDemo::advertise);
    }

    /** Set up and start advertising */
    void advertise()
    {
        ble_error_t error = _gap.setAdvertisingParameters(ble::LEGACY_ADVERTISING_HANDLE, advertising_params);
        if (error) {
            print_error(error, "Gap::setAdvertisingParameters() failed");
            return;
        }

        /* to create a payload we'll use a helper class that builds a valid payload */
        /* AdvertisingDataSimpleBuilder is a wrapper over AdvertisingDataBuilder that allocated the buffer for us */
        ble::AdvertisingDataSimpleBuilder<ble::LEGACY_ADVERTISING_MAX_SIZE> data_builder;

        /* builder methods can be chained together as they return the builder object */
        data_builder.setFlags().setName("Legacy Set");

        /* Set payload for the set */
        error = _gap.setAdvertisingPayload(ble::LEGACY_ADVERTISING_HANDLE, data_builder.getAdvertisingData());
        if (error) {
            print_error(error, "Gap::setAdvertisingPayload() failed");
            return;
        }

        /* Start advertising the set */
        error = _gap.startAdvertising(ble::LEGACY_ADVERTISING_HANDLE);
        if (error) {
            print_error(error, "Gap::startAdvertising() failed");
            return;
        }

        printf(
            "\r\nAdvertising started (type: 0x%x, interval: [%d : %d]ms)\r\n",
            advertising_params.getType(),
            advertising_params.getMinPrimaryInterval().valueInMs(),
            advertising_params.getMaxPrimaryInterval().valueInMs()
        );

#if BLE_FEATURE_EXTENDED_ADVERTISING
        /* if we support extended advertising we'll also additionally advertise another set at the same time */
        if (_gap.isFeatureSupported(ble::controller_supported_features_t::LE_EXTENDED_ADVERTISING)) {
            /* With Bluetooth 5; it is possible to advertise concurrently multiple
             * payloads at different rate. The combination of payload and its associated
             * parameters is named an advertising set. To refer to these advertising
             * sets the Bluetooth system use an advertising set handle that needs to
             * be created first.
             * The only exception is the legacy advertising handle which is usable
             * on Bluetooth 4 and Bluetooth 5 system. It is created at startup and
             * its lifecycle is managed by the system.
             */
            ble_error_t error = _gap.createAdvertisingSet(&_extended_adv_handle, extended_advertising_params);
            if (error) {
                print_error(error, "Gap::createAdvertisingSet() failed");
                return;
            }

            /* we can reuse the builder, we just replace the name */
            data_builder.setName("Extended Set");

            /* Set payload for the set */
            error = _gap.setAdvertisingPayload(_extended_adv_handle, data_builder.getAdvertisingData());
            if (error) {
                print_error(error, "Gap::setAdvertisingPayload() failed");
                return;
            }

            /* Start advertising the set */
            error = _gap.startAdvertising(_extended_adv_handle);
            if (error) {
                print_error(error, "Gap::startAdvertising() failed");
                return;
            }

            printf(
                "Advertising started (type: 0x%x, interval: [%d : %d]ms)\r\n",
                extended_advertising_params.getType(),
                extended_advertising_params.getMinPrimaryInterval().valueInMs(),
                extended_advertising_params.getMaxPrimaryInterval().valueInMs()
            );
        }
#endif // BLE_FEATURE_EXTENDED_ADVERTISING

        _demo_duration.reset();
        _demo_duration.start();

        /* this will stop advertising if no connection takes place in the meantime */
        _cancel_handle = _event_queue.call_in(advertising_duration, [this]{ end_advertising_mode(); });
    }

    /** Set up and start scanning */
    void scan()
    {
        ble_error_t error = _gap.setScanParameters(scan_params);
        if (error) {
            print_error(error, "Error caused by Gap::setScanParameters");
            return;
        }

        /* start scanning and attach a callback that will handle advertisements
         * and scan requests responses */
        error = _gap.startScan(scan_duration);
        if (error) {
            print_error(error, "Error caused by Gap::startScan");
            return;
        }

        printf("\r\nScanning started (interval: %dms, window: %dms, timeout: %dms).\r\n",
               scan_params.get1mPhyConfiguration().getInterval().valueInMs(),
               scan_params.get1mPhyConfiguration().getWindow().valueInMs(),
               scan_duration.valueInMs());

        _demo_duration.reset();
        _demo_duration.start();
    }

    /* helper function to hide the casts */
    int read_demo_duration_in_ms()
    {
        return duration_cast<duration<int, milli>>(_demo_duration.elapsed_time()).count();
    }

private:
    /* Gap::EventHandler */

    /** Look at scan payload to find a peer device and connect to it */
    void onAdvertisingReport(const ble::AdvertisingReportEvent &event) override
    {
        /* keep track of scan events for performance reporting */
        _scan_count++;

        /* don't bother with analysing scan result if we're already connecting */
        if (_is_connecting) {
            return;
        }

        /* only look at events from devices at a close range */
        if (event.getRssi() < -65) {
            return;
        }

        ble::AdvertisingDataParser adv_parser(event.getPayload());

        /* parse the advertising payload, looking for a discoverable device */
        while (adv_parser.hasNext()) {
            ble::AdvertisingDataParser::element_t field = adv_parser.next();

            /* skip non discoverable device */
            if (field.type != ble::adv_data_type_t::FLAGS ||
                field.value.size() != 1 ||
                !ble::adv_data_flags_t(field.value[0]).getGeneralDiscoverable()) {
                continue;
            }

            /* connect to a discoverable device */

            /* abort timeout as the mode will end on disconnection */
            _event_queue.cancel(_cancel_handle);

            printf("We found a connectable device\r\n");
            ble_error_t error = _gap.connect(
                event.getPeerAddressType(),
                event.getPeerAddress(),
                ble::ConnectionParameters() // use the default connection parameters
            );
            if (error) {
                print_error(error, "Error caused by Gap::connect");
                return;
            }

            /* we may have already scan events waiting
             * to be processed so we need to remember
             * that we are already connecting and ignore them */
            _is_connecting = true;
            return;
        }
    }

    void onAdvertisingEnd(const ble::AdvertisingEndEvent &event) override
    {
        ble::advertising_handle_t adv_handle = event.getAdvHandle();
        if (event.getStatus() == BLE_ERROR_UNSPECIFIED) {
            printf("Error: Failed to stop advertising set %d\r\n", adv_handle);
        } else {
            printf("Stopped advertising set %d\r\n", adv_handle);

            if (event.getStatus() == BLE_ERROR_TIMEOUT) {
                printf("Stopped due to timeout\r\n");
            } else if (event.getStatus() == BLE_ERROR_LIMIT_REACHED) {
                printf("Stopped due to max number of adv events reached\r\n");
            } else if (event.getStatus() == BLE_ERROR_NONE) {
                if (event.isConnected()) {
                    printf("Stopped early due to connection\r\n");
                } else {
                    printf("Stopped due to user request\r\n");
                }
            }
        }

#if BLE_FEATURE_EXTENDED_ADVERTISING
        if (event.getAdvHandle() == _extended_adv_handle) {
            /* we were waiting for it to stop before destroying it and starting scanning */
            ble_error_t error = _gap.destroyAdvertisingSet(_extended_adv_handle);
            if (error) {
                print_error(error, "Error caused by Gap::destroyAdvertisingSet");
            }

            _extended_adv_handle = ble::INVALID_ADVERTISING_HANDLE;

            _is_in_scanning_phase = true;

            _event_queue.call_in(delay, [this]{ scan(); });
        }
#endif //BLE_FEATURE_EXTENDED_ADVERTISING
    }

    void onAdvertisingStart(const ble::AdvertisingStartEvent &event) override
    {
        printf("Advertising set %d started\r\n", event.getAdvHandle());
    }

    void onScanTimeout(const ble::ScanTimeoutEvent&) override
    {
        printf("Stopped scanning due to timeout parameter\r\n");
        _event_queue.call(this, &GapDemo::end_scanning_mode);
    }

    /** This is called by Gap to notify the application we connected,
     *  in our case it immediately disconnects */
    void onConnectionComplete(const ble::ConnectionCompleteEvent &event) override
    {
        _is_connecting = false;
        _demo_duration.stop();

#if BLE_FEATURE_EXTENDED_ADVERTISING
        if (!_is_in_scanning_phase) {
            /* if we have more than one advertising sets one of them might still be active */
            if (_extended_adv_handle != ble::INVALID_ADVERTISING_HANDLE) {
                /* if it's still active, stop it */
                if (_gap.isAdvertisingActive(_extended_adv_handle)) {
                    _gap.stopAdvertising(_extended_adv_handle);
                } else if (_gap.isAdvertisingActive(ble::LEGACY_ADVERTISING_HANDLE)) {
                    _gap.stopAdvertising(ble::LEGACY_ADVERTISING_HANDLE);
                }
            }
        }
#endif // BLE_FEATURE_EXTENDED_ADVERTISING

        if (event.getStatus() != BLE_ERROR_NONE) {
            print_error(event.getStatus(), "Connection failed");
            return;
        }

        printf("Connected in %dms\r\n", read_demo_duration_in_ms());

        /* cancel the connect timeout since we connected */
        _event_queue.cancel(_cancel_handle);

        _cancel_handle = _event_queue.call_in(
            delay,
            [this, handle=event.getConnectionHandle()]{
                _gap.disconnect(handle, ble::local_disconnection_reason_t::USER_TERMINATION);
            }
        );

    }

    /** This is called by Gap to notify the application we disconnected,
     *  in our case it calls next_demo_mode() to progress the demo */
    void onDisconnectionComplete(const ble::DisconnectionCompleteEvent &event) override
    {
        printf("Disconnected\r\n");

        /* if it wasn't us disconnecting then we should cancel our attempt */
        if (event.getReason() == ble::disconnection_reason_t::REMOTE_USER_TERMINATED_CONNECTION) {
            _event_queue.cancel(_cancel_handle);
        }

        if (_is_in_scanning_phase) {
            _event_queue.call(this, &GapDemo::end_scanning_mode);
        } else {
            _event_queue.call(this, &GapDemo::end_advertising_mode);
        }
    }

    /**
     * Implementation of Gap::EventHandler::onReadPhy
     */
    void onReadPhy(
        ble_error_t error,
        ble::connection_handle_t connectionHandle,
        ble::phy_t txPhy,
        ble::phy_t rxPhy
    ) override
    {
        if (error) {
            printf(
                "Phy read on connection %d failed with error code %s\r\n",
                connectionHandle, BLE::errorToString(error)
            );
        } else {
            printf(
                "Phy read on connection %d - Tx Phy: %s, Rx Phy: %s\r\n",
                connectionHandle, phy_to_string(txPhy), phy_to_string(rxPhy)
            );
        }
    }

    /**
     * Implementation of Gap::EventHandler::onPhyUpdateComplete
     */
    void onPhyUpdateComplete(
        ble_error_t error,
        ble::connection_handle_t connectionHandle,
        ble::phy_t txPhy,
        ble::phy_t rxPhy
    ) override
    {
        if (error) {
            printf(
                "Phy update on connection: %d failed with error code %s\r\n",
                connectionHandle, BLE::errorToString(error)
            );
        } else {
            printf(
                "Phy update on connection %d - Tx Phy: %s, Rx Phy: %s\r\n",
                connectionHandle, phy_to_string(txPhy), phy_to_string(rxPhy)
            );
        }
    }

    /**
     * Implementation of Gap::EventHandler::onDataLengthChange
     */
    void onDataLengthChange(
        ble::connection_handle_t connectionHandle,
        uint16_t txSize,
        uint16_t rxSize
    ) override
    {
        printf(
            "Data length changed on the connection %d.\r\n"
            "Maximum sizes for over the air packets are:\r\n"
            "%d octets for transmit and %d octets for receive.\r\n",
            connectionHandle, txSize, rxSize
        );
    }

private:
    /** Finish the mode by shutting down advertising or scanning and move to the next mode. */
    void end_scanning_mode()
    {
        print_scanning_performance();
        ble_error_t error = _gap.stopScan();

        if (error) {
            print_error(error, "Error caused by Gap::stopScan");
        }

        _is_in_scanning_phase = false;
        _scan_count = 0;

        _event_queue.call_in(delay, this, &GapDemo::advertise);
    }

    void end_advertising_mode()
    {
        print_advertising_performance();

        printf("Requesting stop advertising.\r\n");

        _gap.stopAdvertising(ble::LEGACY_ADVERTISING_HANDLE);

#if BLE_FEATURE_EXTENDED_ADVERTISING
        if (_extended_adv_handle != ble::INVALID_ADVERTISING_HANDLE) {
            /* if it's still active, stop it */
            if (_gap.isAdvertisingActive(_extended_adv_handle)) {
                ble_error_t error = _gap.stopAdvertising(_extended_adv_handle);
                if (error) {
                    print_error(error, "Error caused by Gap::stopAdvertising");
                }
            }
        }
        /* we have to wait before we destroy it until it's stopped */
#else
        _is_in_scanning_phase = true;

        _event_queue.call_in(delay, [this]{ scan(); });
#endif // BLE_FEATURE_EXTENDED_ADVERTISING
    }

    /** print some information about our radio activity */
    void print_scanning_performance()
    {
        /* measure time from mode start, may have been stopped by timeout */
        uint16_t duration_ms = read_demo_duration_in_ms();

        /* convert ms into timeslots for accurate calculation as internally
         * all durations are in timeslots (0.625ms) */
        uint16_t duration_ts = ble::scan_interval_t(ble::millisecond_t(duration_ms)).value();
        uint16_t interval_ts = scan_params.get1mPhyConfiguration().getInterval().value();
        uint16_t window_ts = scan_params.get1mPhyConfiguration().getWindow().value();
        /* this is how long we scanned for in timeslots */
        uint16_t rx_ts = (duration_ts / interval_ts) * window_ts;
        /* convert to milliseconds */
        uint16_t rx_ms = ble::scan_interval_t(rx_ts).valueInMs();

        printf(
            "We have scanned for %dms with an interval of %d"
            " timeslots and a window of %d timeslots\r\n",
            duration_ms, interval_ts, window_ts
        );

        printf("We have been listening on the radio for at least %dms\r\n", rx_ms);
    }

    /** print some information about our radio activity */
    void print_advertising_performance()
    {
        /* measure time from mode start, may have been stopped by timeout */
        uint16_t duration_ms = read_demo_duration_in_ms();

        /* convert ms into timeslots for accurate calculation as internally
         * all durations are in timeslots (0.625ms) */
        uint16_t duration_ts = ble::adv_interval_t(ble::millisecond_t(duration_ms)).value();
        uint16_t interval_ts = advertising_params.getMaxPrimaryInterval().value();
        /* this is how many times we advertised */
        uint16_t events = (duration_ts / interval_ts);
        uint16_t extended_events = 0;

#if BLE_FEATURE_EXTENDED_ADVERTISING
        if (_extended_adv_handle != ble::INVALID_ADVERTISING_HANDLE) {
            duration_ts = ble::adv_interval_t(ble::millisecond_t(duration_ms)).value();
            interval_ts = extended_advertising_params.getMaxPrimaryInterval().value();
            /* this is how many times we advertised */
            extended_events = (duration_ts / interval_ts);
        }
#endif // BLE_FEATURE_EXTENDED_ADVERTISING

        printf("We have advertised for %dms\r\n", duration_ms);

        /* non-scannable and non-connectable advertising
         * skips rx events saving on power consumption */
        if (advertising_params.getType() == ble::advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
            printf("We created at least %d tx events\r\n", events);
        } else {
            printf("We created at least %d tx and rx events\r\n", events);
        }

#if BLE_FEATURE_EXTENDED_ADVERTISING
        if (extended_events) {
            if (extended_advertising_params.getType() == ble::advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
                printf("We created at least %d tx events with extended advertising\r\n", extended_events);
            } else {
                printf("We created at least %d tx and rx events with extended advertising\r\n", extended_events);
            }
        }

#endif // BLE_FEATURE_EXTENDED_ADVERTISING
    }

private:
    BLE &_ble;
    ble::Gap &_gap;
    events::EventQueue &_event_queue;

    /* Keep track of our progress through demo modes */
    bool _is_in_scanning_phase = false;
    bool _is_connecting = false;

    /* Remember the call id of the function on _event_queue
     * so we can cancel it if we need to end the phase early */
    int _cancel_handle = 0;

    /* Measure performance of our advertising/scanning */
    Timer _demo_duration;
    size_t _scan_count = 0;

#if BLE_FEATURE_EXTENDED_ADVERTISING
    ble::advertising_handle_t _extended_adv_handle = ble::INVALID_ADVERTISING_HANDLE;
#endif // BLE_FEATURE_EXTENDED_ADVERTISING
};

/** Schedule processing of events from the BLE middleware in the event queue. */
void schedule_ble_events(BLE::OnEventsToProcessCallbackContext *context)
{
    event_queue.call(Callback<void()>(&context->ble, &BLE::processEvents));
}

int main()
{
    mbed_trace_init();

    BLE &ble = BLE::Instance();

    /* this will inform us off all events so we can schedule their handling
     * using our event queue */
    ble.onEventsToProcess(schedule_ble_events);

    GapDemo demo(ble, event_queue);

    demo.run();

    return 0;
}

Important Information for this Arm website

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