AWS IoT Core Device Advisor

2023/04/27 - AWS IoT Core Device Advisor - 7 updated api methods

Changes  AWS IoT Core Device Advisor now supports MQTT over WebSocket. With this update, customers can run all three test suites of AWS IoT Core Device Advisor - qualification, custom, and long duration tests - using Signature Version 4 for MQTT over WebSocket.

CreateSuiteDefinition (updated) Link ¶
Changes (request) 
{'suiteDefinitionConfiguration': {'devices': {'deviceRoleArn': 'string'},
                                  'protocol': {'MqttV3_1_1_OverWebSocket',
                                               'MqttV5_OverWebSocket'}}}

Creates a Device Advisor test suite.

Requires permission to access the CreateSuiteDefinition action.

See also: AWS API Documentation

Request Syntax

client.create_suite_definition(
    suiteDefinitionConfiguration={
        'suiteDefinitionName': 'string',
        'devices': [
            {
                'thingArn': 'string',
                'certificateArn': 'string',
                'deviceRoleArn': 'string'
            },
        ],
        'intendedForQualification': True|False,
        'isLongDurationTest': True|False,
        'rootGroup': 'string',
        'devicePermissionRoleArn': 'string',
        'protocol': 'MqttV3_1_1'|'MqttV5'|'MqttV3_1_1_OverWebSocket'|'MqttV5_OverWebSocket'
    },
    tags={
        'string': 'string'
    }
)
type suiteDefinitionConfiguration:

dict

param suiteDefinitionConfiguration:

[REQUIRED]

Creates a Device Advisor test suite with suite definition configuration.

  • suiteDefinitionName (string) -- [REQUIRED]

    Gets the suite definition name. This is a required parameter.

  • devices (list) --

    Gets the devices configured.

    • (dict) --

      Information of a test device. A thing ARN, certificate ARN or device role ARN is required.

      • thingArn (string) --

        Lists device's thing ARN.

      • certificateArn (string) --

        Lists device's certificate ARN.

      • deviceRoleArn (string) --

        Lists device's role ARN.

  • intendedForQualification (boolean) --

    Gets the tests intended for qualification in a suite.

  • isLongDurationTest (boolean) --

    Verifies if the test suite is a long duration test.

  • rootGroup (string) -- [REQUIRED]

    Gets the test suite root group. This is a required parameter.

  • devicePermissionRoleArn (string) -- [REQUIRED]

    Gets the device permission ARN. This is a required parameter.

  • protocol (string) --

    Sets the MQTT protocol that is configured in the suite definition.

type tags:

dict

param tags:

The tags to be attached to the suite definition.

  • (string) --

    • (string) --

rtype:

dict

returns:

Response Syntax

