Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes
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 (void) 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=NULL)
 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 (void) const
 Indicate if the BLE instance has been initialized. More...
 
ble_error_t shutdown (void)
 Shut down the underlying stack, and reset state of this BLE instance. More...
 
const char * getVersion (void)
 This call allows the application to get the BLE stack version information. More...
 
Gap & gap ()
 Accessor to Gap. More...
 
const Gap & gap () const
 A const alternative to gap(). More...
 
GattServergattServer ()
 Accessor to GattServer. More...
 
const GattServergattServer () const
 A const alternative to gattServer(). More...
 
GattClientgattClient ()
 Accessors to GattClient. More...
 
const GattClientgattClient () const
 A const alternative to gattClient(). More...
 
SecurityManagersecurityManager ()
 Accessors to SecurityManager. More...
 
const SecurityManagersecurityManager () const
 A const alternative to securityManager(). More...
 

Static Public Member Functions

static BLEInstance (InstanceID_t id=DEFAULT_INSTANCE)
 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:

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:

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 139 of file BLE.h.

Member Typedef Documentation

typedef void(* InitializationCompleteCallback_t) (InitializationCompleteCallbackContext *context)

Initialization complete event handler.

Note
There are two versions of init(). In addition to the function-pointer, init() can also take an <Object, member> tuple as its callback target. In case of the latter, the following declaration doesn't apply.

Definition at line 255 of file BLE.h.

typedef unsigned InstanceID_t

Opaque type used to store the ID of a BLE instance.

Definition at line 144 of file BLE.h.

Events to process event handler.

Definition at line 206 of file BLE.h.

Member Function Documentation

static const char* errorToString ( ble_error_t  error)
static

Translate error code into a printable string.

Parameters
[in]errorError code returned by BLE functions.
Returns
A pointer to a const string describing the error.
Gap& gap ( )

Accessor to Gap.

All Gap-related functionality requires going through this accessor.

Returns
A reference to a Gap object associated to this BLE instance.
const Gap& gap ( ) const

A const alternative to gap().

Returns
A const reference to a Gap object associated to this BLE instance.
GattClient& gattClient ( )

Accessors to GattClient.

All GattClient related functionality requires going through this accessor.

Returns
A reference to a GattClient object associated to this BLE instance.
const GattClient& gattClient ( ) const

A const alternative to gattClient().

Returns
A const reference to a GattClient object associated to this BLE instance.
GattServer& gattServer ( )

Accessor to GattServer.

All GattServer related functionality requires going through this accessor.

Returns
A reference to a GattServer object associated to this BLE instance.
const GattServer& gattServer ( ) const

A const alternative to gattServer().

Returns
A const reference to a GattServer object associated to this BLE instance.
InstanceID_t getInstanceID ( void  ) const

Fetch the ID of a BLE instance.

Returns
Instance id of this BLE instance.

Definition at line 184 of file BLE.h.

const char* getVersion ( void  )

This call allows the application to get the BLE stack version information.

Returns
A pointer to a const string representing the version.
Note
The BLE API owns the string returned.
bool hasInitialized ( void  ) const

Indicate if the BLE instance has been initialized.

Returns
true if initialization has completed for the underlying BLE transport.
Note
The application should set up a callback to signal completion of initialization when using init().
ble_error_t init ( InitializationCompleteCallback_t  completion_cb = NULL)

Initialize the BLE controller/stack.

init() hands control to the underlying BLE module to accomplish initialization. This initialization may tacitly depend on other hardware setup (such as clocks or power-modes) that happens early on during system startup. It may not be safe to call init() from a global static context where ordering is compiler-specific and can't be guaranteed - it is safe to call BLE::init() from within main().

Parameters
[in]completion_cbA callback for when initialization completes for a BLE instance. This is an optional parameter; if no callback is set up, the application can still determine the status of initialization using BLE::hasInitialized() (see below).
Returns
BLE_ERROR_NONE if the initialization procedure started successfully.
Note
If init() returns BLE_ERROR_NONE, the underlying stack must invoke the initialization completion callback at some point.
Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the corresponding transport is initialized.
There are two versions of init(). In addition to the function-pointer, init() can also take an <Object, member> pair as its callback target.
Attention
This should be called before using anything else in the BLE API.

Definition at line 290 of file BLE.h.

ble_error_t init ( T *  object,
void(T::*)(InitializationCompleteCallbackContext *context)  completion_cb 
)

Initialize the BLE controller/stack.

This is an alternate declaration for init(). This one takes an <Object, member> pair as its callback target.

Parameters
[in]objectObject, which will be used to invoke the completion callback.
[in]completion_cbMember function pointer, which will be invoked when initialization is complete.

Definition at line 307 of file BLE.h.

static BLE& Instance ( InstanceID_t  id = DEFAULT_INSTANCE)
static

Get a reference to the BLE singleton corresponding to a given interface.

There is a static array of BLE singletons.

Note
Calling Instance() is preferred over constructing a BLE object directly because it returns references to singletons.
Parameters
[in]idBLE Instance ID to get.
Returns
A reference to a single object.
Precondition
id shall be less than NUM_INSTANCES.
void onEventsToProcess ( const OnEventsToProcessCallback_t on_event_cb)

Register a callback called when the BLE stack has pending work.

By registering a callback, application code can know when event processing has to be scheduled.

Parameters
on_event_cbCallback invoked when there are new events to process.
void processEvents ( )

Process ALL pending events living in the BLE stack and return once all events have been consumed.

See also
onEventsToProcess()
SecurityManager& securityManager ( )

Accessors to SecurityManager.

All SecurityManager-related functionality requires going through this accessor.

Returns
A reference to a SecurityManager object associated to this BLE instance.
const SecurityManager& securityManager ( ) const

A const alternative to securityManager().

Returns
A const reference to a SecurityManager object associated to this BLE instance.
ble_error_t shutdown ( void  )

Shut down the underlying stack, and reset state of this BLE instance.

Returns
BLE_ERROR_NONE if the instance was shut down without error or the appropriate error code.
Attention
init() must be called afterward to reinstate services and GAP state. This API offers a way to repopulate the GATT database with new services and characteristics.

Field Documentation

const InstanceID_t DEFAULT_INSTANCE = 0
static

The value of the BLE::InstanceID_t for the default BLE instance.

Definition at line 149 of file BLE.h.

const InstanceID_t NUM_INSTANCES = 1
static

The number of permitted BLE instances for the application.

Definition at line 155 of file BLE.h.

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.