Menu
AWS Greengrass
Developer Guide

Tutorial: Deploying AWS Greengrass to a Raspberry Pi

In this tutorial, we will create an AWS Greengrass group, add an AWS Greengrass core, and deploy the AWS Greengrass core software to a Raspberry Pi. Then we'll test the deployment by running a Lambda function on the AWS Greengrass core device.

This tutorial is intended to help you start working with AWS Greengrass in as few steps as possible. To do that, the tutorial makes some assumptions about hardware and takes an opinionated approach to configuring the Raspberry Pi. The tutorial should take one to two hours to complete.

Note

This tutorial is designed for a Mac.

Requirements

To complete this tutorial, you'll need the following:

  • A Mac

  • A Raspberry Pi (For this tutorial, we use a Raspberry Pi 3 Model B, but any Pi should work.)

  • An AWS account

  • The AWS Command Line Interface (See the AWS Command Line Interface User Guide for installation instructions.)

If you don't have an AWS account, you can create one by following the steps at Create an AWS Account.

Set Up the Raspberry Pi

To set up the Raspberry Pi:

  1. Format the SD card using the SD Memory Card Formatter. You can download the Mac version of the SD Formatter app at the Mac Download page. You can use the Quick Format option.

  2. Install the latest Raspbian operating system on the Pi.

    1. Download the latest Raspbian operating system from the Raspberry Pi downloads page. For this tutorial, you can download the Lite version.

    2. Determine where your SD card is mounted (the size should help you identify the disk you’re looking for):

      $ diskutil list

    3. Run the following command, where N corresponds to the number of the disk you identified in the previous step.

      $ diskutil unmountDisk /dev/diskN

    4. Install the OS you downloaded from Raspberry Pi (the process may take a few moments to complete):

      $ sudo dd bs=1m if=file_name.img of=/dev/diskN

  3. Create an SSH file (this is a workaround that enables SSH on the Pi):

    $ cd /Volumes/boot

    $ touch ssh

    At this point, the SD card should be ready to install on the Rasbperry Pi.

  4. Connect the Raspberry Pi to the Mac. First, ensure that your Mac has a wireless Internet connection and that Internet sharing is enabled on an appropriate port. Then follow the steps below:

    1. Insert the SD card into the Raspberry Pi.

    2. Connect the Raspberry Pi to the Mac using an ethernet cable.

    3. Connect the Raspberry Pi to a power supply.

    At this point, the Raspberry Pi should have its own IP address.

  5. Determine the IP address of the Raspberry Pi. The simplest way to find the IP address is to run ping raspberrypi or ping raspi. If pinging doesn't work, try one of the following approaches:

  6. Connect to your Raspberry Pi over SSH, replacing the example IP address with the address of your Raspberry Pi.

    ssh pi@192.168.1.154

    The initial password will be raspberry. As a best practice, you should change it to something more secure.

  7. Install software upgrades for your Raspbian distro:

    $ sudo apt-get update

    $ sudo apt-get upgrade

  8. Set the timezone:

    $ sudo dpkg-reconfigure tzdata

  9. Run the Raspbian configuration tool and configure the operating system:

    $ sudo raspi-config

    1. Choose Update to update the raspi-config tool.

    2. Choose Hostname and set the hostname for the Raspberry Pi.

    3. Choose Advanced Options > Expand Filesystem to ensure that the all of the SD card storage is available.

    4. When you're finished making changes, reboot the Raspberry Pi.

      To learn more about raspi-config, see the official documentation.

Prepare the Raspberry Pi for Greengrass

Follow these steps to prepare your Raspberry Pi for running the AWS Greengrass core software.

To run the AWS Greengrass core software:

  1. Use the following commands to add a user named ggc_user and a group named ggc_group:

    sudo adduser --system ggc_user

    sudo addgroup --system ggc_group

  2. Use the following command to install sqlite3:

    sudo apt-get install sqlite3

The AWS Greengrass core software checks if hardlink/softlink protection is activated on the operating system at startup. We recommend that you activate this protection to improve security on your device. Follow these steps.

  1. Set system variables by adding the following two lines to /etc/sysctl.d/98-rpi.conf:

    Copy
    fs.protected_hardlinks = 1 fs.protected_symlinks = 1

    If the file /etc/sysctl.d/98-rpi.conf doesn't exist, follow the instructions in /etc/sysctl.d/README.sysctl.

  2. Reboot the system:

    sudo reboot

  3. Validate the change by running:

    sudo sysctl -a | grep fs

    If the system variables were set successfully, you should see the following settings in the output:

    fs.protected_hardlinks = 1

    fs.protected_symlinks = 1

Create an AWS Greengrass Group and AWS Greengrass Core

An AWS Greengrass group is a cloud-configured and managed collection of local devices and Lambda functions that can be programmed to communicate with each other through an AWS Greengrass core device. To create an AWS Greengrass group and an AWS Greengrass core, log in to the AWS IoT console and follow the steps below.

  1. From the navigation pane, choose Greengrass.

  2. On the AWS Greengrass page, choose Get Started.

