Running AWS IoT Device Tester - FreeWaveTechnologies/ZumIQ GitHub Wiki

Introduction

This page is included in the wiki for reference purposes. End users will never need to run this procedure. It is used at the factory to qualify new FreeWave products for AWS IoT Greengrass.

Resources

Prerequisites are listed in https://docs.aws.amazon.com/greengrass/latest/developerguide/device-config-setup.html . We go with Option 2: Use an Existing Installation of AWS IoT Greengrass with AWS IoT Device Tester.

This procedure follows the official AWS documentation at https://docs.aws.amazon.com/greengrass/latest/developerguide/device-tester-for-greengrass-ug.html .

The official documentation can be wordy and confusing at times. It can feel like you're slashing your way through an overgrown jungle with a machete, looking for what everybody insists is a well-marked trail. I wrote this document to cut through the brush and make the trail easier to follow.

ZumLink setup

Install Greengrass on your system. For instructions on how to install Greengrass, see the wiki page https://github.com/FreeWaveTechnologies/ZumIQ/wiki/Installing-AWS-IoT-Greengrass .
At the freewave-ib:$ prompt, type sudo usermod -aG sudo devuser.
Log out and log back in. Run the command sudo echo test. AWS says that you should see the test response, without the device asking you for the devuser password. Sometimes it works, sometimes it doesn't. If it does ask you for the password, don't freak out. Just keep going. The rest of this procedure seems to work anyway.
Edit the /etc/sudoers file. You can't edit it directly. You have to do this:

sudo visudo

Add this line to the end of the file.

devuser ALL=(ALL) NOPASSWD: ALL

Remember to save your changes before you exit.

PC setup

Download the AWS IoT Device Tester to your PC, from this page: https://docs.aws.amazon.com/greengrass/latest/developerguide/dev-test-versions.html
Extract the ZIP file. You'll end up with a directory called devicetester_greengrass_win_x.x.x, and inside it, another directory called devicetester_greengrass_win. Remember this directory's location. You'll need it often.

Store your AWS credentials

You should have already created an AWS account and downloaded your credentials to your PC — an access key and a secret access key. If not, then follow the instructions under Create and Configure an AWS Account at https://docs.aws.amazon.com/greengrass/latest/developerguide/dev-tst-prereqs.html .
Save your access key and secret access key on your PC, someplace where you can find them again. You will definitely need them more than once, and AWS only generates them once. If you lose them, you will have to generate new ones. It doesn't cost extra money, just extra time and effort.
Add your AWS credentials to the credentials file at C:\Users\your_username\.aws\credentials. Note the dot: that's dot a w s. The file should look like this:

[default]
aws_access_key_id = <your_access_key_id>
aws_secret_access_key = <your_secret_access_key>

Edit the config.json file in directory devicetester_greengrass_win\configs. It should look like this:

{
  "log": {
    "location": "../logs/"
  },
  "configFiles": {
    "root": "../configs",
    "device": "../configs/device.json"
  },
  "testPath": "../tests/",
  "reportPath": "../results/",
  "certificatePath": "../certificates/",
  "awsRegion": "us-west-2",
  "auth": {
    "method": "file",
	"credentials": {
	  "profile": "default"
	}
  }
}

The "method" : "file" entry tells AWS to use the credentials in your .aws\credentials file.

Device configuration

Now you need to edit the device.json file in directory devicetester_greengrass_win\configs. It should look something like this:

[
  {
    "id": "ZumIQ",
    "sku": "ZIQ-PE2",
    "features": [
      {
        "name": "os",
        "value": "linux"
      },
      {
        "name": "arch",
        "value": "armv7l"
      }
    ],
    "kernelConfigLocation": "",
    "greengrassLocation": "/ptp/greengrass",
    "devices": [
      {
        "id": "4026772183",
        "connectivity": {
          "protocol": "ssh",
          "ip": "192.168.137.183",
          "auth": {
            "method": "password",
            "credentials": {
              "user": "devuser",
              "password": "devuser"
            }
          }
        }
      }
    ]
  }
]

Fields you will need to edit:

The first "id" field defines a device pool. Think of this as the product family. Use "ZumIQ" for all ZumIQ devices. Use "ZumLink" for all ZumLink devices. Since ZumLink has a built-in radio and ZumIQ doesn't, they are two separate device types and so they need two separate device pools.
The "sku" field is the external part number which a customer uses to buy our products. For example, the first FreeWave device to go through IoT Device Testing was the four-port ZumIQ. Its "sku" is ZIQ-PE2.
The "greengrassLocation" field is the Linux-style path to the directory on the device under test where Greengrass is installed.
The "devices.id" field is the serial number of the device under test. This is important for traceability, especially if the test fails.
The "devices.ip" field is the IP address that the PC uses to communicate via ssh with the device under test.

Run the IoT Device Test

On your PC, open a Command.com window or a PowerShell window. Make it taller and wider than the default, so you can see the test results.
Change to the directory devicetester_greengrass_win\bin. Execute the command:

devicetester_win_x86-64.exe run-suite --suite-id GGQ_1 --pool-id ZumIQ

If you changed the "id" field in device.json from "ZumIQ" to something else, then you must change the --pool-id option to match it.

Leave the window open, while you go and do something else. It takes a long time to run through all the tests.
When the test completes, it gives you a summary of test results, including which tests passed and failed. It also points you to the location of an XML file, which is useful if you incorporate the IDT into CI testing. All test results can be found in the directory devicetester_greengrass_win\results.
If the test failed, examine the output in the Command or PowerShell window for clues to the failure. Examine the log files pointed to by the output text. See the next section, Error Codes and Troubleshooting to help you fix anything that went wrong.

Error Codes and Troubleshooting

The AWS error codes and troubleshooting page: https://docs.aws.amazon.com/greengrass/latest/developerguide/idt-troubleshooting.html

General Greengrass troubleshooting: https://docs.aws.amazon.com/greengrass/latest/developerguide/gg-troubleshooting.html

One thing that helps to isolate errors is to install Greengrass and run the IoT Device Test on a Raspberry Pi, and compare the results for the two devices.

You can also find help on the AWS Forums.