AWS Greengrass
Developer Guide

Module 1: Environment Setup for Greengrass

This module shows you how to get an out-of-the-box Raspberry Pi, Amazon EC2 instance, or other device ready to be used by AWS Greengrass.

Important

Use the Filter View drop-down list in the upper-right corner of this webpage to choose your platform.

This module should take less than 30 minutes to complete.

Setting Up a Raspberry Pi

If you are setting up a Raspberry Pi for the first time, you must follow all of these steps. If you are using an existing Raspberry Pi, you can skip to step 9. However, we recommend that you re-image your Raspberry Pi with the operating system as recommended in step 2.

  1. Download and install an SD card formatter such as SD Memory Card Formatter or PiBakery. Insert the SD card into your computer. Start the program and choose the drive where your have inserted your SD card. You can quick format the SD card.

  2. Download the Raspbian Jessie operating system as a .zip file.

    Note

    You can choose to use Raspbian Stretch instead of Jessie, but this will not support OTA Updates. Using Stretch will also require additional memory set-up.

  3. Using an SD card-writing tool (such as Etcher), follow the tool's instructions to flash the downloaded zip file onto the SD card. Because the operating system image is large, this step might take some time. Eject your SD card from your computer, and insert the microSD card into your Raspberry Pi.

  4. For the first boot, we recommend that you connect the Raspberry Pi to a monitor (through HDMI), a keyboard, and a mouse. Next, connect your Pi to a micro USB power source and the Raspbian operating system should start up.

  5. You may want to configure the Pi's keyboard layout before proceeding. To do so, choose the Raspberry icon in the upper-right, choose Preferences and then Mouse and Keyboard Settings. Next, choose the Keyboard tab, Keyboard Layout, and then choose an appropriate keyboard variant.

  6. Next, connect your Raspberry Pi to the internet through a Wi-Fi network or an Ethernet cable.

    Note

    Connect your Raspberry Pi to the same network that your computer is connected to, and be sure that both your computer and Raspberry Pi have internet access before proceeding. If you're in a work environment or behind a firewall, you may need to connect your Pi and your computer to the guest network in order to get both devices on the same network. This approach, however, may disconnect your computer from local network resources such as your intranet. One solution may be to connect the Pi to the guest Wi-Fi network, your computer to the guest Wi-Fi network and your local network through an Ethernet cable. In this configuration, your computer should be able to connect to the Raspberry Pi via the guest Wi-Fi network and your local network resources through the Ethernet cable.

  7. You must set up SSH on your Pi to remotely connect to it. On your Raspberry Pi, open a terminal window and run the following command:

    sudo raspi-config

    You should see the following:

    
                            Raspberry Pi Software Configuration Tool (raspi-config)
                                screenshot.

    Scroll down and choose Interfacing Options and then choose P2 SSH. When prompted, choose Yes using the Tab key (followed by Enter). SSH should now be enabled, choose OK. Tab key to Finish and then press the Enter key. Lastly, reboot your Pi by running the following command:

    sudo reboot
  8. On your Raspberry Pi, run the following command in the terminal:

    hostname -I

    This returns the IP address of your Raspberry Pi.

    Note

    For the following, if you receive an ECDSA key fingerprint related message Are you sure you want to continue connecting (yes/no)?, enter yes. Additionally, the default password for the Raspberry Pi is raspberry.

    If you are using macOS, open a Terminal window and type the following:

    ssh pi@IP-address

    Here, IP-address corresponds to the IP address of your Raspberry Pi that you obtained by using the prior hostname -I command.

    If you are using Windows, you need to install and configure PuTTY. Choose Connection, Data, and make sure that Prompt is selected:

    
                            PuTTY window with Prompt selected.

    Next, choose Session, type the IP address of the Raspberry Pi, and choose Open using default settings. For example (your IP address, in all likelihood, will be different):

    
                            PuTTY window with IP address in the "Host Name (or IP address)"
                                field.

    If a PuTTY Security Alert dialog is displayed, choose an appropriate response such as Yes.

    This will result in a terminal window similar to the following. The default Raspberry Pi login and password are pi and raspberry, respectively.

    
                            Initial PuTTY terminal window.

    Note

    If your computer is connected to a remote network using VPN (such as a work related network), this may cause difficulty connecting from the computer to the Raspberry Pi using SSH.

  9. You are now ready to set up the Raspberry Pi for AWS Greengrass. First, run the following commands from a local Raspberry Pi terminal window or an SSH terminal window:

    sudo adduser --system ggc_user sudo addgroup --system ggc_group
  10. Run the following commands to update the Linux kernel version of your Raspberry Pi.

    sudo apt-get install rpi-update sudo rpi-update b81a11258fc911170b40a0b09bbd63c84bc5ad59

    Although several kernel versions might work with AWS Greengrass, for the best security and performance, we recommend that you use the kernel version indicated in step 2. In order to activate the new firmware, reboot your Raspberry Pi:

    sudo reboot

    As applicable, reconnect to the Raspberry Pi using SSH after minute or so. Next, run the following command to ensure you have the correct kernel version:

    uname -a

    You should receive output similar to the following, the key item being the Linux Raspberry Pi version information 4.9.30:

    
                            Raspberry Pi "uname -a" command output showing kernel
                                version.
  11. To improve security on the Pi device, run the following commands to enable hardlink and softlink protection at operating system start-up.

    cd /etc/sysctl.d ls

    If you see the 98-rpi.conf file, use a text editor (such as leafpad, nano, or vi) to add the following two lines to the end of the file (you can run the text editor using the sudo command to avoid write permission issues, as in sudo nano 98-rpi.conf).

    fs.protected_hardlinks = 1 fs.protected_symlinks = 1

    If you do not see the 98-rpi.conf file, follow the instructions in the README.sysctl file.

    Now reboot the Pi:

    sudo reboot

    After about a minute, connect to the Pi using SSH as applicable and then run the following commands from a Raspberry Pi terminal to confirm the hardlink/symlink change:

    sudo sysctl -a 2> /dev/null | grep fs.protected

    You should see fs.protected_hardlinks = 1 and fs.protected_symlinks = 1.

  12. If using Raspbian Stretch, edit your command line boot file to enable and mount memory cgroups. This allows AWS Greengrass to set the memory limit for Lambda functions. Without this, the Greengrass daemon is unable to run.

    1. Navigate to your boot directory.

      cd /boot/
    2. Use a text editor to open cmdline.txt. Add the following line to the end of the file. This option should be added in-line.

      cgroup_enable=memory cgroup_memory=1
    3. Now reboot the Pi:

      sudo reboot
  13. Your Raspberry Pi should now be ready for AWS Greengrass. To ensure that you have all of the dependencies required for AWS Greengrass, download the AWS Greengrass dependency checker from the GitHub repository and run it on the Pi as follows:

    cd /home/pi/Downloads git clone https://github.com/aws-samples/aws-greengrass-samples.git cd aws-greengrass-samples cd greengrass-dependency-checker-GGCv1.6.0 sudo modprobe configs sudo ./check_ggc_dependencies | more

    With respect to the more command, press the Spacebar key to display another screen of text.

    Important

    This tutorial uses the AWS IoT Device SDK for Python, so you can ignore warnings about the missing optional NodeJS 6.10 and Java 8 prerequisites that the check_ggc_dependencies script might produce.

    For information about the modprobe command, you can run man modprobe in the terminal.

