本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 低功耗蓝牙演示应用程序
**重要**
该演示托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 [Amazon-FreeRTOS Github 存储库迁移指南](github-repo-migration.md)。
## 概述
FreeRTOS 低功耗蓝牙包括三个演示应用程序：
+ [低功耗蓝牙 MQTT](#ble-demo-mqtt) 演示
此应用程序演示如何使用低功耗蓝牙 MQTT 服务。
+ [Wi-Fi 预置](#ble-demo-wifi) 演示
此应用程序演示如何使用低功耗蓝牙预置服务。
+ [通用属性服务器](#ble-demo-server) 演示
此应用程序演示如何使用 FreeRTOS 低功耗蓝牙 APIs 中间件来创建简单的 GATT 服务器。
**注意**
要设置和运行 FreeRTOS 演示，请按照[开始使用 FreeRTOS](freertos-getting-started.md)中的步骤操作。
## 先决条件
要按照这些演示练习，您的微控制器需要具备低功耗蓝牙功能。您还需要 [适用于 FreeRTOS 蓝牙设备的 iOS 开发工具包](freertos-ble-mobile.md#freertos-ble-ios) 或 [适用于 FreeRTOS 蓝牙设备的 Android 开发工具包](freertos-ble-mobile.md#freertos-ble-android)。
### 为 FreeRTOS 低功耗蓝牙设置 AWS IoT 和 Amazon Cognito
要通过 MQTT 将您的设备连接到 AWS IoT ，您需要设置 AWS IoT 和 Amazon Cognito。
**要设置 AWS IoT**
1. 在 [https://aws.amazon.com/](https://aws.amazon.com/)上 AWS 开设一个账户。
1. 打开 [AWS IoT 控制台](https://console.aws.amazon.com/iot/)，从导航窗格中，依次选择**管理**和**事物**。
1. 选择**创建**，然后选择**创建单个事物**。
1. 输入您设备的名称，然后选择**下一步**。
1. 如果您通过移动设备将微控制器连接到云中，请选择**创建没有证书的事物**。由于移动设备 SDKs 使用 Amazon Cognito 进行设备身份验证，因此您无需为使用低功耗蓝牙的演示创建设备证书。
如果您直接通过 Wi-Fi 将微控制器连接到云中，请依次选择**创建证书**和**激活**，然后下载事物的证书、公有密钥和私有密钥。
1. 从已注册事物列表中选择您刚刚创建的事物，然后从事物的页面中选择**交互**。记下 AWS IoT REST API 端点。
有关设置的更多信息，请参阅《[入门》 AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)。
**创建 Amazon Cognito 用户群体**
1. 打开 Amazon Cognito 控制台，然后选择**管理用户群体**。
1. 选择**创建用户池**。
1. 指定用户池名称，然后选择**查看默认值**。
1. 在导航窗格中，选择**应用程序客户端**，然后选择**添加应用程序客户端**。
1. 输入应用程序客户端的名称，然后选择**创建应用程序客户端**。
1. 在导航窗格中，选择 **审核**，然后选择 **创建池**。
记录在您用户池的**常规设置**页面中显示的池 ID。
1. 在导航窗格中，选择**应用程序客户端**，然后选择**显示详细信息**。记录应用程序客户端 ID 和应用程序客户端密钥。
**创建 Amazon Cognito 身份池**
1. 打开 Amazon Cognito 控制台，然后选择**管理身份池**。
1. 为身份池输入一个名称。
1. 展开**身份验证提供商**，选择 **Cognito** 选项卡，然后输入您的用户池 ID 和应用程序客户端 ID。
1. 选择**创建池**。
1. 展开**查看详细信息**，记下两个 IAM 角色名称。要访问 Amazon Cognito，请选择**允许**，以便为经过身份验证和未经过身份验证的身份创建 IAM 角色。
1. 选择**编辑身份池**。记录身份池 ID。其格式应为 `us-west-2:12345678-1234-1234-1234-123456789012`。
有关设置 Amazon Cognito 的更多信息，请参阅 [Amazon Cognito 入门](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-getting-started.html)。
**创建 IAM policy 并将其附加到经过身份验证的身份**
1. 打开 IAM 控制台，然后在导航窗格中选择**角色**。
1. 查找并选择您的经过身份验证的角色，然后依次选择**附加策略**和**添加内联策略**。
1. 选择 **JSON** 选项卡，然后粘贴以下 JSON：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"iot:AttachPolicy",
"iot:AttachPrincipalPolicy",
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:DeleteThingShadow"
],
"Resource":[
"*"
]
}
]
}
```
------
1. 选择**查看策略**，输入策略的名称，然后选择**创建策略**。
请随身携 AWS IoT 带您和亚马逊 Cognito 的信息。您需要端点并使用 AWS 云端 IDs 对您的移动应用程序进行身份验证。
### 为低功耗蓝牙设置 FreeRTOS 环境
要设置环境，您需要在微控制器下载包含[低功耗蓝牙库](freertos-ble-library.md) 的 FreeRTOS，并在移动设备上下载和配置适用于 FreeRTOS 蓝牙设备的移动开发工具包。
**在微控制器环境中设置 FreeRTOS 低功耗蓝牙**
1. 从中下载或克隆 FreeRTOS。[GitHub](https://github.com/aws/amazon-freertos)有关说明，请参阅 [README.md](https://github.com/aws/amazon-freertos/blob/main/README.md) 文件。
1. 在微控制器上设置 FreeRTOS。
有关在符合 FreeRTOS 条件的微控制器上开始使用 FreeRTOS 的信息，请参阅 [FreeRTOS 入门](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html)中有关您主板的指南。
**注意**
您可在任何已启用低功耗蓝牙且具有 FreeRTOS 和移植的 FreeRTOS 低功耗蓝牙库的微控制器上运行演示。目前，FreeRTOS [低功耗蓝牙 MQTT](#ble-demo-mqtt) 演示项目已完全移植到以下启用低功耗蓝牙的设备：
[Espressif ESP32-DevKit C 和 the ESP-WROVER-KIT](https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_espressif.html)
[Nordic n RF52840-DK](https://docs.aws.amazon.com/freertos/latest/userguide/getting_started_nordic.html)
## 常见组件
FreeRTOS 演示应用程序有两个常见组件：
+ Network Manager
+ 低功耗蓝牙移动开发工具包演示应用程序
### Network Manager
网络管理器管理微控制器的网络连接。它位于您的 FreeRTOS 目录中，路径为：`demos/network_manager/aws_iot_network_manager.c`。如果为 Wi-Fi 和低功耗蓝牙均启用了网络管理器，则默认情况下通过低功耗蓝牙启动演示。如果低功耗蓝牙连接中断，而您的主板已中断 Wi-Fi-enabled，则网络管理器会切换到可用的 Wi-Fi 连接，以防止您断开与网络的连接。
要在 Network Manager 中启用网络连接类型，请将网络连接类型添加到中的`configENABLED_NETWORKS`参数中`vendors/vendor/boards/board/aws_demos/config_files/aws_iot_network_config.h`（其中，*board*是供应商名称，是您用于运行演示的主板的名称）。*vendor*
例如，如果您同时启用了低功耗蓝牙和 Wi-Fi，则 `aws_iot_network_config.h` 中以 `#define configENABLED_NETWORKS` 开头的一行应如下所示：
```
#define configENABLED_NETWORKS ( AWSIOT_NETWORK_TYPE_BLE | AWSIOT_NETWORK_TYPE_WIFI )
```
要获取当前支持的网络连接类型列表，请查看 `aws_iot_network.h` 中以 `#define AWSIOT_NETWORK_TYPE` 开头的行。
### FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序
FreeRTOS 低功耗蓝牙移动 SDK 演示应用程序位于 FreeRTOS 蓝牙设备的 Android [SDK 下，FreeRTOS 蓝牙](https://github.com/aws/amazon-freertos-ble-android-sdk)设备`amazon-freertos-ble-android-sdk/app`的 [iOS](https://github.com/aws/amazon-freertos-ble-ios-sdk) SDK 位于 GitHub 下方。`amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo`在本示例中，我们使用 iOS 版本的演示移动应用程序的屏幕截图。
**注意**
如果您使用的是 iOS 设备，则需要 Xcode 来构建演示移动应用程序。如果您使用的是 Android 设备，则可使用 Android Studio 来构建演示移动应用程序。
**配置 iOS 开发工具包演示应用程序**
当您定义配置变量时，使用在配置文件中提供的占位符值的格式。
1. 确认已安装 [适用于 FreeRTOS 蓝牙设备的 iOS 开发工具包](freertos-ble-mobile.md#freertos-ble-ios)。
1. 从 `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/` 发布以下命令：
```
$ pod install
```
1. 打开具有 Xcode 的 `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo.xcworkspace` 项目，将签名开发人员账户更改为您的账户。
1. 在您所在的地区创建 AWS IoT 政策（如果您还没有）。
**注意**
此策略不同于为经过 Amazon Cognito 身份验证的身份创建的 IAM policy。
1. 打开 [AWS IoT 控制台](https://console.aws.amazon.com/iot/)。
1. 在导航窗格中依次选择**安全**、**策略**和**创建**。输入用于标识您的策略的名称。在**添加语句**部分中，选择**高级模式**。将以下 JSON 复制并粘贴到策略编辑器窗口中。*aws-account*用您的 AWS 地区*aws-region*和账户 ID 替换和。
1. 选择**创建**。
1. 打开 `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo/Amazon/AmazonConstants.swift` 并重新定义以下变量：
+ `region`: 您所在 AWS 的地区。
+ `iotPolicyName`: 您的 AWS IoT 保单名称。
+ `mqttCustomTopic`：您要发布到的 MQTT 主题。
1. 打开 `amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo/Support/awsconfiguration.json`。
在 `CognitoIdentity` 下，重新定义以下变量：
+ `PoolId`：您的 Amazon Cognito 身份池 ID。
+ `Region`: 您所在 AWS 的地区。
在 `CognitoUserPool` 下，重新定义以下变量：
+ `PoolId`：您的 Amazon Cognito 用户群体 ID。
+ `AppClientId`：您的应用程序客户端 ID。
+ `AppClientSecret`：您的应用程序客户端密钥。
+ `Region`: 您所在 AWS 的地区。
**配置 Android 开发工具包演示应用程序**
当您定义配置变量时，使用在配置文件中提供的占位符值的格式。
1. 确认已安装 [适用于 FreeRTOS 蓝牙设备的 Android 开发工具包](freertos-ble-mobile.md#freertos-ble-android)。
1. 在您所在的地区创建 AWS IoT 政策（如果您还没有）。
**注意**
此策略不同于为经过 Amazon Cognito 身份验证的身份创建的 IAM policy。
1. 打开 [AWS IoT 控制台](https://console.aws.amazon.com/iot/)。
1. 在导航窗格中依次选择**安全**、**策略**和**创建**。输入用于标识您的策略的名称。在**添加语句**部分中，选择**高级模式**。将以下 JSON 复制并粘贴到策略编辑器窗口中。*aws-account*用您的 AWS 地区*aws-region*和账户 ID 替换和。
1. 选择**创建**。
1. 打开 [ https://github.com/aws/amazon-freertos-ble-android-sdk/blob/master/app/src/main/java/software/amazon/freertos/demo/DemoConstants .java](https://github.com/aws/amazon-freertos-ble-android-sdk/blob/master/app/src/main/java/software/amazon/freertos/demo/DemoConstants.java) 并重新定义以下变量：
+ `AWS_IOT_POLICY_NAME`: 您的 AWS IoT 保单名称。
+ `AWS_IOT_REGION`: 您所在 AWS 的地区。
1. 打开 [ https://github.com/aws/amazon-freertos-ble-android-sdk/blob/master/app/src/main/res/raw/awsconfiguration .json。](https://github.com/aws/amazon-freertos-ble-android-sdk/blob/master/app/src/main/res/raw/awsconfiguration.json)
在 `CognitoIdentity` 下，重新定义以下变量：
+ `PoolId`：您的 Amazon Cognito 身份池 ID。
+ `Region`: 您所在 AWS 的地区。
在 `CognitoUserPool` 下，重新定义以下变量：
+ `PoolId`：您的 Amazon Cognito 用户群体 ID。
+ `AppClientId`：您的应用程序客户端 ID。
+ `AppClientSecret`：您的应用程序客户端密钥。
+ `Region`: 您所在 AWS 的地区。
**通过低功耗蓝牙发现微控制器并建立安全连接**
1. 为了将您的微控制器和移动设备安全配对（步骤 6），您需要一个同时具有输入和输出功能的串行终端仿真器（例如 TeraTerm）。将终端配置为通过串行连接来连接到主板，如[安装终端仿真器](gsg-troubleshooting.md#uart-term)中所述。
1. 在您的微控制器上运行低功耗蓝牙演示项目。
1. 在移动设备上运行低功耗蓝牙移动开发工具包演示应用程序。
要在 Android 开发工具包中从命令行启动演示应用程序，请运行以下命令：
```
$ ./gradlew installDebug
```
1. 确认您的微控制器显示在低功耗蓝牙移动开发工具包演示应用程序的 **Devices (设备)** 下。
![\[显示设备及其唯一标识符的 ESP32 设备管理页面。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list1.png)
**注意**
处于范围内的所有具有 FreeRTOS 的设备以及设备信息服务 (`freertos/.../device_information`) 均会显示在列表中。
1. 从设备列表中选择您的微控制器。应用程序与主板建立连接，在已连接设备的旁边会显示一根绿色线条。
![\[ESP32 显示了设备 ID。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list2.png)
您可以通过将线条拖动到左侧，从微控制器上断开连接。
![\[显示设备 ID 和另一个 ESP32 设备 ID 的设备页面。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list3.png)
1. 如果出现提示，请将您的微控制器和移动设备进行配对。
![\[控制台输出，展示了 BLE 设备断开连接、MQTT 服务断开连接、广告启动、与远程设备的 BLE 连接以及数字比较提示。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/pairing-board.png)
![\[设备 “” ESP32 的蓝牙配对请求对话框显示代码 “465520”，需要在 “” 上进行确认。ESP32\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/pairing-mobile.png)
如果两个设备上用于比较数字的代码相同，则配对这两个设备。
**注意**
低功耗蓝牙移动开发工具包演示应用程序使用 Amazon Cognito 进行用户身份验证。确保您已设置 Amazon Cognito 用户和身份池，并且将 IAM policy 附加到了通过身份验证的身份。
## 低功耗蓝牙 MQTT
在 MQTT 低功耗蓝牙演示中，您的微控制器通过 MQTT 代理向 AWS 云端发布消息。
**订阅演示 MQTT 主题**
1. 登录 AWS IoT 控制台。
1. 在导航窗格中选择**测试**，然后选择 **MQTT 测试客户端**，以便打开 MQTT 客户端。
1. 在 **Subscription topic (订阅主题)**中，输入 ***thing-name*/example/topic1**，然后选择 **Subscribe to topic (订阅主题)**。
如果您使用低功耗蓝牙将微控制器与移动设备配对，则通过您移动设备上的低功耗蓝牙移动开发工具包演示应用程序来路由 MQTT 消息。
**通过低功耗蓝牙启用演示**
1. 打开 `vendors/vendor/boards/board/aws_demos/config_files/aws_demo_config.h` 并定义 `CONFIG_MQTT_BLE_TRANSPORT_DEMO_ENABLED`。
1. 打开`demos/include/aws_clientcredential.h`，然后`clientcredentialMQTT_BROKER_ENDPOINT`使用 AWS IoT 代理端点进行配置。使用 BLE 微控制器设备的事物名称配置 `clientcredentialIOT_THING_NAME`。 AWS IoT 代理端点可以通过在 AWS IoT 控制台左侧导航窗格中选择 **“设置**” 获取，也可以通过 CLI 运行命令获取：`aws iot describe-endpoint --endpoint-type=iot:Data-ATS`。
**注意**
AWS IoT 代理端点和事物名称必须位于配置 cognito 身份和用户池的同一区域。
**运行演示**
1. 在微控制器上生成并运行演示项目。
1. 确保您已使用 [FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序](#ble-sdk-app)将主板与移动设备配对。
1. 从演示移动应用程序的 **Devices (设备)** 列表中，选择您的微控制器，然后选择 **MQTT Proxy (MQTT 代理)** 以打开 MQTT 代理设置。
![\[三 ESP32 台设备清单，下面有 MQTT 代理 IDs、Network Config 和 Custom GATT MQTT 选项。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list4.png)
1. 在启用 MQTT 代理之后，MQTT 消息将显示在 `thing-name/example/topic1` 主题上，并且数据将输出到 UART 终端。
## Wi-Fi 预置
Wi-Fi 预置是一项 FreeRTOS 低功耗蓝牙服务，让您可以安全地将 Wi-Fi 网络凭证通过低功耗蓝牙从移动设备发送到微控制器。Wi-Fi 预置服务的源代码位于 `freertos/.../wifi_provisioning`。
**注意**
Espressi ESP32 f-C 目前支持 Wi-Fi 配置演示 DevKit
**启用演示**
1. 启用 Wi-Fi 预置服务。打开`vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h`，然后设置`#define IOT_BLE_ENABLE_WIFI_PROVISIONING`为`1`（其中*vendor*是供应商的名称，*board*是您用来运行演示的主板的名称）。
**注意**
默认情况下禁用 Wi-Fi 预置服务。
1. 配置 [Network Manager](#ble-demo-network-manager) 以启用低功耗蓝牙和 Wi-Fi。
**运行演示**
1. 在微控制器上生成并运行演示项目。
1. 确保您已使用 [FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序](#ble-sdk-app)将微控制器与移动设备配对。
1. 从演示移动应用程序的 **Devices (设备)** 列表中，选择您的微控制器，然后选择 **Network Config (网络配置)** 以打开网络配置设置。
![\[三 ESP32 台设备清单，下面有 MQTT 代理 IDs、Network Config 和 Custom GATT MQTT 选项。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list4.png)
1. 在为主板选择 **Network Config (网络配置)** 之后，微控制器会将附近的网络列表发送到移动设备。可用 Wi-Fi 网络显示在 **Scanned Networks (扫描到的网络)** 下的列表中。
![\[ESP32 设备管理界面显示未保存的网络，两个已扫描的开放Wi-Fi网络，一个 WPA2 安全性和 RSSI 为 -29，另一个具有开放安全性，RSSI 为 -50。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-network-config1.png)
从 **Scanned Networks (扫描到的网络)** 列表中选择网络，然后输入 SSID 和密码（如果需要）。
![\[Wi-Fi 网络密码输入对话框，其中包含空的密码字段、“取消”按钮和“保存”按钮。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-wifi-password.png)
该微控制器连接到网络并保存网络信息。网络显示在 **Saved Networks (已保存网络)** 下。
![\[网络界面显示已保存和扫描的 WiFi 网络，一个由网络保护 WPA2，另一个处于打开状态，并带有信号强度指示器。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-network-config2.png)
您可以在演示移动应用程序中保存多个网络。在您重新启动应用程序和演示时，微控制器会连接到 **Saved Networks (已保存网络)** 列表中自上而下的第一个可用的已保存网络。
要更改网络优先级顺序或者删除网络，请在 **Network Configuration (网络配置)** 页面上选择 **Editing Mode (编辑模式)**。要更改网络优先级顺序，请选择您要重排优先级的网络的右侧，然后向上或向下拖动网络。要删除网络，请选择待删除网络左侧的红色按钮。
![\[Wifi 网络设置屏幕，展示了已保存的网络、用于删除或更改优先级的编辑选项以及扫描到的网络。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-network-editing.png)
## 通用属性服务器
在本示例中，您的微控制器上的演示通用属性 (GATT) 服务器应用程序发送简单的计数值到 [FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序](#ble-sdk-app)。
使用低功耗蓝牙手机 SDKs，您可以为移动设备创建自己的 GATT 客户端，该客户端通过微控制器连接到 GATT 服务器，并与演示移动应用程序并行运行。
**启用演示**
1. 启用低功耗蓝牙 GATT 演示。在`vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h`（其中*vendor*是供应商的名称，*board*是您用来运行演示的主板的名称）中，添加`#define IOT_BLE_ADD_CUSTOM_SERVICES ( 1 )`到 define 语句列表中。
**注意**
低功耗蓝牙 GATT 演示在默认情况下处于禁用状态。
1. 打开 `freertos/vendors/vendor/boards/board/aws_demos/config_files/aws_demo_config.h`，注释掉 `#define CONFIG_CORE_MQTT_MUTUAL_AUTH_DEMO_ENABLED` 并定义 `CONFIG_BLE_GATT_SERVER_DEMO_ENABLED`。
**运行演示**
1. 在微控制器上生成并运行演示项目。
1. 确保您已使用 [FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序](#ble-sdk-app)将主板与移动设备配对。
1. 从应用程序的 **Devices (设备)** 列表中，选择您的主板，然后选择 **MQTT Proxy (MQTT 代理)** 以打开 MQTT 代理选项。
![\[三 ESP32 台设备清单，下面有 MQTT 代理 IDs、Network Config 和 Custom GATT MQTT 选项。\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/userguide/images/ble-device-list4.png)
1. 返回到 **Devices (设备)** 列表，选择您的主板，然后选择 **Custom GATT MQTT (自定义 GATT MQTT)** 以打开自定义 GATT 服务选项。
1. 选择 **Start Counter (启动计数器)** 以开始将数据发布到 ***your-thing-name*/example/topic** MQTT 主题。
在启用 MQTT 代理之后，Hello World 和递增计数消息将显示在 `your-thing-name/example/topic` 主题上。