用于 STM32Cube 的 Google Cloud Platform™扩展包入门
引言
本用户手册描述 STM32Cube™ 扩展包的内容，该扩展包用于 Google Cloud Platform™（GCP）Google Cloud IoT Core 的服务。用于 GCP 的 STM32Cube 扩展包（X-CUBE-GCP）提供了将 STMicroelectronics 板卡连接到 Google Cloud Platform™ 的 Google Cloud IoT Core 的应用示例。它将 MQTT 客户端库移植到相应的 STM32 器件上去实现与云平台的连接。
X-CUBE-GCP 可在五个平台上运行：
通过Inventek ISM43362 模块支持Wi-Fi®连接的B-L475E-IOT01A和 32F413HDISCOVERY 板
提供原生以太网接口的 32F769IDISCOVERY 板
P-L496G-CELL01 和 P-L496G-CELL02 探索包分别通过 2G/3G（UG96）和 LTE（BG96）Quectel 蜂窝调制解调器子板支持蜂窝连接
对于这五个平台，应用示例配置了网络连接参数，并说明了设备与GCP交互的各种方式。
该扩展包包含了设备到云端的遥测数据报告、用于安全连接云端的云端到设备的消息、向云端发送命令和从连接的设备接收通知的实现示例。
B-L475E-IOT01A 板报告遥测数据，例如湿度、温度和大气压力测量值。
1、概述
用于 Google Cloud Platform™ 的 Google Cloud IoT Core 的 X-CUBE-GCP 扩展包在基于 Arm® Cortex®-M 处理器 的 STM32 32位微控制器上运行。表 1 给出了相关缩略语的定义，帮助您更好地理解本文档。
▲ 表 1. 缩略语列表
2、Google Cloud Platform™
本章介绍 Google Cloud Platform™ 的 Google Cloud IoT Core。与 Google Cloud Platform™（GCP）相关的详细信息可从 Google Cloud™ 专用网站http://cloud.google.com 下载。X-CUBE-GCP 实现嵌入式C客户端，能够将板安全地连接到GCP 的 Google Cloud IoT Core。X-CUBE-GCP 所针对的GCP生态系统如图 1 所示。
▲ 图 1. Google Cloud IoT Core 生态系统
用户可以使用智能手机或个人计算机连接到云端，并可以随时随地访问该板提供的信息。Google Cloud™ 在GCP在线文档中展示的 Google Cloud IoT Core 如图 2 所示。
图 2. Google Cloud IoT Core 图
注意 ©2018 Google LLC，经许可使用。Google 和 Google 徽标是 Google LLC. 的注册商标 X-CUBE-GCP 实现必要的服务，将设备连接到图 2 中用蓝色框出的生态系统部分。
特别是，该扩展包演示了如何配置 GCP 的 IoT Core 服务，以便将设备安全地连接到 Google Cloud IoT Core 服 务。设备使用私钥（ECDSA 或 RSA）签署连接云平台时需要的 JWT（JSON 网络令牌）。Cloud IoT Core 通过在设备 创建过程中上传到云服务的相应公钥验证设备的 JWT。X-CUBE-GCP 还提供了示例，展示了如何使用数据格式和使用 MQTT 协议在设备与 IoT Core 元件之间交换数据， 将遥测数据发送到云端，以及从云端接收配置数据。发送到 Cloud IoT Core 的数据随后可通过 Pub/Sub（发布/订 阅）服务发布，并能在日后需要使用时通过网络应用进行访问。用于数据分析和使用的网络应用的开发不在 XCUBE-GCP 的范围之内。
3、软件包说明
本章详述了 X-CUBE-GCP 扩展包的内容和使用。
3.1 概述
X-CUBE-GCP 扩展包由多系列的基于 STM32L4 系列，STM32F4 系列和 STM32F7 系列微控制器的库和应用示例组成。
X-CUBE-GCP 可在五个平台上运行：
通过 Inventek ISM43362 模块支持 Wi-Fi®连接的 B-L475E-IOT01A 和 32F413HDISCOVERY 板
提供原生以太网接口的 32F769IDISCOVERY 板
P-L496G-CELL01 和 P-L496G-CELL02 包分别通过 Quectel 的 2G/3G UG96 和 LTE BG96 蜂窝调制解调器子板支持蜂窝连接。用于连接 2G/3G 蜂窝网络与云端的 P-L496G-CELL01 STM32 探索包（STM32-C2C/ 2G-3G）和用于连接 LTE 蜂窝网络与云端的 P-L496G-CELL02 STM32 探索包（STM32-C2C/2G-LTE）是基于蜂窝网络和云技术的解决方案的完整开发平台。探索包内含一个基于 STM32L496AGI6 的带预加载固件的低功耗探索主板和一个带天线的 STMod+ 蜂窝网络扩展板。
X-CUBE-GCP 扩展包包含以下组件：
Eclipse™ Paho MQTT 嵌入式 C 客户端
mbedTLS
用于 B-L475E-IOT01A 和 32F413HDISCOVERY 板的 Inventek ISM43362 Wi-Fi®驱动程序
用于 32F769IDISCOVERY 板的以太网驱动程序、FreeRTOS™和 LwIP
用于 B-L475E-IOT01A 板的传感器驱动 • 用于 P-L496G-CELL01 和 P-L496G-CELL02 套件的蜂窝网络驱动程序
用于所有 MCU 板的 BSP
STM32L4 系列、STM32F4 系列，和 STM32F7 系列 HAL
应用程序示例
软件以 zip 文档的形式提供，其中包含源代码。可支持以下集成开发环境：
IAR Embedded Workbench® 对于 Arm®（EWARM）
Keil®微控制器开发套件（MDK-ARM）
System Workbench for STM32 有关所支持 IDE 版本的信息，请参阅软件包根文件夹中的版本说明。
有关所支持 IDE 版本的信息，请参阅软件包根文件夹中的版本说明。
3.2 架构
本节介绍 X-CUBE-GCP 中的软件组件。X-CUBE-GCP 是 STM32Cube™ 的扩展软件。其主要功能和特性如下：
完全兼容 STM32Cube™ 架构
为了能够开发应用程序来访问和使用 Google Cloud Platform™ 的 Google Cloud IoT Core，扩展了 STM32Cube™
基于 STM32 微控制器的硬件抽象层 STM32CubeHAL
应用软件访问和使用 Google Cloud Platform™ 的 Google Cloud IoT Core 所用的软件组件如下：
STM32Cube HAL
HAL 驱动层提供通用的多实例简单 API 组（应用程序编程接口），以便与上层（应用、库和协议栈）交互。它由通用和扩展 API 构成。它直接围绕通用架构构建，允许在其基础上的软件层，例如中间件层，实现了它 的功能又无需依赖给定 MCU 的特定硬件配置。此结构可提高库代码的可复用性，并确保可向其他设备轻松移植。
板级支持包（BSP）
除 MCU 之外，板软件包需支持 STM32 板上的外设。板支持包中包含此软件。这是一个有限的 API 集，为板 特有的某些外设（例如 LED 和用户按钮等）提供编程接口
mbedTLS
MQTT 中间件使用由 mbedTLS 库实现的 TLS 连接。
MQTT 客户端中间件
它由 Eclipse™ Paho MQTT 嵌入式 C 客户端库（被 MQTT 应用用作传输层）和 JSON 解析器构成。
TCP/IP
TCP/IP 连接可由 Wi-Fi®模块（当使用 Wi-Fi®连接时）、LwIP TCP-IP 栈（当使用以太网连接时）或通过蜂窝 连接（当使用蜂窝网络扩展板时）来处理。
FreeRTOS™
它是一个实时操作系统，使用 LwIP 为用户提供基于套接字的接口时，需要用到。
Google Cloud™IoT
示例应用程序 一个应用示例，实现了连接 GCP Google Cloud IoT Core 组件所需的设备服务。这包括连接管理、JWT 安全 连接处理和与云端交互的合适消息格式。
X-CUBE-GCP 软件的架构如图 3 所示。
▲ 图 3. X-CUBE-GCP 软件架构
3.3 文件夹结构
X-CUBE-GCP 扩展包的文件夹结构如图 4 所示。
▲ 图 4. 项目文件结构
3.4 B-L475E-IOT01A 板传感器
应用示例使用的板载传感器包括：
用于相对湿度和温度测量的电容式数字传感器（HTS221）
高性能 3 轴磁力计（LIS3MDL）
3D 加速度计和 3D 陀螺仪（LSM6DSL）
260-1260 hPa 绝对数字输出气压计（LPS22HB）
接近传感器（VL53L0X）
B-L475E-IOT01A 板传感器报告值的单位如表 2 所示。
▲ 表 2. B-L475E-IOT01A 板传感器报告值的单位
3.5 Wi-Fi®元件
Wi-Fi®软件分为两部分，Drivers/BSP/Components 下是模块专用软件，Projects//WiFi 下是 I/O 操作和 WiFi®模块的抽象层。
3.6 复位按钮
复位按钮（黑色）用于随时复位板子。此操作可使板重新启动。
3.7 用户按钮
用户按钮（蓝色）用于以下情况：
要配置 Wi-Fi® 和 Google Cloud™安全证书，从板启动时开始直到启动后五秒，都可以完成此操作。
板子初始化后，如果用户按下按钮的时间很短，则应用程序仅发布 B-L475E-IOT01A 板子的传感器值、0/1 切 换值（绿色 LED 将相应切换）以及时间戳。双击按钮后，应用程序进入循环并每秒自动发布一次。再一次双 击将恢复先前的模式。应用程序通过板级支持包功能来配置和管理用户按钮。BSP 功能位于 DriversBSP 目录中。使用 BSP 按钮功能时（采用 BUTTON_USER 值），对于给定的平台，应用不会从硬件角度考虑此按钮连接的方式；该映射由 BSP 处理。
3.8 用户 LED
应用程序所用的用户LED 配置通过板级支持包功能完成。 BSP 功能位于 DriversBSP目录中。 使用 BSP 功能时（采用 LED_GREEN 值），对于给定的平台，应用不会考虑 LED 映射的方式；该映射由 BSP 处 理。
3.9 实时时钟
STM32 器件的 RTC 在启动时从 http://www.gandi.net 网络服务器进行更新。用户可以使用 HAL_RTC_GetTime() 函数得到时间值。例如，此函数可以用于时间戳消息。
3.10 mbedTLS 配置
利用#include配置文件，可以对mbedTLS 中间件进行配置。可使用 MBEDTLS_CONFIG_FILE #define 指令覆盖配置文件名。X-CUBE-GCP 包使用文件 googleiot_mbedtls_config.h来实现项目配置。这可以通过在 mbedTLS.c 和 mbedTLS.h 文件开头设置以下#指令来实现：
#if !defined(MBEDTLS_CONFIG_FILE) #include "mbedtls/config.h" #else #include MBEDTLS_CONFIG_FILE #endif
配置文件指定了要使用的相关加密参数。
4、硬件和软件环境设置
为了设置硬件和软件环境，必须利用 USB 线将支持的板连接到个人计算机。连接到 PC 后，允许用户：
烧写板
存储 Wi-Fi®和 Google Cloud™安全证书
通过 UART 控制台与板进行交互
调试
B-L475E-IOT01A 和 32F413HDISCOVERY 板必须连接到 Wi-Fi®接入点，P-L496G-CELL01 和 P-L496G-CELL02 套件的天线必须插入以连接到周围的蜂窝网络，并且 32F769IDISCOVERY 板必须连接到以太网接口，如图 5 所 示。
▲ 图 5. 硬件和软件设置环境
运行示例的先决条件是：
以下连接解决方案之一：
一个 Wi-Fi® 接入点，具有透明的互联网连接，也就是说不能有代理服务器或者防火墙阻止开发板与外网 的通信。它必须运行一个 DHCP 服务器，将 IP 和 DNS 配置提供给主板。
以太网连接，具有透明的互联网连接，也就是说不能有代理服务器或者防火墙阻止开发板与外网的通信。
有效的蜂窝网络订阅，激活了无线通信数据服务，来自集成了 MVNO 配置文件的嵌入式 SIM 或外部 Micro-SIM。
一台开发 PC，用于构建应用、利用 ST-LINK 进行编程以及运行虚拟控制台。
一台计算机，用于运行连接 Google Cloud™控制台的网络浏览器或管理 Google Cloud Platform™的 GCLOUD SDK 命令行工具。计算机防火墙（如果有）必须允许 MQTT 连接进入（通常是端口 1883 和 8883）。例如，它可以是开发 PC、虚拟专用服务器或单板计算机。
OpenSSL 工具套件，用于构建新的设备公钥/私钥对。
5、应用程序示例
本章介绍如何注册和登录 Google Cloud Platform™的 Google Cloud IoT Core，以及如何使用 X-CUBE-GCP 扩展包中的 GCP IoT Core 应用。此外，还展示了如何从 Google Cloud™控制台配置 GCP，但也可以使用 Google Cloud™ SDK 中的命令行工具应用相同配置。请参考 Google Cloud™ SDK 文档了解关于命令行工具的更多详细信息。
5.1 应用描述
应用提供下列服务：
连接管理
应用首先配置板连接（Wi-Fi®、以太网或蜂窝网络），并确保连接正常且正常工作，以便提供有效的 IP 地址 和 IP 连接。通过 JWT 提供安全连接
一旦有 IP 连接可用，应用将通过 JSON 网络令牌（JWT）创建安全地连接到 GCP IoT Core 服务。GCP IoT core 支持多种密钥格式。该应用支持两种密钥格式：ES256 和 RS256。发送/获取设备状态
一旦安全连接，应用将向 GCP IoT Core 发送更新后的设备状态。这将允许从 GCP 控制台获取设备信息。设 备状态是设备的内部表达。
在 X-CUBE-GCP 应用中，设备状态是一个简单的 JSON 字符串，包含板 LED 状态、遥测间隔、本地时间 戳、MAC 地址和当前固件版本。下面是发布的设备状态示例：
{
"LedOn": false,
"TelemetryInterval": 60,
"ts": 1530170497,
"mac":"C47F5104341",
"FW version":"V1.1.0"
}
配置设备
GCP 提供修改设备配置的功能。根据 GCP 文档中的定义，设备配置是一种任意的用户定义的数据 BLOB。XCUBE-GCP 应用使用配置从云端控制 LED 状态，更改遥测间隔并强制重启。应用接受简单 JSON 格式的配 置，如下所示：
{
"LedOn": true,
"TelemetryInterval":60,
"Reboot": false
}
X-CUBE-GCP 在每次连接时对配置进行注册。每次重新注册时，GCP IoT Core 服务总是发送最新配置。因此，如果在配置中发送重启 命令"Reboot": true，用户必须将 配置重新更新为"Reboot": false，以免在每次重新连接时发生无限重启。
通过 MQTT Bridge 发送遥测数据
应用只支持 GCP IoT Core 的 MQTT Bridge 服务。
它不支持 HTTP Bridge。一旦用户按一次用户按钮，应用就发送遥测数据。如果用户按两次用户按钮，设备将进入发布循环，并定期发 送遥测数据。在最初的设备配置步骤中使用参数 TelemetryInterval 配置此循环的周期。
如 GCP 在线文档中所述，设备可以通过发出 PUBLISH 消息（通过 MQTT 连接）来发布遥测事件。应用示例 中使用的 Quality of Service 是 QOS1（至少传输一次）。必须用以下格式将消息发布到 MQTT 主题：/ devices/{device-id}/events。
下面是带传感器的板的消息发布示例：
{
"data":
[{"dataType":"temp","value":"27.91"},
{"dataType":"hum","value":"48.72"},
{"dataType":"pres","value":"1015.17"}]
}
应用行为如图 6 所示。
▲ 图 6. 应用状态机
5.2 GCP 和 IoT Core 帐户设置
为了使用 Google Cloud IoT Core 服务，需创建 Google Cloud Platform™帐户。用户必须先创建帐户，然后才能继 续操作并创建或选择 GCP 项目。
提示关于注册、项目创建和 API 使能，请访问 http://cloud.google.com。 创建用户帐户的步骤如下： 1. 使能项目计费，如图 7 所示。如不使能项目计费，用户将无法继续执行帐户创建的剩余步骤。
▲ 图 7. 需要计费
2. 使能应用使用的“Google Cloud IoT Core”和“Pub/Sub” API。在 GCP 控制台中，进入“API 和服务仪表板”，如 图 8 所示。
▲ 图 8. 使能 API 菜单
3. 使用“使能 API 和服务”并至少使能 Google Cloud IoT API 和 Cloud Pub/Sub API，如图 9. 使能 Google Cloud IoT API 和图 10. 使能 Cloud Pub/Sub API 所示。
▲ 图 9. 使能 Google Cloud IoT API
▲ 图 10. 使能 Cloud Pub/Sub API
5.3 在 GCP IoT core 上创建设备
关于 Google Cloud IoT Core 的完整文档和如何创建注册表、设备和遥测主题，请访问 http://cloud.google.com/iot/ docs。
按照下述步骤创建并注册新设备： 1. 在 Google Cloud IoT Core 中，创建新设备注册表（在连接字符串中定义为{registry-id}），如图 11 所 示。
▲ 图 11. GCP“创建注册表”按钮
2. 在注册表创建面板上选择一个区域（默认为 us-central1），以后可以将其作为连接字符串中的{cloudregion}进行配置。如果不存在，创建名为“events”的遥测主题，并维持默认状态主题。该主题必须命名为 “events”，因为这是应用使用的名称。应用只支持 MQTT 协议；不支持 HTTP 且可以取消选中 HTTP。用户无 需添加证书。注册表创建设置的专用窗口如图 12 所示。
▲ 图 12. GCP“创建注册表”设置
3. 在新创建的注册表中添加新设备
定义设备 ID，即连接字符串中的{device-id}。
按照 GCP 的“创建公钥/私钥对”文档中的描述，使用“openssl”创建 RS256 或 RS256 类型的公钥和私钥。
对于 RS256
> openssl genrsa -out rsa_private.pem 2048 > openssl rsa -in rsa_private.pem -pubout -out rsa_public.pem
对于 ES256
> openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem > openssl ec -in ec_private.pem -pubout -out ec_public.pem
将公钥 pem 文件的内容添加到设备并保存私钥，私钥将通过控制台接口传递到设备。设备的创建如 图 13. GCP“创建设备”设置所示。
▲ 图 13. GCP“创建设备”设置
在执行上述步骤后，云的设置完毕；可以使用设备并将其连接到 GCP。
5.4 应用程序编译和烧写
提示 使用任何工具链打开项目之前，请确保文件夹安装路径不太深，否则工具链可能会在编译之后报告错误。
使用所支持的某种开发工具链打开并编译项目（有关版本要求的详细信息，请参阅版本说明）。在 STM32 板上编程固件：将ProjectsApplicationsCloudGoogleIoTBinary 下的二进制文件复制 （或拖放）到 STM32 板插入 PC 时所创建的 USB 大容量存储位置。或者，用户可以直接通过所支持的其中一个开 发工具链对 STM32 板进行编程。
5.5 应用程序首次启动
1. 必须通过 USB（ST-LINK USB 端口）将板连接到 PC。通过串行终端仿真器（如 Tera Term）打开控制台，选择板子的 ST-LINK COM 端口，并进行以下配置：
8 位数据长度，无校验，1 位停止位，115200 波特率，无硬件流控制
行结束符设置为 LF
“echo on”选项，以便能够读取用户输入的参数
此外，建议使能“自动模式”选项（如果有）
有关详细信息，请参见第 6 节 与板交互。 对于支持 Wi-Fi®的板，通过控制台输入 Wi-Fi® SSID、加密模式和密码。对于蜂窝网络连接，输入选中操作员 提供的接入点和密码。
2. 系统提示用户输入连接字符串，其中包含与使用 GCP 用户帐户创建的项目和注册设备相关的必要信息。输入设备的 Google Cloud IoT Core 连接字符串：（模板：project-id=xxx;registry-id=xxx;deviceid=xxx;cloud-region=xxx） 连接字符串的示例： project-id=my-project-123456;registry-id=stm32registry;deviceid=mystm32device;cloud-region=us-central1
3. 设置 TLS 根 CA 证书： 复制粘贴Projects CommonGoogleIoT comodo_google.pem的内容。该设备使用它通过TLS对远程主机进 行身份验证。 注意：示例应用程序要求提供2个CA证书的连结。 a. 用于HTTPS 服务器，启动时通过该服务器检索当前时间和日期（“Comodo”证书） b. 用于GCP，以便验证云服务器。根据服务器，可能需要按照 Google Cloud™的支持CA列表更新 comodo_google.pem（可在 http://pki.google.com/roots.pem 中找到）。