AWS IoT Greengrass V2 Quickstart

Revision History
Document Version	Date	Description of change
v1.0	10/27/2022	Initial version of AWS IoT Greengrass guide targeting the phyCORE-AM64x SOM running BSP-Yocto-TISDK-AM64x-ALPHA2 based Linux.
v1.1	1/19/2023	Minor style, grammar, and clarity edits.
v2.0	4/17/2023	Updated the AWS IoT Greengrass guide targeting the phyCORE-AM64x SOM running BSP-Yocto-AM64x-PD23.1.0 based Linux.
v3.0	10/04/2023	Updated the AWS IoT Greengrass guide targeting the phyCORE-AM64x SOM running BSP-Yocto-Ampliphy-AM64x-PD23.2.0 based Linux.

The phyCORE®-AM64x System on Module is a robust and reliable embedded solution designed for headless industrial communication systems. The 50mm x 37mm SOM has an extensive 280-pin interconnect supporting common factory communication protocols such as CAN, EtherCAT, UART, I2C and also automation specific interfaces such as EPWM, ECAP, and EQEP. Due to the heterogeneous architecture of the TI AM64x processor, you can run the majority of your application using Linux and offload critical components to the specialized low latency real-time cores. AWS IoT Greengrass is an excellent solution for your phyCORE-AM64x SOM to connect those critical, real-time processes to the cloud.

This guide will help you get started with integrating AWS IoT Greengrass V2 onto your phyCORE-AM64x Development kit running software based on the BSP-Yocto-Ampliphy-AM64x-PD23.2.0 Linux release.

Note

BSP-Yocto-Ampliphy-AM64x-PD23.2.0 doesn’t have AWS IoT Greengrass V2 support integrated by default but this will be available in a future release as a pre-built image. For now, this guide will help you to manually install the necessary dependencies by modifying the base BSP-Yocto-Ampliphy-AM64x-PD23.2.0 Linux release using Yocto.

To learn more about AWS IoT Greengrass, see How It Works and What’s New.

Requirements

In order to follow this guide, you will need:

The phyCORE-AM64x development kit. This includes:
- phyCORE-AM64x System on Module, PL1565 (PCM-072)
- phyBOARD-AM64x (Electra) Carrier Board, PL1566 (PBA-C-25)
- Micro USB cable
- Ethernet cable
- Two 2x5 .1” header to DB9 cables
- Pre-flashed Bootable SD Card (BSP-Yocto-Ampliphy-AM64x-PD23.2.0)
- 12V/2A Power Supply Barrel Adapter
- USB-MicroSD Card Reader
An AWS account. More information can be found in the steps below.

The only thing not included in the development kit is the recommended Host Machine and development environment (see the steps below).

Steps

The first step will be to configure a Ubuntu 20.04 Host environment and build the base BSP-Yocto-Ampliphy-AM64x-PD23.2.1 software release according to the steps outlined in Build the BSP. In this guide, we will be modifying the default Yocto-based Linux Board Support Package (BSP).

Head over to the Build the BSP guide and follow the instructions outlined there carefully.

With the default BSP built we can now start fulfilling the Greengrass V2 dependencies using Yocto.

Java Dependency

Navigate into the BSP’s sources/ directory and clone meta-java. This is a community-maintained Yocto meta-layer that can provide openjdk-8 support.

Host (Linux)

cd $BUILDDIR/../sources
git clone https://git.yoctoproject.org/meta-java -b kirkstone

Enable meta-java as a active layer in our build configuration:

Host (Linux)

cd $BUILDDIR
bitbake-layers add-layer ../sources/meta-java

Installing the Dependencies

With our BSP properly configured for building openjdk-8, we can now specify it and other dependencies already available in the build tree to be included in the phytec-headless-image (these won’t be included by default).

Add the following line to the end of conf/local.conf:

conf/local.conf

IMAGE_INSTALL:append = " nodejs ntpdate openjdk-8 sudo"

Note

If you encounter strange linker errors when compiling the nodejs package, this is likely due to constrained compute resources (this package seems to require a lot of RAM, specifically). If you have more RAM you can allocate to your Host than do so, otherwise use the following steps to create a Swap file (depending on your Host setup, you may need to incrementally increase its size until you can build the package):

