Getting started with AWS IoT Greengrass V2

To set up a Raspberry Pi for AWS IoT Greengrass V2

1. Enable SSH on your Raspberry Pi to remotely connect to it. For more information, see SSH (Secure shell) in the Raspberry Pi Documentation.

2. Find the IP address of your Raspberry Pi to connect to it with SSH. To do so, you can run the following command on your Raspberry Pi.

   hostname -I

3. Connect to your Raspberry Pi with SSH.

   On your development computer, run the following command. Replace username with the name of the user to sign in, and replace pi-ip-address with the IP address that you found in the previous step.

   ssh username@pi-ip-address

   The default Raspberry Pi user name and password are pi and raspberry, respectively.

   Important

   If your development computer uses an earlier version of Windows, you might not have the ssh command, or you might have ssh but can't connect to your Raspberry Pi. To connect to your Raspberry Pi, you can install and configure PuTTY, which is a no-cost, open source SSH client. Consult the PuTTY documentation to connect to your Raspberry Pi.

4. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. On your Raspberry Pi, use the following commands to install Java 11.

   sudo apt install default-jdk

   When the installation completes, run the following command to verify that Java runs on your Raspberry Pi.

   java -version

   The command prints the version of Java that runs on the device. The output might look similar to the following example.

   openjdk version "11.0.9.1" 2020-11-04
   OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
   OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)

To set up a Windows device for AWS IoT Greengrass V2

1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use Amazon Corretto 11 or OpenJDK 11..

2. Open the Windows Command Prompt (cmd.exe) as an administrator.

3. Create the default user in the LocalSystem account on the Windows device. Replace password with a secure password.

   net user /add ggc_user password

4. Download and install the PsExec utility from Microsoft on the device.

5. Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace password with the user's password that you set earlier.

   psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password

   If the PsExec License Agreement opens, choose Accept to agree to the license and run the command.

   Note

   On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must use the PsExec utility to store the default user information in the LocalSystem account. Using the Credential Manager application stores this information in the Windows account of the currently logged on user, instead of the LocalSystem account.

1. Sign in to the AWS IoT Greengrass console.

2. Under Get started with Greengrass, choose Set up one core device.

3. Under Step 1: Register a Greengrass core device, for Core device name, enter the name of the AWS IoT thing for your Greengrass core device. If the thing doesn't exist, the installer creates it.

4. Under Step 2: Add to a thing group to apply a continuous deployment, for Thing group, choose the AWS IoT thing group to which you want to add your core device.

   • If you select Enter a new group name, then in Thing group name, enter the name of the new group to create. The installer creates the new group for you.

   • If you select Select an existing group, then in Thing group name, choose the existing group that you want to use.

   • If you select No group, then the installer doesn't add the core device to a thing group.

5. Under Step 3: Install the Greengrass Core software, complete the following steps.

   1. Choose your core device's operating system: Linux or Windows.

   2. Provide your AWS credentials to the device so that the installer can provision the AWS IoT and IAM resources for your core device. To increase security, you can get credentials for an IAM role that allows only the minimum permissions necessary to provision. For more information, see Minimal IAM policy for installer to provision resources.

      Note

      The installer doesn't save or store your credentials.

      On your device, do one of the following to retrieve credentials and make them available to the AWS IoT Greengrass Core software installer:

      • Use long-term credentials from an IAM user:

        1. Provide the access key ID and secret access key for your IAM user. For more information about how to retrieve long-term credentials, see Managing access keys for IAM users in the IAM User Guide.

        2. Run the following commands to provide the credentials to the AWS IoT Greengrass Core software.

           Linux or Unix

           export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
           export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

           Windows Command Prompt (CMD)

           set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
           set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

           PowerShell

           $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
           $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

      • (Recommended) Use temporary security credentials from an IAM role:

        1. Provide the access key ID, secret access key, and session token from an IAM role that you assume. For more information about how to retrieve these credentials, see Using temporary security credentials with the AWS CLI in the IAM User Guide.

        2. Run the following commands to provide the credentials to the AWS IoT Greengrass Core software.

           Linux or Unix

           export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
           export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
           export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=

           Windows Command Prompt (CMD)

           set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
           set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
           set AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=

           PowerShell

           $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
           $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
           $env:AWS_SESSION_TOKEN="AQoDYXdzEJr1K...o5OytwEXAMPLE="

   3. Under Run the installer, complete the following steps.

      1. Under Download the installer, choose Copy and run the copied command on your core device. This command downloads the latest version of the AWS IoT Greengrass Core software and unzips it on your device.

      2. Under Run the installer, choose Copy, and run the copied command on your core device. This command uses the AWS IoT thing and thing group names that you specified earlier to run the AWS IoT Greengrass Core software installer and set up AWS resources for your core device.

         This command also does the following:

         • Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices, this requires the Systemd init system.

         • Deploy the AWS IoT Greengrass CLI component, which is a command-line tool that enables you to develop custom Greengrass components on the core device.

         • Specify to use the ggc_user system user to run software components on the core device. On Linux devices, this command also specifies to use the ggc_group system group, and the installer creates the system user and group for you.

         When you run this command, you should see the following messages to indicate that the installer succeeded.

         Successfully configured Nucleus with provisioned resource details!
         Configured Nucleus to deploy aws.greengrass.Cli component
         Successfully set up Nucleus as a system service

         Note

         If you have a Linux device and it doesn't have systemd, the installer won't set up the software as a system service, and you won't see the success message for setting up the nucleus as a system service.

To install and configure the AWS IoT Greengrass Core software

1. On your Greengrass core device, run the following command to switch to the home directory.

   Linux or Unix

   cd ~

   Windows Command Prompt (CMD)

   cd %USERPROFILE%

   PowerShell

   cd ~

2. On your core device, download the AWS IoT Greengrass Core software to a file named greengrass-nucleus-latest.zip.

   Linux or Unix

   curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip > greengrass-nucleus-latest.zip

   Windows Command Prompt (CMD)

   curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip > greengrass-nucleus-latest.zip

   PowerShell

   iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip -OutFile greengrass-nucleus-latest.zip

   By downloading this software, you agree to the Greengrass Core Software License Agreement.

3. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace GreengrassInstaller with the folder that you want to use.

   Linux or Unix

   unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-nucleus-latest.zip

   Windows Command Prompt (CMD)

   mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -C GreengrassInstaller && del greengrass-nucleus-latest.zip

   PowerShell

   Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .\GreengrassInstaller
   rm greengrass-nucleus-latest.zip

4. Run the following command to launch the AWS IoT Greengrass Core software installer. This command does the following:

   • Create the AWS resources that the core device requires to operate.

   • Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices, this requires the Systemd init system.

   • Deploy the AWS IoT Greengrass CLI component, which is a command-line tool that enables you to develop custom Greengrass components on the core device.

   • Specify to use the ggc_user system user to run software components on the core device. On Linux devices, this command also specifies to use the ggc_group system group, and the installer creates the system user and group for you.

   Replace argument values in your command as follows.

   1. /greengrass/v2 or C:\greengrass\v2: The path to the root folder to use to install the AWS IoT Greengrass Core software.

   2. GreengrassInstaller. The path to the folder where you unpacked the AWS IoT Greengrass Core software installer.

   3. region. The AWS Region in which to find or create resources.

   4. MyGreengrassCore. The name of the AWS IoT thing for your Greengrass core device. If the thing doesn't exist, the installer creates it. The installer downloads the certificates to authenticate as the AWS IoT thing. For more information, see Device authentication and authorization for AWS IoT Greengrass.

      Note

      The thing name can't contain colon (:) characters.

   5. MyGreengrassCoreGroup. The name of AWS IoT thing group for your Greengrass core device. If the thing group doesn't exist, the installer creates it and adds the thing to it. If the thing group exists and has an active deployment, the core device downloads and runs the software that the deployment specifies.

      Note

      The thing group name can't contain colon (:) characters.

   6. GreengrassV2IoTThingPolicy. The name of the AWS IoT policy that allows the Greengrass core devices to communicate with AWS IoT and AWS IoT Greengrass. If the AWS IoT policy doesn't exist, the installer creates a permissive AWS IoT policy with this name. You can restrict this policy's permissions for you use case. For more information, see Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices.

   7. GreengrassV2TokenExchangeRole. The name of the IAM role that allows the Greengrass core device to get temporary AWS credentials. If the role doesn't exist, the installer creates it and creates and attaches a policy named GreengrassV2TokenExchangeRoleAccess. For more information, see Authorize core devices to interact with AWS services.

   8. GreengrassCoreTokenExchangeRoleAlias. The alias to the IAM role that allows the Greengrass core device to get temporary credentials later. If the role alias doesn't exist, the installer creates it and points it to the IAM role that you specify. For more information, see Authorize core devices to interact with AWS services.

   Linux or Unix

   sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
     -jar ./GreengrassInstaller/lib/Greengrass.jar \
     --aws-region region \
     --thing-name MyGreengrassCore \
     --thing-group-name MyGreengrassCoreGroup \
     --thing-policy-name GreengrassV2IoTThingPolicy \
     --tes-role-name GreengrassV2TokenExchangeRole \
     --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias \
     --component-default-user ggc_user:ggc_group \
     --provision true \
     --setup-system-service true \
     --deploy-dev-tools true

   Windows Command Prompt (CMD)

   java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
     -jar ./GreengrassInstaller/lib/Greengrass.jar ^
     --aws-region region ^
     --thing-name MyGreengrassCore ^
     --thing-group-name MyGreengrassCoreGroup ^
     --thing-policy-name GreengrassV2IoTThingPolicy ^
     --tes-role-name GreengrassV2TokenExchangeRole ^
     --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias ^
     --component-default-user ggc_user ^
     --provision true ^
     --setup-system-service true ^
     --deploy-dev-tools true

   PowerShell

   java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
     -jar ./GreengrassInstaller/lib/Greengrass.jar `
     --aws-region region `
     --thing-name MyGreengrassCore `
     --thing-group-name MyGreengrassCoreGroup `
     --thing-policy-name GreengrassV2IoTThingPolicy `
     --tes-role-name GreengrassV2TokenExchangeRole `
     --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias `
     --component-default-user ggc_user `
     --provision true `
     --setup-system-service true `
     --deploy-dev-tools true

   Note

   If you are running AWS IoT Greengrass on a device with limited memory, you can control the amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation, you can set JVM heap size options in the jvmOptions configuration parameter in your nucleus component. For more information, see Control memory allocation with JVM options.

   When you run this command, you should see the following messages to indicate that the installer succeeded.

   Successfully configured Nucleus with provisioned resource details!
   Configured Nucleus to deploy aws.greengrass.Cli component
   Successfully set up Nucleus as a system service

   Note

   If you have a Linux device and it doesn't have systemd, the installer won't set up the software as a system service, and you won't see the success message for setting up the nucleus as a system service.

1. Use an S3 bucket in your AWS account to host AWS IoT Greengrass component artifacts. When you deploy the component to a core device, the device downloads the component's artifacts from the bucket.

   You can use an existing S3 bucket, or you can create a new bucket.

   1. In the Amazon S3 console, under Buckets, choose Create bucket.

   2. For Bucket name, enter a unique bucket name. For example, you can use greengrass-component-artifacts-123456789012-region. Replace 123456789012 with your AWS account ID and region with the AWS Region that you use for this tutorial.

   3. For AWS region, select the AWS Region that you use for this tutorial.

   4. Choose Create bucket.

   5. Under Buckets, choose the bucket that you created, upload the hello_world.py script to the artifacts/com.example.HelloWorld/1.0.0 folder in the bucket. For information about uploading objects to S3 buckets, see Uploading objects in the Amazon Simple Storage Service User Guide.

   6. Copy the S3 URI of the hello_world.py object in the S3 bucket. This URI should look similar to the following example. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.

      s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

2. 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 DOC-EXAMPLE-BUCKET with the name of the bucket to use.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
          }
        ]
      }

   3. Choose Next: Tags, and then choose Next: Review.

   4. For Name, enter MyGreengrassV2ComponentArtifactPolicy.

   5. Choose Create policy.

   6. In the IAM console navigation menu, choose Role, and then choose the GreengrassV2TokenExchangeRole role that you specified when you ran the AWS IoT Greengrass Core software.

   7. Under Permissions, choose Attach policies.

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

3. Use the component recipe to create a component in the AWS IoT Greengrass console.

   1. In the AWS IoT Greengrass console navigation menu, choose Components, and then choose Create component.

   2. Under Component information, choose Enter recipe as JSON. The placeholder recipe should look similar to the following example.

      {
        "RecipeFormatVersion": "2020-01-25",
        "ComponentName": "com.example.HelloWorld",
        "ComponentVersion": "1.0.0",
        "ComponentDescription": "My first Greengrass component.",
        "ComponentPublisher": "Amazon",
        "ComponentConfiguration": {
          "DefaultConfiguration": {
            "Message": "world"
          }
        },
        "Manifests": [
          {
            "Lifecycle": {
              "Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
            },
            "Artifacts": [
              {
                "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
              }
            ]
          }
        ]
      }

   3. Replace the placeholder URI with S3 URI of your hello_world.py object.

   4. Choose Create component.

   5. On the com.example.HelloWorld component page, verify that the Status of the component is Deployable.

To upload your Hello World component

