Amazon FreeRTOS
User Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

AWS IoT Greengrass Discovery Demo Application

Before you run the AWS IoT Greengrass Discovery demo for Amazon FreeRTOS, you need to set up AWS, AWS IoT Greengrass, and AWS IoT. To set up AWS, follow the instructions at Setting Up Your AWS Account and Permissions. To set up AWS IoT Greengrass, you need to create a Greengrass group and then add a Greengrass core. For more information about setting up AWS IoT Greengrass, see Getting Started with AWS IoT Greengrass.

After you set up AWS and AWS IoT Greengrass, you need to configure some additional permissions for AWS IoT Greengrass.

To set up AWS IoT Greengrass permissions

  1. Browse to the IAM console.

  2. From the navigation pane, choose Roles, and then find and choose Greengrass_ServiceRole.

  3. Choose Attach policies, select AmazonS3FullAccess and AWSIoTFullAccess, and then choose Attach policy.

  4. Browse to the AWS IoT console.

  5. In the navigation pane, choose Greengrass, choose Groups, and then choose the Greengrass group that you previously created.

  6. Choose Settings, and then choose Add role.

  7. Choose Greengrass_ServiceRole, and then choose Save.

You can use the Quick Connect workflow in the Amazon FreeRTOS console to quickly connect your board to the AWS IoT and run the demo. Amazon FreeRTOS configurations are currently not available for the following boards:

  • Cypress CYW943907AEVAL1F Development Kit

  • Cypress CYW954907AEVAL1F Development Kit

  • Espressif ESP-WROVER-KIT

  • Espressif ESP32-DevKitC

  • Nordic nRF52840-DK

You can also connect your board to AWS IoT and configure your Amazon FreeRTOS demo manually.

  1. Registering Your MCU Board with AWS IoT

    After you register your board, you need to create and attach a new Greengrass policy to the device's certificate.

    To create a new AWS IoT Greengrass policy

    1. Browse to the AWS IoT console.

    2. In the navigation pane, choose Secure, choose Policies, and then choose Create.

    3. Enter a name to identify your policy.

    4. In the Add statements section, choose Advanced mode. Copy and paste the following JSON into the policy editor window:

      { "Effect": "Allow", "Action": [ "greengrass:*" ], "Resource": "*" }

      This policy grants AWS IoT Greengrass permissions to all resources.

    5. Choose Create.

    To attach the AWS IoT Greengrass policy to your device's certificate

    1. Browse to the AWS IoT console.

    2. In the navigation pane, choose Manage, choose Things, and then choose the thing that you previously created.

    3. Choose Security, and then choose the certificate attached to your device.

    4. Choose Policies, choose Actions, and then choose Attach Policy.

    5. Find and choose the Greengrass policy that you created earlier, and then choose Attach.

  2. Downloading Amazon FreeRTOS


    If you are downloading Amazon FreeRTOS from the Amazon FreeRTOS console, choose Connect to AWS IoT Greengrass- Platform instead of Connect to AWS IoT- Platform.

  3. Configuring the Amazon FreeRTOS Demos.

    Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_demos/config_files/aws_demo_config.h, comment out #define CONFIG_MQTT_DEMO_ENABLED, and define CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED.

After you set up AWS IoT and AWS IoT Greengrass, and after you download and configure Amazon FreeRTOS, you can build, flash, and run the Greengrass demo on your device. To set up your board's hardware and software development environment, follow the instructions in the Board-specific Getting Started Guides.

The Greengrass demo publishes a series of messages to the Greengrass core, and to the AWS IoT MQTT client. To view the messages in the AWS IoT MQTT client, open the AWS IoT console, choose Test, and then add a subscription to freertos/demos/ggd.

In the MQTT client, you should see the following strings:

Message from Thing to Greengrass Core: Hello world msg #1! Message from Thing to Greengrass Core: Hello world msg #0! Message from Thing to Greengrass Core: Address of Greengrass Core found! <123456789012>.<us-west-2>