Create Amazon IoT Greengrass components
You can develop custom Amazon IoT Greengrass components on a local development computer or a Greengrass core device. Amazon IoT Greengrass provides the Amazon IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to help you create, build, and publish components from predefined component templates and community components. You can also run built-in shell commands to create, build, and publish components. Choose from the following options to create custom Greengrass components:
-
Use the Greengrass Development Kit CLI
Use the GDK CLI to develop components on a local development computer. The GDK CLI builds and packages component source code into a recipe and artifacts that you can publish as a private component to the Amazon IoT Greengrass service. You can configure the GDK CLI to automatically update the component's version and artifact URIs when you publish the component, so you don't need to update the recipe each time. To develop a component using the GDK CLI, you can start from a template or a community component from the Greengrass Software Catalog. For more information, see Amazon IoT Greengrass Development Kit Command-Line Interface.
-
Run built-in shell commands
You can run built-in shell commands to develop components on a local development computer or on a Greengrass core device. You use shell commands to copy or build component source code into artifacts. Each time you create a new version of a component, you must create or update the recipe with the new component version. When you publish the component to the Amazon IoT Greengrass service, you must update the URI to each component artifact in the recipe.
Create a component (GDK CLI)
Follow instructions in this section to create and build a component using the GDK CLI.
To develop a Greengrass component (GDK CLI)
-
If you haven't already, install the GDK CLI on your development computer. For more information, see Install or update the Amazon IoT Greengrass Development Kit Command-Line Interface.
-
Change to the folder where you want to create component folders.
-
Choose a component template or community component to download. The GDK CLI downloads the template or community component, so you can start from a functional example. Use the component list command to retrieve the list of available templates or community components.
-
To list component templates, run the following command. Each line in the response includes a template's name and programming language.
gdk component list --template
-
To list community components, run the following command.
gdk component list --repository
-
-
Create and change to a component folder where the GDK CLI downloads the template or community component. Replace
HelloWorld
with the name of the component, or another name that helps you identify this component folder. -
Download the template or community component to the current folder. Use the component init command.
-
To create a component folder from a template, run the following command. Replace
HelloWorld
with the name of the template, and replacepython
with the name of the programming language.gdk component init --template
HelloWorld
--languagepython
-
To create a component folder from a community component, run the following command. Replace
ComponentName
with the name of the community component.gdk component init --repository
ComponentName
Note
If you use GDK CLI v1.0.0, you must run this command in an empty folder. The GDK CLI downloads the template or community component to the current folder.
If you use GDK CLI v1.1.0 or later, you can specify the
--name
argument to specify the folder where the GDK CLI downloads the template or community component. If you use this argument, specify a folder that doesn't exist. The GDK CLI creates the folder for you. If you don't specify this argument, the GDK CLI uses the current folder, which must be empty. -
-
The GDK CLI reads from the GDK CLI configuration file, named
gdk-config.json
, to build and publish components. This configuration file exists in the root of the component folder. The previous step creates this file for you. In this step, you updategdk-config.json
with information about your component. Do the following:-
Open
gdk-config.json
in a text editor. -
(Optional) Change the name of the component. The component name is the key in the
component
object. -
Change the author of the component.
-
(Optional) Change the version of the component. Specify one of the following:
-
NEXT_PATCH
– When you choose this option, the GDK CLI sets the version when you publish the component. The GDK CLI queries the Amazon IoT Greengrass service to identify the latest published version of the component. Then, it sets the version to the next patch version after that version. If you haven't published the component before, the GDK CLI uses version1.0.0
.If you choose this option, you can't use the Greengrass CLI to locally deploy and test the component to your local development computer that runs the Amazon IoT Greengrass Core software. To enable local deployments, you must specify a semantic version instead.
-
A semantic version, such as
1.0.0
. Semantic versions use a major.minor.patch numbering system. For more information, see the semantic version specification. If you develop components on a Greengrass core device where you want to deploy and test the component, choose this option. You must build the component with a specific version to create local deployments with the Greengrass CLI.
-
-
(Optional) Change the build configuration for the component. The build configuration defines how the GDK CLI builds the component's source into artifacts. Choose from the following options for
build_system
:-
zip
– Packages the component's folder into a ZIP file to define as the component's only artifact. Choose this option for the following types of components:-
Components that use interpreted programming languages, such as Python or JavaScript.
-
Components that package files other than code, such as machine learning models or other resources.
The GDK CLI zips the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is
HelloWorld
, the GDK CLI creates a zip file namedHelloWorld.zip
.Note
If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters.
When the GDK CLI zips the component's folder into a zip file, it skips the following files:
-
The
gdk-config.json
file -
The recipe file (
recipe.json
orrecipe.yaml
) -
Build folders, such as
greengrass-build
-
-
maven
– Runs themvn clean package
command to build the component's source into artifacts. Choose this option for components that use Maven, such as Java components. On Windows devices, this feature is available for GDK CLI v1.1.0 and later.
-
gradle
– Runs thegradle build
command to build the component's source into artifacts. Choose this option for components that use Gradle. This feature is available for GDK CLI v1.1.0 and later. The
gradle
build system supports Kotlin DSL as the build file. This feature is available for GDK CLI v1.2.0 and later. -
gradlew
– Runs thegradlew
command to build the component's source into artifacts. Choose this option for components that use the Gradle Wrapper. This feature is available for GDK CLI v1.2.0 and later.
-
custom
– Runs a custom command to build the component's source into a recipe and artifacts. Specify the custom command in thecustom_build_command
parameter.
-
-
If you specify
custom
forbuild_system
, add thecustom_build_command
to thebuild
object. Incustom_build_command
, specify a single string or list of strings, where each string is a word in the command. For example, to run a custom build command for a C++ component, you might specify["cmake", "--build", "build", "--config", "Release"]
. -
If you use GDK CLI v1.1.0 or later, you can specify the
--bucket
argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is
, wherebucket
-region
-accountId
bucket
andregion
are the values that you specify ingdk-config.json
, andaccountId
is your Amazon Web Services account ID. The GDK CLI creates the bucket if it doesn't exist.Change the publish configuration for the component. Do the following:
-
Specify the name of the S3 bucket to use to host component artifacts.
-
Specify the Amazon Web Services Region where the GDK CLI publishes the component.
-
When you're done with this step, the
gdk-config.json
file might look similar to the following example.{ "component": { "com.example.PythonHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "zip" }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2" } } }, "gdk_version": "1.0.0" }
-
-
Update the component recipe file, named
recipe.yaml
orrecipe.json
. Do the following:-
If you downloaded a template or community component that uses the
zip
build system, check that the zip artifact name matches the name of the component folder. The GDK CLI zips the component folder into a zip file with the same name as the component folder. The recipe contains the zip artifact name in the list of component artifacts and in lifecycle scripts that use files in the zip artifact. Update theArtifacts
andLifecycle
definitions such that the zip file name matches the name of the component folder. The following partial recipe examples highlight the zip file name in theArtifacts
andLifecycle
definitions. -
(Optional) Update the component description, default configuration, artifacts, lifecycle scripts, and platform support. For more information, see Amazon IoT Greengrass component recipe reference.
When you're done with this step, the recipe file might look similar to the following examples.
-
-
Develop and build the Greengrass component. The component build command produces a recipe and artifacts in the
greengrass-build
folder in the component folder. Run the following command.gdk component build
When you're ready to test your component, use the GDK CLI to publish it to the Amazon IoT Greengrass service. Then, you can deploy the component to Greengrass core devices. For more information, see Publish components to deploy to your core devices.
Create a component (shell commands)
Follow instructions in this section to create recipe and artifact folders that contain source code and artifacts for multiple components.
To develop a Greengrass component (shell commands)
-
Create a folder for your components 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. Replace
~/greengrassv2
or%USERPROFILE%\greengrassv2
with the path to the folder to use for local development. -
Use a text editor to 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. You can choose YAML or JSON format for your recipe.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
Note
Amazon IoT Greengrass uses semantic versions for components. Semantic versions follow a major.minor.patch number system. For example, version
1.0.0
represents the first major release for a component. For more information, see the semantic version specification. -
Define the recipe for your component. For more information, see Amazon IoT Greengrass component recipe reference.
Your recipe might look similar to the following Hello World example recipe.
This recipe runs a Hello World Python script, which might look similar to the following example script.
import sys message = "Hello, %s!" % sys.argv[1] # Print the message to stdout, which Greengrass saves in a log file. print(message)
-
Create a folder for the component version to develop. We recommend that you use a separate folder for each component version's artifacts so that you can identify which artifacts are for each component version. Run the following command.
Important
You must use the following format for the artifact folder path. Include the component name and version that you specify in the recipe.
artifacts/
componentName
/componentVersion
/ -
Create the artifacts for your component in the folder that you created in the previous step. Artifacts can include software, images, and any other binaries that your component uses.
When your component is ready, test your component.