Table of contents
About AWS Greengrass
AWS Greengrass is software that extends AWS cloud capabilities to local devices, making it possible for them to collect and analyze data closer to the source of information, while also securely communicating with each other on local networks. More specifically, developers who use AWS Greengrass can author serverless code (AWS Lambda functions) in the cloud and conveniently deploy it to devices for local execution of applications.
AWS Greengrass makes it possible for customers to use Lambda functions to build IoT devices and application logic. Specifically, AWS Greengrass provides cloud-based management of applications that can be deployed for local execution. Locally deployed Lambda functions are triggered by local events, messages from the cloud, or other sources.
In AWS Greengrass, devices securely communicate on a local network and exchange messages with each other without having to connect to the cloud. AWS Greengrass provides a local pub/sub message manager that can intelligently buffer messages if connectivity is lost so that inbound and outbound messages to the cloud are preserved.
AWS Greengrass consists of:
- Software distributions
- AWS Greengrass Core software (GGC) - we will be using the latest version (1.3.0)
- AWS Greengrass Core SDK
- Cloud service
- AWS Greengrass API
- Lambda runtime
- Shadows implementation
- Message manager
- Group management
- Discovery service
Requirements for AWS Greengrass
Setting up AWS Greengrass on MACCHIATObin requires the following:
- A Mac, Windows PC, or UNIX-like system. We will be using a Linux-based system in this tutorial.
- An Amazon Web Services (AWS) account. If you don't have an AWS account, create one by following the steps below:
- Open the AWS home page, choose Create an AWS Account and follow the instructions on the screen.
- Note: If you've signed in to AWS recently, you might see Sign In to the Console instead.
- Follow the online instructions. Part of the sign-up procedure involves receiving a phone call and entering a PIN using your phone keypad.
- Important: Ensure that your account has administrative privileges before proceeding. See this page to set up an AWS account and create an administrator user.
- Open the AWS home page, choose Create an AWS Account and follow the instructions on the screen.
- The use of an AWS region that supports AWS Greengrass such as US East (N. Virginia), US West (Oregon), EU (Frankfurt), Asia Pacific (Sydney), Asia Pacific (Tokyo) – for more information, see AWS Greengrass FAQs.
- Important: Make note of your region to ensure that it is consistently used throughout this tutorial – inadvertently switching regions midway through the tutorial would be problematic.
Environment setup for AWS Greengrass
AWS Greengrass core v1.3.0 supports the ARMv8 (AArch64) platform and Ubuntu distribution, releases 14.04 – 16.04 (Annapurna Alpine V2).
AWS Greengrass core v1.3.0 requires the following (the list below contains links to necessary pre-built components):
- Minimum 128 MB RAM allocated to the AWS Greengrass core device.
- Linux kernel version 4.4 or greater: while several versions may work with AWS Greengrass, for optimal security and performance, we recommend version 4.4 or greater. We will be using Linux kernel version 4.4.52.
- Glibc library version 2.14 or greater.
- The /var/run directory must be present on the device.
- AWS Greengrass requires hardlink and softlink protection to be enabled on the device. Without this, AWS Greengrass can only be run in insecure mode, using the -i flag.
- The ggc_user and ggc_group user and group must be present on the device.
- The following Linux kernel configurations must be enabled on the device:
- Namespace: CONFIG_IPC_NS, CONFIG_UTS_NS, CONFIG_USER_NS, CONFIG_PID_NS
- CGroups: CONFIG_CGROUP_DEVICE, CONFIG_CGROUPS, CONFIG_MEMCG
- Others: CONFIG_POSIX_MQUEUE, CONFIG_OVERLAY_FS, CONFIG_HAVE_ARCH_SECCOMP_FILTER, CONFIG_SECCOMP_FILTER, CONFIG_KEYS, CONFIG_SECCOMP
- A pre-made config file with these options included can be downloaded from here in order to build the 4.4.52 kernel manually.
- Alternatively, download the necessary pre-built files below:
- The sqlite3 package is required for AWS IoT device shadows. Ensure it’s added to your PATH environment variable.
- /dev/stdin, /dev/stdout, and /dev/stderrmus must be enabled.
- The Linux kernel must support cgroups.
- The memory cgroup must be enabled and mounted to allow AWS Greengrass to set the memory limit for Lambdas.
- The root certificate for Amazon S3 and AWS IoT must be present in the system trust store.
- Python version 2.7 is required if Python Lambdas are used. If so, ensure that it's added to your PATH environment variable. We will be using Python Lambdas for our "Hello World" example later on.
Preparing SD card
After manually building or downloading the pre-built kernel image and dtb file, we will transfer them to an SD card already containing the Ubuntu root filesystem. The Ubuntu file system can be either built manually or downloaded as a pre-built SD card image by following instructions in Creating Ubuntu filesystem. If building the file system manually, prepare the SD card as instructed in Boot from MicroSD card/USB stick - Ubuntu. Lastly, copy the image and dtb with:
# Replace the below paths for the downloaded/built files and SD card partition to suit your setup. When using prebuilt SD card image, the filesystem is located in the second partition. $ cd path-to-downloaded-files $ sudo cp armada-8040-mcbin.dtb /path-to-sd-card/boot/ $ sudo cp Image /path-to-sd-card/boot/
Exit the directory and unmount your SD card. Remove the SD card from your local machine and plug it into the Micro SD card slot on the MACCHIATObin, plug the power adapter and connect to the board via Micro USB cable and serial connection as described in Quick Start Guide. If you built your Ubuntu file system manually, you may also need to set up the required U-Boot parameters as shown in Boot from MicroSD card/USB stick - Ubuntu.
Once the board is booted, setup a working network configuration as shown in Quick Start Guide. Now install the necessary packages:
$ sudo apt-get update $ sudo apt-get install binutils vim git
To make sure your MACCHIATObin is ready to run AWS Greengrass, download and extract the AWS Greengrass dependency checker from the GitHub repository and run the following script to check for missing dependencies:
$ git clone https://github.com/aws-samples/aws-greengrass-samples.git $ cd aws-greengrass-samples/greengrass-dependency-checker-GGCv1.3.0 # The script requires the following Linux system commands: printf, uname, cat, # ls, head, find, zcat, awk, sed, sysctl, wc, cut, sort, expr, grep, test, # dirname, readlink, xargs, strings, uniq $ sudo ./check_ggc_dependencies ==========================Checking script dependencies============================== The device has all commands required for the script to run. ========================Dependency check report for GGC v1.3========================= System configuration: Kernel architecture: aarch64 Init process: /lib/systemd/systemd Kernel version: 4.4 C library: Ubuntu GLIBC 2.23-0ubuntu9 C library version: 2.23 Directory /var/run: Present /dev/stdin: Found /dev/stdout: Found /dev/stderr: Found --------------------------------Kernel configuration-------------------------------- Kernel config file: /proc/config.gz Namespace configs: CONFIG_IPC_NS: Enabled CONFIG_UTS_NS: Enabled CONFIG_USER_NS: Enabled CONFIG_PID_NS: Enabled Cgroup configs: CONFIG_CGROUP_DEVICE: Enabled CONFIG_CGROUPS: Enabled CONFIG_MEMCG: Enabled Other required configs: CONFIG_POSIX_MQUEUE: Enabled CONFIG_OVERLAY_FS: Enabled CONFIG_HAVE_ARCH_SECCOMP_FILTER: Enabled CONFIG_SECCOMP_FILTER: Enabled CONFIG_KEYS: Enabled CONFIG_SECCOMP: Enabled ------------------------------------Cgroups check----------------------------------- Cgroups mount directory: /sys/fs/cgroup Devices cgroup: Enabled and Mounted Memory cgroup: Enabled and Mounted ----------------------------Commands and software packages-------------------------- SQLite 3: Not found Python 2.7: Not found NodeJS 6.10: Not found Java 8: Not found OpenSSL version: 1.0.2 wget: Present realpath: Present tar: Present readlink: Present basename: Present dirname: Present pidof: Present df: Present grep: Present umount: Present ---------------------------------Platform security---------------------------------- Hardlinks_protection: Enabled Symlinks protection: Enabled -----------------------------------User and group----------------------------------- User ggc_user: Not found Group ggc_group: Not found ------------------------------------Results----------------------------------------- Note: 1. It looks like the kernel uses 'systemd' as the init process. Be sure to set the 'useSystemd' field in the file 'config.json' to 'yes' when configuring Greengrass core. Missing optional dependencies: 1. Could not find the binary 'python2.7'. If Python 2.7 is installed on the device, name the binary 'python2.7' and add its parent directory to the PATH environment variable. Python 2.7 is required to execute Python lambdas on Greengrass core. 2. Could not find the binary 'nodejs6.10'. If NodeJS 6.10 or later is installed on the device, name the binary 'nodejs6.10' and add its parent directory to the PATH environment variable. NodeJS 6.10 or later is required to execute NodeJS lambdas on Greengrass core. 3. Could not find the binary 'java8'. If Java 8 or later is installed on the device name the binary 'java8' and add its parent directory to the PATH environment variable. Java 8 or later is required to execute Java lambdas on Greengrass core. Missing required dependencies: 1. Could not find the binary 'sqlite3'. If SQLite version 3 or later is installed on the device, name the binary 'sqlite3' and add its parent directory to the PATH environment variable. 2. User ggc_user, required to run Greengrass core, is not present on the device. Refer to the official Greengrass documentation to fix this. 3. Group ggc_group, required to run Greengrass core, is not present on the device. Refer to the official Greengrass documentation to fix this. ----------------------------------Exit status--------------------------------------- Either the script failed to verify all dependencies or the device is missing one or more of the required dependencies for Greengrass version 1.3. Refer to the 'Errors' and 'Missing required dependencies' sections under 'Results' for details.
It is important that you resolve the dependencies indicated by the script before moving on with the installation, in our example we had to add the user ggc_user and group ggc_group as well as install the sqlite3 and python2.7 packages:
$ sudo adduser --system ggc_user $ sudo addgroup --system ggc_group $ sudo apt-get install sqlite3 python2.7
If no errors appear in the output, then AWS Greengrass should be able to run successfully on the MACCHIATObin.
Installing AWS Greengrass core software on MACCHIATObin
Now on to installing AWS Greengrass core software on the MACCHIATObin board. The AWS Greengrass core software provides the following functionality:
- Allows deployment and execution of local applications that are created by using AWS Lambda functions and managed through the deployment API.
- Enables local messaging between devices over a secure network by using a managed subscription scheme through the MQTT protocol.
- Ensures secure connections between devices and the cloud using device authentication and authorization.
- Provides secure, over-the-air, software updates of user-defined Lambda functions.
Follow the instructions for the AWS IoT console as shown here. In step 7, after downloading the required security resources for your AWS Greengrass core, you will need to download the current Greengrass Core software binary for the MACCHIATObin's CPU architecture, which is AArch64 (ARMv8).
It is vital that you download both the security resources and the AWS Greengrass Core software before choosing Finish.
Starting AWS Greengrass on MACCHIATObin
In the previous step we downloaded two files from AWS Greengrass console:
- greengrass-linux-aarch64-1.3.0.tar.gz - this compressed file contains the AWS Greengrass core software that will run on AWS Greengrass core device, that is, on the MACCHIATObin board.
- GUID-setup.tar.gz - this compressed file contains security certificates enabling secure communications with AWS IoT and config.json which contains configuration information specific to your AWS Greengrass core and the AWS IoT endpoint.
From your local machine we will now - using SCP, web server or some other method - transfer these files to the MACCHIATObin board. We will be using SCP:
# Replace the IP address below with the IP address of your MACCHIATObin board $ cd path-to-downloaded-files $ scp greengrass-linux-aarch64-1.3.0.tar.gz mcbin@IP-address:/home/mcbin/ $ scp GUID-setup.tar.gz mcbin@IP-address:/home/mcbin/
Next, in the MACCHIATObin console navigate to the location of the downloaded files and extract both the AWS Greengrass core binary and the security resources:
$ cd path-to-compressed-files # Creating a /greengrass directory in the root folder of the Ubuntu file system $ sudo tar -xzvf greengrass-linux-aarch64-1.3.0.tar.gz -C / # Copying certificates into /greengrass/certs and config.json into /greengrass/config directories $ sudo tar -xzvf GUID-setup.tar.gz -C /greengrass/
The AWS Greengrass config.json file is contained in the /greengrass/config directory and should be ready to go as-is. You can optionally review the contents of this file by running the following command:
$ cat /greengrass/config/config.json
Parameters shown in config.json are explained in more detail at the bottom of this page.
Next we install the Symantec VeriSign root CA onto the MACCHIATObin board. This certificate enables your device to communicate with AWS IoT using the MQTT messaging protocol over TLS. Make sure the AWS Greengrass core device is connected to the internet, then run the following commands (note that -O is the capital letter O):
$ cd /greengrass/certs/ $ sudo wget -O root.ca.pem http://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem
Run the following command to confirm that the root.ca.pem file is not empty:
$ cat root.ca.pem
If the root.ca.pem file is empty, check the wget URL and try again.
Finally, use the following commands to start AWS Greengrass:
$ cd /greengrass/ggc/packages/1.3.0/ $ sudo ./greengrassd start Setting up greengrass daemon Validating hardlink/softlink protection Validating execution environment Found cgroup subsystem: cpu Found cgroup subsystem: cpuacct Found cgroup subsystem: memory Found cgroup subsystem: devices Found cgroup subsystem: freezer Found cgroup subsystem: hugetlb Found cgroup subsystem: pids Starting greengrass daemon Greengrass successfully started with PID: 7229
Next, run the following command to confirm that the AWS Greengrass core software (daemon) is functioning. Replace with your own PID number:
$ ps aux | grep PID-number root 7229 0.9 0.4 430616 17708 pts/0 Sl 15:11 0:00 /greengrass/ggc/packages/1.3.0/bin/daemon -core-dir=/greengrass/ggc/packages/1.3.0 -greengrassdPid=7198
You should see a path to the running AWS Greengrass daemon, as in /greengrass/ggc/packages/1.3.0/bin/daemon.
Configuring and deploying a Lambda function on AWS Greengrass
Now that we have a running AWS Greengrass core device, we can move on to configuring a Lambda function and deploying it to the MACCHIATObin board. The Lambda function contains information about MQTT messaging, subscriptions, deployments on AWS Greengrass, and Lambda function configurations.
This section should enable you to deploy a Lambda function on MACCHIATObin board (our AWS Greengrass core device) that sends "Hello World" messages to the AWS Greengrass cloud.
In order for a Python Lambda function to run on an AWS Greengrass core, it must be packaged with specific folders from the Python AWS Greengrass Core SDK.
Follow the instructions shown in Module 3 (Part 1) to download the Python AWS Greengrass SDK to your computer, decompress it and obtain a Python Lambda function (named greengrassHelloWorld.py) from it. In this module you will also create a Lambda function deployment package named hello_world_python_lambda.zip that contains greengrassHelloWorld.py and three required SDK folders, as well as learn how to create your own Lambda function from scratch.
On the next page, you will be able to configure the Lambda function for AWS Greengrass.
Third page of this part shows you how to deploy the cloud configurations to a core device (MACCHIATObin). Lastly, follow the instructions on this page to verify that the Lambda function is running on the MACCHIATObin and that our AWS Greengrass core device is sending "Hello World" messages to the AWS Greengrass cloud: