Amazon IoT Greengrass V1 discovery demo application - FreeRTOS
Amazon EC2
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 V1 discovery demo application

Important

This demo is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

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

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

To set up Amazon 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 Amazon 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.

Connect your board to Amazon IoT and configure your FreeRTOS demo.

  1. Registering your MCU board with Amazon 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 Amazon IoT Greengrass policy

    1. Browse to the Amazon 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 Amazon IoT Greengrass permissions to all resources.

    5. Choose Create.

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

    1. Browse to the Amazon 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 FreeRTOS

    Note

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

  3. Configuring the FreeRTOS demos.

    Open freertos/vendors/vendor/boards/board/aws_demos/config_files/aws_demo_config.h, comment out #define CONFIG_CORE_MQTT_MUTUAL_AUTH_DEMO_ENABLED, and define CONFIG_GREENGRASS_DISCOVERY_DEMO_ENABLED.

After you set up Amazon IoT and Amazon IoT Greengrass, and after you download and configure 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 Amazon IoT MQTT client. To view the messages in the Amazon IoT MQTT client, open the Amazon IoT console, choose Test, choose MQTT test client 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.compute.amazonaws.com

Using an Amazon EC2 instance

If you are working with an Amazon EC2 instance

  1. Find the Public DNS (IPv4) associated with your Amazon EC2 instance— go to the Amazon EC2 console, and in the left navigation panel, choose Instances. Choose your Amazon EC2 instance, and then choose the Description panel. Look for the entry for the Public DNS (IPv4) and make a note of it.

  2. Find the entry for Security groups and choose the security group attached to your Amazon EC2 instance.

  3. Choose the Inbound rules tab then choose Edit inbound rules and add the following rules.

    Inbound rules
    Type Protocol Port range Source Description - optional
    HTTP TCP 80 0.0.0.0/0 -
    HTTP TCP 80 ::/0 -
    SSH TCP 22 0.0.0.0/0 -
    Custom TCP TCP 8883 0.0.0.0/0 MQTT communications
    Custom TCP TCP 8883 ::/0 MQTT communications
    HTTPS TCP 443 0.0.0.0/0 -
    HTTPS TCP 443 ::0/0 -
    All ICMP - IPv4 ICMP All 0.0.0.0/0 -
    All ICMP - IPv4 ICMP All ::0/0 -

  4. In the Amazon IoT console choose Greengrass, then Groups, and choose the Greengrass group that you previously created. Choose Settings. Change the Local connection detection to Manually manage connection information.

  5. In the navigation pane, choose Cores then select your group core.

  6. Choose Connectivity and make sure you have only one core endpoint (delete all of the rest) and that it is not an IP address (because it is subject to change). The best option is to use the Public DNS (IPv4) that you noted in the first step.

  7. Add the FreeRTOS IoT thing you created to the GG group.

    1. Choose the back arrow to return to the Amazon IoT Greengrass group page. In the navigation pane, choose Devices then choose Add Device.

    2. Choose Select an IoT Thing. Choose your device then choose Finish.

  8. Add the necessary subscriptions— in the Greengrass Group page, choose Subscriptions then choose Add Subscription and enter information as shown here.

    Subscriptions
    Source Target Topic
    TIGG1 IoT Cloud freertos/demos/ggd

    Where "Source" is the name given to the Amazon IoT thing created in the Amazon IoT console when you registered your board - "TIGG1" in the example given here.

  9. Start a deployment of your Amazon IoT Greengrass group and make sure that the deployment is successful. You should now be able to successfully run the Amazon IoT Greengrass discovery demo.