Initialization complete event handler.

Note

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

Definition at line 255 of file BLE.h.

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

Definition at line 144 of file BLE.h.

Events to process event handler.

Definition at line 206 of file BLE.h.

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]

instanceID

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

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.

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

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.

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

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.

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

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.

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

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.

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

Add a service declaration to the local server ATT table.

Also add the characteristics contained within.

Parameters

[in]

service

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

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

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

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.

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

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.

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

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.

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.

Translate error code into a printable string.

Parameters

[in]

error

Error code returned by BLE functions.

Returns

A pointer to a const string describing the error.

Accessor to Gap.

All Gap-related functionality requires going through this accessor.

Returns

A reference to a Gap object associated to this BLE instance.

A const alternative to gap().

Returns

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

Accessors to GattClient.

All GattClient related functionality requires going through this accessor.

Returns

A reference to a GattClient object associated to this BLE instance.

A const alternative to gattClient().

Returns

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

Accessor to GattServer.

All GattServer related functionality requires going through this accessor.

Returns

A reference to a GattServer object associated to this BLE instance.

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]	typeP	Type of the current address set.
[out]	address	Value 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 493 of file BLE.h.

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

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

Get the appearance characteristic in the Gap service.

Parameters

[out]

appearanceP

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

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

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

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

Fetch the ID of a BLE instance.

Returns

Instance id of this BLE instance.

Definition at line 184 of file BLE.h.

Get the security status of a connection.

Parameters

[in]	connectionHandle	Handle to identify the connection.
[out]	securityStatusP	Security 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 1541 of file BLE.h.

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

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

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

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.

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

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.

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

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.

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

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.

Attention

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

Definition at line 290 of file BLE.h.

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

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]	enableBonding	Allow for bonding.
[in]	requireMITM	Require protection against man-in-the-middle attacks.
[in]	iocaps	To 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]	passkey	To 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 1517 of file BLE.h.

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.

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

Parameters

[in]

callback

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

Set up a callback for connection events.

Refer to Gap::ConnectionEventCallback_t.

Parameters

[in]

connectionCallback

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

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]

callback

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

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

Parameters

[in]	objPtr	Pointer to the instance that is used to invoke the event handler (memberPtr).
[in]	memberPtr	Event 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 1798 of file BLE.h.

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]

callback

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

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

Parameters

[in]	objPtr	Pointer to the instance that is used to invoke the event handler.
[in]	memberPtr	Event 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 1692 of file BLE.h.

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]

callback

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

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

Parameters

[in]	objPtr	Pointer to the instance that is used to invoke the event handler (memberPtr).
[in]	memberPtr	Event 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 1742 of file BLE.h.

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

Parameters

[in]

disconnectionCallback

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

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

Parameters

[in]	tptr	Instance used to invoke mptr.
[in]	mptr	Event 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 1621 of file BLE.h.

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.

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]

callback

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

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]

callback

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

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

callback

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

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

Parameters

[in]

callback

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

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]

callback

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

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]

callback

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

Set up a callback for timeout events.

Refer to Gap::TimeoutSource_t for possible event types.

Parameters

[in]

timeoutCallback

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

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

Parameters

[in]

callback

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

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

Parameters

[in]

callback

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

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

See also

onEventsToProcess()

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

Return values

BLE_ERROR_NONE	On success; else returns an error code indicating the reason for the failure.
BLE_ERROR_INVALID_STATE	If 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 1560 of file BLE.h.

Read the value of a characteristic from the local GattServer.

Parameters

[in]	attributeHandle	Attribute handle for the value attribute of the characteristic.
[out]	buffer	A buffer to hold the value being read.
[in,out]	lengthP	Length 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 1378 of file BLE.h.

Read the value of a characteristic from the local GattServer.

Parameters

[in]	connectionHandle	Connection Handle.
[in]	attributeHandle	Attribute handle for the value attribute of the characteristic.
[out]	buffer	A buffer to hold the value being read.
[in,out]	lengthP	Length 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 1411 of file BLE.h.

Accessors to SecurityManager.

All SecurityManager-related functionality requires going through this accessor.

Returns

A reference to a SecurityManager object associated to this BLE instance.

A const alternative to securityManager().

Returns

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

Set up parameters for GAP scanning (observer mode).

Parameters

[in]

activeScanning

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

Set the BTLE MAC address and type.

Parameters

[in]	type	Type of the address to set.
[in]	address	Value 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(...).

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]

advData

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

Set the advertising interval.

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.

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.

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]

advParams

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

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.

Set the advertising duration.

A timeout event is genenerated once the advertising period expired.

Parameters

[in]

timeout

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

Set the GAP advertising mode to use for this device.

Parameters

[in]

advType

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

Set the appearance characteristic in the Gap service.

Parameters

[in]

appearance

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

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.

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

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.

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

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

Parameters

[in]

interval

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

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.

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

Set up parameters for GAP scanning (observer mode).

Parameters

[in]

timeout

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

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

Parameters

[in]

window

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

Set the radio's transmit power.

Parameters

[in]

txPower

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

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.

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

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

Parameters

[in]

callback

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

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]	object	Instance used to invoke callbackMember.
[in]	memberCallback	Advertisement 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).

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

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

Update the value of a characteristic on the local GattServer.

Parameters

[in]	attributeHandle	Handle for the value attribute of the characteristic.
[in]	value	A pointer to a buffer holding the new value.
[in]	size	Size of the new value (in bytes).
[in]	localOnly	Should 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 1445 of file BLE.h.

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]	connectionHandle	Connection Handle.
[in]	attributeHandle	Handle for the value attribute of the Characteristic.
[in]	value	A pointer to a buffer holding the new value.
[in]	size	Size of the new value (in bytes).
[in]	localOnly	Should 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 1483 of file BLE.h.

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.

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

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

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

Definition at line 149 of file BLE.h.

The number of permitted BLE instances for the application.

Definition at line 155 of file BLE.h.