Mbed OS Reference | BLE Class Reference

Abstract away BLE-capable radio transceivers or SOCs. More...

#include <BLE.h>

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::Gap &	gap ()
	Accessor to Gap. More...

const ble::Gap &	gap () const
	A const alternative to gap(). More...

ble::GattServer &	gattServer ()
	Accessor to GattServer. More...

const ble::GattServer &	gattServer () const
	A const alternative to gattServer(). More...

ble::GattClient &	gattClient ()
	Accessors to GattClient. More...

const ble::GattClient &	gattClient () const
	A const alternative to gattClient(). More...

ble::SecurityManager &	securityManager ()
	Accessors to SecurityManager. More...

const ble::SecurityManager &	securityManager () 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 BLE &	Instance ()
	Get a reference to the BLE singleton. More...

static BLE &	Instance (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...

Detailed Description

Abstract away BLE-capable radio transceivers or SOCs.

Instances of this class have three responsibilities:

Initialize the inner BLE subsystem.
Signal user code that BLE events are available and an API to process them.
Manage access to the instances abstracting each BLE layer:
- GAP: Handle advertising and scan, as well as connection and disconnection.
- GATTServer: API to construct and manage a GATT server, which connected peers can access.
- GATTClient: API to interact with a peer GATT server.
- SecurityManager: API to manage security.

The user should not create BLE instances directly but rather access to the singleton(s) holding the BLE interfaces present in the system by using the static function Instance().

#include "ble/BLE.h"
BLE& ble_interface = BLE::Instance();

Next, the signal handling/process mechanism should be set up. By design, Mbed BLE does not impose to the user an event handling/processing mechanism; however, it exposes APIs, which allows an application to compose its own:

onEventsToProcess(), which registers a callback that the BLE subsystem will call when there is an event ready to be processed.
processEvents(), which processes all the events present in the BLE subsystem.

It is common to bind BLE event mechanism with Mbed EventQueue:

#include <events/mbed_events.h>
#include "ble/BLE.h"
// declare the event queue, which the whole application will share.
static EventQueue event_queue(4 * EVENTS_EVENT_SIZE);
// Function invoked when there is a BLE event available.
// Event processing is put into the event queue.
void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) {
  event_queue.call(callback(&(context->ble), &BLE::processEvents));
}
int main()
{
  BLE &ble_interface = BLE::Instance();
  // Bind event signaling to schedule_ble_processing
  ble_interface.onEventsToProcess(schedule_ble_processing);
  // Launch BLE initialisation
  // Dispatch events in the event queue
  event_queue.dispatch_forever();
  return 0;
}

Once the event processing mechanism is in place, the Bluetooth subsystem can be initialized with the init() function. That function accepts in input a callback, which will be invoked once the initialization process has finished.

void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context)
{
  BLE& ble_interface = context->ble;
  ble_error_t initialization_error = context->error;
  if (initialization_error) {
    // handle error
    return;
  }
  // The BLE interface can be accessed now.
}
int main() {
  BLE &ble_interface = BLE::Instance();
  ble_interface.onEventsToProcess(schedule_ble_processing);
  // Initialize the BLE interface
  ble_interface.init(on_ble_init_complete);
  event_queue.dispatch_forever();
  return 0;
}

Definition at line 137 of file BLE.h.

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Important Information for this Arm website