{
    'suiteDefinitionId': 'string',
    'suiteDefinitionArn': 'string',
    'suiteDefinitionName': 'string',
    'createdAt': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • suiteDefinitionId (string) --

      The UUID of the test suite created.

    • suiteDefinitionArn (string) --

      The Amazon Resource Name (ARN) of the test suite.

    • suiteDefinitionName (string) --

      The suite definition name of the test suite. This is a required parameter.

    • createdAt (datetime) --

      The timestamp of when the test suite was created.

GetEndpoint (updated) Link ¶
Changes (request) 
{'authenticationMethod': 'X509ClientCertificate | SignatureVersion4',
 'deviceRoleArn': 'string'}

Gets information about an Device Advisor endpoint.

See also: AWS API Documentation

Request Syntax

client.get_endpoint(
    thingArn='string',
    certificateArn='string',
    deviceRoleArn='string',
    authenticationMethod='X509ClientCertificate'|'SignatureVersion4'
)
type thingArn:

string

param thingArn:

The thing ARN of the device. This is an optional parameter.

type certificateArn:

string

param certificateArn:

The certificate ARN of the device. This is an optional parameter.

type deviceRoleArn:

string

param deviceRoleArn:

The device role ARN of the device. This is an optional parameter.

type authenticationMethod:

string

param authenticationMethod:

The authentication method used during the device connection.

rtype:

dict

returns:

Response Syntax

{
    'endpoint': 'string'
}

Response Structure

  • (dict) --

    • endpoint (string) --

      The response of an Device Advisor endpoint.

GetSuiteDefinition (updated) Link ¶
Changes (response) 
{'suiteDefinitionConfiguration': {'devices': {'deviceRoleArn': 'string'},
                                  'protocol': {'MqttV3_1_1_OverWebSocket',
                                               'MqttV5_OverWebSocket'}}}

Gets information about a Device Advisor test suite.

Requires permission to access the GetSuiteDefinition action.

See also: AWS API Documentation

Request Syntax

client.get_suite_definition(
    suiteDefinitionId='string',
    suiteDefinitionVersion='string'
)
type suiteDefinitionId:

string

param suiteDefinitionId:

[REQUIRED]

Suite definition ID of the test suite to get.

type suiteDefinitionVersion:

string

param suiteDefinitionVersion:

Suite definition version of the test suite to get.

rtype:

dict

returns:

Response Syntax

{
    'suiteDefinitionId': 'string',
    'suiteDefinitionArn': 'string',
    'suiteDefinitionVersion': 'string',
    'latestVersion': 'string',
    'suiteDefinitionConfiguration': {
        'suiteDefinitionName': 'string',
        'devices': [
            {
                'thingArn': 'string',
                'certificateArn': 'string',
                'deviceRoleArn': 'string'
            },
        ],
        'intendedForQualification': True|False,
        'isLongDurationTest': True|False,
        'rootGroup': 'string',
        'devicePermissionRoleArn': 'string',
        'protocol': 'MqttV3_1_1'|'MqttV5'|'MqttV3_1_1_OverWebSocket'|'MqttV5_OverWebSocket'
    },
    'createdAt': datetime(2015, 1, 1),
    'lastModifiedAt': datetime(2015, 1, 1),
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • suiteDefinitionId (string) --

      Suite definition ID of the suite definition.

    • suiteDefinitionArn (string) --

      The ARN of the suite definition.

    • suiteDefinitionVersion (string) --

      Suite definition version of the suite definition.

    • latestVersion (string) --

      Latest suite definition version of the suite definition.

    • suiteDefinitionConfiguration (dict) --

      Suite configuration of the suite definition.

      • suiteDefinitionName (string) --

        Gets the suite definition name. This is a required parameter.

      • devices (list) --

        Gets the devices configured.

        • (dict) --

          Information of a test device. A thing ARN, certificate ARN or device role ARN is required.

          • thingArn (string) --

            Lists device's thing ARN.

          • certificateArn (string) --

            Lists device's certificate ARN.

          • deviceRoleArn (string) --

            Lists device's role ARN.

      • intendedForQualification (boolean) --

        Gets the tests intended for qualification in a suite.

      • isLongDurationTest (boolean) --

        Verifies if the test suite is a long duration test.

      • rootGroup (string) --

        Gets the test suite root group. This is a required parameter.

      • devicePermissionRoleArn (string) --

        Gets the device permission ARN. This is a required parameter.

      • protocol (string) --

        Sets the MQTT protocol that is configured in the suite definition.

    • createdAt (datetime) --

      Date (in Unix epoch time) when the suite definition was created.

    • lastModifiedAt (datetime) --

      Date (in Unix epoch time) when the suite definition was last modified.

    • tags (dict) --

      Tags attached to the suite definition.

      • (string) --

        • (string) --

GetSuiteRun (updated) Link ¶
Changes (response) 
{'suiteRunConfiguration': {'primaryDevice': {'deviceRoleArn': 'string'}}}

Gets information about a Device Advisor test suite run.

Requires permission to access the GetSuiteRun action.

See also: AWS API Documentation

Request Syntax

client.get_suite_run(
    suiteDefinitionId='string',
    suiteRunId='string'
)
type suiteDefinitionId:

string

param suiteDefinitionId:

[REQUIRED]

Suite definition ID for the test suite run.

type suiteRunId:

string

param suiteRunId:

[REQUIRED]

Suite run ID for the test suite run.

rtype:

dict

returns:

Response Syntax

{
    'suiteDefinitionId': 'string',
    'suiteDefinitionVersion': 'string',
    'suiteRunId': 'string',
    'suiteRunArn': 'string',
    'suiteRunConfiguration': {
        'primaryDevice': {
            'thingArn': 'string',
            'certificateArn': 'string',
            'deviceRoleArn': 'string'
        },
        'selectedTestList': [
            'string',
        ],
        'parallelRun': True|False
    },
    'testResult': {
        'groups': [
            {
                'groupId': 'string',
                'groupName': 'string',
                'tests': [
                    {
                        'testCaseRunId': 'string',
                        'testCaseDefinitionId': 'string',
                        'testCaseDefinitionName': 'string',
                        'status': 'PASS'|'FAIL'|'CANCELED'|'PENDING'|'RUNNING'|'STOPPING'|'STOPPED'|'PASS_WITH_WARNINGS'|'ERROR',
                        'startTime': datetime(2015, 1, 1),
                        'endTime': datetime(2015, 1, 1),
                        'logUrl': 'string',
                        'warnings': 'string',
                        'failure': 'string',
                        'testScenarios': [
                            {
                                'testCaseScenarioId': 'string',
                                'testCaseScenarioType': 'Advanced'|'Basic',
                                'status': 'PASS'|'FAIL'|'CANCELED'|'PENDING'|'RUNNING'|'STOPPING'|'STOPPED'|'PASS_WITH_WARNINGS'|'ERROR',
                                'failure': 'string',
                                'systemMessage': 'string'
                            },
                        ]
                    },
                ]
            },
        ]
    },
    'startTime': datetime(2015, 1, 1),
    'endTime': datetime(2015, 1, 1),
    'status': 'PASS'|'FAIL'|'CANCELED'|'PENDING'|'RUNNING'|'STOPPING'|'STOPPED'|'PASS_WITH_WARNINGS'|'ERROR',
    'errorReason': 'string',
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • suiteDefinitionId (string) --

      Suite definition ID for the test suite run.

    • suiteDefinitionVersion (string) --

      Suite definition version for the test suite run.

    • suiteRunId (string) --

      Suite run ID for the test suite run.

    • suiteRunArn (string) --

      The ARN of the suite run.

    • suiteRunConfiguration (dict) --

      Suite run configuration for the test suite run.

      • primaryDevice (dict) --

        Sets the primary device for the test suite run. This requires a thing ARN or a certificate ARN.

        • thingArn (string) --

          Lists device's thing ARN.

        • certificateArn (string) --

          Lists device's certificate ARN.

        • deviceRoleArn (string) --

          Lists device's role ARN.

      • selectedTestList (list) --

        Sets test case list.

        • (string) --

      • parallelRun (boolean) --

        TRUE if multiple test suites run in parallel.

    • testResult (dict) --

      Test results for the test suite run.

      • groups (list) --

        Show each group of test results.

        • (dict) --

          Show Group Result.

          • groupId (string) --

            Group result ID.

          • groupName (string) --

            Group Result Name.

          • tests (list) --

            Tests under Group Result.

            • (dict) --

              Provides the test case run.

              • testCaseRunId (string) --

                Provides the test case run ID.

              • testCaseDefinitionId (string) --

                Provides the test case run definition ID.

              • testCaseDefinitionName (string) --

                Provides the test case run definition name.

              • status (string) --

                Provides the test case run status. Status is one of the following:

                • PASS: Test passed.

                • FAIL: Test failed.

                • PENDING: Test has not started running but is scheduled.

                • RUNNING: Test is running.

                • STOPPING: Test is performing cleanup steps. You will see this status only if you stop a suite run.

                • STOPPED Test is stopped. You will see this status only if you stop a suite run.

                • PASS_WITH_WARNINGS: Test passed with warnings.

                • ERORR: Test faced an error when running due to an internal issue.

              • startTime (datetime) --

                Provides test case run start time.

              • endTime (datetime) --

                Provides test case run end time.

              • logUrl (string) --

                Provides test case run log URL.

              • warnings (string) --

                Provides test case run warnings.

              • failure (string) --

                Provides test case run failure result.

              • testScenarios (list) --

                Provides the test scenarios for the test case run.

                • (dict) --

                  Provides test case scenario.

                  • testCaseScenarioId (string) --

                    Provides test case scenario ID.

                  • testCaseScenarioType (string) --

                    Provides test case scenario type. Type is one of the following:

                    • Advanced

                    • Basic

                  • status (string) --

                    Provides the test case scenario status. Status is one of the following:

                    • PASS: Test passed.

                    • FAIL: Test failed.

                    • PENDING: Test has not started running but is scheduled.

                    • RUNNING: Test is running.

                    • STOPPING: Test is performing cleanup steps. You will see this status only if you stop a suite run.

                    • STOPPED Test is stopped. You will see this status only if you stop a suite run.

                    • PASS_WITH_WARNINGS: Test passed with warnings.

                    • ERORR: Test faced an error when running due to an internal issue.

                  • failure (string) --

                    Provides test case scenario failure result.

                  • systemMessage (string) --

    • startTime (datetime) --

      Date (in Unix epoch time) when the test suite run started.

    • endTime (datetime) --

      Date (in Unix epoch time) when the test suite run ended.

    • status (string) --

      Status for the test suite run.

    • errorReason (string) --

      Error reason for any test suite run failure.

    • tags (dict) --

      The tags attached to the suite run.

      • (string) --

        • (string) --

ListSuiteDefinitions (updated) Link ¶
Changes (response) 
{'suiteDefinitionInformationList': {'defaultDevices': {'deviceRoleArn': 'string'},
                                    'protocol': {'MqttV3_1_1_OverWebSocket',
                                                 'MqttV5_OverWebSocket'}}}

Lists the Device Advisor test suites you have created.

Requires permission to access the ListSuiteDefinitions action.

See also: AWS API Documentation

Request Syntax

client.list_suite_definitions(
    maxResults=123,
    nextToken='string'
)
type maxResults:

integer

param maxResults:

The maximum number of results to return at once.

type nextToken:

string

param nextToken:

A token used to get the next set of results.

rtype:

dict

returns:

Response Syntax

{
    'suiteDefinitionInformationList': [
        {
            'suiteDefinitionId': 'string',
            'suiteDefinitionName': 'string',
            'defaultDevices': [
                {
                    'thingArn': 'string',
                    'certificateArn': 'string',
                    'deviceRoleArn': 'string'
                },
            ],
            'intendedForQualification': True|False,
            'isLongDurationTest': True|False,
            'protocol': 'MqttV3_1_1'|'MqttV5'|'MqttV3_1_1_OverWebSocket'|'MqttV5_OverWebSocket',
            'createdAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • suiteDefinitionInformationList (list) --

      An array of objects that provide summaries of information about the suite definitions in the list.

      • (dict) --

        Information about the suite definition.

        • suiteDefinitionId (string) --

          Suite definition ID of the test suite.

        • suiteDefinitionName (string) --

          Suite name of the test suite.

        • defaultDevices (list) --

          Specifies the devices that are under test for the test suite.

          • (dict) --

            Information of a test device. A thing ARN, certificate ARN or device role ARN is required.

            • thingArn (string) --

              Lists device's thing ARN.

            • certificateArn (string) --

              Lists device's certificate ARN.

            • deviceRoleArn (string) --

              Lists device's role ARN.

        • intendedForQualification (boolean) --

          Specifies if the test suite is intended for qualification.

        • isLongDurationTest (boolean) --

          Verifies if the test suite is a long duration test.

        • protocol (string) --

          Gets the MQTT protocol that is configured in the suite definition.

        • createdAt (datetime) --

          Date (in Unix epoch time) when the test suite was created.

    • nextToken (string) --

      A token used to get the next set of results.

StartSuiteRun (updated) Link ¶
Changes (request) 
{'suiteRunConfiguration': {'primaryDevice': {'deviceRoleArn': 'string'}}}

Starts a Device Advisor test suite run.

Requires permission to access the StartSuiteRun action.

See also: AWS API Documentation

Request Syntax

client.start_suite_run(
    suiteDefinitionId='string',
    suiteDefinitionVersion='string',
    suiteRunConfiguration={
        'primaryDevice': {
            'thingArn': 'string',
            'certificateArn': 'string',
            'deviceRoleArn': 'string'
        },
        'selectedTestList': [
            'string',
        ],
        'parallelRun': True|False
    },
    tags={
        'string': 'string'
    }
)
type suiteDefinitionId:

string

param suiteDefinitionId:

[REQUIRED]

Suite definition ID of the test suite.

type suiteDefinitionVersion:

string

param suiteDefinitionVersion:

Suite definition version of the test suite.

type suiteRunConfiguration:

dict

param suiteRunConfiguration:

[REQUIRED]

Suite run configuration.

  • primaryDevice (dict) -- [REQUIRED]

    Sets the primary device for the test suite run. This requires a thing ARN or a certificate ARN.

    • thingArn (string) --

      Lists device's thing ARN.

    • certificateArn (string) --

      Lists device's certificate ARN.

    • deviceRoleArn (string) --

      Lists device's role ARN.

  • selectedTestList (list) --

    Sets test case list.

    • (string) --

  • parallelRun (boolean) --

    TRUE if multiple test suites run in parallel.

type tags:

dict

param tags:

The tags to be attached to the suite run.

  • (string) --

    • (string) --

rtype:

dict

returns:

Response Syntax

{
    'suiteRunId': 'string',
    'suiteRunArn': 'string',
    'createdAt': datetime(2015, 1, 1),
    'endpoint': 'string'
}

Response Structure

  • (dict) --

    • suiteRunId (string) --

      Suite Run ID of the started suite run.

    • suiteRunArn (string) --

      Amazon Resource Name (ARN) of the started suite run.

    • createdAt (datetime) --

      Starts a Device Advisor test suite run based on suite create time.

    • endpoint (string) --

      The response of an Device Advisor test endpoint.

UpdateSuiteDefinition (updated) Link ¶
Changes (request) 
{'suiteDefinitionConfiguration': {'devices': {'deviceRoleArn': 'string'},
                                  'protocol': {'MqttV3_1_1_OverWebSocket',
                                               'MqttV5_OverWebSocket'}}}

Updates a Device Advisor test suite.

Requires permission to access the UpdateSuiteDefinition action.

See also: AWS API Documentation

Request Syntax

client.update_suite_definition(
    suiteDefinitionId='string',
    suiteDefinitionConfiguration={
        'suiteDefinitionName': 'string',
        'devices': [
            {
                'thingArn': 'string',
                'certificateArn': 'string',
                'deviceRoleArn': 'string'
            },
        ],
        'intendedForQualification': True|False,
        'isLongDurationTest': True|False,
        'rootGroup': 'string',
        'devicePermissionRoleArn': 'string',
        'protocol': 'MqttV3_1_1'|'MqttV5'|'MqttV3_1_1_OverWebSocket'|'MqttV5_OverWebSocket'
    }
)
type suiteDefinitionId:

string

param suiteDefinitionId:

[REQUIRED]

Suite definition ID of the test suite to be updated.

type suiteDefinitionConfiguration:

dict

param suiteDefinitionConfiguration:

[REQUIRED]

Updates a Device Advisor test suite with suite definition configuration.

  • suiteDefinitionName (string) -- [REQUIRED]

    Gets the suite definition name. This is a required parameter.

  • devices (list) --

    Gets the devices configured.

    • (dict) --

      Information of a test device. A thing ARN, certificate ARN or device role ARN is required.

      • thingArn (string) --

        Lists device's thing ARN.

      • certificateArn (string) --

        Lists device's certificate ARN.

      • deviceRoleArn (string) --

        Lists device's role ARN.

  • intendedForQualification (boolean) --

    Gets the tests intended for qualification in a suite.

  • isLongDurationTest (boolean) --

    Verifies if the test suite is a long duration test.

  • rootGroup (string) -- [REQUIRED]

    Gets the test suite root group. This is a required parameter.

  • devicePermissionRoleArn (string) -- [REQUIRED]

    Gets the device permission ARN. This is a required parameter.

  • protocol (string) --

    Sets the MQTT protocol that is configured in the suite definition.

rtype:

dict

returns:

Response Syntax

{
    'suiteDefinitionId': 'string',
    'suiteDefinitionArn': 'string',
    'suiteDefinitionName': 'string',
    'suiteDefinitionVersion': 'string',
    'createdAt': datetime(2015, 1, 1),
    'lastUpdatedAt': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • suiteDefinitionId (string) --

      Suite definition ID of the updated test suite.

    • suiteDefinitionArn (string) --

      Amazon Resource Name (ARN) of the updated test suite.

    • suiteDefinitionName (string) --

      Updates the suite definition name. This is a required parameter.

    • suiteDefinitionVersion (string) --

      Suite definition version of the updated test suite.

    • createdAt (datetime) --

      Timestamp of when the test suite was created.

    • lastUpdatedAt (datetime) --

      Timestamp of when the test suite was updated.