Configure your device to run IDT tests - 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.

Amazon IoT Greengrass Version 1 no longer receives feature updates, and will receive only security patches and bug fixes until June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. We strongly recommend that you migrate to Amazon 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 Amazon IoT Greengrass dependencies, configure the Amazon IoT Greengrass Core software, configure your host computer to access your device, and configure user permissions on your device.

Verify Amazon IoT Greengrass dependencies on the device under test

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

Configure the Amazon IoT Greengrass software

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

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

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

Note

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

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

You can download the Amazon IoT Greengrass Core software from the Amazon 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 Amazon 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 Amazon 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 Amazon IoT Greengrass Core software is /greengrass.

Note

Your device should have an installation of the Amazon 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 Amazon 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 Amazon 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 Amazon IoT Greengrass qualification suite.