Quick start: Greengrass device setup - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Quick start: Greengrass device setup

Greengrass device setup is a script that sets up your core device in minutes, so that you can start using Amazon IoT Greengrass. Use this script to:

  1. Configure your device and installs the Amazon IoT Greengrass Core software.

  2. Configure your cloud-based resources.

  3. Optionally deploy a Greengrass group with a Hello World Lambda function that sends MQTT messages to Amazon IoT from the Amazon IoT Greengrass core. This sets up the Greengrass environment shown in the following diagram.

    Hello World Lambda function sending an MQTT message to Amazon IoT from the Amazon IoT Greengrass core.

Requirements

Greengrass device setup has the following requirements:

Run Greengrass device setup

You can run Greengrass device setup in just a few steps. After you provide your Amazon Web Services account credentials, the script provisions your Greengrass core device and deploys a Greengrass group in minutes. Run the following commands in a terminal window on the target device.

Note

These steps show you how to run the script in interactive mode, which prompts you to enter or accept each input value. For information about how to run the script silently, see Run Greengrass device setup in silent mode.

 

  1. Provide your credentials. In this procedure, we assume you provide temporary security credentials as environment variables.

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

    If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of these commands. You must provide them again after you reboot the device.

  2. Download and start the script. You can use wget or curl to download the script.

    wget:

    wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive

    curl:

    curl https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh > gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive
  3. Proceed through the command prompts for input values. You can press the Enter key to use the default value or type a custom value and then press Enter.

    The script writes status messages to the terminal that are similar to the following.

    Output messages in the terminal.
  4. If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.

    1. When prompted to reboot the device, run one of the following commands.

      For Raspbian platforms:

      sudo reboot

      For OpenWrt platforms:

      reboot
    2. After the device reboots, open the terminal and provide your credentials as environment variables.

      export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
    3. Restart the script.

      sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive
    4. When prompted whether to use your input values from the previous session or start a new installation, enter yes to reuse your input values.

      Note

      On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the GreengrassDeviceSetup.config.info file.

    When the setup is complete, the terminal displays a success status message that's similar to the following.

    Success message in the terminal output.
  5. Review the new Greengrass group that the script configures using the input values you provide.

    1. Sign in to the Amazon Web Services Management Console on your computer and open the Amazon IoT console.

      Note

      Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).

    2. In the navigation pane, expand Greengrass devices, then choose Groups (V1) to locate the newly created group.

  6. If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.

    Note

    Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).

    If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.

     

Troubleshooting issues

You can use the following information to troubleshoot issues with the Amazon IoT Greengrass device setup.

Error: Python (python3.7) not found. Attempting to install it...

Solution: You might see this error when working with an Amazon EC2 instance. This error occurs when Python is not installed in the /usr/bin/python3.7 folder. To resolve this error, move Python in the correct directory after installing it:

sudo ln -s /usr/local/bin/python3.7 /usr/bin/python3.7

Additional troubleshooting

To troubleshoot additional issues with the Amazon IoT Greengrass device setup, you can look for debug information in the log files:

  • For issues with the Greengrass device setup configuration, check the /tmp/greengrass-device-setup-bootstrap-epoch-timestamp.log file.

  • For issues with the Greengrass group or core environment setup, check the GreengrassDeviceSetup-date-time.log file in the same directory as gg-device-setup-latest.sh or in the location you specified.

For more troubleshooting help, see Troubleshooting Amazon IoT Greengrass or check the Amazon IoT Greengrass tag on Amazon re:Post.

Greengrass device setup configuration options

You configure Greengrass device setup to access your Amazon resources and set up your Greengrass environment.

Provide Amazon Web Services account credentials

Greengrass device setup uses your Amazon Web Services account credentials to access your Amazon resources. It supports long-term credentials for an IAM user or temporary security credentials from an IAM role.

First, get your credentials.

  • To use long-term credentials, provide the access key ID and secret access key for your IAM user. For information about creating access keys for long-term credentials, see Managing access keys for IAM users in the IAM User Guide.

     

  • To use temporary security credentials (recommended), provide the access key ID, secret access key, and session token from an assumed IAM role. For information about extracting temporary security credentials from the Amazon STS assume-role command, see Using temporary security credentials with the Amazon CLI in the IAM User Guide.

Note

For the purposes of this tutorial, we assume that the IAM user or IAM role has administrator access permissions.

Then, provide your credentials to Greengrass device setup in one of two ways:

  • As environment variables. Set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN (if required) environment variables before you start the script, as shown in step 1 of Run Greengrass device setup.

     

  • As input values. Enter your access key ID, secret access key, and session token (if required) values directly in the terminal after you start the script.

Greengrass device setup doesn't save or store your credentials.

 

Provide input values

In interactive mode, Greengrass device setup prompts you for input values. You can press the Enter key to use the default value or type a custom value and then press Enter. In silent mode, you provide input values after you start the script.

Amazon access key ID

The access key ID from the long-term or temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.

Option name for silent mode: --aws-access-key-id

Amazon secret access key

The secret access key from the long-term or temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.

Option name for silent mode: --aws-secret-access-key

Amazon session token

The session token from the temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.

Option name for silent mode: --aws-session-token

