本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS IoT Greengrass 探索程式庫
<a name="freertos-lib-gg-connectivity"></a>

**注意**  <a name="out-of-date-message"></a>
此頁面上的內容可能不是up-to-date。如需最新更新，請參閱 [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 探索程式庫，您必須在 中建立物件 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 裝置會透過向包含 Greengrass 核心連線參數的 AWS IoT 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`**  
向 發出 HTTP GET 請求 AWS IoT ，以啟動探索請求，以探索 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。