AWS IoT Greengrass V2 Quickstart - UNTESTED

Revision History
Document Version	Date	Description of change
v1.0	1/17/2023	Initial version of AWS IoT Greengrass guide targeting the phyCORE-AM62Ax SOM running BSP-Yocto-TISDK-AM62Ax-ALPHA1 based Linux.
v2.0	4/19/2023	Updated the AWS IoT Greengrass guide for the phyCORE-AM62Ax SOM running BSP-Yocto-AM62Ax-ALPHA1 based Linux.

The phyCORE®-AM62Ax is a scalable system on module designed to be deployed in a wide variety of embedded applications from edge computing devices to industrial HMIs and to headless gateways. Measuring in at 43mm x 32mm, it’s one of PHYTEC’s smallest SOMs to date. The compact form factor, available with board-to-board connectors as well as a direct solder variant, has an extensive 240-pin interconnect supporting common protocols such as Ethernet, CAN, UART, I2C, SPI but also rich multimedia with dual display, MIPI CSI-2 camera, and audio. AWS IoT Greengrass is an excellent solution for your phyCORE-AM62Ax SOM to connect your edge devices to the cloud.

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

Note

BSP-Yocto-AM62Ax-ALPHA1 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-AM62Ax-ALPHA1 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-AM62Ax development kit. This includes:
- phyCORE-AM62Ax System on Module, PL1573 (PCM-075)
- phyBOARD-AM62Ax (Lyra) Carrier Board, PL1576 (PBA-C-24)
- Micro-USB cable
- Ethernet cable
- Two 2x5 .1” header to DB9 cables
- Pre-flashed Bootable SD Card (BSP-Yocto-AM62Ax-ALPHA1)
- 12V/2A USB-C Power Supply
- 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-AM62Ax-ALPHA1 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 (Ubuntu)

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

Now we can enable meta-java as a active layer in our build configuration:

Host (Ubuntu)

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-qt5demo-image (these aren’t included by default).

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

conf/local.conf

IMAGE_INSTALL_append = " nodejs ntpdate openjdk-8"

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

Host (Ubuntu)

bitbake phytec-qt5demo-image

Booting the Resulting Image

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

A good, quick reference on booting your phyCORE-AM62Ax development kit into Linux from an SD Card can be found in the Quickstart.

Setting Up the Hardware

Once you have booted your phyCORE-AM62Ax 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-AM62Ax development kit must have a valid network connection. Checkout the Ethernet guide to help you with this.

Enable the Network Time Protocol (NTP) such that your system time is correct:

Note

NTP will be enabled by default in a future release. According to the default steps outlined in this guide, currently you will need to manually enable NTP on every boot. An accurate system time is necessary in order for AWS IoT Greengrass to work properly.

Target (Linux)

ntpdate pool.ntp.org

Once that completes, we can quickly double check the system time with the following command (note that the time is shown in UTC time):

Target (Linux)

date

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

Target (Linux)

useradd --system --create-home ggc_user
usermod -aG root ggc_user

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

Target (Linux)

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.

AWS Account

Note

This section is intended as a simple quickstart into AWS IoT Greengrass and its integration into PHYTEC’s phyCORE-AM62Ax development kit and any potential production systems that employ the phyCORE-AM62Ax 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-AM62Ax 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-AM62Ax serial console (you need to run these commands with your specific keys!):

Target (Linux)

export AWS_ACCESS_KEY_ID=<REPLACE-WITH-YOUR-ACCESS-KEY>
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.

Target (Linux)

cd ~
mkdir ~/GreengrassInstaller
wget https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
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:

Target (Linux)

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.

Target (Linux)

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 deploy the Greengrass CLI component to the core device. With this you can develop and test custom components directly on the phyCORE-AM62Ax.

Upon successful completion of the above command, you should have Greengrass Core running on your phyCORE-AM62Ax 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 automatically.

Target (Linux)

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.

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, 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-AM62Ax 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.
Target (Linux)
```
mkdir -p ~/greengrassv2/{recipes,artifacts}
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:
Target (Linux)
```
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>/

Target (Linux)

mkdir -p artifacts/com.example.HelloWorld/1.0.0

Create a Python script artifact file for your Hello World component.
Target (Linux)
```
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:
Target (Linux)
```
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:
Target (Linux)
```
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:

Target (Linux)

sudo /greengrass/v2/bin/greengrass-cli deployment create --remove="com.example.HelloWorld"

Note

Target (Linux)

sudo tail -f /greengrass/v2/logs/greengrass.log

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:

Target (Linux)

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!