本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 低功耗藍牙程式庫 **重要** 此程式庫託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從[這裡開始](freertos-getting-started-modular.md)。如果您已經有以現在已棄用的 Amazon-FreeRTOS 儲存庫為基礎的現有 FreeRTOS 專案，請參閱 [Amazon-FreeRTOS Github 儲存庫遷移指南](github-repo-migration.md)。 FreeRTOS ## 概觀 FreeRTOS 支援透過代理裝置，例如行動電話，透過低功耗藍牙發佈和訂閱訊息佇列遙測傳輸 (MQTT) 主題。透過 FreeRTOS [低功耗藍牙](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/ble/index.html) (BLE) 程式庫，您的微型控制器可以安全地與 AWS IoT MQTT 代理程式通訊。 ![透過 AWS Cognito AWS IoT Core 透過 MQTT/HTTP/Websocket 連線至 的 BLE 裝置。](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/blediagram.jpg) 使用適用於 FreeRTOS 藍牙裝置的 Mobile SDKs，您可以撰寫原生行動應用程式，透過 BLE 與微型控制器上的內嵌應用程式通訊。如需行動軟體開發套件的詳細資訊，請參閱 [適用於 FreeRTOS 藍牙裝置的 Mobile SDKs](freertos-ble-mobile.md)。 FreeRTOS BLE 程式庫包含設定 Wi-Fi 網路、傳輸大量資料，以及透過 BLE 提供網路抽象化的服務。FreeRTOS BLE 程式庫也包含中介軟體和低階 APIs可讓您更直接控制 BLE 堆疊。 ## Architecture FreeRTOS BLE 程式庫由三層組成：服務、中介軟體和低階包裝函式。 ![雲端架構層：使用者應用程式、服務、中介軟體、低階包裝函式、製造商 BLE Stack。](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/ble-architecture.png) ### 服務 FreeRTOS BLE 服務層包含四個利用中介軟體 APIs 的一般屬性 (GATT) 服務： + 裝置資訊 + Wi-Fi 佈建 + 網路抽象 + 大型物件傳輸 #### 裝置資訊 裝置資訊服務會收集有關微控制器的詳細資訊，包括： + 您的裝置正在使用的 FreeRTOS 版本。 + 註冊裝置之帳戶的 AWS IoT 端點。 + 低功耗藍牙最大傳輸單位 (MTU)。 #### Wi-Fi 佈建 Wi-Fi 佈建服務可讓微型控制器具有 Wi-Fi 功能，以執行下列動作： + 列出範圍內的網路。 + 將網路和網路登入資料儲存至快閃記憶體。 + 設定網路優先順序。 + 從快閃記憶體中刪除網路和網路登入資料。 #### 網路抽象 網路抽象服務可為應用程式擷取網路連線類型。常見的 API 會與您裝置的 Wi-Fi、乙太網路和低功耗藍牙硬體堆疊進行互動，讓應用程式相容於多種連線類型。 #### 大型物件傳輸 大型物件傳輸服務會將資料傳送至用戶端，並從用戶端接收資料。其他服務，例如 Wi-Fi 佈建和網路抽象，請使用大型物件傳輸服務來傳送和接收資料。您也可以使用大型物件傳輸 API 直接與服務互動。 #### 透過 BLE 的 MQTT MQTT over BLE 包含 GATT 設定檔，用於透過 BLE 建立 MQTT 代理服務。MQTT 代理服務允許 MQTT 用戶端透過閘道裝置與 AWS MQTT 代理程式通訊。例如，您可以使用代理服務，透過智慧型手機應用程式將執行 FreeRTOS 的裝置連線至 AWS MQTT。BLE 裝置是 GATT 伺服器，並公開閘道裝置的服務和特性。GATT 伺服器使用這些公開服務和特性，以該裝置的雲端執行 MQTT 操作。如需更多詳細資訊，請參閱 [附錄 A：透過 BLE GATT 設定檔的 MQTT](#freertos-ble-gatt-profile)。 ### 中介軟體 FreeRTOS 低功耗藍牙中介軟體是低階 APIs抽象概念。中介軟體 API 對低功耗藍牙堆疊組成了使用者更易用的界面。 使用中介軟體 API，您可以跨多層向單一事件註冊數個回呼。初始化低功耗藍牙中介軟體也會初始化服務，並開始進行廣告。 #### 彈性回呼訂閱 假設您的低功耗藍牙硬體中斷連線，而且透過 MQTT 的低功耗藍牙服務需要偵測連線中斷。您撰寫的應用程式也可能需要偵測相同的連線中斷事件。低功耗藍牙中介軟體可以將事件路由到程式碼的不同部分，而您已在其中已註冊回呼，這使得更高層級無需爭用更低階的資源。 ### 低階包裝函式 低階 FreeRTOS 低功耗藍牙包裝函式是製造商低功耗藍牙堆疊的抽象概念。低階包裝函式提供一組常用的 API，以直接控制硬體。低階 API 會最佳化 RAM 使用量，但限於功能方面。 使用低功耗藍牙服務 API 以和低功耗藍牙服務進行互動。服務 API 需要的資源比低階 API 更多。 ## 相依性和要求 低功耗藍牙程式庫有以下直接相依性： + [線性容器](https://docs.aws.amazon.com/freertos/latest/lib-ref/c-sdk/linear_containers/index.html)程式庫 + 與作業系統接觸的平台層，適用於執行緒管理、計時器、時鐘函數和網路存取。 ![顯示元件的架構圖：BLE、List/Queue、Network 和 Clock，具有指示互動的方向箭頭。](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/images/ble-dependencies.png) 只有 Wi-Fi 佈建服務具有 FreeRTOS 程式庫相依性： **** | GATT 服務 | 相依性 | | --- | --- | | Wi-Fi 佈建 | [Wi-Fi 程式庫](freertos-wifi.md) | 若要與 AWS IoT MQTT 代理程式通訊，您必須擁有 AWS 帳戶，而且必須將裝置註冊為 AWS IoT 實物。如需設定的詳細資訊，請參閱 [AWS IoT 開發人員指南](https://docs.aws.amazon.com/iot/latest/developerguide/)。 FreeRTOS 低功耗藍牙使用 Amazon Cognito 在您的行動裝置上進行使用者身分驗證。若要使用 MQTT 代理服務，您必須建立 Amazon Cognito 身分和使用者集區。每個 Amazon Cognito 身分都必須連接適當的政策。如需詳細資訊，請參閱 [Amazon Cognito 開發人員指南](https://docs.aws.amazon.com/cognito/latest/developerguide/)。 ## 程式庫組態檔案 使用 FreeRTOS MQTT over Bluetooth Low Energy 服務的應用程式必須提供已定義組態參數的`iot_ble_config.h`標頭檔案。未定義的組態參數會採用 `iot_ble_config_defaults.h` 中指定的預設值。 有些重要的組態參數包括： **`IOT_BLE_ADD_CUSTOM_SERVICES`** 允許使用者建立自己的服務。 **`IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG`** 允許使用者自訂廣告和掃描回應訊息。 如需詳細資訊，請參閱[低功耗藍牙 API 參考](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/ble/index.html)。 ## 最佳化 當最佳化主機板的效能時，請考慮以下情況： + 低階 API 使用更少的 RAM，但提供的功能有限。 + 您可以將 `iot_ble_config.h` 標頭檔案中的 `bleconfigMAX_NETWORK` 參數設定為較低的值，以減少堆疊的消耗量。 + 您可以將 MTU 大小增加至其最大值，以限制訊息緩衝，並使程式碼執行更快且耗用更少的 RAM。 ## 使用限制 根據預設，FreeRTOS 低功耗藍牙程式庫會將 `eBTpropertySecureConnectionOnly` 屬性設定為 TRUE，這會讓裝置進入僅安全連線模式。如同 [Bluetooth Core Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification) 5.0 版第 3 冊 C 篇 10.2.4 中所指定，當裝置處於僅限安全連線模式時，需有最高 LE 安全模式 1 層級 4，才能存取其具有的許可高於最低 LE 安全模式 1 層級 1 的任何屬性。在 LE 安全模式 1 層級 4 中，裝置必須具有輸入和輸出功能，才能進行數字比較。 以下是支援的模式，及其關聯的屬性： **模式 1、第 1 級 (不安全)** ``` /* Disable numeric comparison */ #define IOT_BLE_ENABLE_NUMERIC_COMPARISON ( 0 ) #define IOT_BLE_ENABLE_SECURE_CONNECTION ( 0 ) #define IOT_BLE_INPUT_OUTPUT ( eBTIONone ) #define IOT_BLE_ENCRYPTION_REQUIRED ( 0 ) ``` **模式 1、第 2 級 (未驗證配對與加密)** ``` #define IOT_BLE_ENABLE_NUMERIC_COMPARISON ( 0 ) #define IOT_BLE_ENABLE_SECURE_CONNECTION ( 0 ) #define IOT_BLE_INPUT_OUTPUT ( eBTIONone ) ``` **模式 1、第 2 級 (已驗證配對與加密)** 不支援此模式。 **模式 1、第 4 級 (已驗證的 LE 安全連線配對與加密)** 依預設支援此模式。 如需 LE 安全模式的詳細資訊，請參閱 [Bluetooth Core Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification) 5.0 版第 3 冊 C 篇 10.2.1。 ## 初始化 如果您的應用程式透過中介軟體與低功耗藍牙堆疊互動，則您只需要初始化中介軟體。中介軟體負責初始化更低階的堆疊。 ### 中介軟體 **初始化中介軟體** 1. 在呼叫低功耗藍牙中介軟體 API 之前，請初始化任何低功耗藍牙硬體驅動程式。 1. 啟用低功耗藍牙。 1. 以 `IotBLE_Init()` 初始化中介軟體。 **注意** 如果您正在執行 AWS 示範，則不需要此初始化步驟。示範初始化是由 `{{freertos}}/demos/network_manager` 中的網路管理員進行處理。 ### 低階 API 如果您不想使用 FreeRTOS 低功耗藍牙 GATT 服務，您可以略過中介軟體，並直接與低階 APIs互動以節省資源。 **初始化低階 API** 1. **** 在呼叫 API 前初始化任何低功耗藍牙硬體驅動程式。驅動程式初始化並不屬於低功耗藍牙低階 API。 1. **** 低功耗藍牙低階 API 提供啟用/停用呼叫低功耗藍牙堆疊的功能，以最佳化電源和資源。呼叫 API 之前，您必須啟用低功耗藍牙。 ``` const BTInterface_t * pxIface = BTGetBluetoothInterface(); xStatus = pxIface->pxEnable( 0 ); ``` 1. **** 藍牙管理員包含低功耗藍牙和藍牙傳統常用的 API。接著必須初始化常用管理員的回呼。 ``` xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb ); ``` 1. **** 低功耗藍牙轉接器放在常用 API 之上。您必須初始化其回呼，如同您初始化常用 API 一般。 ``` xBTInterface.pxBTLeAdapterInterface = ( BTBleAdapter_t * ) xBTInterface.pxBTInterface->pxGetLeAdapter(); xStatus = xBTInterface.pxBTLeAdapterInterface->pxBleAdapterInit( &xBTBleAdapterCb ); ``` 1. **** 註冊新的使用者應用程式。 ``` xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid ); ``` 1. **** 初始化 GATT 伺服器的回呼。 ``` xBTInterface.pxGattServerInterface = ( BTGattServerInterface_t * ) xBTInterface.pxBTLeAdapterInterface->ppvGetGattServerInterface(); xBTInterface.pxGattServerInterface->pxGattServerInit( &xBTGattServerCb ); ``` 在初始化低功耗藍牙轉接器之後，您可以新增 GATT 伺服器。您一次只能註冊一部 GATT 伺服器。 ``` xStatus = xBTInterface.pxGattServerInterface->pxRegisterServer( pxAppUuid ); ``` 1. **** 設定應用程式屬性，像是僅限安全連線和 MTU 大小。 ``` xStatus = xBTInterface.pxBTInterface->pxSetDeviceProperty( &pxProperty[ usIndex ] ); ``` ## API 參考 如需完整的 API 參考，請參閱[低功耗藍牙 API 參考](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/ble/index.html)。 ## 範例使用方式 以下範例示範如何使用低功耗藍牙程式庫進行廣告並建立新的服務。如需完整的 FreeRTOS 低功耗藍牙示範應用程式，請參閱[低功耗藍牙示範應用程式](https://docs.aws.amazon.com/freertos/latest/userguide/ble-demo.html)。 ### 廣告 1. 在您的應用程式中設定廣告 UUID： ``` static const BTUuid_t _advUUID = { .uu.uu128 = IOT_BLE_ADVERTISING_UUID, .ucType = eBTuuidType128 }; ``` 1. 然後定義 `IotBle_SetCustomAdvCb` 回呼函式： ``` void IotBle_SetCustomAdvCb( IotBleAdvertisementParams_t * pAdvParams, IotBleAdvertisementParams_t * pScanParams) { memset(pAdvParams, 0, sizeof(IotBleAdvertisementParams_t)); memset(pScanParams, 0, sizeof(IotBleAdvertisementParams_t)); /* Set advertisement message */ pAdvParams->pUUID1 = &_advUUID; pAdvParams->nameType = BTGattAdvNameNone; /* This is the scan response, set it back to true. */ pScanParams->setScanRsp = true; pScanParams->nameType = BTGattAdvNameComplete; } ``` 此回呼會在廣告訊息中傳送 UUID 訊息，並在掃描回應中傳送完整名稱。 1. 開啟 `vendors/{{vendor}}/boards/{{board}}/aws_demos/config_files/iot_ble_config.h`，並將 `IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG` 設為 `1`。這會觸發 `IotBle_SetCustomAdvCb` 回呼。 ### 新增服務 如需完整服務範例，請參閱 `{{freertos}}/.../ble/services`。 1. 為服務的特性和描述項建立 UUID： ``` #define xServiceUUID_TYPE \ {\ .uu.uu128 = gattDemoSVC_UUID, \ .ucType = eBTuuidType128 \ } #define xCharCounterUUID_TYPE \ {\ .uu.uu128 = gattDemoCHAR_COUNTER_UUID,\ .ucType = eBTuuidType128\ } #define xCharControlUUID_TYPE \ {\ .uu.uu128 = gattDemoCHAR_CONTROL_UUID,\ .ucType = eBTuuidType128\ } #define xClientCharCfgUUID_TYPE \ {\ .uu.uu16 = gattDemoCLIENT_CHAR_CFG_UUID,\ .ucType = eBTuuidType16\ } ``` 1. 建立緩衝以註冊特性和描述項的處理常式： ``` static uint16_t usHandlesBuffer[egattDemoNbAttributes]; ``` 1. 建立屬性表格。若要節省一些 RAM，請將表格定義為 `const`。 **重要** 請一律按順序建立屬性，並將服務做為第一個屬性。 ``` static const BTAttribute_t pxAttributeTable[] = { { .xServiceUUID = xServiceUUID_TYPE }, { .xAttributeType = eBTDbCharacteristic, .xCharacteristic = { .xUuid = xCharCounterUUID_TYPE, .xPermissions = ( IOT_BLE_CHAR_READ_PERM ), .xProperties = ( eBTPropRead | eBTPropNotify ) } }, { .xAttributeType = eBTDbDescriptor, .xCharacteristicDescr = { .xUuid = xClientCharCfgUUID_TYPE, .xPermissions = ( IOT_BLE_CHAR_READ_PERM | IOT_BLE_CHAR_WRITE_PERM ) } }, { .xAttributeType = eBTDbCharacteristic, .xCharacteristic = { .xUuid = xCharControlUUID_TYPE, .xPermissions = ( IOT_BLE_CHAR_READ_PERM | IOT_BLE_CHAR_WRITE_PERM ), .xProperties = ( eBTPropRead | eBTPropWrite ) } } }; ``` 1. 建立一系列的回呼。此回呼陣列必須遵循上述表格陣列所定義的相同順序。 例如，如果存取 `xCharCounterUUID_TYPE` 時 `vReadCounter` 被觸發了，而存取 `xCharControlUUID_TYPE` 時 `vWriteCommand` 被觸發了，則依下列內容定義陣列： ``` static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] = { NULL, vReadCounter, vEnableNotification, vWriteCommand }; ``` 1. 建立服務： ``` static const BTService_t xGattDemoService = { .xNumberOfAttributes = egattDemoNbAttributes, .ucInstId = 0, .xType = eBTServiceTypePrimary, .pusHandlesBuffer = usHandlesBuffer, .pxBLEAttributes = (BTAttribute_t *)pxAttributeTable }; ``` 1. 使用您在上一步驟建立的結構來呼叫 API `IotBle_CreateService`。中介軟體會同步所有服務的建立，所以在 `IotBle_AddCustomServicesCb` 回呼觸發時，任何新的服務都必須已完成定義。 1. 在 `vendors/{{vendor}}/boards/{{board}}/aws_demos/config_files/iot_ble_config.h` 中將 `IOT_BLE_ADD_CUSTOM_SERVICES` 設為 `1`。 1. 在應用程式中建立 IotBle\_AddCustomServicesCb： ``` void IotBle_AddCustomServicesCb(void) { BTStatus_t xStatus; /* Select the handle buffer. */ xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray ); } ``` ## 移植 ### 使用者輸入和輸出周邊 安全連線需要輸入和輸出兩者，才能進行數字比較。您可以使用事件管理員註冊 `eBLENumericComparisonCallback` 事件： ``` xEventCb.pxNumericComparisonCb = &prvNumericComparisonCb; xStatus = BLE_RegisterEventCb( eBLENumericComparisonCallback, xEventCb ); ``` 周邊必須顯示數字密碼，並採取比較結果做為輸入。 ### 移植 API 實作 若要將 FreeRTOS 移植到新目標，您必須實作 Wi-Fi 佈建服務和低功耗藍牙功能的一些 APIs。 #### 低功耗藍牙 API 若要使用 FreeRTOS 低功耗藍牙中介軟體，您必須實作一些 APIs。 ##### GAP for Bluetooth Classic 與 GAP for Bluetooth Low Energy 之間常用的 API + `pxBtManagerInit` + `pxEnable` + `pxDisable` + `pxGetDeviceProperty` + `pxSetDeviceProperty` (除 `eBTpropertyRemoteRssi` 和 `eBTpropertyRemoteVersionInfo` 以外的所有選項都是必要選項) + `pxPair` + `pxRemoveBond` + `pxGetConnectionState` + `pxPinReply` + `pxSspReply` + `pxGetTxpower` + `pxGetLeAdapter` + `pxDeviceStateChangedCb` + `pxAdapterPropertiesCb` + `pxSspRequestCb` + `pxPairingStateChangedCb` + `pxTxPowerCb` ##### 適用於低功耗藍牙的 GAP 特定 API + `pxRegisterBleApp` + `pxUnregisterBleApp` + `pxBleAdapterInit` + `pxStartAdv` + `pxStopAdv` + `pxSetAdvData` + `pxConnParameterUpdateRequest` + `pxRegisterBleAdapterCb` + `pxAdvStartCb` + `pxSetAdvDataCb` + `pxConnParameterUpdateRequestCb` + `pxCongestionCb` ##### GATT 伺服器 + `pxRegisterServer` + `pxUnregisterServer` + `pxGattServerInit` + `pxAddService` + `pxAddIncludedService` + `pxAddCharacteristic` + `pxSetVal` + `pxAddDescriptor` + `pxStartService` + `pxStopService` + `pxDeleteService` + `pxSendIndication` + `pxSendResponse` + `pxMtuChangedCb` + `pxCongestionCb` + `pxIndicationSentCb` + `pxRequestExecWriteCb` + `pxRequestWriteCb` + `pxRequestReadCb` + `pxServiceDeletedCb` + `pxServiceStoppedCb` + `pxServiceStartedCb` + `pxDescriptorAddedCb` + `pxSetValCallbackCb` + `pxCharacteristicAddedCb` + `pxIncludedServiceAddedCb` + `pxServiceAddedCb` + `pxConnectionCb` + `pxUnregisterServerCb` + `pxRegisterServerCb` 如需有關將 FreeRTOS 低功耗藍牙程式庫移植到平台的詳細資訊，請參閱 FreeRTOS 移植指南中的[移植低功耗藍牙程式庫](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ble.html)。 ## 附錄 A：透過 BLE GATT 設定檔的 MQTT ### GATT 服務詳細資訊 透過 BLE 的 MQTT 會使用資料傳輸 GATT 服務的執行個體，在 FreeRTOS 裝置和代理裝置之間傳送 MQTT 簡潔二進位物件表示法 (CBOR) 訊息。資料傳輸服務會公開特定特性，以協助透過 BLE GATT 通訊協定傳送和接收原始資料。它也會處理大於 BLE 最大傳輸單位 (MTU) 大小之承載的分段和組合。 **服務 UUID** `A9D7-166A-D72E-40A9-A002-4804-4CC3-FF00` **服務執行個體** 每個使用代理程式的 MQTT 工作階段都會建立一個 GATT 服務的執行個體。每個服務都有唯一 UUID （兩個位元組） 來識別其類型。每個個別執行個體都會以執行個體 ID 區分。 每個服務都會在每個 BLE 伺服器裝置上執行個體化為主要服務。您可以在指定裝置上建立服務的多個執行個體。MQTT 代理服務類型具有唯一的 UUID。 **特性** 特性內容格式：**CBOR** 特徵值大小上限：512 個位元組 **** [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/freertos-ble-library.html) **GATT 程序需求 ** **** [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/freertos-ble-library.html) **訊息類型 ** 交換下列訊息類型。 **** [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/freertos/latest/userguide/freertos-ble-library.html) **大型承載傳輸特性 ** **TXLargeMessage ** 裝置會使用 TXLargeMessage 來傳送大於針對 BLE 連線交涉之 MTU 大小的大型承載。 + 裝置會透過 特性傳送承載的第一個 MTU 位元組做為通知。 + 代理會針對剩餘的位元組傳送此特性的讀取請求。 + 裝置最多會傳送 MTU 大小或承載的剩餘位元組，以較小者為準。每次它都會增加所傳送承載大小的位移讀取。 + 代理將繼續讀取特徵，直到其獲得零長度承載或承載小於 MTU 大小為止。 + 如果裝置未在指定的逾時內收到讀取請求，傳輸會失敗，且代理和閘道會釋出緩衝區。 + 如果代理未在指定的逾時內收到讀取回應，則傳輸會失敗，代理會釋出緩衝區。 **RXLargeMessage ** 裝置會使用 RXLargeMessage 來接收大於針對 BLE 連線交涉之 MTU 大小的大型承載。 + 代理會逐一寫入訊息至 MTU 大小，並使用寫入搭配此特性的回應。 + 裝置會緩衝訊息，直到收到零長度或長度小於 MTU 大小的寫入請求為止。 + 如果裝置未在指定的逾時內收到寫入請求，傳輸會失敗，且裝置會釋出緩衝區。 + 如果代理未在指定的逾時內收到寫入回應，則傳輸會失敗，代理會釋出緩衝區。