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...
 
Gapgap ()
 Accessor to Gap. More...
 
const Gapgap () 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...
 
 BLE (InstanceID_t instanceID=DEFAULT_INSTANCE)
 Constructor for a handle to a BLE instance (the BLE stack). More...
 
void waitForEvent (void)
 Yield control to the BLE stack or to other tasks waiting for events. More...
 
ble_error_t setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
 Set the BTLE MAC address and type. More...
 
ble_error_t getAddress (BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
 Fetch the Bluetooth Low Energy MAC address and type. More...
 
void setAdvertisingType (GapAdvertisingParams::AdvertisingType advType)
 Set the GAP advertising mode to use for this device. More...
 
void setAdvertisingInterval (uint16_t interval)
 Set the advertising interval. More...
 
uint16_t getMinAdvertisingInterval (void) const
 Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types. More...
 
uint16_t getMinNonConnectableAdvertisingInterval (void) const
 Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type. More...
 
uint16_t getMaxAdvertisingInterval (void) const
 Get the maximum advertising interval in milliseconds. More...
 
void setAdvertisingTimeout (uint16_t timeout)
 Set the advertising duration. More...
 
void setAdvertisingParams (const GapAdvertisingParams &advParams)
 Set up a particular, user-constructed set of advertisement parameters for the underlying stack. More...
 
const GapAdvertisingParamsgetAdvertisingParams (void) const
 Get the current advertising parameters. More...
 
ble_error_t accumulateAdvertisingPayload (uint8_t flags)
 Accumulate an AD structure in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::Appearance app)
 Accumulate an AD structure in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayloadTxPower (int8_t power)
 Accumulate an AD structure in the advertising payload. More...
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Accumulate a variable length byte-stream as an AD structure in the advertising payload. More...
 
ble_error_t setAdvertisingData (const GapAdvertisingData &advData)
 Set up a particular, user-constructed advertisement payload for the underlying stack. More...
 
const GapAdvertisingDatagetAdvertisingData (void) const
 Get a reference to the current advertising payload. More...
 
void clearAdvertisingPayload (void)
 Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload(). More...
 
ble_error_t setAdvertisingPayload (void)
 Dynamically reset the accumulated advertising payload and scanResponse. More...
 
ble_error_t accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Accumulate a variable length byte-stream as an AD structure in the scanResponse payload. More...
 
void clearScanResponse (void)
 Reset any scan response prepared from prior calls to accumulateScanResponse(). More...
 
ble_error_t startAdvertising (void)
 Start advertising. More...
 
ble_error_t stopAdvertising (void)
 Stop advertising. More...
 
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)
 Set up parameters for GAP scanning (observer mode). More...
 
ble_error_t setScanInterval (uint16_t interval)
 Set up the scanInterval parameter for GAP scanning (observer mode). More...
 
ble_error_t setScanWindow (uint16_t window)
 Set up the scanWindow parameter for GAP scanning (observer mode). More...
 
ble_error_t setScanTimeout (uint16_t timeout)
 Set up parameters for GAP scanning (observer mode). More...
 
void setActiveScan (bool activeScanning)
 Set up parameters for GAP scanning (observer mode). More...
 
ble_error_t startScan (void(*callback)(const Gap::AdvertisementCallbackParams_t *params))
 Start scanning (Observer Procedure) based on the parameters currently in effect. More...
 
template<typename T >
ble_error_t startScan (T *object, void(T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params))
 Start the scanning procedure. More...
 
ble_error_t stopScan (void)
 Stop scanning. More...
 
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)
 Create a connection (GAP Link Establishment). More...
 
ble_error_t disconnect (Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason)
 This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback. More...
 
ble_error_t disconnect (Gap::DisconnectionReason_t reason)
 This call initiates the disconnection procedure, and its completion is communicated to the application with an invocation of the onDisconnection callback. More...
 
Gap::GapState_t getGapState (void) const
 Returns the current Gap state of the device using a bitmask that describes whether the device is advertising or connected. More...
 
ble_error_t getPreferredConnectionParams (Gap::ConnectionParams_t *params)
 Get the GAP peripheral's preferred connection parameters. More...
 
ble_error_t setPreferredConnectionParams (const Gap::ConnectionParams_t *params)
 Set the GAP peripheral's preferred connection parameters. More...
 
ble_error_t updateConnectionParams (Gap::Handle_t handle, const Gap::ConnectionParams_t *params)
 Update connection parameters while in the peripheral role. More...
 
ble_error_t setDeviceName (const uint8_t *deviceName)
 Set the device name characteristic in the Gap service. More...
 
ble_error_t getDeviceName (uint8_t *deviceName, unsigned *lengthP)
 Get the value of the device name characteristic in the Gap service. More...
 
ble_error_t setAppearance (GapAdvertisingData::Appearance appearance)
 Set the appearance characteristic in the Gap service. More...
 
ble_error_t getAppearance (GapAdvertisingData::Appearance *appearanceP)
 Get the appearance characteristic in the Gap service. More...
 
ble_error_t setTxPower (int8_t txPower)
 Set the radio's transmit power. More...
 
void getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP)
 Query the underlying stack for permitted arguments for setTxPower(). More...
 
ble_error_t addService (GattService &service)
 Add a service declaration to the local server ATT table. More...
 
ble_error_t readCharacteristicValue (GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
 Read the value of a characteristic from the local GattServer. More...
 
ble_error_t readCharacteristicValue (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
 Read the value of a characteristic from the local GattServer. More...
 
ble_error_t updateCharacteristicValue (GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
 Update the value of a characteristic on the local GattServer. More...
 
ble_error_t updateCharacteristicValue (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
 Update the value of a characteristic on the local GattServer. More...
 
ble_error_t initializeSecurity (bool enableBonding=true, bool requireMITM=true, SecurityManager::SecurityIOCapabilities_t iocaps=SecurityManager::IO_CAPS_NONE, const SecurityManager::Passkey_t passkey=NULL)
 Enable the BLE stack's Security Manager. More...
 
ble_error_t getLinkSecurity (Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP)
 Get the security status of a connection. More...
 
ble_error_t purgeAllBondingState (void)
 Delete all peer device context and all related bonding information from the database within the security manager. More...
 
void onTimeout (Gap::TimeoutEventCallback_t timeoutCallback)
 Set up a callback for timeout events. More...
 
void onConnection (Gap::ConnectionEventCallback_t connectionCallback)
 Set up a callback for connection events. More...
 
void onDisconnection (Gap::DisconnectionEventCallback_t disconnectionCallback)
 Append to a chain of callbacks to be invoked upon GAP disconnection. More...
 
template<typename T >
void onDisconnection (T *tptr, void(T::*mptr)(const Gap::DisconnectionCallbackParams_t *))
 The same as onDisconnection() but allows an object reference and member function to be added to the chain of callbacks. More...
 
void onRadioNotification (void(*callback)(bool))
 Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack. More...
 
void onDataSent (void(*callback)(unsigned count))
 Add a callback for the GATT event DATA_SENT (which is triggered when updates are sent out by GATT in the form of notifications). More...
 
template<typename T >
void onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count))
 The same as onDataSent() but allows an object reference and member function to be added to the chain of callbacks. More...
 
void onDataWritten (void(*callback)(const GattWriteCallbackParams *eventDataP))
 Set up a callback for when an attribute has its value updated by or at the connected peer. More...
 
template<typename T >
void onDataWritten (T *objPtr, void(T::*memberPtr)(const GattWriteCallbackParams *context))
 The same as onDataWritten() but allows an object reference and member function to be added to the chain of callbacks. More...
 
ble_error_t onDataRead (void(*callback)(const GattReadCallbackParams *eventDataP))
 Set up a callback to be invoked on the peripheral when an attribute is being read by a remote client. More...
 
template<typename T >
ble_error_t onDataRead (T *objPtr, void(T::*memberPtr)(const GattReadCallbackParams *context))
 The same as onDataRead() but allows an object reference and member function to be added to the chain of callbacks. More...
 
void onUpdatesEnabled (GattServer::EventCallback_t callback)
 Set up a callback for when notifications or indications are enabled for a characteristic on the local GattServer. More...
 
void onUpdatesDisabled (GattServer::EventCallback_t callback)
 Set up a callback for when notifications or indications are disabled for a characteristic on the local GattServer. More...
 
void onConfirmationReceived (GattServer::EventCallback_t callback)
 Set up a callback for when the GATT server receives a response for an indication event sent previously. More...
 
void onSecuritySetupInitiated (SecurityManager::SecuritySetupInitiatedCallback_t callback)
 Set up a callback for when the security setup procedure (key generation and exchange) for a link has started. More...
 
void onSecuritySetupCompleted (SecurityManager::SecuritySetupCompletedCallback_t callback)
 Set up a callback for when the security setup procedure (key generation and exchange) for a link has completed. More...
 
void onLinkSecured (SecurityManager::LinkSecuredCallback_t callback)
 Set up a callback for when a link with the peer is secured. More...
 
void onSecurityContextStored (SecurityManager::HandleSpecificEvent_t callback)
 Set up a callback for successful bonding, meaning that link-specific security context is stored persistently for a peer device. More...
 
void onPasskeyDisplay (SecurityManager::PasskeyDisplayCallback_t callback)
 Set up a callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability. 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 137 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 253 of file BLE.h.

typedef unsigned InstanceID_t

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

Definition at line 142 of file BLE.h.

Events to process event handler.

Definition at line 204 of file BLE.h.

Constructor & Destructor Documentation

BLE ( InstanceID_t  instanceID = DEFAULT_INSTANCE)

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

Parameters
[in]instanceIDBLE Instance ID to get.

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.

Deprecated:
Use the Instance() function instead of the constructor.

Member Function Documentation

ble_error_t accumulateAdvertisingPayload ( uint8_t  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]flagsThe flags to add. Please refer to GapAdvertisingData::Flags for valid flags. Multiple flags may be specified in combination.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::accumulateAdvertisingPayload(uint8_t). A former call to ble.accumulateAdvertisingPayload(flags) should be replaced with ble.gap().accumulateAdvertisingPayload(flags).
ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::Appearance  app)

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]appThe appearance of the peripheral.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance). A former call to ble.accumulateAdvertisingPayload(appearance) should be replaced with ble.gap().accumulateAdvertisingPayload(appearance).
ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)

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
typeThe type that describes the variable length data.
dataData bytes.
lenData length.
Returns
BLE_ERROR_NONE if the advertisement payload was updated based on matching AD type; otherwise, an appropriate error.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t). A former call to ble.accumulateAdvertisingPayload(...) should be replaced with ble.gap().accumulateAdvertisingPayload(...).
ble_error_t accumulateAdvertisingPayloadTxPower ( int8_t  power)

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]powerThe max transmit power to be used by the controller. This is only a hint.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::accumulateAdvertisingPayloadTxPower(). A former call to ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
ble_error_t accumulateScanResponse ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)

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

