引言

本用户手册描述STM32Cube™扩展包的内容，该扩展包用于GoogleCloudPlatform™（GCP）GoogleCloudIoTCore的服务。用于GCP的STM32Cube扩展包（X-CUBE-GCP）提供了将STMicroelectronics板卡连接到GoogleCloudPlatform™的GoogleCloudIoTCore的应用示例。它将MQTT客户端库移植到相应的STM32器件上去实现与云平台的连接。

X-CUBE-GCP可在五个平台上运行：

通过InventekISM43362模块支持Wi-Fi®连接的B-L475E-IOT01A和32F413HDISCOVERY板

提供原生以太网接口的32F769IDISCOVERY板

P-L496G-CELL01和P-L496G-CELL02探索包分别通过2G/3G（UG96）和LTE（BG96）Quectel蜂窝调制解调器子板支持蜂窝连接

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

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

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

1、概述

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

▲表1.缩略语列表

2、GoogleCloudPlatform™

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

▲图1.GoogleCloudIoTCore生态系统

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

图2.GoogleCloudIoTCore图

注意©2018GoogleLLC，经许可使用。Google和Google徽标是GoogleLLC.的注册商标X-CUBE-GCP实现必要的服务，将设备连接到图2中用蓝色框出的生态系统部分。

特别是，该扩展包演示了如何配置GCP的IoTCore服务，以便将设备安全地连接到GoogleCloudIoTCore服务。设备使用私钥（ECDSA或RSA）签署连接云平台时需要的JWT（JSON网络令牌）。CloudIoTCore通过在设备创建过程中上传到云服务的相应公钥验证设备的JWT。X-CUBE-GCP还提供了示例，展示了如何使用数据格式和使用MQTT协议在设备与IoTCore元件之间交换数据，将遥测数据发送到云端，以及从云端接收配置数据。发送到CloudIoTCore的数据随后可通过Pub/Sub（发布/订阅）服务发布，并能在日后需要使用时通过网络应用进行访问。用于数据分析和使用的网络应用的开发不在XCUBE-GCP的范围之内。

3、软件包说明

本章详述了X-CUBE-GCP扩展包的内容和使用。

3.1概述

X-CUBE-GCP扩展包由多系列的基于STM32L4系列，STM32F4系列和STM32F7系列微控制器的库和应用示例组成。

X-CUBE-GCP可在五个平台上运行：

通过InventekISM43362模块支持Wi-Fi®连接的B-L475E-IOT01A和32F413HDISCOVERY板

提供原生以太网接口的32F769IDISCOVERY板

P-L496G-CELL01和P-L496G-CELL02包分别通过Quectel的2G/3GUG96和LTEBG96蜂窝调制解调器子板支持蜂窝连接。用于连接2G/3G蜂窝网络与云端的P-L496G-CELL01STM32探索包（STM32-C2C/2G-3G）和用于连接LTE蜂窝网络与云端的P-L496G-CELL02STM32探索包（STM32-C2C/2G-LTE）是基于蜂窝网络和云技术的解决方案的完整开发平台。探索包内含一个基于STM32L496AGI6的带预加载固件的低功耗探索主板和一个带天线的STMod+蜂窝网络扩展板。

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

Eclipse™PahoMQTT嵌入式C客户端

mbedTLS

用于B-L475E-IOT01A和32F413HDISCOVERY板的InventekISM43362Wi-Fi®驱动程序

用于32F769IDISCOVERY板的以太网驱动程序、FreeRTOS™和LwIP

用于B-L475E-IOT01A板的传感器驱动•用于P-L496G-CELL01和P-L496G-CELL02套件的蜂窝网络驱动程序

用于所有MCU板的BSP

STM32L4系列、STM32F4系列，和STM32F7系列HAL

应用程序示例

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

IAREmbeddedWorkbench®对于Arm®（EWARM）

Keil®微控制器开发套件（MDK-ARM）

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

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

3.2架构

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

完全兼容STM32Cube™架构

为了能够开发应用程序来访问和使用GoogleCloudPlatform™的GoogleCloudIoTCore，扩展了STM32Cube™

基于STM32微控制器的硬件抽象层STM32CubeHAL

应用软件访问和使用GoogleCloudPlatform™的GoogleCloudIoTCore所用的软件组件如下：

STM32CubeHALHAL驱动层提供通用的多实例简单API组（应用程序编程接口），以便与上层（应用、库和协议栈）交互。它由通用和扩展API构成。它直接围绕通用架构构建，允许在其基础上的软件层，例如中间件层，实现了它的功能又无需依赖给定MCU的特定硬件配置。此结构可提高库代码的可复用性，并确保可向其他设备轻松移植。

