本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
低功耗蓝牙演示应用程序
重要
该演示托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时,我们建议从此处开始。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目,请参阅 Amazon-FreeRTOS Github 存储库迁移指南。
概述
FreeRTOS 低功耗蓝牙包括三个演示应用程序:
-
低功耗蓝牙 MQTT 演示
此应用程序演示如何使用低功耗蓝牙 MQTT 服务。
-
Wi-Fi 预置 演示
此应用程序演示如何使用低功耗蓝牙预置服务。
-
通用属性服务器 演示
此应用程序演示如何使用 FreeRTOS 低功耗蓝牙中间件 API 来创建一个简单的 GATT 服务器。
注意
要设置和运行 FreeRTOS 演示,请按照开始使用 FreeRTOS中的步骤操作。
先决条件
要按照这些演示练习,您的微控制器需要具备低功耗蓝牙功能。您还需要 适用于 FreeRTOS 蓝牙设备的 iOS 开发工具包 或 适用于 FreeRTOS 蓝牙设备的 Android 开发工具包。
为 FreeRTOS 低功耗蓝牙设置 AWS IoT 和亚马逊 Cognito
要通过 MQTT 将您的设备连接到 AWS IoT ,您需要设置 AWS IoT 和 Amazon Cognito。
要设置 AWS IoT
-
在 https://aws.amazon.com/
上 AWS 开设一个账户。 -
打开 AWS IoT 控制台
,从导航窗格中,依次选择管理和事物。 -
选择创建,然后选择创建单个事物。
-
输入您设备的名称,然后选择下一步。
-
如果您通过移动设备将微控制器连接到云中,请选择创建没有证书的事物。由于移动开发工具包使用 Amazon Cognito 进行设备身份验证,因此,您无需为使用低功耗蓝牙的演示创建设备证书。
如果您直接通过 Wi-Fi 将微控制器连接到云中,请依次选择创建证书和激活,然后下载事物的证书、公有密钥和私有密钥。
-
从已注册事物列表中选择您刚刚创建的事物,然后从事物的页面中选择交互。记下 AWS IoT REST API 端点。
有关设置的更多信息,请参阅《入门》 AWS IoT。
创建 Amazon Cognito 用户群体
-
打开 Amazon Cognito 控制台,然后选择管理用户群体。
-
选择创建用户池。
-
指定用户池名称,然后选择查看默认值。
-
在导航窗格中,选择应用程序客户端,然后选择添加应用程序客户端。
-
输入应用程序客户端的名称,然后选择创建应用程序客户端。
-
在导航窗格中,选择 审核,然后选择 创建池。
记录在您用户池的常规设置页面中显示的池 ID。
-
在导航窗格中,选择应用程序客户端,然后选择显示详细信息。记录应用程序客户端 ID 和应用程序客户端密钥。
创建 Amazon Cognito 身份池
-
打开 Amazon Cognito 控制台,然后选择管理身份池。
-
为身份池输入一个名称。
-
展开身份验证提供商,选择 Cognito 选项卡,然后输入您的用户池 ID 和应用程序客户端 ID。
-
选择创建池。
-
展开查看详细信息,记下两个 IAM 角色名称。要访问 Amazon Cognito,请选择允许,以便为经过身份验证和未经过身份验证的身份创建 IAM 角色。
-
选择编辑身份池。记录身份池 ID。其格式应为
us-west-2:12345678-1234-1234-1234-123456789012
。
有关设置 Amazon Cognito 的更多信息,请参阅 Amazon Cognito 入门。
创建 IAM policy 并将其附加到经过身份验证的身份
-
打开 IAM 控制台,然后在导航窗格中选择角色。
-
查找并选择您的经过身份验证的角色,然后依次选择附加策略和添加内联策略。
-
选择 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":[ "*" ] } ] }
-
选择查看策略,输入策略的名称,然后选择创建策略。
请随身携 AWS IoT 带您和亚马逊 Cognito 的信息。您需要端点和 ID 才能在 AWS 云端对您的移动应用程序进行身份验证。
为低功耗蓝牙设置 FreeRTOS 环境
要设置环境,您需要在微控制器下载包含低功耗蓝牙库 的 FreeRTOS,并在移动设备上下载和配置适用于 FreeRTOS 蓝牙设备的移动开发工具包。
在微控制器环境中设置 FreeRTOS 低功耗蓝牙
-
在微控制器上设置 FreeRTOS。
有关在符合 FreeRTOS 条件的微控制器上开始使用 FreeRTOS 的信息,请参阅 FreeRTOS 入门中有关您主板的指南。
注意
您可在任何已启用低功耗蓝牙且具有 FreeRTOS 和移植的 FreeRTOS 低功耗蓝牙库的微控制器上运行演示。目前,FreeRTOS 低功耗蓝牙 MQTT 演示项目已完全移植到以下启用低功耗蓝牙的设备:
常见组件
FreeRTOS 演示应用程序有两个常见组件:
-
网络管理器
-
低功耗蓝牙移动开发工具包演示应用程序
网络管理器
网络管理器管理微控制器的网络连接。它位于您的 FreeRTOS 目录中,路径为:demos/network_manager/aws_iot_network_manager.c
。如果为 Wi-Fi 和低功耗蓝牙均启用了网络管理器,则默认情况下通过低功耗蓝牙启动演示。如果低功耗蓝牙连接中断,并且您的主板启用了 Wi-Fi,则网络管理器切换到可用的 Wi-Fi 连接来防止您从网络断开连接。
要使用网络管理器来启用网络连接类型,请将网络连接类型添加到 vendors/
中的 vendor
/boards/board
/aws_demos/config_files/aws_iot_network_config.hconfigENABLED_NETWORKS
参数(其中,vendor
是供应商的名称,board
是您用来运行演示的主板的名称)。
例如,如果您同时启用了低功耗蓝牙和 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 蓝牙amazon-freertos-ble-android-sdk/app
的 iOSamazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo
在本示例中,我们使用 iOS 版本的演示移动应用程序的屏幕截图。
注意
如果您使用的是 iOS 设备,则需要 Xcode 来构建演示移动应用程序。如果您使用的是 Android 设备,则可使用 Android Studio 来构建演示移动应用程序。
配置 iOS 开发工具包演示应用程序
当您定义配置变量时,使用在配置文件中提供的占位符值的格式。
-
确认已安装 适用于 FreeRTOS 蓝牙设备的 iOS 开发工具包。
-
从
amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/
发布以下命令:$ pod install
-
打开具有 Xcode 的
amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo.xcworkspace
项目,将签名开发人员账户更改为您的账户。 -
在您所在的地区创建 AWS IoT 政策(如果您还没有)。
注意
此策略不同于为经过 Amazon Cognito 身份验证的身份创建的 IAM policy。
-
打开AWS IoT 控制台
。 -
在导航窗格中依次选择安全、策略和创建。输入用于标识您的策略的名称。在添加语句部分中,选择高级模式。将以下 JSON 复制并粘贴到策略编辑器窗口中。将
aws-reg
ion 和 aws-account 替换为您的地区和
账户 ID AWS 。{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Connect", "Resource":"arn:aws:iot:
region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": "arn:aws:iot:region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": "arn:aws:iot:region
:account-id
:*" } ] } -
选择创建。
-
-
打开
amazon-freertos-ble-ios-sdk/Example/AmazonFreeRTOSDemo/AmazonFreeRTOSDemo/Amazon/AmazonConstants.swift
并重新定义以下变量:-
region
: 您所在 AWS 的地区。 -
iotPolicyName
: 您的 AWS IoT 保单名称。 -
mqttCustomTopic
:您要发布到的 MQTT 主题。
-
-
打开
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 开发工具包演示应用程序
当您定义配置变量时,使用在配置文件中提供的占位符值的格式。
-
在您所在的地区创建 AWS IoT 政策(如果您还没有)。
注意
此策略不同于为经过 Amazon Cognito 身份验证的身份创建的 IAM policy。
-
打开AWS IoT 控制台
。 -
在导航窗格中依次选择安全、策略和创建。输入用于标识您的策略的名称。在添加语句部分中,选择高级模式。将以下 JSON 复制并粘贴到策略编辑器窗口中。将
aws-reg
ion 和 aws-account 替换为您的地区和
账户 ID AWS 。{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Connect", "Resource":"arn:aws:iot:
region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": "arn:aws:iot:region
:account-id
:*" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": "arn:aws:iot:region
:account-id
:*" } ] } -
选择创建。
-
-
-
AWS_IOT_POLICY_NAME
: 您的 AWS IoT 保单名称。 -
AWS_IOT_REGION
: 您所在 AWS 的地区。
-
-
在
CognitoIdentity
下,重新定义以下变量:-
PoolId
:您的 Amazon Cognito 身份池 ID。 -
Region
: 您所在 AWS 的地区。
在
CognitoUserPool
下,重新定义以下变量:-
PoolId
:您的 Amazon Cognito 用户群体 ID。 -
AppClientId
:您的应用程序客户端 ID。 -
AppClientSecret
:您的应用程序客户端密钥。 -
Region
: 您所在 AWS 的地区。
-
通过低功耗蓝牙发现微控制器并建立安全连接
-
为了将您的微控制器和移动设备安全配对(步骤 6),您需要一个同时具有输入和输出功能的串行终端仿真器(例如 TeraTerm)。将终端配置为通过串行连接来连接到主板,如安装终端仿真器中所述。
-
在您的微控制器上运行低功耗蓝牙演示项目。
-
在移动设备上运行低功耗蓝牙移动开发工具包演示应用程序。
要在 Android 开发工具包中从命令行启动演示应用程序,请运行以下命令:
$ ./gradlew installDebug
-
确认您的微控制器显示在低功耗蓝牙移动开发工具包演示应用程序的 Devices (设备) 下。
注意
处于范围内的所有具有 FreeRTOS 的设备以及设备信息服务 (
) 均会显示在列表中。freertos
/.../device_information -
从设备列表中选择您的微控制器。应用程序与主板建立连接,在已连接设备的旁边会显示一根绿色线条。
您可以通过将线条拖动到左侧,从微控制器上断开连接。
-
如果出现提示,请将您的微控制器和移动设备进行配对。
FreeRTOS 主板
移动设备
如果两个设备上用于比较数字的代码相同,则配对这两个设备。
注意
低功耗蓝牙移动开发工具包演示应用程序使用 Amazon Cognito 进行用户身份验证。确保您已设置 Amazon Cognito 用户和身份池,并且将 IAM policy 附加到了通过身份验证的身份。
低功耗蓝牙 MQTT
在 MQTT 低功耗蓝牙演示中,您的微控制器通过 MQTT 代理向 AWS 云端发布消息。
订阅演示 MQTT 主题
-
登录 AWS IoT 控制台。
-
在导航窗格中选择测试,然后选择 MQTT 测试客户端,以便打开 MQTT 客户端。
-
在 Subscription topic (订阅主题)中,输入
,然后选择 Subscribe to topic (订阅主题)。thing-name
/example/topic1
如果您使用低功耗蓝牙将微控制器与移动设备配对,则通过您移动设备上的低功耗蓝牙移动开发工具包演示应用程序来路由 MQTT 消息。
通过低功耗蓝牙启用演示
-
打开
vendors/
并定义vendor
/boards/board
/aws_demos/config_files/aws_demo_config.hCONFIG_MQTT_BLE_TRANSPORT_DEMO_ENABLED
。 -
打开
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 身份和用户池的同一区域。
运行演示
-
在微控制器上生成并运行演示项目。
-
确保您已使用 FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序将主板与移动设备配对。
-
从演示移动应用程序的 Devices (设备) 列表中,选择您的微控制器,然后选择 MQTT Proxy (MQTT 代理) 以打开 MQTT 代理设置。
-
在启用 MQTT 代理之后,MQTT 消息将显示在
主题上,并且数据将输出到 UART 终端。thing-name
/example/topic1
Wi-Fi 预置
Wi-Fi 预置是一项 FreeRTOS 低功耗蓝牙服务,让您可以安全地将 Wi-Fi 网络凭证通过低功耗蓝牙从移动设备发送到微控制器。Wi-Fi 预置服务的源代码位于
。freertos
/.../wifi_provisioning
注意
乐新 ESP32-C 目前支持 Wi-Fi 配置演示 DevKit
启用演示
-
启用 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 预置服务。
-
配置 网络管理器 以启用低功耗蓝牙和 Wi-Fi。
运行演示
-
在微控制器上生成并运行演示项目。
-
确保您已使用 FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序将微控制器与移动设备配对。
-
从演示移动应用程序的 Devices (设备) 列表中,选择您的微控制器,然后选择 Network Config (网络配置) 以打开网络配置设置。
-
在为主板选择 Network Config (网络配置) 之后,微控制器会将附近的网络列表发送到移动设备。可用 Wi-Fi 网络显示在 Scanned Networks (扫描到的网络) 下的列表中。
从 Scanned Networks (扫描到的网络) 列表中选择网络,然后输入 SSID 和密码(如果需要)。
该微控制器连接到网络并保存网络信息。网络显示在 Saved Networks (已保存网络) 下。
您可以在演示移动应用程序中保存多个网络。在您重新启动应用程序和演示时,微控制器会连接到 Saved Networks (已保存网络) 列表中自上而下的第一个可用的已保存网络。
要更改网络优先级顺序或者删除网络,请在 Network Configuration (网络配置) 页面上选择 Editing Mode (编辑模式)。要更改网络优先级顺序,请选择您要重排优先级的网络的右侧,然后向上或向下拖动网络。要删除网络,请选择待删除网络左侧的红色按钮。
![Wifi 网络设置屏幕显示已保存的网络、用于删除或更改优先级的编辑选项以及已扫描的网络。](images/ble-network-editing.png)
通用属性服务器
在本示例中,您的微控制器上的演示通用属性 (GATT) 服务器应用程序发送简单的计数值到 FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序。
使用低功耗蓝牙移动开发工具包,您可以为连接到微控制器上 GATT 服务器的移动设备创建自己的 GATT 客户端,并与演示移动应用程序并行运行。
启用演示
-
启用低功耗蓝牙 GATT 演示。在
vendors/
( 其中,vendor
/boards/board
/aws_demos/config_files/iot_ble_config.hvendor
是供应商的名称,board
是您用来运行演示的主板的名称)中,将#define IOT_BLE_ADD_CUSTOM_SERVICES ( 1 )
添加到定义语句的列表中。注意
低功耗蓝牙 GATT 演示在默认情况下处于禁用状态。
-
打开
,注释掉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
。
运行演示
-
在微控制器上生成并运行演示项目。
-
确保您已使用 FreeRTOS 低功耗蓝牙移动开发工具包演示应用程序将主板与移动设备配对。
-
从应用程序的 Devices (设备) 列表中,选择您的主板,然后选择 MQTT Proxy (MQTT 代理) 以打开 MQTT 代理选项。
-
返回到 Devices (设备) 列表,选择您的主板,然后选择 Custom GATT MQTT (自定义 GATT MQTT) 以打开自定义 GATT 服务选项。
-
选择 Start Counter (启动计数器) 以开始将数据发布到
MQTT 主题。your-thing-name
/example/topic在启用 MQTT 代理之后,Hello World 和递增计数消息将显示在
主题上。your-thing-name
/example/topic