Create AWS IoT Greengrass components

If you haven't already, install the GDK CLI on your development computer. For more information, see Install or update the AWS 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 replace python with the name of the programming language.

  gdk component init --template HelloWorld --language python

• 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

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 update gdk-config.json with information about your component. Do the following:

1. Open gdk-config.json in a text editor.

2. (Optional) Change the name of the component. The component name is the key in the component object.

3. Change the author of the component.

4. (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 AWS 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 version 1.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 AWS 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.

5. (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 named HelloWorld.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 or recipe.yaml)

     • Build folders, such as greengrass-build

   • maven – Runs the mvn 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 the gradle 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 the gradlew 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 the custom_build_command parameter.

6. If you specify custom for build_system, add the custom_build_command to the build object. In custom_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"].

7. 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 bucket-region-accountId, where bucket and region are the values that you specify in gdk-config.json, and accountId is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.

   Change the publish configuration for the component. Do the following:

   1. Specify the name of the S3 bucket to use to host component artifacts.

   2. Specify the AWS 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 or recipe.json. Do the following:

1. 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 the Artifacts and Lifecycle 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 the Artifacts and Lifecycle definitions.

   JSON

   {
     ...
     "Manifests": [
       {
         "Platform": {
           "os": "all"
         },
         "Artifacts": [
           {
             "URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
             "Unarchive": "ZIP"
           }
         ],
         "Lifecycle": {
           "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
         }
       }
     ]
   }

   YAML

   ---
   ...
   Manifests:
     - Platform:
         os: all
       Artifacts:
         - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
           Unarchive: ZIP
       Lifecycle:
         Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"

2. (Optional) Update the component description, default configuration, artifacts, lifecycle scripts, and platform support. For more information, see AWS 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

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.

Define the recipe for your component. For more information, see AWS 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.

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.