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.
Configure IDT settings to run the Amazon IoT Greengrass qualification suite
Before you run tests, you must configure settings for Amazon credentials and devices on your host computer.
Configure your Amazon credentials
You must configure your IAM user credentials in the
file. Use the credentials for the IDT for Amazon IoT Greengrass user
created in Create and configure an Amazon Web Services account. You can specify your credentials in
one of two ways:<device-tester-extract-location>
/configs/config.json
-
Credentials file
-
Environment variables
IDT uses the same credentials file as the Amazon CLI. For more information, see Configuration and credential files.
The location of the credentials file varies, depending on the operating system you are using:
-
macOS, Linux:
~/.aws/credentials
-
Windows:
C:\Users\
UserName
\.aws\credentials
Add your Amazon credentials to the credentials
file in the following
format:
[default] aws_access_key_id =
<your_access_key_id>
aws_secret_access_key =<your_secret_access_key>
To configure IDT for Amazon IoT Greengrass to use Amazon credentials from your credentials
file, edit your config.json
file as follows:
{ "awsRegion": "us-west-2", "auth": { "method": "file", "credentials": { "profile": "default" } } }
Note
If you do not use the default
Amazon profile, be sure to change the
profile name in your config.json
file. For more information, see
Named profiles
Environment variables are variables maintained by the operating system and used by
system commands. They are not saved if you close the SSH session. IDT for Amazon IoT Greengrass can use the
AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environment
variables to store your Amazon credentials.
To set these variables on Linux, macOS, or Unix, use export:
export AWS_ACCESS_KEY_ID=
<your_access_key_id>
export AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To set these variables on Windows, use set:
set AWS_ACCESS_KEY_ID=
<your_access_key_id>
set AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To configure IDT to use the environment variables, edit the auth
section
in your config.json
file. Here is an example:
{ "awsRegion": "us-west-2", "auth": { "method": "environment" } }
Configure device.json
In addition to Amazon credentials, IDT for Amazon IoT Greengrass needs information about the devices that tests are run on (for example, IP address, login information, operating system, and CPU architecture).
You must provide this information using the device.json
template
located in
:
<device_tester_extract_location>
/configs/device.json
All fields that contain values are required as described here:
id
-
A user-defined alphanumeric ID that uniquely identifies a collection of devices called a device pool. Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in the pool are used to parallelize the workload. Multiple devices are used to run different tests.
sku
-
An alphanumeric value that uniquely identifies the device under test. The SKU is used to track qualified boards.
Note
If you want to list your board in the Amazon Partner Device Catalog, the SKU you specify here must match the SKU that you use in the listing process.
features
-
An array that contains the device's supported features. All features are required.
os
andarch
-
Supported operating system (OS) and architecture combinations:
-
linux
,x86_64
-
linux
,armv6l
-
linux
,armv7l
-
linux
,aarch64
-
ubuntu
,x86_64
-
openwrt
,armv7l
-
openwrt
,aarch64
Note
If you use IDT to test Amazon IoT Greengrass running in a Docker container, only the x86_64 Docker architecture is supported.
-
container
-
Validates that the device meets all of the software and hardware requirements to run Lambda functions in container mode on a Greengrass core.
The valid value is
yes
orno
. docker
-
Validates that the device meets all the required technical dependencies to use the Greengrass Docker application deployment connector to run containers
The valid value is
yes
orno
. streamManagement
-
Validates that the device meets all of the required technical dependencies to run Amazon IoT Greengrass stream manager.
The valid value is
yes
orno
. hsi
-
Verifies that the provided HSI shared library can interface with the hardware security module (HSM) and implements the required PKCS#11 APIs correctly. The HSM and shared library must be able to sign a CSR, perform TLS operations, and provide the correct key lengths and public key algorithm.
The valid value is
yes
orno
. ml
-
Validates that the device meets all of the required technical dependencies to perform ML inference locally.
The valid value can be any combination of
mxnet
,tensorflow
,dlr
, andno
(for example,mxnet
,mxnet,tensorflow
,mxnet,tensorflow,dlr
, orno
). mlLambdaContainerizationMode
-
Validates that the device meets all of the required technical dependencies to perform ML inference in container mode on a Greengrass device.
The valid value is
container
,process
, orboth
. processor
-
Validates that the device meets all of the hardware requirements for the specified processor type.
The valid value is
cpu
orgpu
.
Note
If you don't want to use the
container
,docker
,streamManager
,hsi
, orml
feature, you can set the correspondingvalue
tono
.Docker only supports feature qualification for
streamManagement
andml
. machineLearning
-
Optional. Configuration information for ML qualification tests. For more information, see Configure device.json for ML qualification.
hsm
-
Optional. Configuration information for testing with an Amazon IoT Greengrass Hardware Security Module (HSM). Otherwise, the
hsm
property should be omitted. For more information, see Hardware security integration.This property applies only if
connectivity.protocol
is set tossh
.hsm.p11Provider
-
The absolute path to the PKCS#11 implementation's libdl-loadable library.
hsm.slotLabel
-
The slot label used to identify the hardware module.
hsm.slotUserPin
-
The user PIN used to authenticate the Amazon IoT Greengrass core to the module.
hsm.privateKeyLabel
-
The label used to identify the key in the hardware module.
hsm.openSSLEngine
-
The absolute path to the OpenSSL engine's
.so
file that enables PKCS#11 support on OpenSSL. Used by the Amazon IoT Greengrass OTA update agent.
devices.id
-
A user-defined unique identifier for the device being tested.
connectivity.protocol
-
The communication protocol used to communicate with this device. Currently, the only supported values are
ssh
for physical devices anddocker
for Docker containers. connectivity.ip
-
The IP address of the device being tested.
This property applies only if
connectivity.protocol
is set tossh
. connectivity.containerId
-
The container ID or name of the Docker container being tested.
This property applies only if
connectivity.protocol
is set todocker
. connectivity.auth
-
Authentication information for the connection.
This property applies only if
connectivity.protocol
is set tossh
.connectivity.auth.method
-
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
-
pki
-
password
-
connectivity.auth.credentials
-
The credentials used for authentication.
connectivity.auth.credentials.password
-
The password used for signing in to the device being tested.
This value applies only if
connectivity.auth.method
is set topassword
. connectivity.auth.credentials.privKeyPath
-
The full path to the private key used to sign in to the device under test.
This value applies only if
connectivity.auth.method
is set topki
. connectivity.auth.credentials.user
-
The user name for signing in to the device being tested.
connectivity.auth.credentials.privKeyPath
-
The full path to the private key used to sign in to the device being tested.
connectivity.port
-
Optional. The port number to use for SSH connections.
The default value is 22.
This property only applies if
connectivity.protocol
is set tossh
. greengrassLocation
-
The location of Amazon IoT Greengrass Core software on your devices.
For physical devices, this value is only used when you use an existing installation of Amazon IoT Greengrass. Use this attribute to tell IDT to use the version of the Amazon IoT Greengrass Core software installed on your devices.
When running tests in a Docker container from Docker image or Dockerfile provided by Amazon IoT Greengrass, set this value to
/greengrass
. kernelConfigLocation
-
Optional. The path to the kernel configuration file. Amazon IoT Device Tester uses this file to check if the devices have the required kernel features enabled. If not specified, IDT uses the following paths to search for the kernel configuration file:
/proc/config.gz
and/boot/config-
. Amazon IoT Device Tester uses the first path it finds.<kernel-version>
Configure device.json for ML qualification
This section describes the optional properties in the device configuration file that apply to ML qualification. If you plan to run tests for ML qualification, you must define the properties that apply to your use case.
You can use the device-ml.json
template to define the configuration
settings for your device. This template contains the optional ML properties. You can also use
device.json
and add the ML qualification properties. These files are
located in
and includes ML qualification properties.
If you use <device-tester-extract-location>
/configsdevice-ml.json
, you must rename the file to
device.json
before you run IDT tests.
For information about device configuration properties that don't apply to ML qualification, see Configure device.json.
ml
in thefeatures
array-
The ML frameworks that your board supports. This property requires IDT v3.1.0 or later.
-
If your board supports only one framework, specify the framework. For example:
{ "name": "ml", "value": "mxnet" }
-
If your board supports multiple frameworks, specify the frameworks as a comma-separated list. For example:
{ "name": "ml", "value": "mxnet,tensorflow" }
-
mlLambdaContainerizationMode
in thefeatures
array-
The containerization mode that you want to test with. This property requires IDT v3.1.0 or later.
-
Choose
process
to run ML inference code with a non-containerized Lambda function. This option requires Amazon IoT Greengrass v1.10.x or later. -
Choose
container
to run ML inference code with a containerized Lambda function. -
Choose
both
to run ML inference code with both modes. This option requires Amazon IoT Greengrass v1.10.x or later.
-
processor
in thefeatures
array-
Indicates the hardware accelerator that your board supports. This property requires IDT v3.1.0 or later.
-
Choose
cpu
if your board uses a CPU as the processor. -
Choose
gpu
if your board uses a GPU as the processor.
-
machineLearning
-
Optional. Configuration information for ML qualification tests. This property requires IDT v3.1.0 or later.
dlrModelPath
-
Required to use the
dlr
framework. The absolute path to your DLR compiled model directory, which must be namedresnet18
. For more information, see Compile the DLR model.Note
The following is an example path on macOS:
/Users/
.<user>
/Downloads/resnet18 environmentVariables
-
An array of key-value pairs that can dynamically pass settings to ML inference tests. Optional for CPU devices. You can use this section to add framework-specific environment variables required by your device type. For information about these requirements, see the official website of the framework or the device. For example, to run MXNet inference tests on some devices, the following environment variables might be required.
"environmentVariables": [ ... { "key": "PYTHONPATH", "value": "$MXNET_HOME/python:$PYTHONPATH" }, { "key": "MXNET_HOME", "value": "$HOME/mxnet/" }, ... ]
Note
The
value
field might vary based on your MXNet installation.If you're testing Lambda functions that run with containerization on GPU devices, add environment variables for the GPU library. This makes it possible for the GPU to perform computations. To use different GPU libraries, see the official documentation for the library or device.
Note
Configure the following keys if the
mlLambdaContainerizationMode
feature is set tocontainer
orboth
."environmentVariables": [ { "key": "PATH", "value": "
<path/to/software/bin>
:$PATH" }, { "key": "LD_LIBRARY_PATH", "value": "<path/to/ld/lib>
" }, ... ] deviceResources
-
Required by GPU devices. Contains local resources that can be accessed by Lambda functions. Use this section to add local device and volume resources.
-
For device resources, specify
"type": "device"
. For GPU devices, device resources should be GPU-related device files under/dev
.Note
The
/dev/shm
directory is an exception. It can be configured as a volume resource only. -
For volume resources, specify
"type": "volume"
.
-