Parameters
[in]typeThe type that describes the variable length data.
[in]dataData bytes.
[in]lenData length.
Returns
BLE_ERROR_NONE if the data was successfully added to the scan response payload.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::accumulateScanResponse(). A former call to ble.accumulateScanResponse(...) should be replaced with ble.gap().accumulateScanResponse(...).
ble_error_t addService ( GattService service)

Add a service declaration to the local server ATT table.

Also add the characteristics contained within.

Parameters
[in]serviceThe service to be added; attribute handle of services, characteristic and characteristic descriptors are updated by the process.
Returns
BLE_ERROR_NONE if the service was successfully added.
Deprecated:
You should use the parallel API from GattServer directly, refer to GattServer::addService(). A former call to ble.addService() should be replaced with ble.gattServer().addService().

Definition at line 1328 of file BLE.h.

void clearAdvertisingPayload ( void  )

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

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

Deprecated:
You should use the parallel API from Gap directly and refer to Gap::clearAdvertisingPayload(). A former call to ble.clearAdvertisingPayload(...) should be replaced with ble.gap().clearAdvertisingPayload(...).
void clearScanResponse ( void  )

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

Deprecated:
You should use the parallel API from Gap directly and refer to Gap::clearScanResponse(). A former call to ble.clearScanResponse(...) should be replaced with ble.gap().clearScanResponse(...).
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 
)

Create a connection (GAP Link Establishment).

Parameters
peerAddr48-bit address, LSB format.
peerAddrTypeAddress type of the peer.
connectionParamsConnection parameters.
scanParamsParameters 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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::connect(). A former call to ble.connect(...) should be replaced with ble.gap().connect(...).
ble_error_t disconnect ( Gap::Handle_t  connectionHandle,
Gap::DisconnectionReason_t  reason 
)

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]reasonThe reason for disconnection; sent back to the peer.
Returns
BLE_ERROR_NONE if the disconnection procedure successfully started.
Deprecated:
You should use the parallel API from Gap directly and refer to GAP::disconnect(). A former call to ble.disconnect(...) should be replaced with ble.gap().disconnect(...).
ble_error_t disconnect ( Gap::DisconnectionReason_t  reason)

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

Parameters
reasonThe reason for disconnection; sent back to the peer.
Returns
BLE_ERROR_NONE if the disconnection procedure successfully started.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::disconnect(). A former call to ble.disconnect(reason) should be replaced with ble.gap().disconnect(reason).
Note
This version of disconnect() doesn't take a connection handle. It works reliably only for stacks that are limited to a single connection.
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.

Fetch the Bluetooth Low Energy MAC address and type.

Parameters
[out]typePType of the current address set.
[out]addressValue of the current address.
Returns
BLE_ERROR_NONE on success.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::getAddress(). A former call to ble.getAddress(...) should be replaced with ble.gap().getAddress(...).

Definition at line 485 of file BLE.h.

const GapAdvertisingData& getAdvertisingData ( void  ) const

Get a reference to the current advertising payload.

Returns
Read back advertising data. Useful for storing and restoring payload.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::getAdvertisingData(). A former call to ble.getAdvertisingData(...) should be replaced with ble.gap().getAdvertisingPayload()(...).
const GapAdvertisingParams& getAdvertisingParams ( void  ) const

Get the current advertising parameters.

Returns
Read back advertising parameters. Useful for storing and restoring parameters rapidly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::getAdvertisingParams(). A former call to ble.getAdvertisingParams(...) should be replaced with ble.gap().getAdvertisingParams(...).
ble_error_t getAppearance ( GapAdvertisingData::Appearance appearanceP)

Get the appearance characteristic in the Gap service.

Parameters
[out]appearancePThe new value for the device-appearance.
Returns
BLE_ERROR_NONE if the device-appearance was fetched correctly from the underlying BLE stack.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::getAppearance(). A former call to ble.getAppearance() should be replaced with ble.gap().getAppearance().

Definition at line 1275 of file BLE.h.

ble_error_t getDeviceName ( uint8_t *  deviceName,
unsigned *  lengthP 
)

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

Parameters
[out]deviceNamePointer 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).
Returns
BLE_ERROR_NONE if the device name was fetched correctly from the underlying BLE stack.
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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::getDeviceName(). A former call to ble.getDeviceName() should be replaced with ble.gap().getDeviceName().

Definition at line 1236 of file BLE.h.

Gap::GapState_t getGapState ( void  ) const

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

Returns
The current GAP state of the device.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::getState(). A former call to ble.getGapState() should be replaced with ble.gap().getState().
InstanceID_t getInstanceID ( void  ) const

