Tutorial: Develop a Greengrass component that defers component updates

On your development computer, run the following command to install the latest version of the GDK CLI from its GitHub repository.

python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.0

Run the following command to verify that the GDK CLI installed successfully.

gdk --help

If the gdk command isn't found, add its folder to PATH.

On your development computer, create a folder for the component source code.

mkdir com.example.BatteryAwareHelloWorld
cd com.example.BatteryAwareHelloWorld

Use a text editor to create a file named gdk-config.json. 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.

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

nano gdk-config.json

Copy the following JSON into the file.

{
  "component": {
    "com.example.BatteryAwareHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "zip"
      },
      "publish": {
        "region": "us-west-2",
        "bucket": "greengrass-component-artifacts"
      }
    }
  },
  "gdk_version": "1.0.0"
}

The configuration file specifies the following:

Use a text editor to create the component source code in a file named main.py.

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

nano main.py

Copy the following Python code into the file.

import json
import os
import sys
import time
import traceback

from pathlib import Path

from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2

HELLO_WORLD_PRINT_INTERVAL = 15  # Seconds
DEFER_COMPONENT_UPDATE_INTERVAL = 30 * 1000  # Milliseconds


class BatteryAwareHelloWorldPrinter():
    def __init__(self, ipc_client: GreengrassCoreIPCClientV2, battery_file_path: Path, battery_threshold: float):
        self.battery_file_path = battery_file_path
        self.battery_threshold = battery_threshold
        self.ipc_client = ipc_client
        self.subscription_operation = None

    def on_component_update_event(self, event):
        try:
            if event.pre_update_event is not None:
                if self.is_battery_below_threshold():
                    self.defer_update(event.pre_update_event.deployment_id)
                    print('Deferred update for deployment %s' %
                          event.pre_update_event.deployment_id)
                else:
                    self.acknowledge_update(
                        event.pre_update_event.deployment_id)
                    print('Acknowledged update for deployment %s' %
                          event.pre_update_event.deployment_id)
            elif event.post_update_event is not None:
                print('Applied update for deployment')
        except:
            traceback.print_exc()

    def subscribe_to_component_updates(self):
        if self.subscription_operation == None:
            # SubscribeToComponentUpdates returns a tuple with the response and the operation.
            _, self.subscription_operation = self.ipc_client.subscribe_to_component_updates(
                on_stream_event=self.on_component_update_event)

    def close_subscription(self):
        if self.subscription_operation is not None:
            self.subscription_operation.close()
            self.subscription_operation = None

    def defer_update(self, deployment_id):
        self.ipc_client.defer_component_update(
            deployment_id=deployment_id, recheck_after_ms=DEFER_COMPONENT_UPDATE_INTERVAL)

    def acknowledge_update(self, deployment_id):
        # Specify recheck_after_ms=0 to acknowledge a component update.
        self.ipc_client.defer_component_update(
            deployment_id=deployment_id, recheck_after_ms=0)

    def is_battery_below_threshold(self):
        return self.get_battery_level() < self.battery_threshold

    def get_battery_level(self):
        # Read the battery level from the virtual battery level file.
        with self.battery_file_path.open('r') as f:
            data = json.load(f)
            return float(data['battery_level'])

    def print_message(self):
        message = 'Hello, World!'
        if self.is_battery_below_threshold():
            message += ' Battery level (%d) is below threshold (%d), so the component will defer updates' % (
                self.get_battery_level(), self.battery_threshold)
        else:
            message += ' Battery level (%d) is above threshold (%d), so the component will acknowledge updates' % (
                self.get_battery_level(), self.battery_threshold)
        print(message)


def main():
    # Read the battery threshold and virtual battery file path from command-line args.
    args = sys.argv[1:]
    battery_threshold = float(args[0])
    battery_file_path = Path(args[1])
    print('Reading battery level from %s and deferring updates when below %d' % (
        str(battery_file_path), battery_threshold))

    try:
        # Create an IPC client and a Hello World printer that defers component updates.
        ipc_client = GreengrassCoreIPCClientV2()
        hello_world_printer = BatteryAwareHelloWorldPrinter(
            ipc_client, battery_file_path, battery_threshold)
        hello_world_printer.subscribe_to_component_updates()
        try:
            # Keep the main thread alive, or the process will exit.
            while True:
                hello_world_printer.print_message()
                time.sleep(HELLO_WORLD_PRINT_INTERVAL)
        except InterruptedError:
            print('Subscription interrupted')
        hello_world_printer.close_subscription()
    except Exception:
        print('Exception occurred', file=sys.stderr)
        traceback.print_exc()
        exit(1)


