引言

本用户手册描述 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 可在五个平台上运行：

对于这五个平台，应用示例配置了网络连接参数，并说明了设备与GCP交互的各种方式。

该扩展包包含了设备到云端的遥测数据报告、用于安全连接云端的云端到设备的消息、向云端发送命令和从连接的设备接收通知的实现示例。

B-L475E-IOT01A 板报告遥测数据，例如湿度、温度和大气压力测量值。

1、概述

用于 Google Cloud Platform™ 的 Google Cloud IoT Core 的 X-CUBE-GCP 扩展包在基于 Arm® Cortex®-M 处理器 的 STM32 32位微控制器上运行。表 1 给出了相关缩略语的定义，帮助您更好地理解本文档。

谷歌云实现和维护（GoogleCloudPlatform）(1)

▲ 表 1. 缩略语列表

2、Google Cloud Platform™

本章介绍 Google Cloud Platform™ 的 Google Cloud IoT Core。与 Google Cloud Platform™（GCP）相关的详细信息可从 Google Cloud™ 专用网站cloud.google.com 下载。X-CUBE-GCP 实现嵌入式C客户端，能够将板安全地连接到GCP 的 Google Cloud IoT Core。X-CUBE-GCP 所针对的GCP生态系统如图 1 所示。

谷歌云实现和维护（GoogleCloudPlatform）(2)

▲ 图 1. Google Cloud IoT Core 生态系统

用户可以使用智能手机或个人计算机连接到云端，并可以随时随地访问该板提供的信息。Google Cloud™ 在GCP在线文档中展示的 Google Cloud IoT Core 如图 2 所示。

谷歌云实现和维护（GoogleCloudPlatform）(3)

图 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 可在五个平台上运行：

X-CUBE-GCP 扩展包包含以下组件：

软件以 zip 文档的形式提供，其中包含源代码。可支持以下集成开发环境：

有关所支持 IDE 版本的信息，请参阅软件包根文件夹中的版本说明。

3.2 架构

本节介绍 X-CUBE-GCP 中的软件组件。X-CUBE-GCP 是 STM32Cube™ 的扩展软件。其主要功能和特性如下：

应用软件访问和使用 Google Cloud Platform™ 的 Google Cloud IoT Core 所用的软件组件如下：

X-CUBE-GCP 软件的架构如图 3 所示。

谷歌云实现和维护（GoogleCloudPlatform）(4)

▲ 图 3. X-CUBE-GCP 软件架构

3.3 文件夹结构

X-CUBE-GCP 扩展包的文件夹结构如图 4 所示。

谷歌云实现和维护（GoogleCloudPlatform）(5)

▲ 图 4. 项目文件结构

3.4 B-L475E-IOT01A 板传感器

应用示例使用的板载传感器包括：

B-L475E-IOT01A 板传感器报告值的单位如表 2 所示。

谷歌云实现和维护（GoogleCloudPlatform）(6)

▲ 表 2. B-L475E-IOT01A 板传感器报告值的单位

3.5 Wi-Fi®元件

Wi-Fi®软件分为两部分，Drivers/BSP/Components 下是模块专用软件，Projects//WiFi 下是 I/O 操作和 WiFi®模块的抽象层。

3.6 复位按钮

复位按钮（黑色）用于随时复位板子。此操作可使板重新启动。

3.7 用户按钮

用户按钮（蓝色）用于以下情况：

3.8 用户 LED

应用程序所用的用户LED 配置通过板级支持包功能完成。

BSP 功能位于 Drivers\BSP\目录中。

使用 BSP 功能时（采用 LED_GREEN 值），对于给定的平台，应用不会考虑 LED 映射的方式；该映射由 BSP 处 理。

3.9 实时时钟

STM32 器件的 RTC 在启动时从 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 后，允许用户：

B-L475E-IOT01A 和 32F413HDISCOVERY 板必须连接到 Wi-Fi®接入点，P-L496G-CELL01 和 P-L496G-CELL02 套件的天线必须插入以连接到周围的蜂窝网络，并且 32F769IDISCOVERY 板必须连接到以太网接口，如图 5 所 示。

谷歌云实现和维护（GoogleCloudPlatform）(7)

▲ 图 5. 硬件和软件设置环境

运行示例的先决条件是：

  1. 一个 Wi-Fi® 接入点，具有透明的互联网连接，也就是说不能有代理服务器或者防火墙阻止开发板与外网 的通信。它必须运行一个 DHCP 服务器，将 IP 和 DNS 配置提供给主板。
  2. 以太网连接，具有透明的互联网连接，也就是说不能有代理服务器或者防火墙阻止开发板与外网的通信。
  3. 有效的蜂窝网络订阅，激活了无线通信数据服务，来自集成了 MVNO 配置文件的嵌入式 SIM 或外部 Micro-SIM。

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 应用描述

应用提供下列服务：