Fetch the ID of a BLE instance.

Returns
Instance id of this BLE instance.

Definition at line 182 of file BLE.h.

ble_error_t getLinkSecurity ( Gap::Handle_t  connectionHandle,
SecurityManager::LinkSecurityStatus_t securityStatusP 
)

Get the security status of a connection.

Parameters
[in]connectionHandleHandle to identify the connection.
[out]securityStatusPSecurity status.
Returns
BLE_SUCCESS or appropriate error code indicating the reason of failure.
Deprecated:
You should use the parallel API from SecurityManager directly, refer to SecurityManager::getLinkSecurity(). A former call to ble.getLinkSecurity(...) should be replaced with ble.securityManager().getLinkSecurity(...).

Definition at line 1516 of file BLE.h.

uint16_t getMaxAdvertisingInterval ( void  ) const

Get the maximum advertising interval in milliseconds.

Returns
Maximum Advertising interval in milliseconds.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::getMaxAdvertisingInterval(). A former call to ble.getMaxAdvertisingInterval(...) should be replaced with ble.gap().getMaxAdvertisingInterval(...).

Definition at line 581 of file BLE.h.

uint16_t getMinAdvertisingInterval ( void  ) const

Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types.

Returns
Minimum Advertising interval in milliseconds.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::getMinAdvertisingInterval(). A former call to ble.getMinAdvertisingInterval(...) should be replaced with ble.gap().getMinAdvertisingInterval(...).

Definition at line 548 of file BLE.h.

uint16_t getMinNonConnectableAdvertisingInterval ( void  ) const

Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type.

Returns
Minimum Advertising interval in milliseconds for nonconnectible mode.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::MinNonConnectableAdvertisingInterval(). A former call to ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with ble.gap().getMinNonConnectableAdvertisingInterval(...).

Definition at line 565 of file BLE.h.

void getPermittedTxPowerValues ( const int8_t **  valueArrayPP,
size_t *  countP 
)

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

Parameters
[out]valueArrayPPOut parameter to receive the immutable array of Tx values.
[out]countPOut parameter to receive the array's size.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::getPermittedTxPowerValues(). A former call to ble.getPermittedTxPowerValues() should be replaced with ble.gap().getPermittedTxPowerValues().
ble_error_t getPreferredConnectionParams ( Gap::ConnectionParams_t params)

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]paramsThe 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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::getPreferredConnectionParams(). A former call to ble.getPreferredConnectionParams() should be replaced with ble.gap().getPreferredConnectionParams().

Definition at line 1140 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 288 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 305 of file BLE.h.

ble_error_t initializeSecurity ( bool  enableBonding = true,
bool  requireMITM = true,
SecurityManager::SecurityIOCapabilities_t  iocaps = SecurityManager::IO_CAPS_NONE,
const SecurityManager::Passkey_t  passkey = NULL 
)

Enable the BLE stack's Security Manager.

The Security Manager implements the cryptographic algorithms and protocol exchanges that allow two devices to securely exchange data and privately detect each other. Calling this API is a prerequisite for encryption and pairing (bonding).

Parameters
[in]enableBondingAllow for bonding.
[in]requireMITMRequire protection against man-in-the-middle attacks.
[in]iocapsTo specify the I/O capabilities of this peripheral, such as availability of a display or keyboard, to support out-of-band exchanges of security data.
[in]passkeyTo specify a static passkey.
Returns
BLE_ERROR_NONE on success.
Deprecated:
You should use the parallel API from SecurityManager directly, refer to SecurityManager.init(). A former call to ble.initializeSecurity(...) should be replaced with ble.securityManager().init(...).

Definition at line 1492 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 onConfirmationReceived ( GattServer::EventCallback_t  callback)

Set up a callback for when the GATT server receives a response for an indication event sent previously.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onConfirmationReceived(). A former call to ble.onConfirmationReceived(callback) should be replaced with ble.gattServer().onConfirmationReceived(callback).

Definition at line 1820 of file BLE.h.

void onConnection ( Gap::ConnectionEventCallback_t  connectionCallback)

Set up a callback for connection events.

Refer to Gap::ConnectionEventCallback_t.

Parameters
[in]connectionCallbackEvent handler being registered.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::onConnection(). A former call to ble.onConnection(callback) should be replaced with ble.gap().onConnection(callback).
ble_error_t onDataRead ( void(*)(const GattReadCallbackParams *eventDataP)  callback)

Set up a callback to be invoked on the peripheral when an attribute is being read by a remote client.

Note
This functionality may not be available on all underlying stacks. You could use GattCharacteristic::setReadAuthorizationCallback() as an alternative.
It is possible to chain together multiple onDataRead callbacks (potentially from different modules of an application) to receive updates to characteristics. Services may add their own onDataRead callbacks behind the scenes to trap interesting events.
It is also possible to set up a callback into a member function of some object.
Parameters
[in]callbackEvent handler being registered.
Returns
BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; else BLE_ERROR_NONE.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onDataRead(). A former call to ble.onDataRead(...) should be replaced with ble.gattServer().onDataRead(...).

Definition at line 1745 of file BLE.h.

