Setting up

Before you use Device Advisor for the first time, complete the following tasks.

Create an IoT thing

First you will need to create a thing and attach a certificate to the thing. Use the following tutorial to create a thing: Create a thing object.

Create an IAM role to be used as your device role

Note

You can quickly create the device role using the Device Advisor console. See Getting started with the Device Advisor in the console for the steps to set up your device role using the Device Advisor console.

1. Go to the AWS IAM console and log in to the account you use for Device Advisor testing.

2. In the left navigation pane, chose Policies.

3. Choose Create policy.

4. Under Create policy, do the following:

   1. For Service, choose IoT.

   2. Under Actions, either select actions based on the policy attached to the IoT thing or certificate created in the previous section (recommended), or search for the following actions in the Filter action box and select them.

      • Connect

      • Publish

      • Subscribe

      • Receive

      • RetainPublish

   3. Under Resources, for best security practices, we recommend you restrict the client, topic, and topicfilter resources using the following steps:

      1. Choose Specify client resource ARN for the Connect action.

         1. Choose Add ARN.

         2. Specify the region, accountId, and clientId in the visual ARN editor, or manually specify the Amazon Resource Names (ARNs) of the IoT topics you want to use to run test cases. The clientId is the MQTT clientId your device uses to interact with Device Advisor.

         3. Choose Add.

      2. Choose Specify topic resource ARN for the Receive and 1 more action.

         1. Choose Add ARN.

         2. Specify the region, accountId, and topic name in the visual ARN editor or manually specify the ARNs of the IoT topics you want to use to run test cases. The topic name is the MQTT topic your device use to publish messages to.

         3. Choose Add.

      3. Choose Specify topicfilter resource ARN for the Subscribe action.

         1. Choose Add ARN.

         2. Specify the region, accountId, and topic name in the visual ARN editor or manually specify the ARNs of the IoT topics you want to use to run test cases. The topic name is the MQTT topic your device uses to subscribe to.

         3. Choose Add.

5. Choose Review policy.

6. Under Review policy, enter a Name.

7. Choose Create policy.

8. On the left navigation pane, Choose Roles.

9. Choose Create Role.

10. Under Or select a service to view its use cases, choose IoT.

11. Under Select your use case, choose IoT.

12. Choose Next: Permissions.

13. (Optional) Under Set permissions boundary, Choose Use a permissions boundary to control the maximum role permissions, and then choose the policy you just created.

14. Choose Next: Tags.

15. Choose Next: Review.

16. Enter a Role name and a Role description.

17. Choose Create role.

18. Navigate to the role you created.

19. In the Permissions tab, choose Attach policies and then choose the policy you created in Step 4.

20. Choose Attach policy.

21. Choose Trust relationships tab and choose Edit trust relationship.

22. Enter this policy:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "AllowAwsIoTCoreDeviceAdvisor",
          "Effect": "Allow",
          "Principal": {
            "Service": "iotdeviceadvisor.amazonaws.com"
          },
          "Action": "sts:AssumeRole"
        }
      ]
    }

23. Choose Update Trust Policy.

Create a custom-managed policy for an IAM user to use Device Advisor

1. Navigate to the IAM console at https://console.aws.amazon.com/iam/. If prompted, enter your AWS credentials to sign in.

2. In the left navigation pane, choose Policies.

3. Choose Create Policy, then choose the JSON tab.

4. Add the necessary permissions to use Device Advisor. The policy document can be found in the topic Security best practices.

5. Choose Review Policy.

6. Enter a Name and Description.

7. Choose Create Policy.

Create an IAM user to use Device Advisor

Note

We recommend that you create an IAM user to use when you run Device Advisor tests. Using an admin user to run Device Advisor tests, while allowed, is not recommended.

1. Navigate to the IAM console at https://console.aws.amazon.com/iam/ If prompted, enter your AWS credentials to sign in.

2. In the left navigation pane, Choose Users.

