Bluetooth Low Energy (BLE)

Bluetooth low energy (BLE) is a very low power wireless technology standard for personal area networks. Typical applications of BLE are health care, fitness trackers, beacons, smart home, security, entertainment, proximity sensors, industrial and automotive.

mbed BLE, also called BLE_API, is the Bluetooth Low Energy software solution for mbed. This thin abstraction runs on many targets and allows developers to easily create new BLE applications.

Getting started

  1. Choose an mbed board that supports BLE, like the NRF51-DK.

    If your platform doesn’t support BLE but is compatible with the Arduino UNO R3 connector, you can use an extension board like the X-NUCLEO-IDB05A1 to add BLE capabilities to your development board.

  2. Install a BLE scanner on your phone. It will allows you to track all BLE activities from your embedded application. This is a mandatory tool for BLE software development:

  3. Compile and run our BLE samples:

    • mbed OS 5 samples are available on and Github:
      • The Beacon example is a good starting point, it demonstrate how you can create a BLE Beacon with just a few lines of code.
      • The heart rate monitor example demonstrate how to build a heart rate sensor that can be connected and monitored by a BLE client like your phone.
      • The LED and LED blinker are a single example, which demonstrate how a client (LED) and a server (LED blinker) work together over BLE.

    Tip: Despite the differences between the different mbed OS versions, there is only one version of mbed BLE, and it is easy to move code from one version of the OS to another. Choose the sample you use according to the version of mbed OS supported by your development board.

Going further

  • mbed BLE intros is a wonderful resources for developers new to BLE and mbed BLE. It covers how to build BLE embedded applications with mbed.

  • The Bluetooth Low Energy main page on also provide samples and resources around BLE.

  • The mbed BLE API reference offer the full details of the API.

  • The mbed BLE online community is also a great place to ask questions and share your knowledge.

API reference

Data Structures

struct  InitializationCompleteCallbackContext
struct  OnEventsToProcessCallbackContext

Public Types

typedef unsigned InstanceID_t
typedef FunctionPointerWithContext< OnEventsToProcessCallbackContext * > OnEventsToProcessCallback_t
typedef void(* InitializationCompleteCallback_t) (InitializationCompleteCallbackContext *context)

Public Member Functions

ble_error_t init (InitializationCompleteCallback_t initCompleteCallback=NULL)
template<typename T >
ble_error_t init (T *object, void(T::*initCompleteCallback)(InitializationCompleteCallbackContext *context))
bool hasInitialized (void) const
ble_error_t shutdown (void)
const char * getVersion (void)
Gap & gap ()
const Gap & gap () const
GattServer & gattServer ()
const GattServer & gattServer () const
GattClient & gattClient ()
const GattClient & gattClient () const
SecurityManager & securityManager ()
const SecurityManager & securityManager () const
void waitForEvent (void)
 BLE (InstanceID_t instanceID=DEFAULT_INSTANCE)