host:~$ sudo dd if=/dev/zero of=/swapfile.img bs=1024 count=8M       #8GB Swap file + 16GB of RAM was tested successfully on PHYTEC's build machine
host:~$ sudo chmod 600 /swapfile.img
host:~$ sudo mkswap /swapfile.img
host:~$ sudo swapon /swapfile.img

The following command can be used to check the swap space available to the Host:

host:~$ cat /proc/swaps

Now you can re-build phytec-headless-image and the build system will automatically build and include those additional packages.

host:~$ bitbake phytec-headless-image

Booting the Resulting Image

Checkout the SD Card guide to help you flash the resulting phytec-headless-image to an SD Card and then use it to boot your development kit.

A good, quick reference on booting your phyCORE-AM64x Development Kit into Linux from an SD Card can be found in the Quickstart.

Setting Up the Hardware

Once you have booted your phyCORE-AM64x Development Kit into Linux and logged in as root, there are a few more things we need to configure at runtime before we can run the AWS IoT Greengrass installer.

First, your phyCORE-AM64x Development Kit must have a valid network connection. Checkout the Ethernet guide to help you with this.

When connected to a valid network, the Network Time Protocol (NTP) support we added to the image will also include a NTP systemd service that will automatically synchronize your system’s date and time with the internet. The system time must be correct in order to successfully complete the Greengrass Setup Steps.

We can quickly double check the system time with the following command (note that the time is shown in UTC time):

phyboard-electra-am64xx-2:~# date

The final step, before we dive into installing Greengrass V2, is to configure a default system user that Greengrass components can run under:

phyboard-electra-am64xx-2:~# useradd --system --create-home ggc_user
phyboard-electra-am64xx-2:~# usermod -aG root ggc_user

Now give the new ggc_user all root permissions and make sure no password is required:

phyboard-electra-am64xx-2:~# sudo visudo

Add the following line to the file to do this:

/etc/sudoers

ggc_user ALL=(ALL) NOPASSWD: ALL

Note

It is not advised to edit the /etc/sudoers file directly. In order to edit this, it is recommended to use the command sudo visudo.

Use passwd to explicitly delete the new user’s password:

phyboard-electra-am64xx-2:~# passwd -d ggc_user

AWS Account

Note

This section is intended as a simple quickstart into AWS IoT Greengrass and its integration into PHYTEC’s phyCORE-AM64x Development Kit and any potential production systems that employ the phyCORE-AM64x SOM. This guide is not intended to be an exhaustive source of documentation on AWS IoT Greengrass or other services.

This guide for the phyCORE-AM64x was largely adapted from https://docs.aws.amazon.com/greengrass/v2/developerguide/install-greengrass-core-v2.html

Please reference this official documentation from AWS for more information about AWS IoT Greengrass and other AWS services.

Before we can begin work with AWS IoT Greengrass you will need a AWS account.

Once you have an AWS account, you have your options for creating and managing IAM Users and Roles. The AWS CLI tool and AWS IAM console (accessed via your web browser) are both quickly available to do this but this guide will primarily utilize the web browser console when possible, which can be accessed here (we at PHYTEC think this is easiest): https://console.aws.amazon.com/iam/

Note

AWS IAM gives you the ability to create and manage security identities that can allow certain users and devices to access certain AWS services and resources. This guide will utilize long term security credentials which can be generated for IAM Users, but temporary credentials via IAM roles are also possible.

Follow the Create IAM Users (console) instructions to create a IAM User. You will need to save the Access Keys generated for the User for use in the following steps.

Warning

The Access Keys can only be viewed and downloaded at the time of creation. It is recommended to download these as a .csv file to your local filesystem (and keep them secret!).

With your Access Keys handy, run the following in your phyCORE-AM64x serial console (you need to run these commands with your specific keys!):

phyboard-electra-am64xx-2:~# export AWS_ACCESS_KEY_ID=<REPLACE-WITH-YOUR-ACCESS-KEY>
phyboard-electra-am64xx-2:~# export AWS_SECRET_ACCESS_KEY=<REPLACE-WITH-SECRET-YOUR-ACCESS-KEY>

Now we are ready to download the Greengrass installer:

AWS IoT Greengrass V2 Installer

Note

By downloading this software, you agree to the Greengrass Core Software License Agreement

Tip