ble_error_t onDataRead ( T *  objPtr,
void(T::*)(const GattReadCallbackParams *context)  memberPtr 
)

The same as onDataRead() but allows an object reference and member function to be added to the chain of callbacks.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler (memberPtr).
[in]memberPtrEvent handler being registered. It is a member function.
Returns
BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; else BLE_ERROR_NONE.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onDataRead(). A former call to ble.onDataRead(...) should be replaced with ble.gattServer().onDataRead(...).

Definition at line 1769 of file BLE.h.

void onDataSent ( void(*)(unsigned count)  callback)

Add a callback for the GATT event DATA_SENT (which is triggered when updates are sent out by GATT in the form of notifications).

Parameters
[in]callbackEvent handler being registered.
Note
It is possible to chain together multiple onDataSent callbacks (potentially from different modules of an application) to receive updates to characteristics.
It is also possible to set up a callback into a member function of some object.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onDataSent(). A former call to ble.onDataSent(...) should be replaced with ble.gattServer().onDataSent(...).

Definition at line 1642 of file BLE.h.

void onDataSent ( T *  objPtr,
void(T::*)(unsigned count)  memberPtr 
)

The same as onDataSent() but allows an object reference and member function to be added to the chain of callbacks.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler.
[in]memberPtrEvent handler being registered. It is a member function.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onDataSent(). A former call to ble.onDataSent(...) should be replaced with ble.gattServer().onDataSent(...).

Definition at line 1663 of file BLE.h.

void onDataWritten ( void(*)(const GattWriteCallbackParams *eventDataP)  callback)

Set up a callback for when an attribute has its value updated by or at the connected peer.

For a peripheral, this callback is triggered when the local GATT server has an attribute updated by a write command from the peer. For a Central, this callback is triggered when a response is received for a write request.

Parameters
[in]callbackThe event handler being registered.
Note
It is possible to chain together multiple onDataWritten callbacks (potentially from different modules of an application) to receive updates to characteristics. Many services, such as DFU and UART, add their own onDataWritten callbacks behind the scenes to trap interesting events.
It is also possible to set up a callback into a member function of some object.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onDataWritten(). A former call to ble.onDataWritten(...) should be replaced with ble.gattServer().onDataWritten(...).

Definition at line 1691 of file BLE.h.

void onDataWritten ( T *  objPtr,
void(T::*)(const GattWriteCallbackParams *context)  memberPtr 
)

The same as onDataWritten() but allows an object reference and member function to be added to the chain of callbacks.

Parameters
[in]objPtrPointer to the instance that is used to invoke the event handler (memberPtr).
[in]memberPtrEvent handler being registered. It is a member function.
Deprecated:
You should use the parallel API from GattServer directly, refer to GattServer::onDataWritten(). A former call to ble.onDataWritten(...) should be replaced with ble.gattServer().onDataWritten(...).

Definition at line 1713 of file BLE.h.

void onDisconnection ( Gap::DisconnectionEventCallback_t  disconnectionCallback)

Append to a chain of callbacks to be invoked upon GAP disconnection.

Parameters
[in]disconnectionCallbackEvent handler being registered.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::onDisconnection(). A former call to ble.onDisconnection(callback) should be replaced with ble.gap().onDisconnection(callback).
void onDisconnection ( T *  tptr,
void(T::*)(const Gap::DisconnectionCallbackParams_t *)  mptr 
)

The same as onDisconnection() but allows an object reference and member function to be added to the chain of callbacks.

Parameters
[in]tptrInstance used to invoke mptr.
[in]mptrEvent handler being registered.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::onDisconnection(). A former call to ble.onDisconnection(callback) should be replaced with ble.gap().onDisconnection(callback).

Definition at line 1594 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_cbCallback invoked when there are new events to process.
void onLinkSecured ( SecurityManager::LinkSecuredCallback_t  callback)

Set up a callback for when a link with the peer is secured.

For bonded devices, subsequent reconnections with a bonded peer will result only in this callback when the link is secured, and setup procedures will not occur unless the bonding information is either lost or deleted on either or both sides. The callback is passed in a SecurityManager::SecurityMode_t according to the level of security in effect for the secured link.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::onLinkSecured(). A former call to ble.onLinkSecured(callback) should be replaced with ble.securityManager().onLinkSecured(callback).

Definition at line 1880 of file BLE.h.

void onPasskeyDisplay ( SecurityManager::PasskeyDisplayCallback_t  callback)

Set up a callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability.

This happens when security is configured to prevent man-in-the-middle attacks, and the peers need to exchange a passkey (or PIN) to authenticate the connection attempt.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::onPasskeyDisplay(). A former call to ble.onPasskeyDisplay(callback) should be replaced with ble.securityManager().onPasskeyDisplay(callback).

Definition at line 1917 of file BLE.h.

void onRadioNotification ( void(*)(bool)  callback)

Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack.

These notify the application when the radio is in use. The signal is sent using software interrupt.

The ACTIVE signal is sent before the radio event starts. The nACTIVE signal is sent at the end of the radio event. These signals can be used by the application programmer to synchronize application logic with radio activity. For example, the ACTIVE signal can be used to shut off external devices to manage peak current drawn during periods when the radio is on, or to trigger sensor data collection for transmission in the radio event.