Amazon Web Services Region

The Amazon Web Services Region where you want to create the Greengrass group. For the list of supported Amazon Web Services Regions, see Amazon IoT Greengrass in the Amazon Web Services General Reference.

Default value: us-west-2

Option name for silent mode: --region

Group name

The name for the Greengrass group.

Default value: GreengrassDeviceSetup_Group_guid

Option name for silent mode: --group-name

Core name

The name for the Greengrass core. The core is an Amazon IoT device (thing) that runs the Amazon IoT Greengrass Core software. The core is added to the Amazon IoT registry and the Greengrass group. If you provide a name, it must be unique in the Amazon Web Services account and Amazon Web Services Region.

Default value: GreengrassDeviceSetup_Core_guid

Option name for silent mode: --core-name

Amazon IoT Greengrass Core software installation path

The location in the device file system where you want to install the Amazon IoT Greengrass Core software.

Default value: /

Option name for silent mode: --ggc-root-path

Hello World Lambda function

Indicates whether to include a Hello World Lambda function in the Greengrass group. The function publishes an MQTT message to the hello/world topic every five seconds.

The script creates and publishes this user-defined Lambda function in Amazon Lambda and adds it to your Greengrass group. The script also creates a subscription in the group that allows the function to send MQTT messages to Amazon IoT.

Note

This is a Python 3.7 Lambda function. If Python 3.7 isn't installed on the device and the script is unable to install it, the script prints an error message in the terminal. To include the Lambda function in the group, you must install Python 3.7 manually and restart the script. To create the Greengrass group without the Lambda function, restart the script and enter no when prompted to include the function.

Default value: no

Option name for silent mode: --hello-world-lambda - This option doesn't take a value. Include it in your command if you want to create the function.

Deployment timeout

The number of seconds before Greengrass device setup stops checking the status of the Greengrass group deployment. This is used only when the group includes the Hello World Lambda function. Otherwise, the group is not deployed.

The deployment time depends on your network speed. For slow network speeds, you can increase this value.

Default value: 180

Option name for silent mode: --deployment-timeout

Log path

The location of the log file that contains information about Greengrass group and core setup operations. Use this log to troubleshoot deployment and other issues with the Greengrass group and core setup.

Default value: ./

Option name for silent mode: --log-path

Verbosity

Indicates whether to print detailed log information in the terminal while the script runs. You can use this information to troubleshoot device setup.

Default value: no

Option name for silent mode: --verbose - This option doesn't take a value. Include it in your command if you want to print detailed log information.

 

Run Greengrass device setup in silent mode

You can run Greengrass device setup in silent mode so that the script doesn't prompt you for any values. To run in silent mode, specify bootstrap-greengrass mode and your input values after you start the script. You can omit input values if you want to use their defaults.

The procedure depends on whether you provide your Amazon Web Services account credentials as environment variables before you start the script, or as input values after you start the script.

  1. Provide your credentials as environment variables. The following example exports temporary credentials, which include the session token.

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

    If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of these commands. You must provide them again after you reboot the device.

  2. Download and start the script. Provide input values as needed. For example:

    • To use all default values:

      wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass
    • To specify custom values:

      wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --region us-east-1 --group-name Custom_Group_Name --core-name Custom_Core_Name --ggc-root-path /custom/ggc/root/path --deployment-timeout 300 --log-path /customized/log/path --hello-world-lambda --verbose
    Note

    To use curl to download the script, replace wget -q -O with curl in the command.

  3. If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.

    1. When prompted to reboot the device, run one of the following commands.

      For Raspbian platforms:

      sudo reboot

      For OpenWrt platforms:

      reboot
    2. After the device reboots, open the terminal and provide your credentials as environment variables.

      export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
    3. Restart the script.

      sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass
    4. When prompted whether to use your input values from the previous session or start a new installation, enter yes to reuse your input values.

      Note

      On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the GreengrassDeviceSetup.config.info file.

    When the setup is complete, the terminal displays a success status message that's similar to the following.

    Success message in the terminal output.
  4. If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.

    Note

    Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).

    If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.

     

  1. Download and start the script. Provide your credentials and any other input values that you want to specify. The following examples show how to provide temporary credentials, which include the session token.

    • To use all default values:

      wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE=
    • To specify custom values:

      wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE= --region us-east-1 --group-name Custom_Group_Name --core-name Custom_Core_Name --ggc-root-path /custom/ggc/root/path --deployment-timeout 300 --log-path /customized/log/path --hello-world-lambda --verbose
    Note

    If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of your credentials. You must provide them again after you reboot the device.

    To use curl to download the script, replace wget -q -O with curl in the command.

  2. If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.

    1. When prompted to reboot the device, run one of the following commands.

      For Raspbian platforms:

      sudo reboot

      For OpenWrt platforms:

      reboot
    2. Restart the script. You must include your credentials in the command, but not the other input values. For example:

      sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE=
    3. When prompted whether to use your input values from the previous session or start a new installation, enter yes to reuse your input values.

      Note

      On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the GreengrassDeviceSetup.config.info file.

    When the setup is complete, the terminal displays a success status message that's similar to the following.

    Success message in the terminal output.
  3. If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.

    Note

    Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).

    If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.