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


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

Arm Mbed BLE is the Bluetooth Low Energy software solution for Mbed. Many Mbed targets and components support Mbed BLE. Developers can use it to create new BLE enabled applications.


Mbed's BLE API is available through C++ classes. It hides the BLE stack’s complexity and is compatible with all BLE-enabled Mbed board. It automatically configures the clocks, timers and other hardware peripherals to work at their lowest power consumption.

BLE API headers

BLE API is accessible through several header files:

Specific documentation for each component is available inside each of these headers.

Thread safety

BLE implementation does not provide thread safety and assumes single thread execution. Event processing and API calls must be dispatched from the same thread.

Asynchronous calls

Many API calls are asynchronous and provide results through callbacks. These are implemented as events. To receive these events register an EventHandler that is specific to that component. For example to receive events from Gap, use Gap::setEventHandler() passing in your implementation that inherits from Gap::EventHandler. Your class will override the events (methods) you are interested in, the others will inherit the do-nothing implementations provided by the parent.

Instancing a BLE device

All BLE operations are executed on an instance of BLE accessible through a function in the header ble/BLE.h.

#include "ble/BLE.h"

BLE& mydevicename = BLE::Instance();

BLE stacks

To build and application using BLE you will be using the Mbed OS BLE API and an implementation of the BLE stack appropriate for your board. The implementation is split into Host and Controller part. They can both run on the same chip or two separate ones. They will be both communicating through HCI (Host Controller Interface, a well defined protocol that is part of the Bluetooth specification). Read more about the HCI interface in Mbed OS here.

Currently, all implementation use the Cordio stack for the Host part. The Controller implementation may be either also Cordio or any other vendor supplier one. Each board will have a driver that implements the communication channel between the Host and its implementation of the controller. To add support for a new board please refer to the BLE porting guide.


To learn about debugging with mbed go to:

Debugging Mbed OS

However, keep in mind when trying to debug connectivity issues that if more than one device is involved it might not be possible to stop your target without the communication breaking down. A less invasive way to help you understand what is happening might be to use tracing.


To debug issues (or to understand what the stack is doing) it may be helpful to enable tracing.

To enable traces override configuration options in you mbed_app.json:

    "target_overrides": {
        "*": {
            "mbed-trace.enable": true,
            "mbed-trace.max-level": "TRACE_LEVEL_DEBUG",
            "cordio.trace-hci-packets": false,
            "cordio.trace-cordio-wsf-traces": false,
            "ble.trace-human-readable-enums": true

Compile your application with --profile debug. Please note that with all options enabled your application may become too big - disable some options or lower the mbed-trace.max-level. Detailed documentation is available in the tracing README.md.

All BLE modules contain tracing, each of the modules prefixed with a unique tag:

  • BLE - general BLE traces
  • BLGP - GAP
  • BLGS - GATT Server
  • BLGC - GATT Client
  • BLSM - Security Manager
  • BLDB - Security Database
  • BLHC - HCI
  • BLCO - Cordio stack
  • BLDM - GAP pal
  • BLAT - ATT client

Any contributions to BLE should include appropriate tracing code.

BLE examples

We have placed all of our BLE examples in a single GitHub repository:

Use the release version matching the mbed-os version you plan to use.

Development happens on the development branch. If you report an issue or open a PR, please check the version on the development branch and target it for any proposed changes.

BLE class reference

Data Structures
struct  InitializationCompleteCallbackContext
 Initialization complete event. More...
struct  OnEventsToProcessCallbackContext
 Events to process event. More...
Public Types
typedef unsigned InstanceID_t
 Opaque type used to store the ID of a BLE instance. More...
typedef FunctionPointerWithContext< OnEventsToProcessCallbackContext * > OnEventsToProcessCallback_t
 Events to process event handler. More...
typedef void(* InitializationCompleteCallback_t) (InitializationCompleteCallbackContext *context)
 Initialization complete event handler. More...
Public Member Functions
InstanceID_t getInstanceID () const
 Fetch the ID of a BLE instance. More...
void onEventsToProcess (const OnEventsToProcessCallback_t &on_event_cb)
 Register a callback called when the BLE stack has pending work. More...
void processEvents ()
 Process ALL pending events living in the BLE stack and return once all events have been consumed. More...
ble_error_t init (InitializationCompleteCallback_t completion_cb=nullptr)
 Initialize the BLE controller/stack. More...
template<typename T >
ble_error_t init (T *object, void(T::*completion_cb)(InitializationCompleteCallbackContext *context))
 Initialize the BLE controller/stack. More...
bool hasInitialized () const
 Indicate if the BLE instance has been initialized. More...
ble_error_t shutdown ()
 Shut down the underlying stack, and reset state of this BLE instance. More...
const char * getVersion ()
 This call allows the application to get the BLE stack version information. More...
ble::Gapgap ()
 Accessor to Gap. More...
const ble::Gapgap () const
 A const alternative to gap(). More...
ble::GattServergattServer ()
 Accessor to GattServer. More...
const ble::GattServergattServer () const
 A const alternative to gattServer(). More...
ble::GattClientgattClient ()
 Accessors to GattClient. More...
const ble::GattClientgattClient () const
 A const alternative to gattClient(). More...
ble::SecurityManagersecurityManager ()
 Accessors to SecurityManager. More...
const ble::SecurityManagersecurityManager () const
 A const alternative to securityManager(). More...
void signalEventsToProcess ()
 This function allows the BLE stack to signal that there is work to do and event processing should be done (BLE::processEvent()). More...
Static Public Member Functions
static BLEInstance ()
 Get a reference to the BLE singleton. More...
static BLEInstance (InstanceID_t id)
 Get a reference to the BLE singleton corresponding to a given interface. More...
static const char * errorToString (ble_error_t error)
 Translate error code into a printable string. More...
Static Public Attributes
static const InstanceID_t DEFAULT_INSTANCE = 0
 The value of the BLE::InstanceID_t for the default BLE instance. More...
static const InstanceID_t NUM_INSTANCES = 1
 The number of permitted BLE instances for the application. More...
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.