Is this page helpful?

Getting Started with AWS IoT GreengrassV2 for Torizon

Introduction

As a participant of the AWS Partner Network, Toradex offers products qualified under the AWS Device Qualification Program (DQP). See the current Toradex products under the DQP in the AWS Partner Device Catalog.

This article introduces the first steps to run AWS IoT GreengrassV2 software in Toradex modules with Torizon OS. You can run AWS IoT GreengrassV2 in a Docker container. To learn more about AWS IoT GreengrassV2, see how it works and what's new.

This article complies with the Typographic Conventions for Toradex Documentation.

Prerequisites

• Compatible Toradex System on Module (SoM) with Torizon OS installed:
  • Maivin (see the Datasheet) or
  • Verdin iMX8M Plus with a Verdin Development Board.
• If using Maivin, follow the Maivin AI Quick Start Guide
• Follow the Torizon Quick Start Guide
• Make sure to have Configured Build Environment for Torizon Containers.
• An Amazon Web Services (AWS) account. If you don't have one, see Create an AWS Account.
• To use an AWS Region that supports AWS IoT GreengrassV2. For the list of supported regions for AWS IoT GreengrassV2, see AWS Regions and Endpoints in the AWS General Reference.

GreengrassV2 Setup

AWS Setup

Setup your AWS account and Permissions

Refer to the instructions at Set up your AWS Account. Follow the steps outlined in these sections to create your account and a user and get started:

• Sign up for an AWS account.
• Create a user and grant permissions.
• Open the AWS IoT console.

Install the AWS Command Line Interface

To install the AWS CLI on your host machine, refer to the instructions at Installing the AWS CLI v2. Installing the CLI is needed to complete the instructions in this guide.

Once you have installed AWS CLI, configure it as per the instructions in this online guide. Set the appropriate values for Access key ID, Secret access key, and AWS Region. It is recommended set Output format to "json" if you prefer.

Build and deploy Docker image with GreengrassV2

Build the Docker image

You need a properly configured Dockerfile to build the docker image with GreengrassV2. The following Dockerfile should be used as a base, but make sure to customize it according to your application needs.

Dockerfile

## Get base image
FROM --platform=linux/arm64 torizon/wayland-base-vivante:2

## Set build arguments
ARG GREENGRASS_RELEASE_VERSION=2.6.0
ARG GREENGRASS_ZIP_FILE=greengrass-${GREENGRASS_RELEASE_VERSION}.zip
ARG GREENGRASS_RELEASE_URI=https://d2s8p88vqu9w66.cloudfront.net/releases/${GREENGRASS_ZIP_FILE}

## Set environment variables for entrypoint
ENV TINI_KILL_PROCESS_GROUP=1 \ 
    GGC_ROOT_PATH=/greengrass/v2 

## Clean apt cache
RUN apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*

## Rename torizon user to ggc_user and create home folder
RUN usermod -l ggc_user torizon
RUN groupmod --new-name ggc_group torizon
RUN rm -r /home/torizon
RUN mkdir /home/ggc_user
RUN chown -R ggc_user:ggc_group /home/ggc_user
RUN mkdir /opt/greengrassv2
RUN chown -R ggc_user:ggc_group /opt/greengrassv2
RUN mkdir /greengrass
RUN chown -R ggc_user:ggc_group /greengrass

## Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
  unzip && \
  apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*

## Install greengrassv2 dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
  default-jre sudo python3 tar unzip wget procps \
  ca-certificates curl gnupg lsb-release && \
  apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*

## Install Docker
RUN mkdir -p /etc/apt/keyrings && \
    curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

## Setup user 
WORKDIR /home/ggc_user
USER ggc_user:ggc_group

## Download and unzip Greengrass v2
RUN wget -q $GREENGRASS_RELEASE_URI
RUN unzip ${GREENGRASS_ZIP_FILE} -d /opt/greengrassv2 && rm ${GREENGRASS_ZIP_FILE}

## Download and configure greengrassv2 entrypoint
RUN wget -q https://github.com/aws-greengrass/aws-greengrass-docker/raw/v2.5.3/greengrass-entrypoint.sh
RUN chmod +x greengrass-entrypoint.sh

ENTRYPOINT ["/home/ggc_user/greengrass-entrypoint.sh"]

With the Dockerfile in your build environment, run:

$ docker build -t <image-tag> .

Push the Docker image to a registry

Make sure to be logged in in your docker registry and push the image to it:

$ docker push <image-tag>

Deploy the Docker image to the device

You will need a docker-compose.yml file in your device to deploy the docker image.

danger

Please, note that by using the following docker-compose.yml with ACCEPT_FSL_EULA=1 you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

docker-compose.yml

version: '3.8'

services:
  greengrass:
    init: false
    container_name: aws-iot-greengrass
    image: <image-tag>
    network_mode: "host"
    environment:
      - THING_NAME=default_thing_name
      - THING_GROUP_NAME=default_thing_group_name
      - TES_ROLE_NAME=default_tes_role_name
      - TES_ROLE_ALIAS_NAME=default_tes_role_alias_name
      - COMPONENT_DEFAULT_USER=default_component_user
      - THING_POLICY_NAME=default_thing_policy_name
      - TRUSTED_PLUGIN=default_trusted_plugin_path
      - INIT_CONFIG=default_init_config
      - PROVISION=true
      - DEPLOY_DEV_TOOLS=true
      - ACCEPT_FSL_EULA=1
      - AWS_REGION=<aws-region>
      - AWS_ACCESS_KEY_ID=<access-key-id>
      - AWS_SECRET_ACCESS_KEY=<secret-access-key>
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Make sure to fill in the information in the above docker-compose.yml file:

• <image-tag>: The image tag that was used during the build step.
• <aws-region>: Your chosen AWS region.
• <access-key-id>: Your AWS access key ID, available in the ~/.aws/credentials file, from your host machine.
• <secret-access-key>: Your AWS secret access key, available in the ~/.aws/credentials file, from your host machine. Please see the note below.

note

The credentials used by the AWS CLI are stored in plain text files and are not encrypted. It is strongly recommended that you configure file system permissions on the $HOME/.aws folder and its child folders and files to restrict access to only authorized users. Use roles with temporary credentials wherever possible to reduce the opportunity for damage if the credentials are compromised. Use long-term credentials only to request and refresh short-term role credentials.

To configure the GreengrassV2 installer arguments, you can refer to Installer Arguments and change the following values on the docker-compose.yml file:

• THING_NAME: If not left as default_thing_name, the value is passed as the --thing-name argument.
• THING_GROUP_NAME: If not left as default_thing_group_name, the value is passed as the --thing-group-name argument.
• TES_ROLE_NAME: If not left as default_tes_role_name, the value is passed as the --tes-role-name argument.
• TES_ROLE_ALIAS_NAME: If not left as default_tes_role_alias_name, the value is passed as the --tes-role-alias-name argument.
• COMPONENT_DEFAULT_USER: If not left as default_component_user, the value is passed as the --component-default-user argument. Do not change this argument unless you also change the user and group in the Dockerfile.
• THING_POLICY_NAME: If not left as default_thing_policy_name, the value is passed as the --thing-policy-name argument.
• TRUSTED_PLUGIN: If not left as default_trusted_plugin_path, the value is passed as the --trusted-plugin argument.
• INIT_CONFIG: If not left as default_init_config, the value is passed as the --init-config argument.

You can also change the field init: false to init: true, if you want to setup the GreengrassV2 container to auto-start.

To run the image:

1. Use SSH to access your device.
2. Copy the configured docker-compose.yml to /home/torizon on your device with scp.
3. Run:

# docker-compose up

You should see an output similar to:

Creating aws-iot-greengrass ... done
Attaching to aws-iot-greengrasss
aws-iot-greengrass | Installing Greengrass for the first time...
aws-iot-greengrass | Running Greengrass with the following options: -Droot=/greengrass/v2 -Dlog.store=FILE -Dlog.level= -jar /opt/greengrassv2/lib/Greengrass.jar --provision true --deploy-dev-tools true --aws-region <aws-region> --start false
aws-iot-greengrass | Provisioning AWS IoT resources for the device with IoT Thing Name: [CORE_DEVICE_THING_NAME]...
aws-iot-greengrass | Creating new IoT policy "GreengrassV2IoTThingPolicy"
aws-iot-greengrass | Creating keys and certificate...
aws-iot-greengrass | Attaching policy to certificate...
aws-iot-greengrass | Creating IoT Thing "CORE_DEVICE_THING_NAME"...
aws-iot-greengrass | Attaching certificate to IoT thing...
aws-iot-greengrass | Successfully provisioned AWS IoT resources for the device with IoT Thing Name: [CORE_DEVICE_THING_NAME]!
aws-iot-greengrass | Setting up resources for aws.greengrass.TokenExchangeService ... 
aws-iot-greengrass | TES role alias "GreengrassV2TokenExchangeRoleAlias" does not exist, creating new alias...
aws-iot-greengrass | TES role "GreengrassV2TokenExchangeRole" does not exist, creating role...
aws-iot-greengrass | IoT role policy "GreengrassTESCertificatePolicyGreengrassV2TokenExchangeRoleAlias" for TES Role alias not exist, creating policy...
aws-iot-greengrass | Attaching TES role policy to IoT thing...
aws-iot-greengrass | No managed IAM policy found, looking for user defined policy...
aws-iot-greengrass | No IAM policy found, will attempt creating one...
aws-iot-greengrass | IAM role policy for TES "GreengrassV2TokenExchangeRoleAccess" created. This policy DOES NOT have S3 access, please modify it with your private components' artifact buckets/objects as needed when you create and deploy private components 
aws-iot-greengrass | Attaching IAM role policy for TES to IAM role for TES...
aws-iot-greengrass | Configuring Nucleus with provisioned resource details...
aws-iot-greengrass | Downloading Root CA from "https://www.amazontrust.com/repository/AmazonRootCA1.pem"
aws-iot-greengrass | Created device configuration
aws-iot-greengrass | Successfully configured Nucleus with provisioned resource details!
aws-iot-greengrass | Creating a deployment for Greengrass first party components to the device
aws-iot-greengrass | Configured Nucleus to deploy aws.greengrass.Cli component
aws-iot-greengrass | Nucleus start set to false, exiting...
aws-iot-greengrass | Making loader script executable...
aws-iot-greengrass | Starting Greengrass...
...
aws-iot-greengrass | Launching Nucleus...
aws-iot-greengrass | Launched Nucleus successfully.

Please take note of your CORE_DEVICE_THING_NAME that is shown in the output.

Verify Deployment

It can take some time for the deployment to be done, to check its status, run on your host machine:

$ aws greengrassv2 list-effective-deployments --core-device-thing-name CORE_DEVICE_THING_NAME

Once the deployment is complete, you should see an output similar to:

{
    "effectiveDeployments": [
        {
            "deploymentId": "...",
            "deploymentName": "Deployment for CORE_DEVICE_THING_NAME",
            "iotJobId": "...",
            "targetArn": "arn:aws:iot:<aws-region>:...:thing/CORE_DEVICE_THING_NAME",
            "coreDeviceExecutionStatus": "COMPLETED",
            "reason": "SUCCESSFUL",
            "creationTimestamp": "...",
            "modifiedTimestamp": "..."
        }
    ]
}

Debugging and logging

View logs

After verifying that the GreengrassV2 deployment was successful, you need to attach a terminal to the container. To do that:

1. Open another SSH connection to your device.
2. Run:

# docker exec -it aws-iot-greengrass bash

At this point you will be in a shell within the GreengrassV2 container and have access to the Greengrass CLI. To verify this, run:

## /greengrass/v2/bin/greengrass-cli help
Greengrass command line interface

      --ggcRootPath=<ggcRootPath>
                  The AWS IoT Greengrass V2 root directory.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help                Show help information for a command.
  component           Retrieve component information and stop or restart
                        components.
  deployment          Create local deployments and retrieve deployment status.
  logs                Analyze Greengrass logs.
  get-debug-password  Generate a password for use with the HTTP debug view
                        component.

To view the logs, run:

## /greengrass/v2/bin/greengrass-cli logs get -ld /greengrass/v2/logs
...

Change log level

To change the log level, set the environment variable LOG_LEVEL in your docker-compose.yml file in the Deploy the Docker image to the device step:

docker-compose.yml

    environment:
      ...
      - LOG_LEVEL=<log-level>

Further Reading

• Greengrass CLI
• Build the AWS IoT Greengrass container image from a Dockerfile
• Run AWS IoT Greengrass Core software in a Docker container
• Running AWS IoT Greengrass V2 in a Docker Container (Repository)
• Greengrass feature compatibility by operating system