Step 4: Develop and test a component on your device - AWS IoT Greengrass

Step 4: Develop and test a component on your device

A component is a software module that runs on AWS IoT Greengrass core devices. Components enable you to create and manage complex applications as discrete building blocks that you can reuse from one Greengrass core device to another. Every component is composed of a recipe and artifacts.

  • Recipes

    Every component contains a recipe file, which defines its metadata. The recipe also specifies the component's configuration parameters, component dependencies, lifecycle, and platform compatibility. The component lifecycle defines the commands that install, run, and shut down the component. For more information, see AWS IoT Greengrass component recipe reference.

    You can define recipes in JSON or YAML format.

  • Artifacts

    Components can have any number of artifacts, which are component binaries. Artifacts can include scripts, compiled code, static resources, and any other files that a component consumes. Components can also consume artifacts from component dependencies.

With AWS IoT Greengrass, you can use the Greengrass CLI to develop and test components locally on a Greengrass core device without interaction with the AWS Cloud. When you complete your local component, you can use the component recipe and artifacts to create that component in the AWS IoT Greengrass service in the AWS Cloud, and then deploy it to all of your Greengrass core devices. For more information about components, see Develop AWS IoT Greengrass components.

In this section, you learn how to create and run a basic Hello World component locally on your core device.

To develop a Hello World component on your device
  1. 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.

    Linux or Unix
    mkdir -p ~/greengrassv2/{recipes,artifacts} cd ~/greengrassv2
    Windows Command Prompt (CMD)
    mkdir %USERPROFILE%\greengrassv2\\recipes, %USERPROFILE%\greengrassv2\\artifacts cd %USERPROFILE%\greengrassv2
    PowerShell
    mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts cd ~/greengrassv2
  2. 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.

    JSON
    nano recipes/com.example.HelloWorld-1.0.0.json
    YAML
    nano recipes/com.example.HelloWorld-1.0.0.yaml
    Note

    AWS 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.

  3. Paste the following recipe into the file.

    JSON
    { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.HelloWorld", "ComponentVersion": "1.0.0", "ComponentDescription": "My first AWS IoT Greengrass component.", "ComponentPublisher": "Amazon", "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}" } } ] }
    YAML
    --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.HelloWorld ComponentVersion: '1.0.0' ComponentDescription: My first AWS IoT Greengrass component. ComponentPublisher: Amazon 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.

  4. Run the following command to create a folder for the component artifacts.

    Linux or Unix
    mkdir -p artifacts/com.example.HelloWorld/1.0.0
    Windows Command Prompt (CMD)
    mkdir artifacts\com.example.HelloWorld\1.0.0
    PowerShell
    mkdir artifacts\com.example.HelloWorld\1.0.0
    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/
  5. Use a text editor to create a Python script artifact file for your Hello World component.

    For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

    nano artifacts/com.example.HelloWorld/1.0.0/hello_world.py

    Copy and paste the following Python script into the file.

    import sys message = "Hello, %s!" % sys.argv[1] # Print the message to stdout, which Greengrass saves in a log file. print(message)
  6. Use the local AWS IoT Greengrass CLI to manage components on your Greengrass core device.

    Run the following command to deploy the component to the AWS IoT Greengrass core. Replace /greengrass/v2 or C:\greengrass\v2 with your AWS IoT Greengrass V2 root folder, and replace ~/greengrassv2 or %USERPROFILE%\greengrassv2 with your component development folder.

    Linux or Unix
    sudo /greengrass/v2/bin/greengrass-cli deployment create \ --recipeDir ~/greengrassv2/recipes \ --artifactDir ~/greengrassv2/artifacts \ --merge "com.example.HelloWorld=1.0.0"
    Windows Command Prompt (CMD)
    C:\greengrass\v2\bin\greengrass-cli deployment create ^ --recipeDir %USERPROFILE%\greengrassv2\recipes ^ --artifactDir %USERPROFILE%\greengrassv2\artifacts ^ --merge "com.example.HelloWorld=1.0.0"
    PowerShell
    C:\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.

  7. The AWS IoT Greengrass Core software saves stdout from component process to log files in the logs folder. Run the following command to verify that the Hello World component runs and prints messages.

    Linux or Unix
    sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
    Windows Command Prompt (CMD)
    type C:\greengrass\v2\logs\com.example.HelloWorld.log

    The type command writes the file's contents to the terminal. Run this command multiple times to observe changes in the file.

    PowerShell
    gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait

    You should see messages similar to the following example.

    Hello, world!
    Note

    If the file doesn'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. Run the following command to view the AWS IoT Greengrass core log file. This file includes logs from the Greengrass core device's deployment service.

    Linux or Unix
    sudo tail -f /greengrass/v2/logs/greengrass.log
    Windows Command Prompt (CMD)
    type C:\greengrass\v2\logs\greengrass.log

    The type command writes the file's contents to the terminal. Run this command multiple times to observe changes in the file.

    PowerShell
    gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  8. Modify the local component to iterate and test your code. Open hello_world.py in a text editor, and add the following code at line 4 to edit the message that the AWS IoT Greengrass core logs.

    message += " Greetings from your first Greengrass component."

    The hello_world.py script should now have the following contents.

    import sys message = "Hello, %s!" % sys.argv[1] message += " Greetings from your first Greengrass component." # Print the message to stdout, which Greengrass saves in a log file. print(message)
  9. Run the following command to update the component with your changes.

    Linux or Unix
    sudo /greengrass/v2/bin/greengrass-cli deployment create \ --recipeDir ~/greengrassv2/recipes \ --artifactDir ~/greengrassv2/artifacts \ --merge "com.example.HelloWorld=1.0.0"
    Windows Command Prompt (CMD)
    C:\greengrass\v2\bin\greengrass-cli deployment create ^ --recipeDir %USERPROFILE%\greengrassv2\recipes ^ --artifactDir %USERPROFILE%\greengrassv2\artifacts ^ --merge "com.example.HelloWorld=1.0.0"
    PowerShell
    C:\greengrass\v2\bin\greengrass-cli deployment create ` --recipeDir ~/greengrassv2/recipes ` --artifactDir ~/greengrassv2/artifacts ` --merge "com.example.HelloWorld=1.0.0"

    This command updates the com.example.HelloWorld component with the latest Hello World artifact.

  10. Run the following command to restart the component. When you restart a component, the core device uses the latest changes.

    Linux or Unix
    sudo /greengrass/v2/bin/greengrass-cli component restart \ --names "com.example.HelloWorld"
    Windows Command Prompt (CMD)
    C:\greengrass\v2\bin\greengrass-cli component restart ^ --names "com.example.HelloWorld"
    PowerShell
    C:\greengrass\v2\bin\greengrass-cli component restart ` --names "com.example.HelloWorld"
  11. Check the log again to verify that the Hello World component prints the new message.

    Linux or Unix
    sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
    Windows Command Prompt (CMD)
    type C:\greengrass\v2\logs\com.example.HelloWorld.log

    The type command writes the file's contents to the terminal. Run this command multiple times to observe changes in the file.

    PowerShell
    gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait

    You should see messages similar to the following example.

    Hello, world! Greetings from your first Greengrass component.
  12. You can update the component's configuration parameters to test different configurations. When you deploy a component, you can specify a configuration update, which defines how to modify the component's configuration on the core device. You can specify which configuration values to reset to default values and the new configuration values to merge onto the core device. For more information, see Update component configurations.

    Do the following:

    1. Use a text editor to create a file called hello-world-config-update.json to contain the configuration update

      For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

      nano hello-world-config-update.json
    2. Copy and paste the following JSON object into the file. This JSON object defines a configuration update that merges the value friend to the Message parameter to update its value. This configuration update doesn't specify any values to reset. You don't need to reset the Message parameter because the merge update replaces the existing value.

      { "com.example.HelloWorld": { "MERGE": { "Message": "friend" } } }
    3. Run the following command to deploy the configuration update to the Hello World component.

      Linux or Unix
      sudo /greengrass/v2/bin/greengrass-cli deployment create \ --merge "com.example.HelloWorld=1.0.0" \ --update-config hello-world-config-update.json
      Windows Command Prompt (CMD)
      C:\greengrass\v2\bin\greengrass-cli deployment create ^ --merge "com.example.HelloWorld=1.0.0" ^ --update-config hello-world-config-update.json
      PowerShell
      C:\greengrass\v2\bin\greengrass-cli deployment create ` --merge "com.example.HelloWorld=1.0.0" ` --update-config hello-world-config-update.json
    4. Check the log again to verify that the Hello World component outputs the new message.

      Linux or Unix
      sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
      Windows Command Prompt (CMD)
      type C:\greengrass\v2\logs\com.example.HelloWorld.log

      The type command writes the file's contents to the terminal. Run this command multiple times to observe changes in the file.

      PowerShell
      gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait

      You should see messages similar to the following example.

      Hello, friend! Greetings from your first Greengrass component.
  13. After you finish testing your component, remove it from your core device. Run the following command.

    Linux or Unix
    sudo /greengrass/v2/bin/greengrass-cli deployment create --remove="com.example.HelloWorld"
    Windows Command Prompt (CMD)
    C:\greengrass\v2\bin\greengrass-cli deployment create --remove="com.example.HelloWorld"
    PowerShell
    C:\greengrass\v2\bin\greengrass-cli deployment create --remove="com.example.HelloWorld"
    Important

    This step is required for you to deploy the component back to the core device after you upload it to AWS IoT Greengrass. Otherwise, the deployment fails with a version compatibility error because the local deployment specifies a different version of the component.

    Run the following command and verify that the com.example.HelloWorld component doesn't appear in the list of components on your device.

    Linux or Unix
    sudo /greengrass/v2/bin/greengrass-cli component list
    Windows Command Prompt (CMD)
    C:\greengrass\v2\bin\greengrass-cli component list
    PowerShell
    C:\greengrass\v2\bin\greengrass-cli component list

Your Hello World component is complete, and you can now upload it to the AWS IoT Greengrass cloud service. Then, you can deploy the component to Greengrass core devices.