板级支持包（BSP）除MCU之外，板软件包需支持STM32板上的外设。板支持包中包含此软件。这是一个有限的API集，为板特有的某些外设（例如LED和用户按钮等）提供编程接口。

mbedTLSMQTT中间件使用由mbedTLS库实现的TLS连接。

MQTT客户端中间件它由Eclipse™PahoMQTT嵌入式C客户端库（被MQTT应用用作传输层）和JSON解析器构成。

TCP/IPTCP/IP连接可由Wi-Fi®模块（当使用Wi-Fi®连接时）、LwIPTCP-IP栈（当使用以太网连接时）或通过蜂窝连接（当使用蜂窝网络扩展板时）来处理。

FreeRTOS™它是一个实时操作系统，使用LwIP为用户提供基于套接字的接口时，需要用到。

GoogleCloud™IoT示例应用程序一个应用示例，实现了连接GCPGoogleCloudIoTCore组件所需的设备服务。这包括连接管理、JWT安全连接处理和与云端交互的合适消息格式。

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

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

3.3文件夹结构

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

▲图4.项目文件结构

3.4B-L475E-IOT01A板传感器

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

用于相对湿度和温度测量的电容式数字传感器（HTS221）

高性能3轴磁力计（LIS3MDL）

3D加速度计和3D陀螺仪（LSM6DSL）

260-1260hPa绝对数字输出气压计（LPS22HB）

接近传感器（VL53L0X）

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

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

3.5Wi-Fi®元件

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

3.6复位按钮

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

3.7用户按钮

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

要配置Wi-Fi®和GoogleCloud™安全证书，从板启动时开始直到启动后五秒，都可以完成此操作。

板子初始化后，如果用户按下按钮的时间很短，则应用程序仅发布B-L475E-IOT01A板子的传感器值、0/1切换值（绿色LED将相应切换）以及时间戳。双击按钮后，应用程序进入循环并每秒自动发布一次。再一次双击将恢复先前的模式。应用程序通过板级支持包功能来配置和管理用户按钮。BSP功能位于Drivers\BSP\目录中。使用BSP按钮功能时（采用BUTTON_USER值），对于给定的平台，应用不会从硬件角度考虑此按钮连接的方式；该映射由BSP处理。

3.8用户LED

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

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

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

3.9实时时钟

STM32器件的RTC在启动时从网络服务器进行更新。用户可以使用HAL_RTC_GetTime()函数得到时间值。例如，此函数可以用于时间戳消息。

3.10mbedTLS配置

利用define指令覆盖配置文件名。X-CUBE-GCP包使用文件googleiot_mbedtls_来实现项目配置。这可以通过在和文件开头设置以下if!defined(MBEDTLS_CONFIG_FILE)elseif

配置文件指定了要使用的相关加密参数。

4、硬件和软件环境设置

为了设置硬件和软件环境，必须利用USB线将支持的板连接到个人计算机。连接到PC后，允许用户：

烧写板

存储Wi-Fi®和GoogleCloud™安全证书

通过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进行编程以及运行虚拟控制台。

一台计算机，用于运行连接GoogleCloud™控制台的网络浏览器或管理GoogleCloudPlatform™的GCLOUDSDK命令行工具。计算机防火墙（如果有）必须允许MQTT连接进入（通常是端口1883和8883）。例如，它可以是开发PC、虚拟专用服务器或单板计算机。

OpenSSL工具套件，用于构建新的设备公钥/私钥对。

5、应用程序示例

本章介绍如何注册和登录GoogleCloudPlatform™的GoogleCloudIoTCore，以及如何使用X-CUBE-GCP扩展包中的GCPIoTCore应用。此外，还展示了如何从GoogleCloud™控制台配置GCP，但也可以使用GoogleCloud™SDK中的命令行工具应用相同配置。请参考GoogleCloud™SDK文档了解关于命令行工具的更多详细信息。

5.1应用描述

应用提供下列服务：

连接管理应用首先配置板连接（Wi-Fi®、以太网或蜂窝网络），并确保连接正常且正常工作，以便提供有效的IP地址和IP连接。

通过JWT提供安全连接一旦有IP连接可用，应用将通过JSON网络令牌（JWT）创建安全地连接到GCPIoTCore服务。GCPIoTcore支持多种密钥格式。该应用支持两种密钥格式：ES256和RS256。