Parameters
callbackThe application handler to be invoked in response to a radio ACTIVE/INACTIVE event.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::onRadioNotification(). A former call to ble.onRadioNotification(...) should be replaced with ble.gap().onRadioNotification(...).
void onSecurityContextStored ( SecurityManager::HandleSpecificEvent_t  callback)

Set up a callback for successful bonding, meaning that link-specific security context is stored persistently for a peer device.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::onSecurityContextStored(). A former call to ble.onSecurityContextStored(callback) should be replaced with ble.securityManager().onSecurityContextStored(callback).

Definition at line 1897 of file BLE.h.

void onSecuritySetupCompleted ( SecurityManager::SecuritySetupCompletedCallback_t  callback)

Set up a callback for when the security setup procedure (key generation and exchange) for a link has completed.

This will be skipped for bonded devices. The callback is passed in the success/failure status of the security setup procedure.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::onSecuritySetupCompleted(). A former call to ble.onSecuritySetupCompleted(callback) should be replaced with ble.securityManager().onSecuritySetupCompleted(callback).

Definition at line 1859 of file BLE.h.

void onSecuritySetupInitiated ( SecurityManager::SecuritySetupInitiatedCallback_t  callback)

Set up a callback for when the security setup procedure (key generation and exchange) for a link has started.

This will be skipped for bonded devices. The callback is passed in parameters received from the peer's security request: bool allowBonding, bool requireMITM and SecurityIOCapabilities_t.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::onSecuritySetupInitiated(). A former call to ble.onSecuritySetupInitiated(callback) should be replaced with ble.securityManager().onSecuritySetupInitiated(callback).

Definition at line 1840 of file BLE.h.

void onTimeout ( Gap::TimeoutEventCallback_t  timeoutCallback)

Set up a callback for timeout events.

Refer to Gap::TimeoutSource_t for possible event types.

Parameters
[in]timeoutCallbackEvent handler being registered.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::onTimeout(). A former call to ble.onTimeout(callback) should be replaced with ble.gap().onTimeout(callback).
void onUpdatesDisabled ( GattServer::EventCallback_t  callback)

Set up a callback for when notifications or indications are disabled for a characteristic on the local GattServer.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onUpdatesDisabled(). A former call to ble.onUpdatesDisabled(callback) should be replaced with ble.gattServer().onUpdatesDisabled(callback).

Definition at line 1803 of file BLE.h.

void onUpdatesEnabled ( GattServer::EventCallback_t  callback)

Set up a callback for when notifications or indications are enabled for a characteristic on the local GattServer.

Parameters
[in]callbackEvent handler being registered.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::onUpdatesEnabled(). A former call to ble.onUpdatesEnabled(callback) should be replaced with ble.gattServer().onUpdatesEnabled(callback).

Definition at line 1786 of file BLE.h.

void processEvents ( )

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

See also
onEventsToProcess()
ble_error_t purgeAllBondingState ( void  )

Delete all peer device context and all related bonding information from the database within the security manager.

Return values
BLE_ERROR_NONEOn success; else returns an error code indicating the reason for the failure.
BLE_ERROR_INVALID_STATEIf the API is called without module initialization or application registration.
Deprecated:
You should use the parallel API from SecurityManager directly and refer to SecurityManager::purgeAllBondingState(). A former call to ble.purgeAllBondingState() should be replaced with ble.securityManager().purgeAllBondingState().

Definition at line 1535 of file BLE.h.

ble_error_t readCharacteristicValue ( GattAttribute::Handle_t  attributeHandle,
uint8_t *  buffer,
uint16_t *  lengthP 
)

Read the value of a characteristic from the local GattServer.

Parameters
[in]attributeHandleAttribute handle for the value attribute of the characteristic.
[out]bufferA buffer to hold the value being read.
[in,out]lengthPLength of the buffer being supplied. If the attribute value is longer than the size of the supplied buffer, this variable will return the total attribute value length (excluding offset). The application may use this information to allocate a suitable buffer size.
Returns
BLE_ERROR_NONE if a value was read successfully into the buffer.
Deprecated:
You should use the parallel API from GattServer directly, GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call to ble.readCharacteristicValue() should be replaced with ble.gattServer().read().

Definition at line 1355 of file BLE.h.

ble_error_t readCharacteristicValue ( Gap::Handle_t  connectionHandle,
GattAttribute::Handle_t  attributeHandle,
uint8_t *  buffer,
uint16_t *  lengthP 
)

Read the value of a characteristic from the local GattServer.

Parameters
[in]connectionHandleConnection Handle.
[in]attributeHandleAttribute handle for the value attribute of the characteristic.
[out]bufferA buffer to hold the value being read.
[in,out]lengthPLength of the buffer being supplied. If the attribute value is longer than the size of the supplied buffer, this variable will return the total attribute value length (excluding offset). The application may use this information to allocate a suitable buffer size.
Returns
BLE_ERROR_NONE if a value was read successfully into the buffer.
Note
This API is a version of the above, with an additional connection handle parameter to allow fetches for connection-specific multivalued attributes (such as the CCCDs).
Deprecated:
You should use the parallel API from GattServer directly, refer to GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t). A former call to ble.readCharacteristicValue() should be replaced with ble.gattServer().read().