The server hosting the installer won’t let you download the installer unless you have a accurate system time. See the step above for enabling NTP if you have trouble downloading.

phyboard-electra-am64xx-2:~# cd ~
phyboard-electra-am64xx-2:~# mkdir ~/GreengrassInstaller
phyboard-electra-am64xx-2:~# wget https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
phyboard-electra-am64xx-2:~# unzip greengrass-nucleus-latest.zip -d ~/GreengrassInstaller && rm greengrass-nucleus-latest.zip

We can verify the version of the AWS IoT Greengrass Core software with the following:

phyboard-electra-am64xx-2:~# java -jar ./GreengrassInstaller/lib/Greengrass.jar --version

This is the time to decide your system’s device identifier and group. Run the installer with the following command, but replace “<thing-name>” and “<thing-group>” with strings specific to your application. For example, if you are a home appliance manufacturer and you are working on a new line of smart Fridges, you might use “fridgeThing1” for the Thing name, and “fridgeGroup” for the Thing group. This way you could potentially identify and troubleshoot specific Fridges, while also being able to roll out software updates to the entire fleet via the group.

Note

Note that AWS Greengrass devices are also referred to as “Things”, from the phrase “Internet-of-Things”, or as “core devices”.

In addition, the geographic region in which your device will operate will also need to be defined here. Amazon hosts AWS resources in multiple, isolated locations globally to keep those resources (compute and storage) as close to end users and devices as possible. Run the installer with the following command, but also replace the “<aws-region>” with the closest applicable region code.

Note

For more information on AWS regions, see: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html

If you are located in Seattle, WA USA then “us-west-2” is a good option, for example.

phyboard-electra-am64xx-2:~# sudo -E java -Droot="/greengrass/v2" -Dlog.storeILE -jar ./GreengrassInstaller/lib/Greengrass.jar --aws-region <aws-region> --thing-name <thing-name> --thing-group-name <thing-group> --component-default-user ggc_user --provision true --setup-system-service true --deploy-dev-tools true

Note

There are a lot of optional installer arguments, some of which are used here. The main one to point out is the use of the --deploy-dev-tools argument which has the installer automatically download and install the Greengrass CLI component to the core device. With this you can develop and test custom components directly on the phyCORE-AM64x.

Upon successful completion of the above command, you should have Greengrass Core running on your phyCORE-AM64x Development Kit. We can confirm this in a couple ways:

We should see a “greengrass” systemd service running. This service will now be enabled to start on every boot.

phyboard-electra-am64xx-2:~# systemctl status greengrass

If we pull up the AWS IoT console and navigate to All Devices -> Things, we should see the newly created device listed. Just be sure to select the correct region in the upper right corner of the console. This must be the same region that you used to setup the Thing, otherwise you will not see your device.

Greengrass components are software modules that run on Greengrass core devices. Components can represent applications, runtime installers, libraries, or any other code that you run on a device. For information on this process, see: https://docs.aws.amazon.com/greengrass/v2/developerguide/develop-greengrass-components.html

Create a Hello World Component

In the following steps, we will use the Greengrass CLI tool directly on the phyCORE-AM64x to create and deploy a local Greengrass component. These steps have been largely adapted from https://docs.aws.amazon.com/greengrass/v2/developerguide/getting-started.html#create-first-component

Create a folder for your local component, with subfolders for recipes and artifacts. Run the following commands on your Greengrass core device to create these folders and change to the component folder.
```
phyboard-electra-am64xx-2:~# mkdir -p ~/greengrassv2/{recipes,artifacts}
phyboard-electra-am64xx-2:~# cd ~/greengrassv2/
```
Create a recipe file that defines your component’s metadata, parameters, dependencies, lifecycle, and platform capability. Include the component version in the recipe file name so that you can identify which recipe reflects which component version. We will use JSON format here but YAML is also an option:
```
phyboard-electra-am64xx-2:~# vi recipes/com.example.HelloWorld-1.0.0.json
```
Edit the file to reflect the following contents before saving and closing the file:
recipes/com.example.HelloWorld-1.0.0.json
```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "My first AWS IoT Greengrass component.",
  "ComponentPublisher": "PHYTEC",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "Message": "world"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      }
    }
  ]
}
```
This recipe’s ComponentConfiguration section defines a parameter, Message, that defaults to world. The Manifests section defines a manifest, which is a set of lifecycle instructions and artifacts for a platform. You can define multiple manifests to specify different install instructions for various platforms, for example. In the manifest, the Lifecycle section instructs the Greengrass core device to run the Hello World script with the Message parameter value as an argument.
Run the following command to create a folder for the component artifacts.
Note