Your Raspberry Pi configuration is complete. Continue to Module 2: Installing the Greengrass Core Software.

Setting Up an Amazon EC2 Instance

  1. Sign in to the AWS Management Console and launch an Amazon EC2 instance using an Amazon Linux AMI (Amazon Machine Image). For information about Amazon EC2 instances, see the Amazon EC2 Getting Started Guide.

  2. After your Amazon EC2 instance is running, enable port 8883 to allow incoming MQTT communications so that other devices can connect with the AWS Greengrass core. In the left pane of the Amazon EC2 console, choose Security Groups.

    
                            Left pane with Security Groups
                                highlighted.

    Choose the instance that you just launched, and then choose the Inbound tab.

    
                            Inbound tab highlighted.

    By default, only one port for SSH is enabled. To enable port 8883, choose the Edit button. Next, choose the Add Rule button and create a custom TCP rule as shown below, then choose Save.

  3. In the left pane, choose Instances, choose your instance, and then choose the Connect button. Connect to your Amazon EC2 instance by using SSH. You can use PuTTY for Windows or Terminal for macOS.

  4. Once connected to your Amazon EC2 instance through SSH, run the following commands to create user ggc_user and group ggc_group:

    sudo adduser --system ggc_user sudo groupadd --system ggc_group
  5. To improve security on the device, enable hardlink/softlink protection on the operating system at start-up. To do so, run the following commands:

    cd /etc/sysctl.d ls

    Using your favorite text editor (leadpad, nano, vi, etc.), add the following two lines to the end of the 00-defaults.conf file, You might need to change permissions (using the chmod command) to write to the file, or use the sudo command to edit as root (for example, sudo nano 00-defaults.conf).

    fs.protected_hardlinks = 1 fs.protected_symlinks = 1

    Run the following command to reboot the Amazon EC2 instance.

    sudo reboot

    After a few minutes, connect to your instance by using SSH as above. Then, run the following command to confirm the change.

    sudo sysctl -a | grep fs.protected

    You should see that hardlinks and softlinks are set to 1.

  6. Extract and run the following script to mount Linux control groups (cgroups). This is an AWS Greengrass dependency:

    curl https://raw.githubusercontent.com/tianon/cgroupfs-mount/951c38ee8d802330454bdede20d85ec1c0f8d312/cgroupfs-mount > cgroupfs-mount.sh chmod +x cgroupfs-mount.sh sudo bash ./cgroupfs-mount.sh

    Your Amazon EC2 instance should now be ready for AWS Greengrass. To be sure that you have all of the dependencies, extract and run the following AWS Greengrass dependency script from the GitHub repository:

    sudo yum install git git clone https://github.com/aws-samples/aws-greengrass-samples.git cd aws-greengrass-samples cd greengrass-dependency-checker-GGCv1.6.0 sudo ./check_ggc_dependencies

    Important

    This tutorial uses the AWS IoT Device SDK for Python, so you can ignore warnings about the missing optional NodeJS 6.10 and Java 8 prerequisites that the check_ggc_dependencies script might produce.

