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.
typedef FunctionPointerWithContext < OnEventsToProcessCallbackContext * >	OnEventsToProcessCallback_t
	Events to process event handler.
typedef void(*	InitializationCompleteCallback_t )(InitializationCompleteCallbackContext *context)
	Initialization complete event handler.
Public Member Functions
InstanceID_t	getInstanceID (void) const
	Fetch the ID of a BLE instance.
void	onEventsToProcess (const OnEventsToProcessCallback_t &on_event_cb)
	Register a callback called when the BLE stack has pending work.
void	processEvents ()
	Process ALL pending events living in the BLE stack and return once all events have been consumed.
ble_error_t	init (InitializationCompleteCallback_t completion_cb=NULL)
	Initialize the BLE controller/stack.
template<typename T >
ble_error_t	init (T object, void(T::completion_cb)(InitializationCompleteCallbackContext *context))
	Initialize the BLE controller/stack.
bool	hasInitialized (void) const
	Indicate if the BLE instance has been initialized.
ble_error_t	shutdown (void)
	Shut down the underlying stack, and reset state of this BLE instance.
const char *	getVersion (void)
	This call allows the application to get the BLE stack version information.
Gap &	gap ()
	Accessor to Gap.
const Gap &	gap () const
	A const alternative to gap().
GattServer &	gattServer ()
	Accessor to GattServer.
const GattServer &	gattServer () const
	A const alternative to gattServer().
GattClient &	gattClient ()
	Accessors to GattClient.
const GattClient &	gattClient () const
	A const alternative to gattClient().
SecurityManager &	securityManager ()
	Accessors to SecurityManager.
const SecurityManager &	securityManager () const
	A const alternative to securityManager().
	MBED_DEPRECATED ("Use BLE::Instance() instead of BLE constructor.") BLE(InstanceID_t instanceID
	Constructor for a handle to a BLE instance (the BLE stack).
	MBED_DEPRECATED ("Use BLE::processEvents() and BLE::onEventsToProcess().") void waitForEvent(void)
	Yield control to the BLE stack or to other tasks waiting for events.
	MBED_DEPRECATED ("Use ble.gap().setAddress(...)") ble_error_t setAddress(BLEProtocol
	Set the BTLE MAC address and type.
	MBED_DEPRECATED ("Use ble.gap().getAddress(...)") ble_error_t getAddress(BLEProtocol
	Fetch the Bluetooth Low Energy MAC address and type.
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingType(...)") void setAdvertisingType(GapAdvertisingParams
	Set the GAP advertising mode to use for this device.
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingInterval(...)") void setAdvertisingInterval(uint16_t interval)
	MBED_DEPRECATED ("Use ble.gap().getMinAdvertisingInterval(...)") uint16_t getMinAdvertisingInterval(void) const
	MBED_DEPRECATED ("Use ble.gap().getMinNonConnectableAdvertisingInterval(...)") uint16_t getMinNonConnectableAdvertisingInterval(void) const
	MBED_DEPRECATED ("Use ble.gap().getMaxAdvertisingInterval(...)") uint16_t getMaxAdvertisingInterval(void) const
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingTimeout(...)") void setAdvertisingTimeout(uint16_t timeout)
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingParams(...)") void setAdvertisingParams(const GapAdvertisingParams &advParams)
	Set up a particular, user-constructed set of advertisement parameters for the underlying stack.
	MBED_DEPRECATED ("Use ble.gap().getAdvertisingParams(...)") const GapAdvertisingParams &getAdvertisingParams(void) const
	MBED_DEPRECATED ("Use ble.gap().accumulateAdvertisingPayload(flags)") ble_error_t accumulateAdvertisingPayload(uint8_t flags)
	Accumulate an AD structure in the advertising payload.
	MBED_DEPRECATED ("Use ble.gap().accumulateAdvertisingPayload(appearance)") ble_error_t accumulateAdvertisingPayload(GapAdvertisingData
	Accumulate an AD structure in the advertising payload.
	MBED_DEPRECATED ("Use ble.gap().accumulateAdvertisingPayloadTxPower(...)") ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power)
	Accumulate an AD structure in the advertising payload.
	MBED_DEPRECATED ("Use ble.gap().accumulateAdvertisingPayload(...)") ble_error_t accumulateAdvertisingPayload(GapAdvertisingData
	Accumulate a variable length byte-stream as an AD structure in the advertising payload.
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingData(...)") ble_error_t setAdvertisingData(const GapAdvertisingData &advData)
	Set up a particular, user-constructed advertisement payload for the underlying stack.
	MBED_DEPRECATED ("Use ble.gap().getAdvertisingData(...)") const GapAdvertisingData &getAdvertisingData(void) const
	MBED_DEPRECATED ("Use ble.gap().clearAdvertisingPayload(...)") void clearAdvertisingPayload(void)
	Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload().
	MBED_DEPRECATED ("Use ble.gap().setAdvertisingPayload(...)") ble_error_t setAdvertisingPayload(void)
	Dynamically reset the accumulated advertising payload and scanResponse.
	MBED_DEPRECATED ("Use ble.gap().accumulateScanResponse(...)") ble_error_t accumulateScanResponse(GapAdvertisingData
	Accumulate a variable length byte-stream as an AD structure in the scanResponse payload.
	MBED_DEPRECATED ("Use ble.gap().clearScanResponse(...)") void clearScanResponse(void)
	Reset any scan response prepared from prior calls to accumulateScanResponse().
	MBED_DEPRECATED ("Use ble.gap().startAdvertising(...)") ble_error_t startAdvertising(void)
	Start advertising.
	MBED_DEPRECATED ("Use ble.gap().stopAdvertising(...)") ble_error_t stopAdvertising(void)
	Stop advertising.
	MBED_DEPRECATED ("Use ble.gap().setScanParams(...)") ble_error_t setScanParams(uint16_t interval
	Set up parameters for GAP scanning (observer mode).
	MBED_DEPRECATED ("Use ble.gap().stopScan()") ble_error_t stopScan(void)
	Stop scanning.
	MBED_DEPRECATED ("Use ble.gap().connect(...)") ble_error_t connect(const BLEProtocol
	Create a connection (GAP Link Establishment).
	MBED_DEPRECATED ("Use ble.gap().disconnect(...)") ble_error_t disconnect(Gap
	This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback.
	MBED_DEPRECATED ("Use ble.gap().disconnect(...)") ble_error_t disconnect(Gap
	This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback.
	MBED_DEPRECATED ("Use ble.gap().getGapState(...)") Gap
	Returns the current Gap state of the device using a bitmask that describes whether the device is advertising or connected.
	MBED_DEPRECATED ("Use ble.gap().getPreferredConnectionParams(...)") ble_error_t getPreferredConnectionParams(Gap
	Get the GAP peripheral's preferred connection parameters.
	MBED_DEPRECATED ("Use ble.gap().setPreferredConnectionParams(...)") ble_error_t setPreferredConnectionParams(const Gap
	Set the GAP peripheral's preferred connection parameters.
	MBED_DEPRECATED ("Use ble.gap().updateConnectionParams(...)") ble_error_t updateConnectionParams(Gap
	Update connection parameters while in the peripheral role.
	MBED_DEPRECATED ("Use ble.gap().setDeviceName(...)") ble_error_t setDeviceName(const uint8_t *deviceName)
	Set the device name characteristic in the Gap service.
	MBED_DEPRECATED ("Use ble.gap().getDeviceName(...)") ble_error_t getDeviceName(uint8_t *deviceName
	Get the value of the device name characteristic in the Gap service.
	MBED_DEPRECATED ("Use ble.gap().setAppearance(...)") ble_error_t setAppearance(GapAdvertisingData
	Set the appearance characteristic in the Gap service.
	MBED_DEPRECATED ("Use ble.gap().getAppearance(...)") ble_error_t getAppearance(GapAdvertisingData
	Get the appearance characteristic in the Gap service.
	MBED_DEPRECATED ("Use ble.gap().setTxPower(...)") ble_error_t setTxPower(int8_t txPower)
	Set the radio's transmit power.
	MBED_DEPRECATED ("Use ble.gap().getPermittedTxPowerValues(...)") void getPermittedTxPowerValues(const int8_t **valueArrayPP
	Query the underlying stack for permitted arguments for setTxPower().
void	signalEventsToProcess ()
	This function allows the BLE stack to signal that there is work to do and event processing should be done (BLE::processEvent()).
ble_error_t	initImplementation (FunctionPointerWithContext< InitializationCompleteCallbackContext * > callback)
	Implementation of init() [internal to BLE_API].
Static Public Member Functions
static BLE &	Instance (InstanceID_t id=DEFAULT_INSTANCE)
	Get a reference to the BLE singleton corresponding to a given interface.
Static Public Attributes
static const InstanceID_t	DEFAULT_INSTANCE = 0
	The value of the BLE::InstanceID_t for the default BLE instance.
static const InstanceID_t	NUM_INSTANCES = 1
	The number of permitted BLE instances for the application.

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(), whichs register 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.
 // It put into the event queue the processing of the event(s)
 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 135 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 251 of file BLE.h.

typedef unsigned InstanceID_t

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

Definition at line 141 of file BLE.h.

typedef FunctionPointerWithContext<OnEventsToProcessCallbackContext*> OnEventsToProcessCallback_t

Events to process event handler.

Definition at line 202 of file BLE.h.

Member Function Documentation

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.

Definition at line 195 of file BLE.cpp.

const Gap & gap ( ) const

A const alternative to gap().

Returns:: A const reference to a Gap object associated to this BLE instance.

Definition at line 186 of file BLE.cpp.

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.

Definition at line 231 of file BLE.cpp.

const GattClient & gattClient ( ) const

A const alternative to gattClient().

Returns:: A const reference to a GattClient object associated to this BLE instance.

Definition at line 222 of file BLE.cpp.

const GattServer & gattServer ( ) const

A const alternative to gattServer().

Returns:: A const reference to a GattServer object associated to this BLE instance.

Definition at line 204 of file BLE.cpp.

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.

Definition at line 213 of file BLE.cpp.

InstanceID_t getInstanceID ( void ) const

Fetch the ID of a BLE instance.

Returns:: Instance id of this BLE instance.

Definition at line 181 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.

Definition at line 177 of file BLE.cpp.

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

Definition at line 158 of file BLE.cpp.

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

This should be called before using anything else in the BLE API.

Definition at line 286 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]	object	Object, which will be used to invoke the completion callback.
[in]	completion_cb	Member function pointer, which will be invoked when initialization is complete.

Definition at line 302 of file BLE.h.

ble_error_t initImplementation ( FunctionPointerWithContext< InitializationCompleteCallbackContext * > callback )

Implementation of init() [internal to BLE_API].

The implementation is separated into a private method because it isn't suitable to be included in the header.

Definition at line 35 of file BLE.cpp.

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] id BLE Instance ID to get.

Returns:: A reference to a single object.

Precondition:: id shall be less than NUM_INSTANCES.

Definition at line 117 of file BLE.cpp.

MBED_DEPRECATED ( "Use ble.gap().disconnect(...)" )

This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback.

Parameters:

reason The reason for disconnection; sent back to the peer.

Note:: This version of disconnect() doesn't take a connection handle. It works reliably only for stacks that are limited to a single connection.

Definition at line 1038 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().disconnect(...)" )

This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback.

Parameters:

[in]	connectionHandle
[in]	reason	The reason for disconnection; sent back to the peer.

Definition at line 1016 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().connect(...)" ) const

Create a connection (GAP Link Establishment).

Parameters:

peerAddr	48-bit address, LSB format.
peerAddrType	Address type of the peer.
connectionParams	Connection parameters.
scanParams	Parameters to use while scanning for the peer.

Returns:: BLE_ERROR_NONE if connection establishment procedure is started successfully. The onConnection callback (if set) is invoked upon a connection event.

Definition at line 999 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().stopScan()" )

Stop scanning.

The current scanning parameters remain in effect.

Return values:

BLE_ERROR_NONE if successfully stopped scanning procedure.

Definition at line 975 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setScanParams(...)" )

Set up parameters for GAP scanning (observer mode).

Parameters:

[in]	interval	Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
[in]	window	Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
[in]	timeout	Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
[in]	activeScanning	Set to True if active-scanning is required. This is used to fetch the scan response from a peer if possible.

The scanning window divided by the interval determines the duty cycle for scanning. For example, if the interval is 100ms and the window is 10ms, then the controller will scan for 10 percent of the time. It is possible to have the interval and window set to the same value. In this case, scanning is continuous, with a change of scanning frequency once every interval.

Once the scanning parameters have been configured, scanning can be enabled by using startScan().

Note:: The scan interval and window are recommendations to the BLE stack.

MBED_DEPRECATED ( "Use ble.gap().stopAdvertising(...)" )

Stop advertising.

Definition at line 796 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().startAdvertising(...)" )

Start advertising.

Definition at line 783 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().clearScanResponse(...)" )

Reset any scan response prepared from prior calls to accumulateScanResponse().

Definition at line 770 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().accumulateScanResponse(...)" )

Accumulate a variable length byte-stream as an AD structure in the scanResponse payload.

Parameters:

[in]	type	The type that describes the variable length data.
[in]	data	Data bytes.
[in]	len	Data length.

Definition at line 756 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingPayload(...)" )

Dynamically reset the accumulated advertising payload and scanResponse.

The application must clear and re- accumulate a new advertising payload (and scanResponse) before using this API.

Returns:: BLE_ERROR_NONE when the advertising payload is set successfully.

Note:: The new APIs in Gap update the underlying advertisement payload implicitly.

Definition at line 738 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getGapState(...)" )

Returns the current Gap state of the device using a bitmask that describes whether the device is advertising or connected.

Definition at line 1052 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().accumulateAdvertisingPayloadTxPower(...)" )

Accumulate an AD structure in the advertising payload.

Please note that the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used as an additional 31 bytes if the advertising payload is too small.

Parameters:

[in] power The max transmit power to be used by the controller. This is only a hint.

Definition at line 655 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().accumulateAdvertisingPayload(...)" )

Accumulate a variable length byte-stream as an AD structure in the advertising payload.

Please note that the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used as an additional 31 bytes if the advertising payload is too small.

Parameters:

type	The type that describes the variable length data.
data	Data bytes.
len	Data length.

Definition at line 675 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingData(...)" ) const

Set up a particular, user-constructed advertisement payload for the underlying stack.

It would be uncommon for this API to be used directly; there are other APIs to build an advertisement payload (see above).

Definition at line 690 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getAdvertisingData(...)" ) const

Returns:: Read back advertising data. Useful for storing and restoring payload.

Definition at line 704 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().accumulateAdvertisingPayload(appearance)" )

Accumulate an AD structure in the advertising payload.

Please note that the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used as an additional 31 bytes if the advertising payload is too small.

Parameters:

[in] app The appearance of the peripheral.

Definition at line 635 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().accumulateAdvertisingPayload(flags)" )

Accumulate an AD structure in the advertising payload.

Please note that the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used as an additional 31 bytes if the advertising payload is too small.

Parameters:

[in] flags The flags to add. Please refer to GapAdvertisingData::Flags for valid flags. Multiple flags may be specified in combination.

Definition at line 615 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getAppearance(...)" )

Get the appearance characteristic in the Gap service.

Parameters:

[out] appearanceP The new value for the device-appearance.

Definition at line 1185 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingParams(...)" ) const

Set up a particular, user-constructed set of advertisement parameters for the underlying stack.

It would be uncommon for this API to be used directly; there are other APIs to tweak advertisement parameters individually (see above).

Definition at line 580 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingTimeout(...)" )

Parameters:

[in] timeout Advertising timeout (in seconds) between 0x1 and 0x3FFF (1 and 16383). Use 0 to disable the advertising timeout.

Definition at line 564 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getDeviceName(...)" )

Get the value of the device name characteristic in the Gap service.

Parameters:

[out]	deviceName	Pointer to an empty buffer where the UTF-8 non NULL- terminated string will be placed. Set this value to NULL to obtain the deviceName-length from the 'length' parameter.
[in,out]	lengthP	(on input) Length of the buffer pointed to by deviceName; (on output) the complete device name length (without the null terminator).

Note:: If the device name is longer than the size of the supplied buffer, the length will return the complete device name length and not the number of bytes actually returned in deviceName. The application may use this information to retry with a suitable buffer size.

MBED_DEPRECATED ( "Use ble.gap().getMinNonConnectableAdvertisingInterval(...)" ) const

Returns:: Minimum Advertising interval in milliseconds for nonconnectible mode.

Definition at line 536 of file BLE.h.

MBED_DEPRECATED ( "Use BLE::Instance() instead of BLE constructor." )

Constructor for a handle to a BLE instance (the BLE stack).

BLE handles are thin wrappers around a transport object (that is, ptr. to BLEInstanceBase).

It is better to create BLE objects as singletons accessed through the Instance() method. If multiple BLE handles are constructed for the same interface (using this constructor), they share the same underlying transport object.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingInterval(...)" )

Parameters:

[in] interval Advertising interval in units of milliseconds. Advertising is disabled if interval is 0. If interval is smaller than the minimum supported value, then the minimum supported value is used instead. This minimum value can be discovered using getMinAdvertisingInterval().

This field must be set to 0 if connectionMode is equal to ADV_CONNECTABLE_DIRECTED.

Note:: Decreasing this value allows central devices to detect a peripheral faster at the expense of more power being used by the radio due to the higher data transmit rate.

Note:: WARNING: This API previously used 0.625ms as the unit for its 'interval' argument. That required an explicit conversion from milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is no longer required as the new units are milliseconds. Any application code depending on the old semantics needs to be updated accordingly.

Definition at line 510 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAdvertisingType(...)" )

Set the GAP advertising mode to use for this device.

Definition at line 479 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getAddress(...)" )

Fetch the Bluetooth Low Energy MAC address and type.

Returns:: BLE_ERROR_NONE on success.

Definition at line 464 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAddress(...)" )

Set the BTLE MAC address and type.

Returns:: BLE_ERROR_NONE on success.

Definition at line 447 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().clearAdvertisingPayload(...)" )

Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload().

This automatically propagates the re- initialized advertising payload to the underlying stack.

Definition at line 719 of file BLE.h.

MBED_DEPRECATED ( "Use BLE::processEvents() and BLE::onEventsToProcess()." )

Yield control to the BLE stack or to other tasks waiting for events.

This is a sleep function that returns when there is an application-specific interrupt. This is not interchangeable with WFE() considering that the MCU might wake up several times to service the stack before returning control to the caller.

MBED_DEPRECATED ( "Use ble.gap().updateConnectionParams(...)" )

Update connection parameters while in the peripheral role.

In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for the central to perform the procedure.

Parameters:

[in]	handle	Connection Handle
[in]	params	Pointer to desired connection parameters. If NULL is provided on a peripheral role, the parameters in the PPCP characteristic of the GAP service will be used instead.

Definition at line 1112 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getMaxAdvertisingInterval(...)" ) const

Returns:: Maximum Advertising interval in milliseconds.

Definition at line 549 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getPermittedTxPowerValues(...)" ) const

Query the underlying stack for permitted arguments for setTxPower().

Parameters:

[out]	valueArrayPP	Out parameter to receive the immutable array of Tx values.
[out]	countP	Out parameter to receive the array's size.

MBED_DEPRECATED ( "Use ble.gap().setDeviceName(...)" ) const

Set the device name characteristic in the Gap service.

Parameters:

[in] deviceName The new value for the device-name. This is a UTF-8 encoded, NULL-terminated string.

Definition at line 1127 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setTxPower(...)" )

Set the radio's transmit power.

Parameters:

[in] txPower Radio transmit power in dBm.

Definition at line 1199 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getPreferredConnectionParams(...)" )

Get the GAP peripheral's preferred connection parameters.

These are the defaults that the peripheral would like to have in a connection. The choice of the connection parameters is eventually up to the central.

Parameters:

[out] params The structure where the parameters will be stored. The caller owns memory for this.

Returns:: BLE_ERROR_NONE if the parameters were successfully filled into the given structure pointed to by params.

Definition at line 1074 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getAdvertisingParams(...)" ) const

Returns:: Read back advertising parameters. Useful for storing and restoring parameters rapidly.

Definition at line 594 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setAppearance(...)" )

Set the appearance characteristic in the Gap service.

Parameters:

[in] appearance The new value for the device-appearance.

Definition at line 1170 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().getMinAdvertisingInterval(...)" ) const

Returns:: Minimum Advertising interval in milliseconds.

Definition at line 523 of file BLE.h.

MBED_DEPRECATED ( "Use ble.gap().setPreferredConnectionParams(...)" ) const

Set the GAP peripheral's preferred connection parameters.

These are the defaults that the peripheral would like to have in a connection. The choice of the connection parameters is eventually up to the central.

Parameters:

[in] params The structure containing the desired parameters.

Definition at line 1092 of file BLE.h.

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_cb Callback invoked when there are new events to process.

Definition at line 282 of file BLE.cpp.

void processEvents ( )

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

See also:: onEventsToProcess()

Definition at line 267 of file BLE.cpp.

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.

Definition at line 249 of file BLE.cpp.

const SecurityManager & securityManager ( ) const

A const alternative to securityManager().

Returns:: A const reference to a SecurityManager object associated to this BLE instance.

Definition at line 240 of file BLE.cpp.

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.

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.

Definition at line 167 of file BLE.cpp.

void signalEventsToProcess ( )

This function allows the BLE stack to signal that there is work to do and event processing should be done (BLE::processEvent()).

Note:: This function should be called by the port of BLE_API. It is not meant to be used by end users.

Definition at line 296 of file BLE.cpp.

Field Documentation

const InstanceID_t DEFAULT_INSTANCE = 0 [static]

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

Definition at line 146 of file BLE.h.

static const InstanceID_t NUM_INSTANCES = 1 [static]

The number of permitted BLE instances for the application.

Definition at line 152 of file BLE.h.

Type:	Program
Mbed OS support:	Mbed OS
Created:	23 Feb 2019
Imports:	43
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	1

BLE Class Reference
[Ble]

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

BLE Class Reference [Ble]

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning

BLE Class Reference
[Ble]