发送/获取设备状态一旦安全连接，应用将向GCPIoTCore发送更新后的设备状态。这将允许从GCP控制台获取设备信息。设备状态是设备的内部表达。
在X-CUBE-GCP应用中，设备状态是一个简单的JSON字符串，包含板LED状态、遥测间隔、本地时间戳、MAC地址和当前固件版本。下面是发布的设备状态示例：

{"LedOn":false,"TelemetryInterval":60,"ts":1530170497,"mac":"C47F5104341","FWversion":""}

配置设备

GCP提供修改设备配置的功能。根据GCP文档中的定义，设备配置是一种任意的用户定义的数据BLOB。XCUBE-GCP应用使用配置从云端控制LED状态，更改遥测间隔并强制重启。应用接受简单JSON格式的配置，如下所示：

{"LedOn":true,"TelemetryInterval":60,"Reboot":false}

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

通过MQTTBridge发送遥测数据

应用只支持GCPIoTCore的MQTTBridge服务。

它不支持HTTPBridge。一旦用户按一次用户按钮，应用就发送遥测数据。如果用户按两次用户按钮，设备将进入发布循环，并定期发送遥测数据。在最初的设备配置步骤中使用参数TelemetryInterval配置此循环的周期。

如GCP在线文档中所述，设备可以通过发出PUBLISH消息（通过MQTT连接）来发布遥测事件。应用示例中使用的QualityofService是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.2GCP和IoTCore帐户设置

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

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

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

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

▲图7.需要计费

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

▲图8.使能API菜单

3.使用“使能API和服务”并至少使能GoogleCloudIoTAPI和CloudPub/SubAPI，如图9.使能GoogleCloudIoTAPI和图10.使能CloudPub/SubAPI所示。

▲图9.使能GoogleCloudIoTAPI

▲图10.使能CloudPub/SubAPI

5.3在GCPIoTcore上创建设备

关于GoogleCloudIoTCore的完整文档和如何创建注册表、设备和遥测主题，请访问/iot/docs。

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

1.在GoogleCloudIoTCore中，创建新设备注册表（在连接字符串中定义为{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

opensslgenrsa-outrsa___

对于ES256

opensslecparam-genkey-nameprime256v1-noout-outec___

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

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

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

5.4应用程序编译和烧写

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

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

5.5应用程序首次启动

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

8位数据长度，无校验，1位停止位，115200波特率，无硬件流控制

行结束符设置为LF

“echoon”选项，以便能够读取用户输入的参数

此外，建议使能“自动模式”选项（如果有）

有关详细信息，请参见第6节与板交互。

对于支持Wi-Fi®的板，通过控制台输入Wi-Fi®SSID、加密模式和密码。对于蜂窝网络连接，输入选中操作员提供的接入点和密码。

2.系统提示用户输入连接字符串，其中包含与使用GCP用户帐户创建的项目和注册设备相关的必要信息。输入设备的GoogleCloudIoTCore连接字符串：（模板：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_的内容。该设备使用它通过TLS对远程主机进行身份验证。

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

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

b.用于GCP，以便验证云服务器。根据服务器，可能需要按照GoogleCloud™的支持CA列表更新comodo_（可在/中找到）。

4.设置设备私钥

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

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

5.6应用程序运行时

1.RTC配置

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

2.设备到云的连接

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

▲图14.IoTcore设备控制台

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

检查最新的错误状态。当设备拔出和与云端的连接中断时，一种典型的错误是“mqtt：服务器：MQTT保持连接检查失败导致连接断开”。

在相应菜单中检查配置和状态历史。系统提供最新发布的设备状态和配置供用户参考。

3.发布的遥测数据

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

短暂按下用户按钮一次后

按用户定义的固定遥测间隔（按下用户按钮两次）。遥测间隔可通过设备配置进行修改。

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

4.云到设备的连接

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

▲图15.IoTcore设备配置

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

5.7仪表板和绘图值

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

请参考GCLOUDSDK文档和gcloudpubsub命令，如：$gcloudpubsubsubscriptionspull

6、与板交互

需要串行终端来：

对板子进行配置

监测应用状态

在本地显示云到设备消息

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

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

确定PC上所用的用于探索板的STM32ST-LINK虚拟COM端口。在一台Windows®PC上，打开设备管理器。

打开PC上的串行终端并将其连接到上述虚拟COM端口。

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

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

终端设置

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

▲图16.终端设置

串口设置

串口必须配置：

实际的COM端口号

115200波特率

8位数据

无校验位

1个停止位

无流控

串口设置如图17中所示。

▲图17.串口设置

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

7、常见问题

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

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

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

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

答：根据是使用B-L475E-IOT01A还是其他板，文件中需要分别更新函数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的左下角附近。