Amazon IoT Greengrass Development Kit Command-Line Interface - Amazon IoT Greengrass
PrerequisitesChangelog
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Development Kit Command-Line Interface

The Amazon IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides features that help you develop custom Greengrass components. You can use the GDK CLI to create, build, and publish custom components. When you create a component repository with the GDK CLI, you can start from a template or a community component from the Greengrass Software Catalog. Then, you can choose a build system that packages files as ZIP archives, uses a Maven or Gradle build script, or runs a custom build command. After you create a component, you can use the GDK CLI to publish it to the Amazon IoT Greengrass service, so you can use the Amazon IoT Greengrass console or API to deploy the component to your Greengrass core devices.

When you develop Greengrass components without the GDK CLI, you must update the version and artifact URIs in the component recipe file each time you create a new version of the component. When you use the GDK CLI, it can automatically update the version and artifact URIs for you each time you publish a new version of the component.

The GDK CLI is open source and available on GitHub. You can customize and extend the GDK CLI to meet your component development needs. We invite you to open issues and pull requests on the GitHub repository. You can find the GDK CLI source at the following link: https://github.com/aws-greengrass/aws-greengrass-gdk-cli.

Prerequisites

To install and use the Greengrass Development Kit CLI, you need the following:

  • An Amazon Web Services account. If you don't have one, see Set up an Amazon Web Services account.

  • A Windows, macOS, or Unix-like development computer with an internet connection.

  • For GDK CLI version 1.1.0 or later, Python 3.6 or later installed on your development computer.

    For GDK CLI version 1.0.0, Python 3.8 or later installed on your development computer.

  • Git installed on your development computer.

  • Amazon Command Line Interface (Amazon CLI) installed and configured with credentials on your development computer. For more information, see Installing, updating, and uninstalling the Amazon CLI and Configuring the Amazon CLI in the Amazon Command Line Interface User Guide.

    Note

    If you use a Raspberry Pi or another 32-bit ARM device, install Amazon CLI V1. Amazon CLI V2 isn't available for 32-bit ARM devices. For more information, see Installing, updating, and uninstalling the Amazon CLI version 1.

  • To use the GDK CLI to publish components to the Amazon IoT Greengrass service, you must have the following permissions:

    • s3:CreateBucket

    • s3:PutObject

    • greengrass:CreateComponentVersion

    • greengrass:ListComponentVersions

  • To use the GDK CLI to build a component whose artifacts exist in an S3 bucket and not in the local file system, you must have the s3:ListBucket permission.

    This feature is available for GDK CLI v1.1.0 and later.

Changelog

The following table describes the changes in each version of the GDK CLI. For more information, see the GDK CLI Releases page on GitHub.

Version

Changes
1.2.1
Bug fixes and improvements

  • Accepts the Canada (Central) (ca-central-1) Amazon Web Services Region in the region configuration entry in the gdk-config.json file.

  • Fixes issues with the --region GDK CLI argument to the publish command.
1.2.0
New features

  • Adds the options entry to the build configuration in the GDK CLI configuration file. Supports exclude under options to exclude certain files from the zip artifact when using the zip build system.

  • Adds the gradlew build system to use Gradle Wrapper to build components.

  • Adds support for Kotlin DSL build files for the gradle build option.

  • Adds an options entry to the publish configuration in the GDK CLI configuration file. Supports the file_upload_args under options to provide extra arguments when uploading files to Amazon S3.

Bug fixes and improvements

  • Fixes an issue where Gradle builds didn't clean before running a build command.

  • Fixes an issue where the build didn't exit when the build command fails.

  • Improves the output format of the gdk component list command.

1.1.0
New features

  • Adds support for the Gradle build system.

  • Adds support for the Maven build system on Windows devices.

  • Adds the --bucket argument to the component publish command. You can use this argument to specify the exact bucket where the GDK CLI uploads component artifacts.

  • Adds the --name argument to the component init command. You can use this option to specify the folder where the GDK CLI initializes the component.

  • Adds support for component artifacts that exist in an S3 bucket but not in the local component build folder. You can use this feature to reduce bandwidth costs for large component artifacts, such as machine learning models.

Bug fixes and improvements

  • Updates the component publish command to check if the component is built before it publishes the component. If the component isn't built, this command now builds the component for you.

  • Fixes an issue where the zip build system fails to build on Windows devices when the ZIP file name contains capital letters.

  • Improves the log message format and changes the default log level to INFO on devices that run Python versions earlier than 3.8.

  • Changes the minimum Python version requirement to Python 3.6.

1.0.0

Initial version.