Mbed OS 文档翻译 之 参考（API（蓝牙（BLE）））
BLE
蓝牙低功耗（BLE）是用于构建个人区域网络的低功率无线技术标准。BLE 的典型应用是医疗保健，健身追踪器，信标，智能家居，安全，娱乐，接近传感器，工业和汽车。
Arm Mbed BLE，也称为 BLE_API，是 Mbed 的蓝牙低功耗软件解决方案。许多 Mbed 目标和组件支持 Mbed BLE。开发人员可以使用它来创建新的支持 BLE 的应用程序。
Mbed 的 BLE_API 与平台上的 BLE 控制器接口。它隐藏了 BLE 堆栈在 C++ 抽象背后的复杂性，并且与所有支持 BLE 的 Mbed 平台兼容。Mbed OS BLE_API 自动配置时钟，定时器和其他硬件外设，以最低功耗工作。
BLE_API，桥接和栈
您可以使用 Mbed OS，BLE_API 和控制器特定的蓝牙栈以及一些桥接软件构建 BLE 应用程序，以使其适应 BLE_API：
- BLE_API 如上所述。
- 桥接软件特定于每个供应商的平台。它为 BLE_API 提供的接口提供实例化，并帮助驱动底层控制器和蓝牙栈。
- 蓝牙栈实现蓝牙协议并且特定于控制器，因此使用不同控制器的供应商可以提供不同的栈。
在 BLE_API 里面
BLE_API 提供构建块来帮助构建应用程序。这些分为两大类：
-
在 ble/表达 BLE 结构的接口，例如 GAP，GATT，服务和特性。
-
ble/services 下的类为许多常用的 GATT 配置文件提供参考实现。'services/' 下的代码不是必需的，但它是原型设计的有用起点。我们继续实施标准的 GATT 配置文件。
BLEDevice 类和头文件
Mbed 的 BLE_API 的入口点是使用标题 ble/BLE.h 可访问的 BLE 类。此类允许您获取 BLE 对象，该对象包含规范兼容的 BLE 设备的基本属性，并且可以与任何 BLE 无线电一起使用：
#include "ble/BLE.h"
BLE& mydevicename = BLE::Instance();
该类的成员函数可以按目的划分：
-
基本 BLE 操作，例如初始化控制器。
-
管理 GAP，GATT 或安全性的蓝牙模块的访问者。
用法
- 设置广告和连接模式。
- 将 UUID 分配给服务及其特性。
- 创建输入特征。
- 构造一个服务类并将其添加到 BLE 栈。
- 特征值更改时推送通知。
BLE 类参考
BLE 类参考
| 数据结构 | |
| struct | InitializationCompleteCallbackContext |
| struct | OnEventsToProcessCallbackContext |
| 公共类型 | |
| typedef unsigned | InstanceID_t |
| typedef FunctionPointerWithContext< OnEventsToProcessCallbackContext * > | OnEventsToProcessCallback_t |
| typedef void(* | InitializationCompleteCallback_t) (InitializationCompleteCallbackContext *context) |
| 公共成员函数 | |
| InstanceID_t | getInstanceID (void) const |
| void | onEventsToProcess (const OnEventsToProcessCallback_t &on_event_cb) |
| void | processEvents () |
| ble_error_t | init (InitializationCompleteCallback_t completion_cb=NULL) |
| template |
|
| ble_error_t | init (T *object, void(T::*completion_cb)(InitializationCompleteCallbackContext *context)) |
| bool | hasInitialized (void) const |
| ble_error_t | shutdown (void) |
| const char * | getVersion (void) |
| Gap & | gap () |
| const Gap & | gap () const |
| GattServer & | gattServer () |
| const GattServer & | gattServer () const |
| GattClient & | gattClient () |
| const GattClient & | gattClient () const |
| SecurityManager & | securityManager () |
| const SecurityManager & | securityManager () const |
| BLE (InstanceID_t instanceID=DEFAULT_INSTANCE) | |
| void | waitForEvent (void) |
| ble_error_t | setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) |
| ble_error_t | getAddress (BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) |
| void | setAdvertisingType (GapAdvertisingParams::AdvertisingType advType) |
| 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) |
| const GapAdvertisingParams & | getAdvertisingParams (void) const |
| ble_error_t | accumulateAdvertisingPayload (uint8_t flags) |
| ble_error_t | accumulateAdvertisingPayload (GapAdvertisingData::Appearance app) |
| ble_error_t | accumulateAdvertisingPayloadTxPower (int8_t power) |
| ble_error_t | accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) |
| ble_error_t | setAdvertisingData (const GapAdvertisingData &advData) |
| const GapAdvertisingData & | getAdvertisingData (void) const |
| void | clearAdvertisingPayload (void) |
| ble_error_t | setAdvertisingPayload (void) |
| ble_error_t | accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) |
| void | clearScanResponse (void) |
| ble_error_t | startAdvertising (void) |
| ble_error_t | stopAdvertising (void) |
| 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) |
| ble_error_t | setScanInterval (uint16_t interval) |
| ble_error_t | setScanWindow (uint16_t window) |
| ble_error_t | setScanTimeout (uint16_t timeout) |
| void | setActiveScan (bool activeScanning) |
| ble_error_t | startScan (void(*callback)(const Gap::AdvertisementCallbackParams_t *params)) |
| template |
|
| ble_error_t | startScan (T *object, void(T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params)) |
| ble_error_t | stopScan (void) |
| 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) |
| ble_error_t | disconnect (Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) |
| ble_error_t | disconnect (Gap::DisconnectionReason_t reason) |
| Gap::GapState_t | getGapState (void) const |
| ble_error_t | getPreferredConnectionParams (Gap::ConnectionParams_t *params) |
| ble_error_t | setPreferredConnectionParams (const Gap::ConnectionParams_t *params) |
| ble_error_t | updateConnectionParams (Gap::Handle_t handle, const Gap::ConnectionParams_t *params) |
| ble_error_t | setDeviceName (const uint8_t *deviceName) |
| ble_error_t | getDeviceName (uint8_t *deviceName, unsigned *lengthP) |
| ble_error_t | setAppearance (GapAdvertisingData::Appearance appearance) |
| ble_error_t | getAppearance (GapAdvertisingData::Appearance *appearanceP) |
| ble_error_t | setTxPower (int8_t txPower) |
| void | getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP) |
| ble_error_t | addService (GattService &service) |
| ble_error_t | readCharacteristicValue (GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) |
| ble_error_t | readCharacteristicValue (Gap::Handle_t connectionHandle, 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) |
| ble_error_t | updateCharacteristicValue (Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false) |
| ble_error_t | initializeSecurity (bool enableBonding=true, bool requireMITM=true, SecurityManager::SecurityIOCapabilities_t iocaps=SecurityManager::IO_CAPS_NONE, const SecurityManager::Passkey_t passkey=NULL) |
| ble_error_t | getLinkSecurity (Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) |
| ble_error_t | purgeAllBondingState (void) |
| void | onTimeout (Gap::TimeoutEventCallback_t timeoutCallback) |
| void | onConnection (Gap::ConnectionEventCallback_t connectionCallback) |
| void | onDisconnection (Gap::DisconnectionEventCallback_t disconnectionCallback) |
| template |
|
| void | onDisconnection (T *tptr, void(T::*mptr)(const Gap::DisconnectionCallbackParams_t *)) |
| void | onRadioNotification (void(*callback)(bool)) |
| void | onDataSent (void(*callback)(unsigned count)) |
| template |
|
| void | onDataSent (T *objPtr, void(T::*memberPtr)(unsigned count)) |
| void | onDataWritten (void(*callback)(const GattWriteCallbackParams *eventDataP)) |
| template |
|
| void | onDataWritten (T *objPtr, void(T::*memberPtr)(const GattWriteCallbackParams *context)) |
| ble_error_t | onDataRead (void(*callback)(const GattReadCallbackParams *eventDataP)) |
| template |
|
| ble_error_t | onDataRead (T *objPtr, void(T::*memberPtr)(const GattReadCallbackParams *context)) |
| void | onUpdatesEnabled (GattServer::EventCallback_t callback) |
| void | onUpdatesDisabled (GattServer::EventCallback_t callback) |
| void | onConfirmationReceived (GattServer::EventCallback_t callback) |
| void | onSecuritySetupInitiated (SecurityManager::SecuritySetupInitiatedCallback_t callback) |
| void | onSecuritySetupCompleted (SecurityManager::SecuritySetupCompletedCallback_t callback) |
| void | onLinkSecured (SecurityManager::LinkSecuredCallback_t callback) |
| void | onSecurityContextStored (SecurityManager::HandleSpecificEvent_t callback) |
| void | onPasskeyDisplay (SecurityManager::PasskeyDisplayCallback_t callback) |
| 静态公共成员函数 | |
| static BLE & | Instance (InstanceID_t id=DEFAULT_INSTANCE) |
| static const char * | errorToString (ble_error_t error) |
| Static Public Attributes | |
| static const InstanceID_t | DEFAULT_INSTANCE = 0 |
| static const InstanceID_t | NUM_INSTANCES = 1 |
| Friends | |
| class | BLEInstanceBase |
示例：BLE 信标
这是一个演示如何创建 BLE 信标的示例。
main.cpp 导入到 Mbed IDE
/* mbed Microcontroller Library
* Copyright (c) 2006-2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include
#include
#include "ble/BLE.h"
#include "ble/services/iBeacon.h"
static iBeacon* ibeaconPtr;
static EventQueue eventQueue(/* event count */ 4 * EVENTS_EVENT_SIZE);
/**
* This function is called when the ble initialization process has failled
*/
void onBleInitError(BLE &ble, ble_error_t error)
{
/* Initialization error handling should go here */
}
/**
* Callback triggered when the ble initialization process has finished
*/
void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
{
BLE& ble = params->ble;
ble_error_t error = params->error;
if (error != BLE_ERROR_NONE) {
/* In case of error, forward the error handling to onBleInitError */
onBleInitError(ble, error);
return;
}
/* Ensure that it is the default instance of BLE */
if(ble.getInstanceID() != BLE::DEFAULT_INSTANCE) {
return;
}
/**
* The Beacon payload has the following composition:
* 128-Bit / 16byte UUID = E2 0A 39 F4 73 F5 4B C4 A1 2F 17 D1 AD 07 A9 61
* Major/Minor = 0x1122 / 0x3344
* Tx Power = 0xC8 = 200, 2's compliment is 256-200 = (-56dB)
*
* Note: please remember to calibrate your beacons TX Power for more accurate results.
*/
static const uint8_t uuid[] = {0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4,
0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61};
uint16_t majorNumber = 1122;
uint16_t minorNumber = 3344;
uint16_t txPower = 0xC8;
ibeaconPtr = new iBeacon(ble, uuid, majorNumber, minorNumber, txPower);
ble.gap().setAdvertisingInterval(1000); /* 1000ms. */
ble.gap().startAdvertising();
}
void scheduleBleEventsProcessing(BLE::OnEventsToProcessCallbackContext* context) {
BLE &ble = BLE::Instance();
eventQueue.call(Callback(&ble, &BLE::processEvents));
}
int main()
{
BLE &ble = BLE::Instance();
ble.onEventsToProcess(scheduleBleEventsProcessing);
ble.init(bleInitComplete);
eventQueue.dispatch_forever();
return 0;
}
示例：BLE 心率监测器
这是一个示例，演示如何构建可由 BLE 客户端（如手机）连接和监控的心率传感器。
main.cpp 导入到 Mbed IDE
/* mbed Microcontroller Library
* Copyright (c) 2006-2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include
#include
#include "ble/BLE.h"
#include "ble/Gap.h"
#include "ble/services/HeartRateService.h"
DigitalOut led1(LED1, 1);
const static char DEVICE_NAME[] = "HRM";
static const uint16_t uuid16_list[] = {GattService::UUID_HEART_RATE_SERVICE};
static uint8_t hrmCounter = 100; // init HRM to 100bps
static HeartRateService *hrServicePtr;
static EventQueue eventQueue(/* event count */ 16 * EVENTS_EVENT_SIZE);
void disconnectionCallback(const Gap::DisconnectionCallbackParams_t *params)
{
BLE::Instance().gap().startAdvertising(); // restart advertising
}
void updateSensorValue() {
// Do blocking calls or whatever is necessary for sensor polling.
// In our case, we simply update the HRM measurement.
hrmCounter++;
// 100 <= HRM bps <=175
if (hrmCounter == 175) {
hrmCounter = 100;
}
hrServicePtr->updateHeartRate(hrmCounter);
}
void periodicCallback(void)
{
led1 = !led1; /* Do blinky on LED1 while we're waiting for BLE events */
if (BLE::Instance().getGapState().connected) {
eventQueue.call(updateSensorValue);
}
}
void onBleInitError(BLE &ble, ble_error_t error)
{
(void)ble;
(void)error;
/* Initialization error handling should go here */
}
void bleInitComplete(BLE::InitializationCompleteCallbackContext *params)
{
BLE& ble = params->ble;
ble_error_t error = params->error;
if (error != BLE_ERROR_NONE) {
onBleInitError(ble, error);
return;
}
if (ble.getInstanceID() != BLE::DEFAULT_INSTANCE) {
return;
}
ble.gap().onDisconnection(disconnectionCallback);
/* Setup primary service. */
hrServicePtr = new HeartRateService(ble, hrmCounter, HeartRateService::LOCATION_FINGER);
/* Setup advertising. */
ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::BREDR_NOT_SUPPORTED | GapAdvertisingData::LE_GENERAL_DISCOVERABLE);
ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, (uint8_t *)uuid16_list, sizeof(uuid16_list));
ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::GENERIC_HEART_RATE_SENSOR);
ble.gap().accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LOCAL_NAME, (uint8_t *)DEVICE_NAME, sizeof(DEVICE_NAME));
ble.gap().setAdvertisingType(GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED);
ble.gap().setAdvertisingInterval(1000); /* 1000ms */
ble.gap().startAdvertising();
}
void scheduleBleEventsProcessing(BLE::OnEventsToProcessCallbackContext* context) {
BLE &ble = BLE::Instance();
eventQueue.call(Callback(&ble, &BLE::processEvents));
}
int main()
{
eventQueue.call_every(500, periodicCallback);
BLE &ble = BLE::Instance();
ble.onEventsToProcess(scheduleBleEventsProcessing);
ble.init(bleInitComplete);
eventQueue.dispatch_forever();
return 0;
}
相关内容
- Mbed 启用支持 BLE 的目标和组件目标和组件。