# Amazon IoT Greengrass V1 discovery demo application
<a name="gg-demov1"></a>

**Important**  <a name="deprecation-message-demo"></a>
This demo is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you [start here](freertos-getting-started-modular.md) 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](github-repo-migration.md).

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](freertos-prereqs.md#freertos-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](https://docs.amazonaws.cn/greengrass/latest/developerguide/gg-gs.html). 

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](https://console.amazonaws.cn/iam/home).

1. From the navigation pane, choose **Roles**, and then find and choose **Greengrass\$1ServiceRole**.

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

1. Browse to the [Amazon IoT console](https://console.amazonaws.cn/iotv2/).

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

1. Choose **Settings**, and then choose **Add role**.

1. Choose **Greengrass\$1ServiceRole**, and then choose **Save**.

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

1. [Registering your MCU board with Amazon IoT](freertos-prereqs.md#get-started-freertos-thing)

   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](https://console.amazonaws.cn/iotv2/).

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

   1. Enter a name to identify your policy.

   1. 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.

   1. Choose **Create**.

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

   1. Browse to the [Amazon IoT console](https://console.amazonaws.cn/iotv2/).

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

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

   1. Choose **Policies**, choose **Actions**, and then choose **Attach Policy**.

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

1. [Downloading FreeRTOS](freertos-prereqs.md#freertos-download)
**Note**  
If you are downloading FreeRTOS from the FreeRTOS console, choose **Connect to Amazon IoT Greengrass- *Platform*** instead of **Connect to Amazon IoT- *Platform***.

1. [Configuring the FreeRTOS demos](freertos-prereqs.md#freertos-configure).

   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](getting-started-guides.md).

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](https://console.amazonaws.cn/iotv2/), 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
<a name="gg-demo-ec2"></a>

**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.

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

1. Choose the **Inbound rules** tab then choose **Edit inbound rules** and add the following rules.  
**Inbound rules**    
[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/freertos/latest/userguide/gg-demov1.html)

1. 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**.

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

1. 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.

1. 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**.

   1. Choose **Select an IoT Thing**. Choose your device then choose **Finish**.

1. Add the necessary subscriptions— in the **Greengrass Group** page, choose **Subscriptions** then choose **Add Subscription** and enter information as shown here.  
**Subscriptions**    
[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/freertos/latest/userguide/gg-demov1.html)

   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.

1. 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.