Menu
AWS Greengrass
Developer Guide

Setting Up an AWS Greengrass Core Device

Download the AWS Greengrass Core Software

Download the AWS Greengrass distributable for your AWS Greengrass core hardware from AWS Greengrass distributables. Choose Software from the navigation page.

Note

This link will take you to the AWS IoT console. This is the correct place to download the AWS Greengrass core software.

Use the following command to extract the tar file:

Copy
sudo tar -zxvf greengrass-platform-version.tar.gz -C /

Where platform is either:

  • linux-armv7l

  • linux-x86-64

  • linux-aarch64

The compressed tar file contains the following:

GGC v1.0.0GGC v1.1.0
GGC v1.0.0
bin

A directory containing the AWS Greengrass core software binaries.

configuration

A directory containing configuration files, including certificates, config.json, and group.json.

lambda

A directory containing Lambda function code.

license

A directory containing license files.

rootfs

A directory of the root file system for AWS Greengrass core.

runtime

A directory containing the Lambda runtime.

greengrassd

The Greengrass start script.

release_notes.html

Greengrass release notes.

version

The AWS Greengrass core software.

GGC v1.1.0
ggc/core/bin

A directory containing the AWS Greengrass core software binaries.

config

A directory containing configuration files, including certificates, config.json, and group.json.

ggc/deployment/lambda

A directory containing your Lambda function code.

ggc/core/LICENSE

A directory containing license files.

ggc/core/rootfs

A directory of the root file system for AWS Greengrass core.

ggc/core/runtime

A directory containing the Lambda runtime.

ggc/core/greengrassd

The Greengrass start script.

ggc/core/release_notes.html

Greengrass release notes.

ggc/packages/version

The AWS Greengrass core software, pointed to by the symbolic link ggc/core

Create an AWS Greengrass Group

A Greengrass group is a resource that describes your local environment. AWS Greengrass groups contain a AWS Greengrass core device with which all other devices in the group communicate, a list of devices that belong to the group, a list of Lambda functions, and a subscription table that defines how messages are passed between devices, the AWS Greengrass core, and Lambda functions.

To create a Greengrass group, open the AWS IoT console and, in the navigation pane, choose Greengrass. On the Define a Greengrass group tile, choose Get Started. On the Set up your Greengrass Group page, choose Use easy creation, and then follow the instructions. This will walk you through the creation of:

  • A Greengrass group.

  • An AWS IoT thing that represents an AWS Greengrass core in your AWS Greengrass group.

  • A certificate and key pair that your AWS Greengrass core will use to authenticate with AWS IoT and AWS Greengrass.

Create an AWS Greengrass Core Device in the Cloud

Using the AWS IoT console, create an AWS IoT thing, certificate, and policy for your AWS Greengrass core device.

  1. Sign in to the AWS IoT console using your AWS credentials.

  2. Create a AWS IoT thing for your AWS Greengrass core. For more information, see Create a Thing.

  3. Create an AWS IoT certificate and private key for your AWS Greengrass core. For more information, see Create a Device Certificate. The certificate and private key are used by AWS Greengrass cores to establish a connection to cloud-based AWS IoT services. This certificate enables the AWS Greengrass core to:

    • Receive and publish messages to and from the cloud.

    • Get information about deployments.

    Download the certificate and private key and save them in a safe place. You will copy them to your AWS Greengrass core device later.

  4. Attach your device certificate to your AWS IoT thing. For more information, see Attach a Certificate to a Thing.

  5. Make sure your certificate is activated.

  6. Create and attach an AWS IoT policy to your device certificate. The policy determines which AWS IoT resources your AWS Greengrass core is able to access. In the AWS IoT console, choose Security, and then choose Policies. Choose Create to create an AWS IoT policy.

    On the Create a Policy page, type a name for your policy. Under Add statements, in the Action text box, type iot:*, greengrass:*. In the Resource ARN text box, type *. Under Effect choose Allow and then choose Create. This will allow the identity associated with this policy to perform all AWS IoT and AWS Greengrass operations. For more information, see Create an AWS IoT Policy.

    Note

    The AWS Greengrass core software establishes an MQTT connection using a random client ID. For this reason, do not use the {iot:ClientId} policy variable in the AWS IoT policy for your AWS Greengrass core.

