Amazon IoT Greengrass Discovery library - FreeRTOS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Discovery library


The content on this page may not be up-to-date. Please refer to the library page for the latest update.


The Amazon IoT Greengrass Discovery library is used by your microcontroller devices to discover a Greengrass core on your network. Using the Amazon IoT Greengrass Discovery APIs, your device can send messages to a Greengrass core after it finds the core's endpoint.

Dependencies and requirements

To use the Greengrass Discovery library, you must create a thing in Amazon IoT, including a certificate and policy. For more information, see Amazon IoT Getting Started.

You must set values for the following constants in the freertos/demos/include/aws_clientcredential.h file:


Your Amazon IoT endpoint.


The name of your IoT thing.


The SSID for your Wi-Fi network.


Your Wi-Fi password.


The type of security used by your Wi-Fi network.

You must also set values for the following constants in the freertos/demos/include/aws_clientcredential_keys.h file:


The certificate PEM associated with your thing.


The private key PEM associated with your thing.

You must have a Greengrass group and core device set up in the console. For more information, see Getting Started with Amazon IoT Greengrass.

Although the coreMQTT library is not required for Greengrass connectivity, we strongly recommend you install it. The library can be used to communicate with the Greengrass core after it has been discovered.

API reference

For a full API reference, see Greengrass API Reference.

Example usage

Greengrass workflow

The MCU device initiates the discovery process by requesting from Amazon IoT a JSON file that contains the Greengrass core connectivity parameters. There are two methods for retrieving the Greengrass core connectivity parameters from the JSON file:

  • Automatic selection iterates through all of the Greengrass cores listed in the JSON file and connects to the first one available.

  • Manual selection uses the information in aws_ggd_config.h to connect to the specified Greengrass core.

How to use the Greengrass API

All default configuration options for the Greengrass API are defined in aws_ggd_config_defaults.h.

If only one Greengrass core is present, call GGD_GetGGCIPandCertificate to request the JSON file with Greengrass core connectivity information. When GGD_GetGGCIPandCertificate is returned, the pcBuffer parameter contains the text of the JSON file. The pxHostAddressData parameter contains the IP address and port of the Greengrass core to which you can connect.

For more customization options, like dynamically allocating certificates, you must call the following APIs:


Makes an HTTP GET request to Amazon IoT to initiate the discovery request to discover a Greengrass core. GD_SecureConnect_Send is used to send the request to Amazon IoT.


Gets the size of the JSON file from the HTTP response.


Gets the JSON object string. GGD_JSONRequestGetSize and GGD_JSONRequestGetFile use GGD_SecureConnect_Read to get the JSON data from the socket. GGD_JSONRequestStart, GGD_SecureConnect_Send, GGD_JSONRequestGetSize must be called to receive the JSON data from Amazon IoT.


Extracts the IP address and the Greengrass core certificate from the JSON data. You can turn on automatic selection by setting the xAutoSelectFlag to True. Automatic selection finds the first core device your FreeRTOS device can connect to. To connect to a Greengrass core, call the GGD_SecureConnect_Connect function, passing in the IP address, port, and certificate of the core device. To use manual selection, set the following fields of the HostParameters_t parameter:


The ID of the Greengrass group to which the core belongs. You can use the aws greengrass list-groups CLI command to find the ID of your Greengrass groups.


The ARN of the Greengrass core to which you are connecting.