Definition at line 1388 of file BLE.h.

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.
void setActiveScan ( bool  activeScanning)

Set up parameters for GAP scanning (observer mode).

Parameters
[in]activeScanningSet to True if active-scanning is required. This is used to fetch the scan response from a peer if possible.

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

Deprecated:
You should use the parallel API from Gap directly, refer to Gap::setActiveScan(). A former call to ble.setActiveScan(...) should be replaced with ble.gap().setActiveScanning(...).
ble_error_t setAddress ( BLEProtocol::AddressType_t  type,
const BLEProtocol::AddressBytes_t  address 
)

Set the BTLE MAC address and type.

Parameters
[in]typeType of the address to set.
[in]addressValue of the address to set. It is ordered in little endian.
Returns
BLE_ERROR_NONE on success.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::setAddress(). A former call to ble.setAddress(...) should be replaced with ble.gap().setAddress(...).
ble_error_t setAdvertisingData ( const GapAdvertisingData advData)

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

Parameters
[in]advDataAdvertising data to set.
Returns
BLE_ERROR_NONE if the advertising data was set successfully.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::setAdvertisingData(). A former call to ble.setAdvertisingData(...) should be replaced with ble.gap().setAdvertisingPayload(...).
void setAdvertisingInterval ( uint16_t  interval)

Set the advertising interval.

Parameters
[in]intervalAdvertising 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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setAdvertisingInterval(). A former call to ble.setAdvertisingInterval(...) should be replaced with ble.gap().setAdvertisingInterval(...).
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.
void setAdvertisingParams ( const GapAdvertisingParams advParams)

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

Parameters
[in]advParamsThe new advertising parameters.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setAdvertisingParams(). A former call to ble.setAdvertisingParams(...) should be replaced with ble.gap().setAdvertisingParams(...).
ble_error_t setAdvertisingPayload ( void  )

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.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::setAdvertisingPayload().
Note
The new APIs in Gap update the underlying advertisement payload implicitly.
void setAdvertisingTimeout ( uint16_t  timeout)

Set the advertising duration.

A timeout event is genenerated once the advertising period expired.

Parameters
[in]timeoutAdvertising timeout (in seconds) between 0x1 and 0x3FFF (1 and 16383). Use 0 to disable the advertising timeout.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setAdvertisingTimeout(). A former call to ble.setAdvertisingTimeout(...) should be replaced with ble.gap().setAdvertisingTimeout(...).
void setAdvertisingType ( GapAdvertisingParams::AdvertisingType  advType)

Set the GAP advertising mode to use for this device.

Parameters
[in]advTypeNew type of advertising to use.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setAdvertisingType(). A former call to ble.setAdvertisingType(...) should be replaced with ble.gap().setAdvertisingType(...).
ble_error_t setAppearance ( GapAdvertisingData::Appearance  appearance)

Set the appearance characteristic in the Gap service.

Parameters
[in]appearanceThe new value for the device-appearance.
Returns
BLE_ERROR_NONE if the new appearance was set correctly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setAppearance(). A former call to ble.setAppearance() should be replaced with ble.gap().setAppearance().

Definition at line 1255 of file BLE.h.

ble_error_t setDeviceName ( const uint8_t *  deviceName)

Set the device name characteristic in the Gap service.

Parameters
[in]deviceNameThe new value for the device-name. This is a UTF-8 encoded, NULL-terminated string.
Returns
BLE_ERROR_NONE if the device name was set correctly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setDeviceName(). A former call to ble.setDeviceName() should be replaced with ble.gap().setDeviceName().

Definition at line 1203 of file BLE.h.

ble_error_t setPreferredConnectionParams ( const Gap::ConnectionParams_t params)

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]paramsThe structure containing the desired parameters.
Returns
BLE_ERROR_NONE if the preferred connection parameters were set correctly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setPreferredConnectionParams(). A former call to ble.setPreferredConnectionParams() should be replaced with ble.gap().setPreferredConnectionParams().

Definition at line 1162 of file BLE.h.

ble_error_t setScanInterval ( uint16_t  interval)

Set up the scanInterval parameter for GAP scanning (observer mode).

Parameters
[in]intervalScan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Returns
BLE_ERROR_NONE if the scan interval was correctly set.

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

Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setScanInterval(). A former call to ble.setScanInterval(interval) should be replaced with ble.gap().setScanInterval(interval).
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 
)

Set up parameters for GAP scanning (observer mode).

Parameters
[in]intervalScan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
[in]windowScan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
[in]timeoutScan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
[in]activeScanningSet to True if active-scanning is required. This is used to fetch the scan response from a peer if possible.
Returns
BLE_ERROR_NONE if the scan parameters were correctly set.

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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setScanParams(). A former call to ble.setScanParams(...) should be replaced with ble.gap().setScanParams(...).
ble_error_t setScanTimeout ( uint16_t  timeout)

Set up parameters for GAP scanning (observer mode).

Parameters
[in]timeoutScan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
Returns
BLE_ERROR_NONE if the scan timeout was correctly set.

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.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setScanTimeout(). A former call to ble.setScanTimeout(...) should be replaced with ble.gap().setScanTimeout(...).
ble_error_t setScanWindow ( uint16_t  window)