InstanceID_t getInstanceID (void) const
ble_error_t setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
ble_error_t getAddress (BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
void setAdvertisingType (GapAdvertisingParams::AdvertisingType advType)
void setAdvertisingInterval (uint16_t interval)
uint16_t getMinAdvertisingInterval (void) const
uint16_t getMinNonConnectableAdvertisingInterval (void) const
uint16_t getMaxAdvertisingInterval (void) const
void setAdvertisingTimeout (uint16_t timeout)
void setAdvertisingParams (const GapAdvertisingParams &advParams)
const GapAdvertisingParamsgetAdvertisingParams (void) const
ble_error_t accumulateAdvertisingPayload (uint8_t flags)
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::Appearance app)
ble_error_t accumulateAdvertisingPayloadTxPower (int8_t power)
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
ble_error_t setAdvertisingData (const GapAdvertisingData &advData)
const GapAdvertisingDatagetAdvertisingData (void) const
void clearAdvertisingPayload (void)
ble_error_t setAdvertisingPayload (void)
ble_error_t accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
void clearScanResponse (void)
ble_error_t startAdvertising (void)
ble_error_t stopAdvertising (void)
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)
ble_error_t setScanInterval (uint16_t interval)
ble_error_t setScanWindow (uint16_t window)
ble_error_t setScanTimeout (uint16_t timeout)
void setActiveScan (bool activeScanning)
ble_error_t startScan (void(*callback)(const Gap::AdvertisementCallbackParams_t *params))
template<typename T >
ble_error_t startScan (T *object, void(T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params))
ble_error_t stopScan (void)
ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType=BLEProtocol::AddressType::RANDOM_STATIC, const Gap::ConnectionParams_t *connectionParams=NULL, const GapScanningParams *scanParams=NULL)
ble_error_t disconnect (Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason)
ble_error_t disconnect (Gap::DisconnectionReason_t reason)
Gap::GapState_t getGapState (void) const
ble_error_t getPreferredConnectionParams (Gap::ConnectionParams_t *params)
ble_error_t setPreferredConnectionParams (const Gap::ConnectionParams_t *params)
ble_error_t updateConnectionParams (Gap::Handle_t handle, const Gap::ConnectionParams_t *params)
ble_error_t setDeviceName (const uint8_t *deviceName)
ble_error_t getDeviceName (uint8_t *deviceName, unsigned *lengthP)
ble_error_t setAppearance (GapAdvertisingData::Appearance appearance)
ble_error_t getAppearance (GapAdvertisingData::Appearance *appearanceP)
ble_error_t setTxPower (int8_t txPower)
void getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP)
ble_error_t addService (GattService &service)
ble_error_t readCharacteristicValue (GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
ble_error_t readCharacteristicValue (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
ble_error_t updateCharacteristicValue (GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
ble_error_t updateCharacteristicValue (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
ble_error_t initializeSecurity (bool enableBonding=true, bool requireMITM=true, SecurityManager::SecurityIOCapabilities_t iocaps=SecurityManager::IO_CAPS_NONE, const SecurityManager::Passkey_t passkey=NULL)
ble_error_t getLinkSecurity (Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP)
ble_error_t purgeAllBondingState (void)
void onTimeout (Gap::TimeoutEventCallback_t timeoutCallback)
void onConnection (Gap::ConnectionEventCallback_t connectionCallback)
void onDisconnection (Gap::DisconnectionEventCallback_t disconnectionCallback)
template<typename T >
void onDisconnection (T *tptr, void(T::*mptr)(const Gap::DisconnectionCallbackParams_t *))
void onRadioNotification (void(*callback)(bool))
void onDataSent (void(*callback)(unsigned count))
template<typename T >
void onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count))
void onDataWritten (void(*callback)(const GattWriteCallbackParams *eventDataP))
template<typename T >
void onDataWritten (T *objPtr, void(T::*memberPtr)(const GattWriteCallbackParams *context))
ble_error_t onDataRead (void(*callback)(const GattReadCallbackParams *eventDataP))
template<typename T >
ble_error_t onDataRead (T *objPtr, void(T::*memberPtr)(const GattReadCallbackParams *context))
void onUpdatesEnabled (GattServer::EventCallback_t callback)
void onUpdatesDisabled (GattServer::EventCallback_t callback)
void onConfirmationReceived (GattServer::EventCallback_t callback)
void onSecuritySetupInitiated (SecurityManager::SecuritySetupInitiatedCallback_t callback)
void onSecuritySetupCompleted (SecurityManager::SecuritySetupCompletedCallback_t callback)
void onLinkSecured (SecurityManager::LinkSecuredCallback_t callback)
void onSecurityContextStored (SecurityManager::HandleSpecificEvent_t callback)
void onPasskeyDisplay (SecurityManager::PasskeyDisplayCallback_t callback)
void processEvents ()
void onEventsToProcess (const OnEventsToProcessCallback_t &callback)

Static Public Member Functions

static BLEInstance (InstanceID_t id=DEFAULT_INSTANCE)

Static Public Attributes

static const InstanceID_t DEFAULT_INSTANCE = 0
static const InstanceID_t NUM_INSTANCES = 1


class BLEInstanceBase