Configure your device to run IDT tests - AWS IoT Greengrass
Verify AWS IoT Greengrass dependencies on the device under testConfigure the AWS IoT Greengrass softwareConfigure your host computer to access your device under testConfigure user permissions on your deviceConfigure your device to test optional features

AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS 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 AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Configure your device to run IDT tests

To configure your device you must install AWS IoT Greengrass dependencies, configure the AWS IoT Greengrass Core software, configure your host computer to access your device, and configure user permissions on your device.

Verify AWS IoT Greengrass dependencies on the device under test

Before IDT for AWS IoT Greengrass can test your devices, make sure that you have set up your device as described in Getting started with AWS IoT Greengrass. For information about supported platforms, see Supported platforms.

Configure the AWS IoT Greengrass software

IDT for AWS IoT Greengrass tests your device for compatibility with a specific version of AWS IoT Greengrass. IDT provides two options for testing AWS IoT Greengrass on your devices:

  • Download and use a version of the AWS IoT Greengrass Core software. IDT installs the software for you.

  • Use a version of the AWS IoT Greengrass Core software already installed on your device.

Note

Each version of AWS IoT Greengrass has a corresponding IDT version. You must download the version of IDT that corresponds to the version of AWS IoT Greengrass you are using.

The following sections describe these options. You only need to do one.

You can download the AWS IoT Greengrass Core software from the AWS IoT Greengrass Core Software downloads page.

  1. Find the correct architecture and Linux distribution, and then choose Download.

  2. Copy the tar.gz file to the <device-tester-extract-location>/products/greengrass/ggc.

Note

Do not change the name of the AWS IoT Greengrass tar.gz file. Do not place multiple files in this directory for the same operating system and architecture. For example having both greengrass-linux-armv7l-1.7.1.tar.gz and greengrass-linux-armv7l-1.8.1.tar.gz files in that directory will cause the tests to fail.

Configure IDT to test the AWS IoT Greengrass Core software installed on your device by adding the greengrassLocation attribute to the device.json file in the <device-tester-extract-location>/configs folder. For example:

"greengrassLocation" : "<path-to-greengrass-on-device>"

For more information about the device.json file, see Configure device.json.

On Linux devices, the default location of the AWS IoT Greengrass Core software is /greengrass.

Note

Your device should have an installation of the AWS IoT Greengrass Core software that has not been started.

Make sure you have added the ggc_user user and ggc_group on your device. For more information, see Environment setup for AWS IoT Greengrass.

Configure your host computer to access your device under test

IDT runs on your host computer and must be able to use SSH to connect to your device. There are two options to allow IDT to gain SSH access to your devices under test:

  1. Follow the instructions here to create an SSH key pair and authorize your key to sign in to your device under test without specifying a password.

  2. Provide a user name and password for each device in the device.json file. For more information, see Configure device.json.

You can use any SSL implementation to create an SSH key. The following instructions show you how to use SSH-KEYGEN or PuTTYgen (for Windows). If you are using another SSL implementation, refer to the documentation for that implementation.

IDT uses SSH keys to authenticate with your device under test.

To create an SSH key with SSH-KEYGEN

  1. Create an SSH key.

    You can use the Open SSH ssh-keygen command to create an SSH key pair. If you already have an SSH key pair on your host computer, it is a best practice to create a SSH key pair specifically for IDT. This way, after you have completed testing, your host computer can no longer connect to your device without entering a password. It also allows you to restrict access to the remote device to only those who need it.

    Note

    Windows does not have an installed SSH client. For information about installing an SSH client on Windows, see Download SSH Client Software.

    The ssh-keygen command prompts you for a name and path to store the key pair. By default, the key pair files are named id_rsa (private key) and id_rsa.pub (public key). On macOS and Linux, the default location of these files is ~/.ssh/. On Windows, the default location is C:\Users\<user-name>\.ssh.

    When prompted, enter a key phrase to protect your SSH key. For more information, see Generate a New SSH key.

  2. Add authorized SSH keys to your device under test.

    IDT must use your SSH private key to sign in to your device under test. To authorize your SSH private key to sign in to your device under test, use the ssh-copy-id command from your host computer. This command adds your public key into the ~/.ssh/authorized_keys file on your device under test. For example:

    $ ssh-copy-id <remote-ssh-user>@<remote-device-ip>

    Where remote-ssh-user is the user name used to sign in to your device under test and remote-device-ip is the IP address of the device under test to run tests against. For example:

    ssh-copy-id pi@192.168.1.5

    When prompted, enter the password for the user name you specified in the ssh-copy-id command.

    ssh-copy-id assumes the public key is named id_rsa.pub and is stored the default location (on macOS and Linux, ~/.ssh/ and on Windows, C:\Users\<user-name>\.ssh). If you gave the public key a different name or stored it in a different location, you must specify the fully qualified path to your SSH public key using the -i option to ssh-copy-id (for example, ssh-copy-id -i ~/my/path/myKey.pub). For more information about creating SSH keys and copying public keys, see SSH-COPY-ID.

To create an SSH key using PuTTYgen (Windows only)

  1. Make sure you have the OpenSSH server and client installed on your device under test. For more information, see OpenSSH.

  2. Install PuTTYgen on your device under test.

  3. Open PuTTYgen.

  4. Choose Generate and move your mouse cursor inside the box to generate a private key.

  5. From the Conversions menu, choose Export OpenSSH key, and save the private key with a .pem file extension.

  6. Add the public key to the /home/<user>/.ssh/authorized_keys file on device under test.

    1. Copy the public key text from the PuTTYgen window.

    2. Use PuTTY to create a session on your device under test.

      1. From a command prompt or Windows Powershell window, run the following command:

        C:/<path-to-putty>/putty.exe -ssh <user>@<dut-ip-address>

      2. When prompted, enter your device's password.

      3. Use vi or another text editor to append the public key to the /home/<user>/.ssh/authorized_keys file on your device under test.

  7. Update your device.json file with your user name, the IP address, and path to the private key file that you just saved on your host computer for each device under test. For more information, see Configure device.json. Make sure you provide the full path and file name to the private key and use forward slashes ('/'). For example, for the Windows path C:\DT\privatekey.pem, use C:/DT/privatekey.pem in the device.json file.

Configure user permissions on your device

IDT performs operations on various directories and files in a device under test. Some of these operations require elevated permissions (using sudo). To automate these operations, IDT for AWS IoT Greengrass must be able to run commands with sudo without being prompted for a password.

Follow these steps on the device under test to allow sudo access without being prompted for a password.

Note

username refers to the SSH user used by IDT to access the device under test.

To add the user to the sudo group

  1. On the device under test, run sudo usermod -aG sudo <username>.

  2. Sign out and then sign back in for changes to take effect.

  3. To verify your user name was added successfully, run sudo echo test. If you are not prompted for a password, your user is configured correctly.

  4. Open the /etc/sudoers file and add the following line to the end of the file:

    <ssh-username> ALL=(ALL) NOPASSWD: ALL

Configure your device to test optional features

The following topics describe how to configure your devices to run IDT tests for optional features. Follow these configuration steps only if you want to test these features. Otherwise, continue to Configure IDT settings to run the AWS IoT Greengrass qualification suite.

Topics