if __name__ == '__main__':
    main()

This Python application does the following:

Use a text editor to create the component recipe in a file named recipe.json or recipe.yaml. The component recipe defines the component's metadata, default configuration parameters, and platform-specific lifecycle scripts.

This recipe specifies the following:

For more information about component recipes, see AWS IoT Greengrass component recipe reference.

Run the following command to build the component using the GDK CLI. The component build command creates a recipe and artifacts based on the GDK CLI configuration file. In this process, the GDK CLI creates a ZIP file that contains the component's source code.

gdk component build

You should see messages similar to the following example.

[2022-04-28 11:20:16] INFO - Getting project configuration from gdk-config.json
[2022-04-28 11:20:16] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2022-04-28 11:20:16] INFO - Building the component 'com.example.BatteryAwareHelloWorld' with the given project configuration.
[2022-04-28 11:20:16] INFO - Using 'zip' build system to build the component.
[2022-04-28 11:20:16] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'.
[2022-04-28 11:20:16] INFO - Zipping source code files of the component.
[2022-04-28 11:20:16] INFO - Copying over the build artifacts to the greengrass component artifacts build folder.
[2022-04-28 11:20:16] INFO - Updating artifact URIs in the recipe.
[2022-04-28 11:20:16] INFO - Creating component recipe in 'C:\Users\finthomp\greengrassv2\com.example.BatteryAwareHelloWorld\greengrass-build\recipes'.

Run the following command to publish the component to the AWS IoT Greengrass cloud service. The component publish command uploads the component's ZIP file artifact to an S3 bucket. Then, it updates the ZIP file's S3 URI in the component recipe and uploads the recipe to the AWS IoT Greengrass service. In this process, the GDK CLI checks what version of the Hello World component is already available in the AWS IoT Greengrass cloud service, so it can choose the next patch version after that version. If the component doesn't exist yet, the GDK CLI uses version 1.0.0.

gdk component publish

You should see messages similar to the following example. The output tells you the version of the component that the GDK CLI created.

[2022-04-28 11:20:29] INFO - Getting project configuration from gdk-config.json
[2022-04-28 11:20:29] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2022-04-28 11:20:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials
[2022-04-28 11:20:30] INFO - No private version of the component 'com.example.BatteryAwareHelloWorld' exist in the account. Using '1.0.0' as the next version to create.
[2022-04-28 11:20:30] INFO - Publishing the component 'com.example.BatteryAwareHelloWorld' with the given project configuration.
[2022-04-28 11:20:30] INFO - Uploading the component built artifacts to s3 bucket.
[2022-04-28 11:20:30] INFO - Uploading component artifacts to S3 bucket: greengrass-component-artifacts-us-west-2-123456789012. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html.
[2022-04-28 11:20:30] INFO - Not creating an artifacts bucket as it already exists.
[2022-04-28 11:20:30] INFO - Updating the component recipe com.example.BatteryAwareHelloWorld-1.0.0.
[2022-04-28 11:20:31] INFO - Creating a new greengrass component com.example.BatteryAwareHelloWorld-1.0.0
[2022-04-28 11:20:31] INFO - Created private version '1.0.0' of the component in the account.'com.example.BatteryAwareHelloWorld'.

Copy the S3 bucket name from the output. You use the bucket name later to allow the core device to download component artifacts from this bucket.

(Optional) View the component in the AWS IoT Greengrass console to verify that it uploaded successfully. Do the following:

1. In the AWS IoT Greengrass console navigation menu, choose Components.

2. On the Components page, choose the My components tab, and then choose com.example.BatteryAwareHelloWorld.

   On this page, you can see the component's recipe and other information about the component.

Allow the core device to access component artifacts in the S3 bucket.

Each core device has a core device IAM role that allows it to interact with AWS IoT and send logs to the AWS Cloud. This device role doesn't allow access to S3 buckets by default, so you must create and attach a policy that allows the core device to retrieve component artifacts from the S3 bucket.