Create a Greengrass Group

In an AWS Greengrass application, devices are placed into AWS Greengrass groups. An AWS Greengrass group contains information about the devices and how messages are processed in the AWS Greengrass group. Each AWS Greengrass group requires an AWS Greengrass core that processes messages sent within the group. An AWS Greengrass core needs a certificate and an AWS IoT policy to access AWS Greengrass and AWS IoT cloud services. On the Set up your Greengrass group page, choose Use easy creation.

  1. Type a name for your group, and then choose Next.

  2. Use the default name for your AWS Greengrass core, and then choose Next.

  3. Choose Create Group and Core.

  4. Click the links to download the private key, public key, and certificate for your AWS Greengrass core.

  5. Choose the CPU architecture your AWS Greengrass core will be running (in this case, ARMv7l), and then choose Download Greengrass to download the Greengrass software package. When the download is complete, choose Finish.

Provision 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. You can use the scp utility on your Mac to copy the downloaded AWS Greengrass core software to your Pi:

    Copy
    scp greengrass-platform-version.tar.gz pi@ip_address:/path/to/desired/dir

    Then, on your Pi, use the following command to extract greengrass-platform-version.tar.gz:

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

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

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

    Note

    Linux control groups (cgroups) are used to limit the resources that can be accessed by Lambda functions that run on your AWS Greengrass core device. If cgroups are not enabled on the operating system of your AWS Greengrass core device , run this script.

Installing Certificates on your AWS Greengrass Core Device

Your AWS Greengrass core device must establish a secure connection to AWS IoT using MQTT over TLS. To enable this, you will need to place your certificate, private key, and the AWS IoT root CA certificate in the /greengrass/certs directory. You already downloaded the certificate and private key when you created your AWS Greengrass group. Follow the steps below to get the root CA certificate and copy all of the certs to the appropriate location on your Raspberry Pi.

  1. Copy the AWS IoT root CA certificate from Verisign and save it to a file.

  2. From your Mac, copy the root CA certificate to the home directory of your Pi:

    Copy
    scp root-ca-cert.pem pi@ip_address:/home/pi

    Note

    You can use whatever filename you like for the root CA certificate. You will point Greengrass at the file in a later step. In this case, we've saved the certificate in a file called root-ca-cert.pem.

    On your Pi, copy the root certificate to the Greengrass certs directory:

    Copy
    sudo cp root-ca-cert.pem /greengrass/certs/
  3. From your Mac, copy the private key to the home directory of your Pi:

    Copy
    scp GUID-private.pem.key pi@ip_address:/home/pi

    Then, on your Pi, copy the private key to the Greengrass certs directory:

    Copy
    sudo cp GUID-private.pem.key /greengrass/certs/
  4. From your Mac, copy the certificate to the home directory of your Pi:

    Copy
    scp GUID-certificate.pem.crt pi@ip_address:/home/pi

    Then, on your Pi, copy the certificate to the Greengrass certs directory:

    Copy
    sudo cp GUID-certificate.pem.crt /greengrass/certs/

When you're finished, you should have the certificate, private key, and root CA certificate all installed at /greengrass/certs/.

Connect 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. In the IAM console, select Roles > Create Role.

  2. For Role Type, choose AWS service > Greengrass. Then choose Next: Permissions.

  3. For permissions, select AWSGreengrassResourceAccessPolicy, and then choose Next: Review.

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

  5. After creating the role, select it and make a note of the role ARN. You'll need it in the next step.

Associate Your Greengrass Service Role with Your Account

If you haven't already done so, install the AWS Command Line Interface to your Mac, as described in the AWS Command Line Interface User Guide. Then run the following command, replacing the role ARN with the role ARN you noted in the previous step:

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

Configure AWS Greengrass Core

On your Pi, 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 file name of the AWS IoT root CA certificate.

Save the file under /greengrass/certs.

certPath

The file name of the AWS Greengrass core certificate.

Save the file under /greengrass/certs.

keyPath

The file name of the AWS Greengrass core private key.

Save the file under /greengrass/certs.

thingArn

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

You can find this in the AWS IoT console by going to Greengrass > Groups, selecting your Greengrass group, selecting Cores, and selecting your 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.

In constructing the endpoint, add the AWS region you are connecting to.

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. Specify yes.

When an invalid value is specified, an error message will be returned.

Start Your AWS Greengrass Core to Connect It to the Cloud

Run the following command from the /greengrass/ggc/packages/version directory to start your core and enable a cloud connection to AWS IoT.

Copy
sudo ./greengrassd start

If the Greengass daemon starts successfully, you should see output similar to the following:

Copy
sudo /greengrass/greengrassd start Setting up greengrass daemon Validating execution environment ggc_group:x:119: Found cgroup subsystem: cpu Found cgroup subsystem: cpuacct Found cgroup subsystem: blkio Found cgroup subsystem: memory Found cgroup subsystem: devices Found cgroup subsystem: freezer Found cgroup subsystem: net_cls Starting greengrass daemon PID: 1306 Greengrass daemon started

If you see the following error,

Copy
The cgroup subsystem is not mounted: cpuset

run this script to mount enabled cgroups:

Copy
# used script from: https://raw.githubusercontent.com/tianon/cgroupfs-mount/master/cgroupfs-mount sudo bash ./script.sh

Note

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

You can automatically reconfigure the Lambda cgroup when you reboot your AWS Greengrass core device by adding cgroup /sys/fs/cgroup cgroup defaults 0 0 to the /etc/fstab file on your AWS Greengrass core device.

Create a "Hello World" Lambda Function

AWS Greengrass cores can run Lambda functions in response to messages sent by your devices (or other Lambda functions). You will now create a Lambda function that you will add to your AWS Greengrass group and then deploy to your AWS Greengrass core.

  1. From the Service drop-down menu, navigate to the AWS Lambda console.

  2. In the Lambda console, choose Create function.

  3. In the Filter text box, enter Greengrass, and then choose the greengrass-hello-world Lambda function blueprint.

  4. Choose Next.

  5. For Name, type HelloWorld. For Runtime, choose Python 2.7.

  6. Scroll down until you see Lambda function handler and role. For Role, select Choose an existing role. For Existing role, select a role. If you don't have a role, select Create a new role from template(s), and then choose any template from the Policy templates drop-down list. Choose Next.

    Note

    If you have not previously created a Lambda function handler and role in your account, you will need to Create new role from template and then Choose Any.

  7. On the Review page, choose Create function.

  8. Now you need to publish a new version of the Hello World Lambda function. From the Actions menu, choose Publish new version.

  9. In Version description, type Test, and then choose Publish.

Add the Lambda Function to Your Group Definition

Next, you are going to add the Hello World Lambda function to your group definition. After it is deployed locally, the function will send data back to the AWS IoT platform and show that you have deployed a functioning core.

  1. In the AWS IoT console, choose Greengrass, and then choose Groups.

  2. Select the tile for your group.

  3. In the navigation pane, choose Lambdas, and then choose Add your first Lambda.

  4. Choose Use existing Lambda.

  5. Select the Hello World Lambda function you created eariler, and then choose Next.

  6. Select the version of the Hello World Lambda function to use, and then choose Finish.

Configure the HelloWorld Lambda Function

Configure your HelloWorld function to be long-running.

  1. In the upper-right corner of the tile for your Lambda function, choose the ellipsis, and then choose Edit Configuration.

  2. Under Lambda lifecycle, select Make this function long-lived and keep it running indefinitely, and then choose Update.

Add a Subscription to Your Group Definition

AWS Greengrass cores can pass messages between devices, Lambda functions, and AWS using the MQTT protocol. An AWS Greengrass group controls how these components interact using subscriptions that enable more security and predictable interactions. A subscription consists of a source, target, and topic. The source is the originator of the message. The target is the destination of the message. The topic allows you to filter the data that is sent from the source to the target.

  1. In the AWS Greengrass console, find your group, and then select it.

  2. On the group details page, choose Subscriptions.

  3. Choose Add your first Subscription.

  4. Under Select a source, choose your HelloWorld Lambda function.

  5. Under Select a target, choose IoT Cloud.

  6. Choose Next.

  7. A topic filter can be used to control which data is made available for the target. By default, subscriptions use a wildcard topic ("#") and will pass all information from the source to the target. You will now add hello/world as the topic filter for this subscription. In Optional topic filter, type hello/world, and then choose Next.

  8. Choose Finish to confirm and save your subscription.

Deploy Your Group

You have created a group and a core definition, but this information exists only in the cloud. Deploying a group takes this configuration information and copies it onto your AWS Greengrass core device.

  1. In the AWS Greengrass console, choose Groups, choose your group, and then choose Deployments.

  2. From the Actions menu, choose Deploy.

  3. On the Configure how Devices discover your Core page, choose Automatic detection.

  4. On the Grant permission to access other services page, choose Grant permission. (This step is only required once for a given account.)

Your deployment may take several minutes. You will know the deployment was successful when a Deployment successfully completed message is displayed in the group details page.

Verify the Lambda Function Is Running on Your Core Device

In the AWS IoT console, choose Test.

In Subscription topic, type hello/world, and then choose Subscribe to topic to subscribe to the hello/world topic.

If the hello world Lambda function is running on your AWS Greengrass core device, it can publish messages to the hello/world topic:

And that's it. You've just configured an AWS Greengrass group and an AWS Greengrass core, installed the core software on a Raspberry Pi, created a Lambda function and added it to your group definition, added a subscription to the Greengrass group, deployed the group, and run a Lambda function on the Pi.