1. Use an S3 bucket in your AWS account to host AWS IoT Greengrass component artifacts. When you deploy the component to a core device, the device downloads the component's artifacts from the bucket.

   You can use an existing S3 bucket, or run the following command to create a bucket. This command creates a bucket with your AWS account ID and AWS Region to form a unique bucket name. Replace 123456789012 with your AWS account ID and region with the AWS Region that you use for this tutorial.

   aws s3 mb s3://greengrass-component-artifacts-123456789012-region

   The command outputs the following information if the request succeeds.

   make_bucket: greengrass-component-artifacts-123456789012-region

2. 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. Create a file called component-artifact-policy.json and copy the following JSON into the file. This policy allows access to all files in the S3 bucket that you created in the previous step. Replace DOC-EXAMPLE-BUCKET with the name of the bucket to use.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
          }
        ]
      }

   2. Run the following command to create the policy from the policy document in component-artifact-policy.json.

      Linux or Unix

      aws iam create-policy \
        --policy-name MyGreengrassV2ComponentArtifactPolicy \
        --policy-document file://component-artifact-policy.json

      Windows Command Prompt (CMD)

      aws iam create-policy ^
        --policy-name MyGreengrassV2ComponentArtifactPolicy ^
        --policy-document file://component-artifact-policy.json

      PowerShell

      aws iam create-policy `
        --policy-name MyGreengrassV2ComponentArtifactPolicy `
        --policy-document file://component-artifact-policy.json

      Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this ARN to attach this policy to the core device role in the next step.

   3. Run the following command to attach the policy to the core device role. Replace GreengrassV2TokenExchangeRole with the name of the role that you specified when you ran the AWS IoT Greengrass Core software. Replace the policy ARN with the ARN from the previous step.

      Linux or Unix

      aws iam attach-role-policy \
        --role-name GreengrassV2TokenExchangeRole \
        --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy

      Windows Command Prompt (CMD)

      aws iam attach-role-policy ^
        --role-name GreengrassV2TokenExchangeRole ^
        --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy

      PowerShell

      aws iam attach-role-policy `
        --role-name GreengrassV2TokenExchangeRole `
        --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy

      If the command has no output, it succeeded. Your core device can now access artifacts that you upload to this S3 bucket.

3. Upload the Hello World Python script artifact to the S3 bucket.

   Run the following command to upload the script to the same path in the bucket where the script exists on your AWS IoT Greengrass core. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.

   Linux or Unix

   aws s3 cp \
     artifacts/com.example.HelloWorld/1.0.0/hello_world.py \
     s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

   Windows Command Prompt (CMD)

   aws s3 cp ^
     artifacts/com.example.HelloWorld/1.0.0/hello_world.py ^
     s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

   PowerShell

   aws s3 cp `
     artifacts/com.example.HelloWorld/1.0.0/hello_world.py `
     s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

   The command outputs a line that starts with upload: if the request succeeds.

4. Add the artifact's Amazon S3 URI to the component recipe.

   The Amazon S3 URI is composed of the bucket name and the path to the artifact object in the bucket. Your script artifact's Amazon S3 URI is the URI that you upload the artifact to in the previous step. This URI should look similar to the following example. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.

   s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

   To add the artifact to the recipe, add a list of Artifacts that contains a structure with the Amazon S3 URI.

   JSON

   "Artifacts": [
     {
       "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
     }
   ]

   Open the recipe file in a text editor.

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

   nano recipes/com.example.HelloWorld-1.0.0.json

   Add the artifact to the recipe. Your recipe file should look similar to the following example.

   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.HelloWorld",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "My first Greengrass component.",
     "ComponentPublisher": "Amazon",
     "ComponentConfiguration": {
       "DefaultConfiguration": {
         "Message": "world"
       }
     },
     "Manifests": [
       {
         "Platform": {
           "os": "linux"
         },
         "Lifecycle": {
           "Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
         },
         "Artifacts": [
           {
             "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
           }
         ]
       },
       {
         "Platform": {
           "os": "windows"
         },
         "Lifecycle": {
           "Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
         },
         "Artifacts": [
           {
             "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
           }
         ]
       }
     ]
   }

   YAML

   Artifacts:
     - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

   Open the recipe file in a text editor.

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

   nano recipes/com.example.HelloWorld-1.0.0.yaml

   Add the artifact to the recipe. Your recipe file should look similar to the following example.

   ---
   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}"
       Artifacts:
         - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
     - Platform:
         os: windows
       Lifecycle:
         Run: |
           py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
       Artifacts:
         - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

