本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS IoT Greengrass Discovery 库
<a name="freertos-lib-gg-connectivity"></a>

**注意**  <a name="out-of-date-message"></a>
此页面上的内容可能不是最新的。有关最新更新，请参阅 [FreeRTOS.org 库页面](https://www.freertos.org/Documentation/03-Libraries/01-Library-overview/01-All-libraries)。

## 概览
<a name="freertos-gg-overview"></a>

微控制设备使用 [AWS IoT Greengrass Discovery](https://docs.aws.amazon.com/freertos/latest/lib-ref/html1/aws__greengrass__discovery_8h.html) 库来发现网络上的 Greengrass 核心。通过使用 AWS IoT Greengrass Discovery API，设备可以在找到核心的终端节点之后将消息发送到 Greengrass 核心。

## 依赖项和要求
<a name="freertos-gg-dependencies"></a>

要使用 Greengrass Discovery 库，您必须在 AWS IoT 中创建事物，包括证书和策略。有关更多信息，请参阅 [AWS IoT 入门](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)。

您必须为 `freertos/demos/include/aws_clientcredential.h` 文件中的以下常量设置值：

**`clientcredentialMQTT_BROKER_ENDPOINT`**  
您的 AWS IoT 终端节点。

**`clientcredentialIOT_THING_NAME`**  
IoT 事物的名称。

**`clientcredentialWIFI_SSID`**  
Wi-Fi 网络的 SSID。

**`clientcredentialWIFI_PASSWORD`**  
Wi-Fi 密码。

**`clientcredentialWIFI_SECURITY`**  
Wi-Fi 网络所使用的安全类型。

您还必须为 `freertos/demos/include/aws_clientcredential_keys.h` 文件中的以下常量设置值：

**`keyCLIENT_CERTIFICATE_PEM`**  
与事物关联的证书 PEM。

**`keyCLIENT_PRIVATE_KEY_PEM`**  
与事物关联的私有密钥 PEM。

必须在控制台中设置 Greengrass 组和核心设备。有关更多信息，请参见 [AWS IoT Greengrass 入门](https://docs.aws.amazon.com/greengrass/latest/developerguide/)。

尽管 Greengrass 连接不需要 coreMQTT 库，我们仍强烈建议您安装。该库可用于在发现 Greengrass 核心后与其进行通信。

## API 参考
<a name="freertos-gg-api"></a>

有关完整 API 参考，请参阅 [Greengrass API 参考](https://docs.aws.amazon.com/freertos/latest/lib-ref/html1/aws__greengrass__discovery_8h.html)。

## 示例用法
<a name="freertos-gg-example"></a>

### Greengrass 工作流
<a name="freertos-lib-gg-workflow"></a>

MCU 设备向 AWS IoT 请求包含 Greengrass 核心连接参数 的 JSON 文件，以启动发现过程。可通过以下两种方法在 JSON 文件中检索 Greengrass 核心连接参数：
+ 自动选择，循环访问 JSON 文件中列出的所有 Greengrass 核心，并连接到第一个可用核心。
+ 手动选择，使用 `aws_ggd_config.h` 中的信息连接到指定的 Greengrass 核心。

### 如何使用 Greengrass API
<a name="freertos-lib-gg-api"></a>

Greengrass API 的所有默认配置选项在 `aws_ggd_config_defaults.h` 中定义。

如果只存在一个 Greengrass 核心，可调用 `GGD_GetGGCIPandCertificate` 请求包含 Greengrass 核心连接信息的 JSON 文件。`GGD_GetGGCIPandCertificate` 返回后，`pcBuffer` 参数中包含了 JSON 文件的文本。`pxHostAddressData` 参数中包含了您可以连接的 Greengrass 核心的 IP 地址和端口。

对于更多自定义选项，如动态分配证书，必须调用以下 API：

**`GGD_JSONRequestStart`**  
向 AWS IoT 发出 HTTP GET 请求，以启动发现请求来查找 Greengrass 核心。`GD_SecureConnect_Send` 用于将请求发送给 AWS IoT。

**`GGD_JSONRequestGetSize`**  
从 HTTP 响应获取 JSON 文件的大小。

**`GGD_JSONRequestGetFile`**  
获取 JSON 对象字符串。`GGD_JSONRequestGetSize` 和 `GGD_JSONRequestGetFile` 使用 `GGD_SecureConnect_Read` 从套接字获取 JSON 数据。必须调用 `GGD_JSONRequestStart`、 `GGD_SecureConnect_Send`、`GGD_JSONRequestGetSize`，从 AWS IoT 接收 JSON 数据。

**`GGD_GetIPandCertificateFromJSON`**  
从 JSON 数据中提取 IP 地址和 Greengrass 核心证书。可以通过将 `xAutoSelectFlag` 设置为 `True`，打开自动选择功能。自动选择将找到 FreeRTOS 设备可以连接的第一个核心设备。要连接到 Greengrass 核心，可调用 `GGD_SecureConnect_Connect` 函数，传递核心设备的 IP 地址、端口和证书。要使用手动选择，可设置 `HostParameters_t` 参数的以下字段：    
**`pcGroupName`**  
核心所属 Greengrass 组的 ID。可以使用 `aws greengrass list-groups` CLI 命令来查找 Greengrass 组的 ID。  
**`pcCoreAddress`**  
要连接的 Greengrass 核心的 ARN。