You must use the following format for the artifact folder path. Include the component name and version that you specify in the recipe.

Example artifact path
```
artifacts/<componentName>/<componentVersion>/
```
```
phyboard-electra-am64xx-2:~# mkdir -p artifacts/com.example.HelloWorld/1.0.0
```

Create a Python script artifact file for your Hello World component.

phyboard-electra-am64xx-2:~# vi artifacts/com.example.HelloWorld/1.0.0/hello_world.py

Edit the file to reflect the following contents before saving and closing the file:

artifacts/com.example.HelloWorld/1.0.0/hello_world.py

import sys

message = "Hello, %s!" % sys.argv[1]

# Print the message to stdout, which Greengrass saves in a log file.
print(message)

Use the local AWS IoT Greengrass CLI to create the component on your Greengrass core device:
```
phyboard-electra-am64xx-2:~# sudo /greengrass/v2/bin/greengrass-cli deployment create --recipeDir ~/greengrassv2/recipes/ --artifactDir ~/greengrassv2/artifacts/ --merge "com.example.HelloWorld=1.0.0"
```
This command adds the component that uses the recipe in recipes and the Python script in artifacts. The --merge option adds or updates the component and version that you specify.
The AWS IoT Greengrass Core software saves stdout from the component process to log files in the logs folder. Run the following command to verify that the Hello World component runs and prints messages:
```
phyboard-electra-am64xx-2:~# sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
```
You should see the following expected output somewhere in the log:

Expected Output
```
com.example.HelloWorld: stdout. Hello, world
```

The following can be used to remove the deployment:

phyboard-electra-am64xx-2:~# sudo /greengrass/v2/bin/greengrass-cli deployment create --remove="com.example.HelloWorld"

Upload Your Local Deployment

When you finish developing a component on your core device, you can upload it to the AWS IoT Greengrass service in the AWS Cloud. For steps on this process, please reference the AWS documentation: https://docs.aws.amazon.com/greengrass/v2/developerguide/getting-started.html#upload-first-component

Debugging and Troubleshooting

If you have issues building the BSP: Be sure to follow the Build the BSP guide exactly. Common issues encountered during this process often originate from the use of the wrong Host environment, which is Ubuntu 20.04. Other Linux distributions can be made to work with workarounds but using the same Host environment PHYTEC used to verify the BSP and the steps outlined in this guide will ensure you have the easiest time building the Yocto BSP.

Trouble booting your development kit? Follow the steps outlined in the Quickstart to help you set your boot switches correctly to boot from an SD Card. The green LED on the SOM is configured to blink with a “heartbeat” pattern once Linux boots. If you see this LED blinking but are getting no activity on the serial console, double check that your terminal is configured for 115200 Baud, 8 bit data, no parity bits, 1 stop bit and no flow control. If you continue having trouble, a good sanity-check is to boot PHYTEC’s default pre-built software image (without any custom modifications). Checkout the Pre-Built Binaries page for links to these pre-built binaries and refer to the SD Card guide to re-flash your SD Card if necessary.

If you have trouble installing Greengrass Core: Problems can occur if your core device isn’t connected to the internet, has an incorrect system time, or if the default user the component runs under (ie “ggc_user”) doesn’t have the correct permissions. Be sure that you ran through the steps outlined in this guide exactly.

If you have trouble creating the Helloworld Component: Run the following command on your core device to view the AWS IoT Greengrass Core software log file:

phyboard-electra-am64xx-2:~# sudo tail -f /greengrass/v2/logs/greengrass.log

This file includes logs from the Greengrass core device’s deployment service. You can also find logs for all the active components in the deployment here in the /greengrass/v2/logs directory as well. If the files here don’t exist, the local deployment may not be complete yet. If the file doesn’t exist within 15 seconds, the deployment likely failed. This can occur if your recipe isn’t valid, for example. Check the available log files for hints on what went wrong.

Note

For technical support, please visit PHYTEC’s Support Portal!