Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of BLE_API by
BLEDevice Class Reference
The base class used to abstract away BLE capable radio transceivers or SOCs, to enable this BLE API to work with any radio transparently. More...
#include <BLEDevice.h>
Public Member Functions | |
ble_error_t | init () |
Initialize the BLE controller. | |
ble_error_t | shutdown (void) |
Purge the BLE stack of GATT and GAP state. | |
ble_error_t | setAddress (Gap::addr_type_t type, const Gap::address_t address) |
Set the BTLE MAC address and type. | |
ble_error_t | getAddress (Gap::addr_type_t *typeP, Gap::address_t address) |
Fetch the BTLE MAC address and type. | |
void | setAdvertisingType (GapAdvertisingParams::AdvertisingType) |
void | setAdvertisingInterval (uint16_t interval) |
uint16_t | getMinAdvertisingInterval (void) const |
uint16_t | getMinNonConnectableAdvertisingInterval (void) const |
uint16_t | getMaxAdvertisingInterval (void) const |
void | setAdvertisingTimeout (uint16_t timeout) |
void | setAdvertisingParams (const GapAdvertisingParams &advParams) |
Please refer to the APIs above. | |
ble_error_t | setAdvertisingPayload (void) |
This API is typically used as an internal helper to udpate the transport backend with advertising data before starting to advertise. | |
void | clearAdvertisingPayload (void) |
Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload(). | |
ble_error_t | accumulateAdvertisingPayload (uint8_t flags) |
Accumulate an AD structure in the advertising payload. | |
ble_error_t | accumulateAdvertisingPayload (GapAdvertisingData::Appearance app) |
Accumulate an AD structure in the advertising payload. | |
ble_error_t | accumulateAdvertisingPayloadTxPower (int8_t power) |
Accumulate an AD structure in the advertising payload. | |
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. | |
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. | |
ble_error_t | startAdvertising (void) |
Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). | |
ble_error_t | stopAdvertising (void) |
Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). | |
ble_error_t | disconnect (Gap::DisconnectionReason_t reason) |
This call initiates the disconnection procedure, and its completion will be communicated to the application with an invocation of the onDisconnection callback. | |
void | onDisconnection (Gap::DisconnectionEventCallback_t disconnectionCallback) |
Used to setup a callback for GAP disconnection. | |
template<typename T > | |
void | addToDisconnectionCallChain (T *tptr, void(T::*mptr)(void)) |
Append to a chain of callbacks to be invoked upon disconnection; these callbacks receive no context and are therefore different from the onDisconnection callback. | |
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). | |
void | onDataWritten (void(*callback)(const GattCharacteristicWriteCBParams *eventDataP)) |
Setup a callback for when a characteristic has its value updated by a client. | |
ble_error_t | onDataRead (void(*callback)(const GattCharacteristicReadCBParams *eventDataP)) |
Setup a callback for when a characteristic is being read by a client. | |
void | onRadioNotification (Gap::RadioNotificationEventCallback_t callback) |
Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack that notify the application when the radio is in use. | |
ble_error_t | addService (GattService &service) |
Add a service declaration to the local server ATT table. | |
Gap::GapState_t | getGapState (void) const |
Returns the current GAP state of the device using a bitmask which describes whether the device is advertising and/or connected. | |
ble_error_t | readCharacteristicValue (GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) |
ble_error_t | updateCharacteristicValue (GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false) |
void | waitForEvent (void) |
Yield control to the BLE stack or to other tasks waiting for events. | |
const char * | getVersion (void) |
This call allows the application to get the BLE stack version information. | |
ble_error_t | setDeviceName (const uint8_t *deviceName) |
Set the device name characteristic in the GAP service. | |
ble_error_t | getDeviceName (uint8_t *deviceName, unsigned *lengthP) |
Get the value of the device name characteristic in the GAP service. | |
ble_error_t | setAppearance (uint16_t appearance) |
Set the appearance characteristic in the GAP service. | |
ble_error_t | getAppearance (uint16_t *appearanceP) |
Set the appearance characteristic in the GAP service. | |
ble_error_t | setTxPower (int8_t txPower) |
Set the radio's transmit power. | |
void | getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP) |
Query the underlying stack for permitted arguments for setTxPower(). |
Detailed Description
The base class used to abstract away BLE capable radio transceivers or SOCs, to enable this BLE API to work with any radio transparently.
Definition at line 29 of file BLEDevice.h.
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 proves to be too small.
- Parameters:
-
flags The flags to be added. Multiple flags may be specified in combination.
Definition at line 527 of file BLEDevice.h.
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 proves to be too small.
- Parameters:
-
app The appearance of the peripheral.
Definition at line 534 of file BLEDevice.h.
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 proves to be too small.
- Parameters:
-
type The type which describes the variable length data. data data bytes. len length of data.
Definition at line 549 of file BLEDevice.h.
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 proves to be too small.
- Parameters:
-
app The max transmit power to be used by the controller. This is only a hint.
Definition at line 542 of file BLEDevice.h.
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:
-
type The type which describes the variable length data. data data bytes. len length of data.
Definition at line 559 of file BLEDevice.h.
ble_error_t addService | ( | GattService & | service ) |
Add a service declaration to the local server ATT table.
Also add the characteristics contained within.
Definition at line 678 of file BLEDevice.h.
void addToDisconnectionCallChain | ( | T * | tptr, |
void(T::*)(void) | mptr | ||
) |
Append to a chain of callbacks to be invoked upon disconnection; these callbacks receive no context and are therefore different from the onDisconnection callback.
Definition at line 619 of file BLEDevice.h.
void clearAdvertisingPayload | ( | void | ) |
Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload().
Definition at line 520 of file BLEDevice.h.
ble_error_t disconnect | ( | Gap::DisconnectionReason_t | reason ) |
This call initiates the disconnection procedure, and its completion will be communicated to the application with an invocation of the onDisconnection callback.
- Parameters:
-
reason The reason for disconnection to be sent back to the peer.
Definition at line 594 of file BLEDevice.h.
ble_error_t getAddress | ( | Gap::addr_type_t * | typeP, |
Gap::address_t | address | ||
) |
Fetch the BTLE MAC address and type.
- Returns:
- BLE_ERROR_NONE on success.
Definition at line 470 of file BLEDevice.h.
ble_error_t getAppearance | ( | uint16_t * | appearanceP ) |
Set the appearance characteristic in the GAP service.
- Parameters:
-
[out] appearance The new value for the device-appearance.
Definition at line 748 of file BLEDevice.h.
ble_error_t getDeviceName | ( | uint8_t * | deviceName, |
unsigned * | lengthP | ||
) |
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 in order to obtain the deviceName-length from the 'length' parameter. in/out] lengthP (on input) Length of the buffer pointed to by deviceName; (on output) the complete device name length (without the null terminator).
- Note:
- If the device name is longer than the size of the supplied buffer, 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.
Sample use: uint8_t deviceName[20]; unsigned length = sizeof(deviceName); ble.getDeviceName(deviceName, &length); if (length < sizeof(deviceName)) { deviceName[length] = 0; } DEBUG("length: %u, deviceName: %s\r\n", length, deviceName);
Definition at line 736 of file BLEDevice.h.
Gap::GapState_t getGapState | ( | void | ) | const |
Returns the current GAP state of the device using a bitmask which describes whether the device is advertising and/or connected.
Definition at line 684 of file BLEDevice.h.
uint16_t getMaxAdvertisingInterval | ( | void | ) | const |
- Returns:
- Maximum Advertising interval in milliseconds.
Definition at line 503 of file BLEDevice.h.
uint16_t getMinAdvertisingInterval | ( | void | ) | const |
- Returns:
- Minimum Advertising interval in milliseconds.
Definition at line 493 of file BLEDevice.h.
uint16_t getMinNonConnectableAdvertisingInterval | ( | void | ) | const |
- Returns:
- Minimum Advertising interval in milliseconds for non connectible mode.
Definition at line 498 of file BLEDevice.h.
void getPermittedTxPowerValues | ( | const int8_t ** | valueArrayPP, |
size_t * | countP | ||
) |
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.
Definition at line 760 of file BLEDevice.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 string is owned by the BLE_API.
Definition at line 724 of file BLEDevice.h.
ble_error_t init | ( | void | ) |
Initialize the BLE controller.
This should be called before using anything else in the BLE_API.
Definition at line 24 of file BLEDevice.cpp.
ble_error_t onDataRead | ( | void(*)(const GattCharacteristicReadCBParams *eventDataP) | callback ) |
Setup a callback for when a characteristic is being read by a client.
: 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 setup a callback into a member function of some object.
- Returns:
- BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; else BLE_ERROR_NONE.
Definition at line 644 of file BLEDevice.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).
: 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 setup a callback into a member function of some object.
Definition at line 624 of file BLEDevice.h.
void onDataWritten | ( | void(*)(const GattCharacteristicWriteCBParams *eventDataP) | callback ) |
Setup a callback for when a characteristic has its value updated by a client.
: 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 setup a callback into a member function of some object.
Definition at line 634 of file BLEDevice.h.
void onDisconnection | ( | Gap::DisconnectionEventCallback_t | disconnectionCallback ) |
Used to setup a callback for GAP disconnection.
Definition at line 612 of file BLEDevice.h.
void onRadioNotification | ( | Gap::RadioNotificationEventCallback_t | callback ) |
Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack that 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.
Definition at line 672 of file BLEDevice.h.
ble_error_t readCharacteristicValue | ( | GattAttribute::Handle_t | attributeHandle, |
uint8_t * | buffer, | ||
uint16_t * | lengthP | ||
) |
- Parameters:
-
in/out] lengthP input: Length in bytes to be read, output: Total length of attribute value upon successful return.
Definition at line 689 of file BLEDevice.h.
ble_error_t setAddress | ( | Gap::addr_type_t | type, |
const Gap::address_t | address | ||
) |
Set the BTLE MAC address and type.
- Returns:
- BLE_ERROR_NONE on success.
Definition at line 464 of file BLEDevice.h.
void setAdvertisingInterval | ( | uint16_t | 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.
- Decreasing this value will allow central devices to detect your peripheral faster at the expense of more power being used by the radio due to the higher data transmit rate.
- This field must be set to 0 if connectionMode is equal to ADV_CONNECTABLE_DIRECTED
- See Bluetooth Core Specification, Vol 3., Part C, Appendix A for suggested advertising intervals.
: [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 would need to be updated accordingly.
Definition at line 482 of file BLEDevice.h.
void setAdvertisingParams | ( | const GapAdvertisingParams & | advParams ) |
Please refer to the APIs above.
Definition at line 514 of file BLEDevice.h.
ble_error_t setAdvertisingPayload | ( | void | ) |
This API is typically used as an internal helper to udpate the transport backend with advertising data before starting to advertise.
It may also be explicity used to dynamically reset the accumulated advertising payload and scanResponse; to do this, the application can clear and re- accumulate a new advertising payload (and scanResponse) before using this API.
Definition at line 566 of file BLEDevice.h.
void setAdvertisingTimeout | ( | uint16_t | timeout ) |
- Parameters:
-
[in] timeout Advertising timeout between 0x1 and 0x3FFF (1 and 16383) in seconds. Enter 0 to disable the advertising timeout.
Definition at line 508 of file BLEDevice.h.
void setAdvertisingType | ( | GapAdvertisingParams::AdvertisingType | advType ) |
- Parameters:
-
[in] advType The GAP advertising mode to use for this device. Valid values are defined in AdvertisingType:
- ADV_NON_CONNECTABLE_UNDIRECTED
- All connections to the peripheral device will be refused.
- ADV_CONNECTABLE_DIRECTED
- Only connections from a pre-defined central device will be accepted.
- ADV_CONNECTABLE_UNDIRECTED
- Any central device can connect to this peripheral.
- ADV_SCANNABLE_UNDIRECTED
- Include support for Scan Response payloads.
- See Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 9.3 and Core Specification 4.0 (Vol. 6), Part B, Section 2.3.1 for further information on GAP connection modes
Definition at line 476 of file BLEDevice.h.
ble_error_t setAppearance | ( | uint16_t | appearance ) |
Set the appearance characteristic in the GAP service.
- Parameters:
-
[in] appearance The new value for the device-appearance.
Definition at line 742 of file BLEDevice.h.
ble_error_t setDeviceName | ( | const uint8_t * | deviceName ) |
Set the device name characteristic in the GAP service.
- Parameters:
-
deviceName The new value for the device-name. This is a UTF-8 encoded, NULL-terminated string.
Definition at line 730 of file BLEDevice.h.
ble_error_t setTxPower | ( | int8_t | txPower ) |
Set the radio's transmit power.
- Parameters:
-
[in] txPower Radio transmit power in dBm.
Definition at line 754 of file BLEDevice.h.
ble_error_t shutdown | ( | void | ) |
Purge the BLE stack of GATT and GAP state.
init() must be called afterwards to re-instate services and GAP state.
Definition at line 457 of file BLEDevice.h.
ble_error_t startAdvertising | ( | void | ) |
Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
Definition at line 572 of file BLEDevice.h.
ble_error_t stopAdvertising | ( | void | ) |
Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
Definition at line 588 of file BLEDevice.h.
ble_error_t updateCharacteristicValue | ( | GattAttribute::Handle_t | attributeHandle, |
const uint8_t * | value, | ||
uint16_t | size, | ||
bool | localOnly = false |
||
) |
- Parameters:
-
localOnly Only update the characteristic locally regardless of notify/indicate flags in the CCCD.
Definition at line 695 of file BLEDevice.h.
void waitForEvent | ( | void | ) |
Yield control to the BLE stack or to other tasks waiting for events.
This is a sleep function which will return when there is an application specific interrupt, but the MCU might wake up several times before returning (to service the stack). This is not always interchangeable with WFE().
Definition at line 701 of file BLEDevice.h.
Generated on Tue Jul 12 2022 18:47:13 by