{ "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，以免在每次重新连接时发生无限重启。

应用只支持 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 所示。

谷歌云实现和维护（GoogleCloudPlatform）(8)

▲ 图 6. 应用状态机

5.2 GCP 和 IoT Core 帐户设置

为了使用 Google Cloud IoT Core 服务，需创建 Google Cloud Platform™帐户。用户必须先创建帐户，然后才能继 续操作并创建或选择 GCP 项目。

提示 关于注册、项目创建和 API 使能，请访问 cloud.google.com。

创建用户帐户的步骤如下：

1. 使能项目计费，如图 7 所示。如不使能项目计费，用户将无法继续执行帐户创建的剩余步骤。

谷歌云实现和维护（GoogleCloudPlatform）(9)

▲ 图 7. 需要计费

2. 使能应用使用的“Google Cloud IoT Core”和“Pub/Sub” API。在 GCP 控制台中，进入“API 和服务仪表板”，如 图 8 所示。

谷歌云实现和维护（GoogleCloudPlatform）(10)

▲ 图 8. 使能 API 菜单

3. 使用“使能 API 和服务”并至少使能 Google Cloud IoT API 和 Cloud Pub/Sub API，如图 9. 使能 Google Cloud IoT API 和图 10. 使能 Cloud Pub/Sub API 所示。

谷歌云实现和维护（GoogleCloudPlatform）(11)

▲ 图 9. 使能 Google Cloud IoT API

谷歌云实现和维护（GoogleCloudPlatform）(12)

▲ 图 10. 使能 Cloud Pub/Sub API

5.3 在 GCP IoT core 上创建设备

关于 Google Cloud IoT Core 的完整文档和如何创建注册表、设备和遥测主题，请访问 cloud.google.com/iot/ docs。

按照下述步骤创建并注册新设备：

1. 在 Google Cloud IoT Core 中，创建新设备注册表（在连接字符串中定义为{registry-id}），如图 11 所 示。

谷歌云实现和维护（GoogleCloudPlatform）(13)

▲ 图 11. GCP“创建注册表”按钮

2. 在注册表创建面板上选择一个区域（默认为 us-central1），以后可以将其作为连接字符串中的{cloudregion}进行配置。如果不存在，创建名为“events”的遥测主题，并维持默认状态主题。该主题必须命名为 “events”，因为这是应用使用的名称。应用只支持 MQTT 协议；不支持 HTTP 且可以取消选中 HTTP。用户无 需添加证书。注册表创建设置的专用窗口如图 12 所示。

谷歌云实现和维护（GoogleCloudPlatform）(14)

▲ 图 12. GCP“创建注册表”设置

3. 在新创建的注册表中添加新设备

定义设备 ID，即连接字符串中的{device-id}。

按照 GCP 的“创建公钥/私钥对”文档中的描述，使用“openssl”创建 RS256 或 RS256 类型的公钥和私钥。

> openssl genrsa -out rsa_private.pem 2048 > openssl rsa -in rsa_private.pem -pubout -out rsa_public.pem

> openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem > openssl ec -in ec_private.pem -pubout -out ec_public.pem

将公钥 pem 文件的内容添加到设备并保存私钥，私钥将通过控制台接口传递到设备。设备的创建如 图 13. GCP“创建设备”设置所示。

谷歌云实现和维护（GoogleCloudPlatform）(15)

▲ 图 13. GCP“创建设备”设置

在执行上述步骤后，云的设置完毕；可以使用设备并将其连接到 GCP。

5.4 应用程序编译和烧写

提示 使用任何工具链打开项目之前，请确保文件夹安装路径不太深，否则工具链可能会在编译之后报告错误。

使用所支持的某种开发工具链打开并编译项目（有关版本要求的详细信息，请参阅版本说明）。在 STM32 板上编程固件：将Projects\\Applications\Cloud\GoogleIoT\Binary 下的二进制文件复制 （或拖放）到 STM32 板插入 PC 时所创建的 USB 大容量存储位置。或者，用户可以直接通过所支持的其中一个开 发工具链对 STM32 板进行编程。

5.5 应用程序首次启动

1. 必须通过 USB（ST-LINK USB 端口）将板连接到 PC。通过串行终端仿真器（如 Tera Term）打开控制台，选择板子的 ST-LINK COM 端口，并进行以下配置：

有关详细信息，请参见第 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\ Common\GoogleIoT\ comodo_google.pem的内容。该设备使用它通过TLS对远程主机进 行身份验证。

注意：示例应用程序要求提供2个CA证书的连结。

a. 用于HTTPS 服务器，启动时通过该服务器检索当前时间和日期（“Comodo”证书）

b. 用于GCP，以便验证云服务器。根据服务器，可能需要按照 Google Cloud™的支持CA列表更新 comodo_google.pem（可在 pki.google.com/roots.pem 中找到）。

4. 设置设备私钥

复制粘贴在 GCP 控制台上的设备创建步骤中创建的公钥所对应的私钥 rsa_private.pem 或 ec_private.pem 的 内容。

5. 参数配置完成后，如果需要重新更改参数，可以根据提示通过重启板并按下用户按钮（蓝色按钮）来进行更改。

5.6 应用程序运行时

1. RTC 配置

应用程序发出 HTTPS 请求来检索当前时间和日期，并配置 RTC。

2. 设备到云的连接

在正确配置设置后，设备连接到 GCP IoT core。为了核实连接是否正确，用户可以从 GCP IoT core 控制台检 查设备详情，如图 14. IoT core 设备控制台所示。

谷歌云实现和维护（GoogleCloudPlatform）(16)

▲ 图 14. IoT core 设备控制台

从同一控制台菜单，用户可以：

3. 发布的遥测数据

如果板子为 B-L475E-IOT01，则应用可发布传感器值、0/1 切换值（绿色 LED 相应切换）以及时间戳。

上一步“设备到云的连接”中的 IoT Core Device 面板显示了最新接收的遥测数据的日期。GCP 不提供对数据的 即时访问。用户必须依赖其他 GCP 服务或使用 CLOUD SDK 工具套件将数据可视化。

4. 云到设备的连接

可以在 GCP 控制台上使用“更新配置”菜单进行此类交互，将以简单 JSON 格式编码的命令发送至设备（请参 考图 15. IoT core 设备配置）。如果设备没有连接，将在下一次连接时接收配置。

谷歌云实现和维护（GoogleCloudPlatform）(17)

▲ 图 15. IoT core 设备配置

注意：X-CUBE-GCP 在每次连接时对配置进行注册，GCP IoT Core 服务总是在每次重新注册时发送最新配置。因此，如果在配置中发送了重启命令"Reboot": true，用户必须将配置重新更新为"Reboot": false，以免在每次重新连接时发生无限重启。

5.7 仪表板和绘图值

GCP 中没有默认的仪表板用于数据可视化。用户需通过额外的 GCP 服务创建网络应用。或者，可以安装 Google Cloud™的 GCLOUD SDK，并使用工具套件订阅 Pub/Sub 主题。

请参考 GCLOUD SDK 文档和 gcloud pubsub 命令，如：$ gcloud pubsub subscriptions pull

6、与板交互

需要串行终端来：

本文档中使用 Tera Term 进行说明。也可以使用其他类似的工具。

在首次使用板时，必须使用连接字符串数据进行编程：

在开发包实用程序目录中提供了一个 Tera Term 初始化脚本（参考图 4. 项目文件结构）；此脚本设置了正确的参数。要使用它，请打开 Tera Term，选择 Setup，然后选择 Restore 设置。

提示 下面提供的信息可用来配置 UART 终端，使其成为 Tera Term 初始化脚本的替代选择。

终端设置

终端设置如图 16 所示。下面的截屏显示了终端设置和新行的推荐参数。串行终端新行传输配置必须设置为 LineFeed（\n 或 LF），以便允许从 UNIX®类型的文本文件复制粘贴。选择本地 回显选项将使复制粘贴结果显示在控制台上。

谷歌云实现和维护（GoogleCloudPlatform）(18)

▲ 图 16. 终端设置

串口设置

串口必须配置：

串口设置如图 17 中所示。

谷歌云实现和维护（GoogleCloudPlatform）(19)

▲ 图 17. 串口设置

UART 终端和串口设置完毕后，按下板复位按钮（黑色）。按照 UART 终端上的指示上传 Wi-Fi®和云配置数据。这 些数据保留在 Flash 存储器中，并在下次板启动时重复使用。

7、常见问题

问：当我用 IAR™打开项目时，为什么会弹出此提示框？

谷歌云实现和维护（GoogleCloudPlatform）(20)

▲ 图 18. 当 IAR™ IDE 版本与 X-CUBE-GCP 所用的版本不兼容时会弹出此提示框

答：很可能是由于此 IAR™ IDE 版本比开发包所用版本更早（请参阅软件包根文件夹中提供的版本说明，以了解支 持的 IDE 版本），因此不能保证兼容性。这种情况下，需要更新 IAR™ IDE 版本。

问：应该如何修改应用程序来发布其他消息？

答：根据是使用 B-L475E-IOT01A 还是其他板，googleiot.c 文件中需要分别更新函数 GoogleIoT_publishTelemetry ()或 GoogleIoT_publishDeviceState ()。

问：我的设备不能连接到 GCP。我该如何处理？

答：需要检查的事项是：

1、确认连接字符串中的 project-id、registry-id 和 device-id 均正确拼写并提交。GCP 通常创建唯一指定的 project-id，它包含自动生成的名称和/或编号，例如。因此，务必使用注册 控制台上显示的 project-id。 2、如果不成功，则必须再次仔细进行初始配置。

3、如果仍然没有连接，请在 GCP 控制台上检查并确认为设备定义的设备公钥是使用设备上保存的对应的正确私钥设置的。

问：我的设备不能连接到 Wi-Fi®接入点。我该如何处理？

答：请确认其他设备是否可以连接到 Wi-Fi®接入点。如果可以，请在板重置后，按下用户按钮（蓝色）五秒钟，输 入 Wi-Fi®凭证。

问：在 B-L475E-IOT01A 板上，接近传感器总是报告“8190”，即使我将障碍物靠近其放置也是如此。

答：厂家交付的接近传感器贴有临时保护膜。在使用传感器前，确保已将膜去掉。保护膜为橙色，几乎不可见。在 B-L475E-IOT01A 上，接近传感器位于板前侧焊接了 MCU 的左下角附近。

,