Set up the scanWindow parameter for GAP scanning (observer mode).

Parameters
[in]windowScan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Returns
BLE_ERROR_NONE if the scan window was correctly set.

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

Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setScanWindow(). A former call to ble.setScanWindow(window) should be replaced with ble.gap().setScanWindow(window).
ble_error_t setTxPower ( int8_t  txPower)

Set the radio's transmit power.

Parameters
[in]txPowerRadio transmit power in dBm.
Returns
BLE_ERROR_NONE if the new radio's transmit power was set correctly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::setTxPower(). A former call to ble.setTxPower() should be replaced with ble.gap().setTxPower().
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.
ble_error_t startAdvertising ( void  )

Start advertising.

Returns
BLE_ERROR_NONE if the advertising procedure successfully started.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::startAdvertising(). A former call to ble.startAdvertising(...) should be replaced with ble.gap().startAdvertising(...).
ble_error_t startScan ( void(*)(const Gap::AdvertisementCallbackParams_t *params)  callback)

Start scanning (Observer Procedure) based on the parameters currently in effect.

Parameters
[in]callbackThe application-specific callback to be invoked upon receiving every advertisement report. This can be passed in as NULL, in which case scanning may not be enabled at all.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::startScan(). A former call to ble.startScan(callback) should be replaced with ble.gap().startScan(callback).
ble_error_t startScan ( T *  object,
void(T::*)(const Gap::AdvertisementCallbackParams_t *params)  memberCallback 
)

Start the scanning procedure.

Packets received during the scan procedure are forwarded to the scan packet handler passed as argument to this function.

Parameters
[in]objectInstance used to invoke callbackMember.
[in]memberCallbackAdvertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback invoked from object.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Deprecated:
You should use the parallel API from Gap directly, refer to Gap::startScan(). A former call to ble.startScan(callback) should be replaced with ble.gap().startScan(object, callback).
ble_error_t stopAdvertising ( void  )

Stop advertising.

Returns
BLE_ERROR_NONE if the advertising procedure has been successfully stopped.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::stopAdvertising(). A former call to ble.stopAdvertising(...) should be replaced with ble.gap().stopAdvertising(...).
ble_error_t stopScan ( void  )

Stop scanning.

The current scanning parameters remain in effect.

Returns
BLE_ERROR_NONE if successfully stopped scanning procedure.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::stopScan(). A former call to ble.stopScan() should be replaced with ble.gap().stopScan().

Definition at line 1031 of file BLE.h.

ble_error_t updateCharacteristicValue ( GattAttribute::Handle_t  attributeHandle,
const uint8_t *  value,
uint16_t  size,
bool  localOnly = false 
)

Update the value of a characteristic on the local GattServer.

Parameters
[in]attributeHandleHandle for the value attribute of the characteristic.
[in]valueA pointer to a buffer holding the new value.
[in]sizeSize of the new value (in bytes).
[in]localOnlyShould this update be kept on the local GattServer regardless of the state of the notify/indicate flag in the CCCD for this characteristic? If set to true, no notification or indication is generated.
Returns
BLE_ERROR_NONE if we have successfully set the value of the attribute.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool). A former call to ble.updateCharacteristicValue() should be replaced with ble.gattServer().write().

Definition at line 1422 of file BLE.h.

ble_error_t updateCharacteristicValue ( Gap::Handle_t  connectionHandle,
GattAttribute::Handle_t  attributeHandle,
const uint8_t *  value,
uint16_t  size,
bool  localOnly = false 
)

Update the value of a characteristic on the local GattServer.

A version of the above, with a connection handle parameter to allow updates for connection-specific multivalued attributes (such as the CCCDs).

Parameters
[in]connectionHandleConnection Handle.
[in]attributeHandleHandle for the value attribute of the Characteristic.
[in]valueA pointer to a buffer holding the new value.
[in]sizeSize of the new value (in bytes).
[in]localOnlyShould this update be kept on the local GattServer regardless of the state of the notify/indicate flag in the CCCD for this Characteristic? If set to true, no notification or indication is generated.
Returns
BLE_ERROR_NONE if we have successfully set the value of the attribute.
Deprecated:
You should use the parallel API from GattServer directly and refer to GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool). A former call to ble.updateCharacteristicValue() should be replaced with ble.gattServer().write().

Definition at line 1460 of file BLE.h.

ble_error_t updateConnectionParams ( Gap::Handle_t  handle,
const Gap::ConnectionParams_t params 
)

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]handleConnection Handle
[in]paramsPointer 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.
Returns
BLE_ERROR_NONE if the connection parameters were updated correctly.
Deprecated:
You should use the parallel API from Gap directly and refer to Gap::updateConnectionParams(). A former call to ble.updateConnectionParams() should be replaced with ble.gap().updateConnectionParams().
void waitForEvent ( void  )

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.

Deprecated:
This function blocks the CPU. Use the pair onEventsToProcess() and processEvents().

Field Documentation

const InstanceID_t DEFAULT_INSTANCE = 0
static

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

Definition at line 147 of file BLE.h.

const InstanceID_t NUM_INSTANCES = 1
static

The number of permitted BLE instances for the application.

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