Your Amazon EC2 instance configuration is complete. Continue to Module 2: Installing the Greengrass Core Software.

Setting Up Other Devices

If you're new to AWS Greengrass, we recommend that you use a Raspberry Pi or an Amazon EC2 instance as your core device, and follow the setup steps in the corresponding section. To use a different platform, follow the steps in this section. For information about supported device platforms, see Greengrass Core Platform Compatibility.

  1. If your core device is an NVIDIA Jetson TX2, you must first flash the firmware with the JetPack 3.3 installer. If you're configuring a different device, skip to step 2.

    Note

    The JetPack installer version that you use is based on your target CUDA Toolkit version. The following instructions use JetPack 3.3 and CUDA Toolkit 9.0 because the TensorFlow v1.10.1 and MXNet v1.2.1 binaries (that AWS Greengrass provides for machine learning inference on a Jetson TX2) are compiled against this version of CUDA. For more information, see Perform Machine Learning Inference.

    1. On a physical desktop that is running Ubuntu 16.04 or later, flash the firmware with the JetPack 3.3 installer, as described in Download and Install JetPack (3.3) in the NVIDIA documentation.

      Follow the instructions in the installer to install all the packages and dependencies on the Jetson board, which must be connected to the desktop with a Micro-B cable.

    2. Reboot your board in normal mode, and connect a display to the board.

      Note

      Use the default user credentials when using SSH to connect to the Jetson board. The default user name is nvidia and the default password is nvidia.

  2. Run the following commands to create user ggc_user and group ggc_group.

    sudo adduser --system ggc_user sudo addgroup --system ggc_group
  3. Run the following commands to check whether the device is ready to run AWS Greengrass. This step clones the AWS Greengrass Samples repository from GitHub and runs the Greengrass dependency checker.

    git clone https://github.com/aws-samples/aws-greengrass-samples.git cd aws-greengrass-samples cd greengrass-dependency-checker-GGCv1.6.0 sudo ./check_ggc_dependencies

    Note

    The check_ggc_dependencies script runs on AWS Greengrass supported platforms and 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.

  4. Install all required dependencies on your device, as indicated by the dependency script. For missing kernel-level dependencies, you might have to recompile your kernel. For mounting Linux control groups (cgroups), you can run the cgroupfs-mount script.

    If no errors appear in the output, AWS Greengrass should be able to run successfully on your device.

    Important

    This tutorial uses the AWS IoT Device SDK for Python, so you can ignore warnings about the missing optional NodeJS 6.10 and Java 8 prerequisites that the check_ggc_dependencies script might produce.

    For the list of AWS Greengrass requirements and dependencies, see Supported Platforms and Requirements.