Provisioning an AWS Greengrass Core

To provision an AWS Greengrass core, you must install the AWS Greengrass core software and certificates on your AWS Greengrass core device.

Installing the AWS Greengrass Core Software

  1. The AWS Greengrass core software is in the greengrass-platform-version.tar.gz file that you downloaded from the AWS Greengrass console. Use the following command to extract greengrass-platform-version.tar.gz:

    Copy
    sudo tar -zxf greengrass-platform-version.tar.gz -C /

    Note

    This will extract the AWS Greengrass distributable into the greengrass directory in your root directory of your device.

  2. If Linux control groups (cgroups) are not enabled on the operating system of your AWS Greengrass core device , run this script.

    Note

    Linux control groups are used to limit the resources that can be accessed by Lambda functions that run on your AWS Greengrass core device.

  3. To automatically configure the Lambda cgroup, add cgroup /sys/fs/cgroup cgroup defaults 0 0 to the /etc/fstab file on your device, and then reboot your device.

The /greengrass directory is created when you extract the tar file.

Installing Certificates on your AWS Greengrass Core Device

GGC v1.0.0GGC v1.1.0
GGC v1.0.0

Your AWS Greengrass core device must establish a secure connection to AWS IoT using MQTT over TLS. To enable this, place the certificate, private key associated with your device, and the AWS IoT root CA certificate in the /greengrass/configuration/certs directory.

Note

You can download the AWS IoT root CA certificate from Verisign.

GGC v1.1.0

Your AWS Greengrass core device must establish a secure connection to AWS IoT using MQTT over TLS. To enable this, place the certificate, private key associated with your device, and the AWS IoT root CA certificate in the /greengrass/certs directory.

Note

You can download the AWS IoT root CA certificate from Verisign.

Get Connected to AWS

The following steps show how to configure and store your AWS Greengrass settings in the cloud and push changes to your AWS Greengrass core. This is the recommended way to work with AWS Greengrass.

Create a Greengrass Service Role

AWS Greengrass requires access to your AWS Lambda and AWS IoT data.

Use the IAM console (https://console.aws.amazon.com/iam/) to create an IAM role.

  1. For Role Type, choose AWS Greengrass Role.

  2. Select AWSGreengrassResourceAccessRolePolicy, and then choose Next Step.

  3. Type a name for your role, and then choose Create Role.

After creating the role, make a note of the role ARN and use it to call the following CLI command:

Copy
aws greengrass associate-service-role-to-account --role-arn arn:aws:iam::123451234510:role/GreengrassRole

Configure AWS Greengrass Core

GGC v1.0.0GGC v1.1.0
GGC v1.0.0

Edit the configuration file or create one at /greengrass/configuration/config.json:

Copy
{ "coreThing": { "caPath": "[ROOT_CA_PEM_HERE]", "certPath": "[CLOUD_PEM_CRT_HERE]", "keyPath": "[CLOUD_PEM_KEY_HERE]", "thingArn": "[THING_ARN_HERE]", "iotHost": "[HOST_PREFIX_HERE].iot.[AWS_REGION_HERE].amazonaws.com", "ggHost": "greengrass.iot.[AWS_REGION_HERE].amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "[yes|no]" } } }

Field Description Notes

caPath

The path to the AWS IoT root CA certificate relative to /greengrass/configuration/certs folder.

Save the file under /greengrass/configuration/certs.

certPath

The path to the AWS Greengrass core certificate relative to /greengrass/configuration/certs folder.

Save the file under /greengrass/configuration/certs.

keyPath

The path to the AWS Greengrass core private key relative to /greengrass/configuration/certs folder.

Save the file under /greengrass/configuration/certs.

thingArn

The ARN of the thing that represents the AWS Greengrass core.

iotHost

Your AWS IoT endpoint.

Can be obtained using the aws iot describe-endpoint CLI command or in the Settings section of the AWS IoT console.

ggHost

The AWS Greengrass endpoint.

keepAlive

The MQTT KeepAlive period, in seconds.

Optional. The default value is 600 seconds (10 minutes).

useSystemd

Manage cgroup with systemd.

If your system's init system is systemd, we strongly recommend that you use systemd to manage cgroup.

Valid values are yes and no.

A value must be specified.

When an invalid value is specified, an error message will be returned: useSystemd [invalid value] is invalid, it should be "yes" or "no".

GGC v1.1.0

Edit the configuration file or create one at /greengrass/config/config.json:

Copy
{ "coreThing": { "caPath": "[ROOT_CA_PEM_HERE]", "certPath": "[CLOUD_PEM_CRT_HERE]", "keyPath": "[CLOUD_PEM_KEY_HERE]", "thingArn": "[THING_ARN_HERE]", "iotHost": "[HOST_PREFIX_HERE].iot.[AWS_REGION_HERE].amazonaws.com", "ggHost": "greengrass.iot.[AWS_REGION_HERE].amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "[yes|no]" } } }

Field Description Notes

caPath

The path to the AWS IoT root CA certificate relative to /greengrass/certs folder.

Save the file under /greengrass/certs.

certPath

The path to the AWS Greengrass core certificate relative to /greengrass/certs folder.

Save the file under /greengrass/certs.

keyPath

The path to the AWS Greengrass core private key relative to /greengrass/certs folder.

Save the file under /greengrass/certs.

thingArn

The ARN of the thing that represents the AWS Greengrass core.

iotHost

Your AWS IoT endpoint.

Can be obtained using the aws iot describe-endpoint CLI command or in the Settings section of the AWS IoT console.

ggHost

The AWS Greengrass endpoint.

keepAlive

The MQTT KeepAlive period, in seconds.

Optional. The default value is 600 seconds (10 minutes).

useSystemd

Manage cgroup with systemd.

If your system's init system is systemd, we strongly recommend that you use systemd to manage cgroup.

Valid values are yes and no.

A value must be specified.

When an invalid value is specified, an error message will be returned: useSystemd [invalid value] is invalid, it should be "yes" or "no".

Run the AWS Greengrass Core Software

GGC v1.0.0GGC v1.1.0
GGC v1.0.0

Run sudo ./greengrassd start from the /greengrass directory on your AWS Greengrass core device. Make sure your AWS Greengrass core device is connected to the internet. To see if your AWS Greengrass core device is running, check that /greengrass/crash.log is empty and /greengrass/var/log/system/runtime.log has text like the following:

Copy
[INFO]-Deployment agent connected to cloud [INFO]-Subscribed to topic $aws/things/GGC_Thing-gda/shadow/update/delta [INFO]-Subscribed to topic $aws/things/GGC_Thing-gda/shadow/get/accepted

This text means that your AWS Greengrass core device is connected to AWS IoT and waiting for a deployment to take place.

GGC v1.1.0

Run sudo ./greengrassd start from the /greengrass/ggc/core directory on your AWS Greengrass core device. Make sure your AWS Greengrass core device is connected to the internet. To see if your AWS Greengrass core device is running, check that /greengrass/ggc/var/log/crash.log is empty and /greengrass/ggc/var/log/system/runtime.log has text like the following:

Copy
[INFO]-Deployment agent connected to cloud [INFO]-Subscribed to topic $aws/things/GGC_Thing-gda/shadow/update/delta [INFO]-Subscribed to topic $aws/things/GGC_Thing-gda/shadow/get/accepted

This text means that your AWS Greengrass core device is connected to AWS IoT and waiting for a deployment to take place.