3. Choose Add User.

4. Enter a User name.

5. Users need programmatic access if they want to interact with AWS outside of the AWS Management Console. The way to grant programmatic access depends on the type of user that's accessing AWS:

   • If you manage identities in IAM Identity Center, the AWS APIs require a profile, and the AWS Command Line Interface requires a profile or an environment variable.

   • If you have IAM users, the AWS APIs and the AWS Command Line Interface require access keys. Whenever possible, create temporary credentials that consist of an access key ID, a secret access key, and a security token that indicates when the credentials expire.

   To grant users programmatic access, choose one of the following options.

   Which user needs programmatic access?	To	By
   Workforce identity (Users managed in IAM Identity Center)	Use short-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS SDKs).	Following the instructions for the interface that you want to use: For the AWS CLI, follow the instructions in Getting IAM role credentials for CLI access in the AWS IAM Identity Center (successor to AWS Single Sign-On) User Guide. For the AWS APIs, follow the instructions in SSO credentials in the AWS SDKs and Tools Reference Guide.
   IAM	Use short-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS SDKs).	Following the instructions in Using temporary credentials with AWS resources in the IAM User Guide.
   IAM	Use long-term credentials to sign programmatic requests to the AWS CLI or AWS APIs (directly or by using the AWS SDKs). (Not recommended)	Following the instructions in Managing access keys for IAM users in the IAM User Guide.

6. Choose Next: Permissions.

7. To provide access, add permissions to your users, groups, or roles:

   • Users and groups in AWS IAM Identity Center (successor to AWS Single Sign-On):

     Create a permission set. Follow the instructions in Create a permission set in the AWS IAM Identity Center (successor to AWS Single Sign-On) User Guide.

   • Users managed in IAM through an identity provider:

     Create a role for identity federation. Follow the instructions in Creating a role for a third-party identity provider (federation) in the IAM User Guide.

   • IAM users:

     • Create a role that your user can assume. Follow the instructions in Creating a role for an IAM user in the IAM User Guide.

     • (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in Adding permissions to a user (console) in the IAM User Guide.

8. Enter the name of the custom-managed policy the you created in the search box, and then select the check box for Policy name.

9. Choose Next: Tags.

10. Choose Next: Review.

11. Choose Create user.

12. Choose Close.

Device Advisor requires access to your AWS resources (things, certificates, and endpoints) on your behalf. Your IAM user must have the necessary permissions. Device Advisor will also publish logs to Amazon CloudWatch if you attach the necessary permissions policy to your IAM user.

Configure your device

Device Advisor uses the server name indication (SNI) TLS extension to apply TLS configurations. Devices must use this extension when connecting and pass a server name that is identical to the Device Advisor test endpoint.

Device Advisor allows the TLS connection when a test is in the Running state and denies the TLS connection before and after each test run. For this reason, we also recommend using the device connect retry mechanism to have a fully automated testing experience with Device Advisor. If you run a test suite with more than one test case (for instance TLS connect, MQTT connect, and MQTT publish) then we recommend that you have a mechanism built for your device to try connecting to our test endpoint every five seconds. You can then run multiple test cases, in sequence, in an automated manner.

Note

To make your device software ready for testing, we recommend that you have an SDK that can connect to AWS IoT Core and update the SDK with the Device Advisor test endpoint provided for your account.

Device Advisor supports two types of endpoints: Account-level endpoints and Device-level endpoints. Choose the endpoint that best fits your use case. To simultaneously run multiple test suites using different devices, use a Device-level endpoint. Run the following command to get the Device-level endpoint:

aws iotdeviceadvisor get-endpoint --thing-arn your-thing-arn

or

aws iotdeviceadvisor get-endpoint --certificate-arn your-certificate-arn

To run one test suite at a time, choose an Account-level endpoint. Run the following command to get the Account-level endpoint:

aws iotdeviceadvisor get-endpoint