If your device's role already allows access to the S3 bucket, you can skip this step. Otherwise, create an IAM policy that allows access and attach it to the role, as follows:

1. In the IAM console navigation menu, choose Policies, and then choose Create policy.

2. On the JSON tab, replace the placeholder content with the following policy. Replace greengrass-component-artifacts-us-west-2-123456789012 with the name of the S3 bucket where the GDK CLI uploaded the component's artifacts.

   For example, if you specified greengrass-component-artifacts and us-west-2 in the GDK CLI configuration file, and your AWS account ID is 123456789012, the GDK CLI uses the S3 bucket named greengrass-component-artifacts-us-west-2-123456789012.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:GetObject"
         ],
         "Resource": "arn:aws:s3:::greengrass-component-artifacts-us-west-2-123456789012/*"
       }
     ]
   }

3. Choose Next.

4. In the Policy details section, for Name, enter MyGreengrassV2ComponentArtifactPolicy.

5. Choose Create policy.

6. In the IAM console navigation menu, choose Role, and then choose the name of the role for the core device. You specified this role name when you installed the AWS IoT Greengrass Core software. If you did not specify a name, the default is GreengrassV2TokenExchangeRole.

7. Under Permissions, choose Add permissions, then choose Attach policies.

8. On the Add permissions page, select the check box next to the MyGreengrassV2ComponentArtifactPolicy policy that you created, and then choose Add permissions.

Use a text editor to create a virtual battery level file. This file imitates a real battery.

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

sudo nano /home/ggc_user/virtual_battery.json

Copy the following JSON into the file.

{
  "battery_level": 50
}

Deploy the Hello World component to the core device. Do the following:

1. In the AWS IoT Greengrass console navigation menu, choose Components.

2. On the Components page, choose the My components tab, and then choose com.example.BatteryAwareHelloWorld.

3. On the com.example.BatteryAwareHelloWorld page, choose Deploy.

4. From Add to deployment, choose an existing deployment to revise, or choose to create a new deployment, and then choose Next.

5. If you chose to create a new deployment, choose the target core device or thing group for the deployment. On the Specify target page, under Deployment target, choose a core device or thing group, and then choose Next.

6. On the Select components page, verify that the com.example.BatteryAwareHelloWorld component is selected, choose Next.

7. On the Configure components page, select com.example.BatteryAwareHelloWorld, and then do the following:

   1. Choose Configure component.

   2. In the Configure com.example.BatteryAwareHelloWorld modal, under Configuration update, in Configuration to merge, enter the following configuration update.

      {
        "BatteryThreshold": 70
      }

   3. Choose Confirm to close the modal, and then choose Next.

8. On the Confirm advanced settings page, in the Deployment policies section, under Component update policy, confirm that Notify components is selected. Notify components is selected by default when you create a new deployment.

9. On the Review page, choose Deploy.

   The deployment can take up to a minute to complete.

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

You should see messages similar to the following example.

Hello, World! Battery level (50) is below threshold (70), so the component will defer updates.

Create a new deployment to the core device to verify that the component defers the update. Do the following:

1. In the AWS IoT Greengrass console navigation menu, choose Deployments.

2. Choose the deployment that you created or revised earlier.

3. On the deployment page, choose Revise.

4. In the Revise deployment modal, choose Revise deployment.

5. Choose Next at each step, and then choose Deploy.

Run the following command to view the component's logs again, and verify that it defers the update.

You should see messages similar to the following example. The component defers the update for 30 seconds, so the component prints this message repeatedly.

Deferred update for deployment 50722a95-a05f-4e2a-9414-da80103269aa.

Use a text editor to edit the virtual battery level file and change the battery level to a value above the threshold, so the deployment can proceed.

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

sudo nano /home/ggc_user/virtual_battery.json

Change the battery level to 80.

{
  "battery_level": 80
}

Run the following command to view the component's logs again, and verify that it acknowledges the update.

You should see messages similar to the following examples.

Hello, World! Battery level (80) is above threshold (70), so the component will acknowledge updates.
Acknowledged update for deployment f9499eb2-4a40-40a7-86c1-c89887d859f1.