5. Create a component resource in AWS IoT Greengrass from the recipe. Run the following command to create the component from the recipe, which you provide as a binary file.

   JSON

   aws greengrassv2 create-component-version --inline-recipe fileb://recipes/com.example.HelloWorld-1.0.0.json

   YAML

   aws greengrassv2 create-component-version --inline-recipe fileb://recipes/com.example.HelloWorld-1.0.0.yaml

   The response looks similar to the following example if the request succeeds.

   {
     "arn": "arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
     "componentName": "com.example.HelloWorld",
     "componentVersion": "1.0.0",
     "creationTimestamp": "Mon Nov 30 09:04:05 UTC 2020",
     "status": {
       "componentState": "REQUESTED",
       "message": "NONE",
       "errors": {}
     }
   }

   Copy the arn from the output to check the state of the component in the next step.

   Note

   You can also see your Hello World component in the AWS IoT Greengrass console on the Components page.

6. Verify that the component creates and is ready to be deployed. When you create a component, its state is REQUESTED. Then, AWS IoT Greengrass validates that the component is deployable. You can run the following command to query the component status and verify that your component is deployable. Replace the arn with the ARN from the previous step.

   aws greengrassv2 describe-component --arn "arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0"

   If the component validates, the response indicates that the component state is DEPLOYABLE.

   {
     "arn": "arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
     "componentName": "com.example.HelloWorld",
     "componentVersion": "1.0.0",
     "creationTimestamp": "2020-11-30T18:04:05.823Z",
     "publisher": "Amazon",
     "description": "My first Greengrass component.",
     "status": {
       "componentState": "DEPLOYABLE",
       "message": "NONE",
       "errors": {}
     },
     "platforms": [
       {
         "os": "linux",
         "architecture": "all"
       }
     ]
   }

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

2. On the Components page, on the My components tab, choose com.example.HelloWorld.

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

4. From Add to deployment, choose Create new deployment, then choose Next.

5. On the Specify target page, do the following:

   1. In the Name box, enter Deployment for MyGreengrassCore.

   2. For Deployment target, choose Core device, and the name of the AWS IoT thing for your core device. The default value in this tutorial is MyGreengrassCore.

   3. Choose Next.

6. On the Select components page, under My components, verify that the com.example.HelloWorld component is selected, and choose Next.

7. On the Configure components page, choose com.example.HelloWorld, and do the following:

   1. Choose Configure component.

   2. Under Configuration update, in Configuration to merge, enter the following configuration.

      {
        "Message": "universe"
      }

      This configuration update sets the Hello World Message parameter to universe for the device in this deployment.

   3. Choose Confirm.

   4. Choose Next.

8. On the Configure advanced settings page, keep the default configuration settings, and choose Next.

9. On the Review page, choose Deploy

To deploy your Hello World component

1. On your development computer, create a file called hello-world-deployment.json and copy the following JSON into the file. This file defines the components and configurations to deploy.

   {
     "components": {
       "com.example.HelloWorld": {
         "componentVersion": "1.0.0",
         "configurationUpdate": {
           "merge": "{\"Message\":\"universe\"}"
         }
       }
     }
   }

   This configuration file specifies to deploy version 1.0.0 of the Hello World component that you developed and published in the previous procedure. The configurationUpdate specifies to merge the component configuration in a JSON-encoded string. This configuration update sets the Hello World Message parameter to universe for the device in this deployment.

2. Run the following command to deploy the component to your Greengrass core device. You can deploy to things, which are individual devices, or thing groups, which are groups of devices. Replace MyGreengrassCore with the name of the AWS IoT thing for your core device.

   Linux or Unix

   aws greengrassv2 create-deployment \
     --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" \
     --cli-input-json file://hello-world-deployment.json

   Windows Command Prompt (CMD)

   aws greengrassv2 create-deployment ^
     --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" ^
     --cli-input-json file://hello-world-deployment.json

   PowerShell

   aws greengrassv2 create-deployment `
     --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" `
     --cli-input-json file://hello-world-deployment.json

   The command outputs a response similar to the following example.

   {
     "deploymentId": "deb69c37-314a-4369-a6a1-3dff9fce73a9",
     "iotJobId": "b5d92151-6348-4941-8603-bdbfb3e02b75",
     "iotJobArn": "arn:aws:iot:region:account-id:job/b5d92151-6348-4941-8603-bdbfb3e02b75"
   }

3. Verify that the deployment completes successfully. The deployment can take several minutes to complete. Check the Hello World log to verify the change. Run the following command on your Greengrass core device.

   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, universe! Greetings from your first Greengrass component.

   Note

   If the log messages don't change, the deployment failed or didn't reach the core device. This can occur if your core device isn't connected to the internet or doesn't have permissions to retrieve artifacts from your S3 bucket. Run the following command on your core device to view the AWS IoT Greengrass Core software 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

   For more information, see Troubleshooting AWS IoT Greengrass V2.