# Onboard devices and operate them in hub
<a name="managedintegrations-sdk-v2-cookbook-onboard-to-hub"></a>

Set up your devices to be onboarded to your managed integrations hub by creating a managed thing and connecting it to your hub. Devices can be onboarded to a hub through simple setup, user guided setup, or WiFi Simple Setup.

**Topics**
+ [Simple setup to onboard and operate devices](managedintegrations-sdk-v2-cookbook-ss.md)
+ [User guided setup to onboard and operate devices](managedintegrations-sdk-v2-cookbook-ugs.md)
+ [Capability rediscovery](managedintegrations-sdk-v2-onboarding-capability-rediscovery.md)
+ [WiFi Simple Setup to onboard and operate devices](managedintegrations-sdk-v2-cookbook-wss.md)

# Simple setup to onboard and operate devices
<a name="managedintegrations-sdk-v2-cookbook-ss"></a>

Set up your devices to be onboarded to your managed integrations hub by creating a managed thing and connecting it to your hub. This section describes the steps to complete the device onboarding process using simple setup.

## Prerequisites
<a name="managedintegrations-sdk-v2-cookbook-ss-prereq"></a>

Complete these steps before attempting to onboard a device:
+ Onboard a hub device to the managed integrations hub.
+ Install the latest version of AWS CLI from the [Managed Integrations AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Subscribe to [DEVICE\$1LIFE\$1CYCLE](managedintegrations-notifications.md#managedintegrations-notification-setup) event notifications.

**Topics**
+ [Prerequisites](#managedintegrations-sdk-v2-cookbook-ss-prereq)
+ [Step 1: Create a credential locker](#managedintegrations-sdk-v2-cookbook-credential-locker)
+ [Step 2: Add the credential locker to your hub](#managedintegrations-sdk-v2-cookbook-add-to-hub)
+ [Step 3: Create a managed thing with credentials.](#managedintegrations-sdk-v2-cookbook-ss-create-managed-thing)
+ [Step 4: Plug in the device and check its status.](#managedintegrations-sdk-v2-cookbook-ss-check-device-status)
+ [Step 5: Get Device Capabilities](#managedintegrations-sdk-v2-cookbook-ss-check-device-capabilities)
+ [Step 6: Send a command to the managed thing](#managedintegrations-sdk-v2-cookbook-ss-control-device)
+ [Step 7: Remove the managed thing from your hub](#managedintegrations-sdk-v2-cookbook-clean-up)

## Step 1: Create a credential locker
<a name="managedintegrations-sdk-v2-cookbook-credential-locker"></a>

Create a credential locker for your device. 

**To create a credential locker**
+ Use the `create-credential-locker` command. Executing this command will trigger the creation of all manufacturing resources including the Wi-Fi setup key pair and device certificate.

  **create-credential-locker example**

  ```
  aws iot-managed-integrations create-credential-locker \
    --name "DEVICE_NAME"
  ```

  **Response:**

  ```
  {    
    "Id": "LOCKER_ID"
    "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:credential-locker/LOCKER_ID
    "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
  }
  ```

  For more information, see the [create-credential-locker](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-credential-locker.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 2: Add the credential locker to your hub
<a name="managedintegrations-sdk-v2-cookbook-add-to-hub"></a>

Add the credential locker to your hub.

**To add a credential locker to your hub**
+ Use the following command to add a credential locker to your hub.

  ```
  aws iotmi --region AWS_REGION --endpoint AWS_ENDPOINT update-managed-thing \
  --identifier "HUB_MANAGED_THING_ID" --credential-locker-id "LOCKER_ID"
  ```

## Step 3: Create a managed thing with credentials.
<a name="managedintegrations-sdk-v2-cookbook-ss-create-managed-thing"></a>

Create a managed thing with credentials for your device. Each device requires its own managed thing.

**To create a managed thing**
+ Use the `create-managed-thing` command to create a managed thing for your device.

  **create-managed-thing example**

  ```
  #ZWAVE: 
  aws iot-managed-integrations create-managed-thing --role DEVICE \
  --authentication-material '900137947003133...' \ #auth material from zwave qr code
  --authentication-material-type ZWAVE_QR_BAR_CODE \
  --credential-locker-id ${locker_id}
  
  #ZIGBEE:
  aws iot-managed-integrations create-managed-thing --role DEVICE \
  --authentication-material 'Z:286...$I:A4DC00.' \ #auth material from zigbee qr code
  --authentication-material-type ZIGBEE_QR_BAR_CODE \
  --credential-locker-id ${locker_id}
  ```
**Note**  
There are separate commands for Z-wave and Zigbee devices.

  **Response:**

  ```
  {    
    "Id": "DEVICE_MANAGED_THING_ID"
    "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID"
    "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
  }
  ```

  For more information, see the [create-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 4: Plug in the device and check its status.
<a name="managedintegrations-sdk-v2-cookbook-ss-check-device-status"></a>

**Plug in the device and check its status.**
+ Use the `get-managed-thing` command to check your device's status. The ProvisioningStatus of your managed thing must be ACTIVATED. For more information on ProvisioningStatus, see [Device Provisioning](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **get-managed-thing example**

  ```
  #KINESIS NOTIFICATION:
  {
      "version": "1.0.0",
      "messageId": "4ac684bb7f4c41adbb2eecc1e7991xxx",
      "messageType": "DEVICE_LIFE_CYCLE",
      "source": "aws.iotmanagedintegrations",
      "customerAccountId": "12345678901",
      "timestamp": "2025-06-10T05:30:59.852659650Z",
      "region": "us-east-1",
      "resources": ["XXX"],
      "payload": {
          "deviceDetails": {
              "id": "1e84f61fa79a41219534b6fd57052XXX",
              "arn": "XXX",
              "createdAt": "2025-06-09T06:24:34.336120179Z",
              "updatedAt": "2025-06-10T05:30:59.784157019Z"
          },
          "status": "ACTIVATED"
      }
  }
  aws iot-managed-integrations get-managed-thing \
  --identifier :"DEVICE_MANAGED_THING_ID"
  ```

  **Response:**

  ```
  {    
    "Id": "DEVICE_MANAGED_THING_ID"
    "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/MANAGED_THING_ID"
    "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
  }
  ```

  For more information, see the [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 5: Get Device Capabilities
<a name="managedintegrations-sdk-v2-cookbook-ss-check-device-capabilities"></a>

Use the `get-managed-thing-capabilities` command to obtain your endpoint ID and view a list of possible actions for your device.

**To get a device's capabilities**
+ Use the `get-managed-thing-capabilities` command and note the endpoint ID.

  **get-managed-thing-capabilties example**

  ```
  aws iotmi get-managed-thing-capabilities \
  --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **Response:**

  ```
  {    
      "ManagedThingId": "1e84f61fa79a41219534b6fd57052cbc",
      "CapabilityReport": {
          "version": "1.0.0",
          "nodeId": "zw.FCB10009+06",
          "endpoints": [
              {
                  "id": "ENDPOINT_ID"
                  "deviceTypes": [
                      "On/Off Switch"
                  ],
                  "capabilities": [
                      {
                          "id": "matter.OnOff@1.4",
                          "name": "On/Off",
                          "version": "6",
                          "properties": [
                              "OnOff"
                          ],
                          "actions": [
                              "Off",
                              "On"
                          ],
                          "events": []
                      }
                      ...
  }
  ```

  For more information, see the [get-managed-thing-capabilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 6: Send a command to the managed thing
<a name="managedintegrations-sdk-v2-cookbook-ss-control-device"></a>

Use the `send-managed-thing-command` command to send a toggle action command to your managed thing.

**To send a command to your managed thing**
+ Use the `send-managed-thing-command` command to send a command to your managed thing.

  **send-managed-thing-command example**

  ```
  json=$(jq -cr '.|@json') <<EOF
  [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff@1.4",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "Toggle",
              "parameters": {}
            }
          ]
        }
      ]
    }
  ]
  EOF
  aws iot-managed-integrations send-managed-thing-command \
  --managed-thing-id "DEVICE_MANAGED_THING_ID" --endpoints "ENDPOINT_ID"
  ```
**Note**  
This example uses jq cli to but you can also pass the entire `endpointId` string

  **Response:**

  ```
  {    
  "TraceId": "TRACE_ID"
  }
  ```

  For more information, see the [send-managed-thing-command](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 7: Remove the managed thing from your hub
<a name="managedintegrations-sdk-v2-cookbook-clean-up"></a>

Clean up your hub by removing the managed thing.

**To delete a managed thing**
+ Use the `delete-managed-thing` command to remove a managed thing from your device hub.

  **delete-managed-thing example**

  ```
  aws iot-managed-integrations delete-managed-thing \
  --identifier "DEVICE_MANAGED_THING_ID"
  ```

  For more information, see the [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.
**Note**  
If the device is stuck in a `DELETE_IN_PROGRESS` state, append the `--force` flag to the `delete-managed-thing command`.
**Note**  
For Z-wave devices, you need to put the device into pairing mode after executing the command.

# User guided setup to onboard and operate devices
<a name="managedintegrations-sdk-v2-cookbook-ugs"></a>

Set up your devices to be onboarded to your managed integrations hub by creating a managed thing an connecting it to your hub. This section describes the steps to complete the device onboarding process using user guided setup.

## Prerequisites
<a name="managedintegrations-sdk-v2-cookbook-ugs-prereq"></a>

Complete these steps before attempting to onboard a device:
+ Onboard a hub device to the managed integrations hub.
+ Install the latest version of AWS CLI from the [Managed Integrations AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ Subscribe to [DEVICE\$1DISCOVERY\$1STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup) event notifications.

**Topics**
+ [Prerequisites](#managedintegrations-sdk-v2-cookbook-ugs-prereq)
+ [Prerequisite: Enable pairing mode on your Z Wave device](#managedintegrations-sdk-v2-cookbook-pairing-mode)
+ [Step 1: Start device discovery](#managedintegrations-sdk-v2-cookbook-device-discovery)
+ [Step 2: Query the discovery job ID](#managedintegrations-sdk-v2-cookbook-query-discovery)
+ [Step 3: Create a managed thing for your device](#managedintegrations-sdk-v2-cookbook-ugs-managed-thing)
+ [Step 4: Query the managed thing](#managedintegrations-sdk-v2-cookbook-query-managed-thing)
+ [Step 5: Get managed thing capabilities](#managedintegrations-sdk-v2-cookbook-check-device-capabilties)
+ [Step 6: Send a command to the managed thing](#managedintegrations-sdk-v2-cookbook-ugs-control-device)
+ [Step 7: Check the managed thing state](#managedintegrations-sdk-v2-cookbook-ugs-device-state)
+ [Step 8: Remove managed thing from your hub](#managedintegrations-sdk-v2-cookbook-ugs-clean-up)

## Prerequisite: Enable pairing mode on your Z Wave device
<a name="managedintegrations-sdk-v2-cookbook-pairing-mode"></a>

Enable pairing mode on the Z-wave device. The pairing mode can vary for each Z-Wave device, so refer to the device's instructions to properly set up the pairing mode. It is usually a button that the user must press. 

## Step 1: Start device discovery
<a name="managedintegrations-sdk-v2-cookbook-device-discovery"></a>

Start device discovery for your hub to obtain a discovery job ID which is used to onboard your device.

**To start device discovery**
+ Use the [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) command to obtain the discovery job ID.

  **start-device-discovery example**

  ```
  #For Zigbee
    aws iot-managed-integrations start-device-discovery --discovery-type ZIGBEE \
    --controller-identifier HUB_MANAGED_THING_ID
    
    #For Zwave
    aws iot-managed-integrations start-device-discovery --discovery-type ZWAVE \
    --controller-identifier HUB_MANAGED_THING \
    --authentication-material-type ZWAVE_INSTALL_CODE \
    --authentication-material 13333
    
    #For Cloud
    aws iot-managed-integrations start-device-discovery --discovery-type CLOUD \
    --account-association-id C2C_ASSOCIATION_ID \
    
    #For Custom
    aws iot-managed-thing start-device-discovery --discovery-type CUSTOM \
    --controller-identifier HUB_MANAGED_THING_ID \
    --custom-protocol-detail NAME : NON_EMPTY_STRING \
  ```

  **Response:**

  ```
  {
        "Id": DISCOVERY_JOB_ID,
        "StartedAt": "2025-06-03T14:43:12.726000-07:00"
    }
  ```
**Note**  
There are separate commands for Z-wave and Zigbee devices.

  For more information, see the [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) API in the managed integrations AWS CLI *Command Reference*.

## Step 2: Query the discovery job ID
<a name="managedintegrations-sdk-v2-cookbook-query-discovery"></a>

Use the `list-discovered-devices` command to get the authentication material of your device.

**To query your discovery job ID**
+ Use the discovery job ID with the list-discovered-devices command to get the authentication material of your device.

  ```
  aws iot-managed-integrations list-discovered-devices --identifier DISCOVERY_JOB_ID
  ```

**Response:**

```
"Items": [
    {
        "DeviceTypes": [],
        "DiscoveredAt": "2025-06-03T14:43:37.619000-07:00",
        "AuthenticationMaterial": AUTHENTICATION_MATERIAL
    }
]
```

## Step 3: Create a managed thing for your device
<a name="managedintegrations-sdk-v2-cookbook-ugs-managed-thing"></a>

Use the `create-managed-thing` command to create a managed thing for your device. Each device requires its own managed thing. 

**To create a managed thing**
+ Use the `create-managed-thing` command to create a managed thing for your device.

  **create-managed-thing example**

  ```
  aws iot-managed-integrations create-managed-thing \
    --role  DEVICE --authentication-material-type DISCOVERED_DEVICE \
    --authentication-material "AUTHENTICATION_MATERIAL"
  ```

  **Response:**

  ```
  {    
      "Id": "DEVICE_MANAGED_THING_ID"
      "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID"
      "CreatedAt": "2025-06-09T13:58:52.977000+08:00"
    }
  ```

  For more information, see the [create-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/create-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 4: Query the managed thing
<a name="managedintegrations-sdk-v2-cookbook-query-managed-thing"></a>

You can check if a managed thing is activated by using the `get-managed-thing` command. 

**To query a managed thing**
+ Use the `get-managed-thing` command to check if the managed thing's provisioning status is set to `ACTIVATED`. For more information on provisioning status, see [Device Provisioning](https://docs.aws.amazon.com/iot-mi/latest/devguide/device-provisioning.html).

  **get-managed-thing example**

  ```
  aws iot-managed-integrations get-managed-thing \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **Response:**

  ```
  {
        "Id": "DEVICE_MANAGED_THING_ID",
        "Arn": "arn:aws:iotmanagedintegrations:AWS_REGION:AWS_ACCOUNT_ID:managed-thing/DEVICE_MANAGED_THING_ID,
        "Role": "DEVICE",
        "ProvisioningStatus": "ACTIVATED",
        "MacAddress": "MAC_ADDRESS",
        "ParentControllerId": "PARENT_CONTROLLER_ID",
        "CreatedAt": "2025-06-03T14:46:35.149000-07:00",
        "UpdatedAt": "2025-06-03T14:46:37.500000-07:00",
        "Tags": {}
    }
  ```

  For more information, see the [get-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 5: Get managed thing capabilities
<a name="managedintegrations-sdk-v2-cookbook-check-device-capabilties"></a>

You can view a list of a managed thing's available actions by using the `get-managed-thing-capabiltiies`. 

**To get a device's capabilities**
+ Use the `get-managed-thing-capabilities` command to obtain the endpoint ID. Also note the list of possible actions.

  **get-managed-thing-capabilities example**

  ```
  aws iot-managed-integrations get-managed-thing-capabilities \
    --identifier "DEVICE_MANAGED_THING_ID"
  ```

  **Response:**

  ```
  {
        "ManagedThingId": "DEVICE_MANAGED_THING_ID",
        "CapabilityReport": {
            "version": "1.0.0",
            "nodeId": "zb.539D+4A1D",
            "endpoints": [
                {
                    "id": "1",
                    "deviceTypes": [
                        "Unknown Device"
                    ],
                    "capabilities": [
                        {
                            "id": "matter.OnOff@1.4",
                            "name": "On/Off",
                            "version": "6",
                            "properties": [
                                "OnOff",
                                "OnOff",
                                "OnTime",
                                "OffWaitTime"
                            ],
                            "actions": [
                                "Off",
                                "On",
                                "Toggle",
                                "OffWithEffect",
                                "OnWithRecallGlobalScene",
                                "OnWithTimedOff"
                            ],
                            ...
    }
  ```

  For more information, see the [get-managed-thing-capabilities](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-capabilities.html) command in the managed integrations AWS CLI*Command Reference*.

## Step 6: Send a command to the managed thing
<a name="managedintegrations-sdk-v2-cookbook-ugs-control-device"></a>

You can use the send-managed-thing-command command to send a toggle action command to your managed thing. 

**Send a command to the managed thing using a toggle action.**
+ Use the `send-managed-thing-command` command to send a toggle action command.

  **send-managed-thing-command example**

  ```
  json=$(jq -cr '.|@json') <<EOF
    [
      {
        "endpointId": "1",
        "capabilities": [
          {
            "id": "matter.OnOff@1.4",
            "name": "On/Off",
            "version": "1",
            "actions": [
              {
                "name": "Toggle",
                "parameters": {}
              }
            ]
          }
        ]
      }
    ]
    EOF
    aws iot-managed-integrations send-managed-thing-command \
    --managed-thing-id ${device_managed_thing_id} --endpoints ENDPOINT_ID
  ```
**Note**  
This example uses jq cli to but you can also pass the entire `endpointId` string

  **Response:**

  ```
  {    
    "TraceId": TRACE_ID
    }
  ```

  For more information, see the [send-managed-thing-command](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/send-managed-thing-command.html) command in the managed integrations AWS CLI *Command Reference*.

## Step 7: Check the managed thing state
<a name="managedintegrations-sdk-v2-cookbook-ugs-device-state"></a>

Check the managed thing's state to validate the toggle action succeeded.

**To check a managed thing's device state**
+ Use the `get-managed-thing-state` command to validate the toggle action succeeded.

  **get-managed-thing-state example**

  ```
    aws iot-managed-integrations get-managed-thing-state --managed-thing-id DEVICE_MANAGED_THING_ID
  ```

  **Response:**

  ```
  {
        "Endpoints": [
            {
                "endpointId": "1",
                "capabilities": [
                    {
                        "id": "matter.OnOff@1.4",
                        "name": "On/Off",
                        "version": "1.4",
                        "properties": [
                            {
                                "name": "OnOff",
                                "value": {
                                    "propertyValue": true,
                                    "lastChangedAt": "2025-06-03T21:50:39.886Z"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ```

  For more information, see the [get-managed-thing-state](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/get-managed-thing-state.html) command in the managed integrations AWS CLI* Command Reference*.

## Step 8: Remove managed thing from your hub
<a name="managedintegrations-sdk-v2-cookbook-ugs-clean-up"></a>

Clean up your hub by removing the managed thing.

**To delete a managed thing**
+ Use the [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) command to remove a managed thing. 

  **delete-managed-thing example**

  ```
  aws iot-managed-integrations delete-managed-thing \
    --identifier MANAGED_THING_ID
  ```

  For more information, see the [delete-managed-thing](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/delete-managed-thing.html) command in the managed integrations AWS CLI *Command Reference*.
**Note**  
If the device is stuck in a `DELETE_IN_PROGRESS` state, append the `--force` flag to the `delete-managed-thing` command.
**Note**  
For Z-wave devices, you need to put the device into pairing mode after executing the command.

# Capability rediscovery
<a name="managedintegrations-sdk-v2-onboarding-capability-rediscovery"></a>

This section describes the steps to relearn device capability information for hub-connected devices using capability rediscovery.

## Prerequisites
<a name="capability-rediscovery-prereq"></a>

Complete these steps before attempting capability rediscovery:
+ Onboard a hub device to the managed integrations hub.
+ Onboard one or more end devices to the hub.
+ Install the latest version of AWS CLI from the [Managed Integrations AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/)
+ (Optional) Subscribe to [DEVICE\$1DISCOVERY\$1STATUS](managedintegrations-notifications.md#managedintegrations-notification-setup) event notifications.

## When to use capability rediscovery
<a name="capability-rediscovery-use-cases"></a>

Use capability rediscovery in the following scenarios:
+ After a firmware update to an end device that adds or modifies device capabilities
+ After a hub software update that enables support for new device features
+ When device capabilities are not accurately reflected in managed integrations
+ To refresh the capability information for a single device or all devices connected to a hub

## Start capability rediscovery
<a name="capability-rediscovery-start-discovery"></a>

Start capability rediscovery for your hub to update device capabilities.

**To start capability rediscovery**
+ Use the [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) command with the `CONTROLLER_CAPABILITY_REDISCOVERY` discovery type.

  **start-device-discovery example**

  ```
  # For a single device
  aws iot-managed-integrations start-device-discovery \
    --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
    --controller-identifier HUB_MANAGED_THING_ID \
    --protocol PROTOCOL \
    --end-device-identifier DEVICE_MANAGED_THING_ID
  
  # For all devices on a protocol
  aws iot-managed-integrations start-device-discovery \
    --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
    --controller-identifier HUB_MANAGED_THING_ID \
    --protocol PROTOCOL
  ```

  **Response:**

  ```
  {
      "Id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "StartedAt": "2026-01-12T23:07:49.275Z"
  }
  ```
**Note**  
The `--protocol` parameter accepts `ZIGBEE`, `ZWAVE`, or `CUSTOM`.  
If the optional `--end-device-identifier` parameter is not provided, all devices associated with the hub for the selected protocol are rediscovered.

  For more information, see the [start-device-discovery](https://docs.aws.amazon.com/cli/latest/reference/iot-managed-integrations/start-device-discovery.html) command in the managed integrations AWS CLI *Command Reference*.

To verify that the device capabilities have been updated, see [Get managed thing capabilities](managedintegrations-sdk-v2-cookbook-ugs.md#managedintegrations-sdk-v2-cookbook-check-device-capabilties).

## Troubleshooting
<a name="capability-rediscovery-troubleshooting"></a>

Use the following guidance to troubleshoot common issues with capability rediscovery. When capability rediscovery is in progress, managed integrations sends notifications through Kinesis or EventBridge as JSON messages.

### Success notifications
<a name="capability-rediscovery-notifications-success"></a>

**Per device being processed:**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/xyz789uvw012"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1
    }
}
```

**Completion:**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "SUCCEEDED",
        "deviceCount": 0
    }
}
```

### Failure notifications
<a name="capability-rediscovery-notifications-failure"></a>

**Device failure:**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/ghi345jkl678"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1,
        "error": {
            "code": "500",
            "message": "Device unreachable",
            "managedThingId": "ghi345jkl678"
        }
    }
}
```

**Complete failure:**

```
{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "FAILED",
        "deviceCount": 0,
        "error": {
            "code": "404",
            "message": "Specified controller does not exist"
        }
    }
}
```

### No notifications received
<a name="capability-rediscovery-no-notifications"></a>

If you do not receive notifications about the discovery status, verify that you have subscribed to `DEVICE_DISCOVERY_STATUS` event notifications. For more information on setting up notifications, see [Set up managed integrations notifications](managedintegrations-notifications.md#managedintegrations-notification-setup).

### Some devices not updated
<a name="capability-rediscovery-partial-failure"></a>

If some devices fail to update during capability rediscovery, check the error messages in the `DEVICE_DISCOVERY_STATUS` notifications. Common error messages include:
+ `Device unreachable` - The device is offline or not responding
+ `Timeout querying device` - The device is not responding within the expected timeframe
+ `Invalid capability report` - The device firmware may have an issue

To resolve these issues, ensure the affected devices are powered on and reachable, then retry capability rediscovery for the failed devices individually using the `--end-device-identifier` parameter.

### Discovery never completes
<a name="capability-rediscovery-stuck"></a>

If the capability rediscovery process does not complete, check the discovery status using the discovery job ID returned from the `start-device-discovery` command:

```
aws iot-managed-integrations get-device-discovery \
  --identifier DISCOVERY_JOB_ID
```

If the discovery is stuck:
+ Verify that the hub is online and connected to managed integrations
+ Wait up to 15 minutes for the discovery to timeout automatically
+ Retry the capability rediscovery after confirming the hub and devices are operational

# WiFi Simple Setup to onboard and operate devices
<a name="managedintegrations-sdk-v2-cookbook-wss"></a>

WiFi Simple Setup (WSS) is an automated device onboarding method that simplifies WiFi credential provisioning for IoT devices managed through AWS IoT Managed Integrations.

**On this page:**
+ [What is WiFi Simple Setup](#managedintegrations-sdk-v2-cookbook-wss-what-is)
+ [Common use cases](#managedintegrations-sdk-v2-cookbook-wss-use-cases)
+ [When to use WSS](#managedintegrations-sdk-v2-cookbook-wss-when-to-use)
+ [Prerequisites](#managedintegrations-sdk-v2-cookbook-wss-prerequisites)
+ [How WSS works](#managedintegrations-sdk-v2-cookbook-wss-how-it-works)
+ [WSS workflow](#managedintegrations-sdk-v2-cookbook-wss-workflow)
+ [Deployment scenarios](#managedintegrations-sdk-v2-cookbook-wss-deployment-scenarios)

## What is WiFi Simple Setup
<a name="managedintegrations-sdk-v2-cookbook-wss-what-is"></a>

WiFi Simple Setup (WSS) enables devices to automatically receive WiFi credentials from a provisioner device (such as a hub) through a secure, automated process. After a one-time barcode scan, the entire WiFi connection process completes automatically without requiring end-users to manually enter WiFi passwords or select networks.

### Key characteristics
<a name="managedintegrations-sdk-v2-cookbook-wss-key-characteristics"></a>
+ One-time barcode scan to activate device
+ Automatic discovery and connection
+ Secure local credential exchange using TLS 1.2/1.3
+ Configurable time-bounded activation window (Default 15 mins)
+ Automatic fallback to User Guided Setup if needed

## Common use cases
<a name="managedintegrations-sdk-v2-cookbook-wss-use-cases"></a>
+ Smart home cameras requiring WiFi connectivity
+ IoT sensors in residential environments
+ WiFi-enabled appliances and devices
+ Any managed integrations device requiring automated WiFi setup

### Example scenario
<a name="managedintegrations-sdk-v2-cookbook-wss-example-scenario"></a>

A customer purchases a smart home camera. After unboxing, they scan the device barcode with their mobile app, power on the camera, and within 60 seconds the camera automatically connects to their WiFi network without manual password entry. As part of the same process, the camera is also onboarded with managed integrations and can now be controlled using managed integrations APIs.

## When to use WSS
<a name="managedintegrations-sdk-v2-cookbook-wss-when-to-use"></a>

### Comparison of onboarding methods
<a name="managedintegrations-sdk-v2-cookbook-wss-comparison"></a>


**Onboarding method comparison**  

| Method | User Action | Best For | Automation Level | 
| --- | --- | --- | --- | 
| WSS | Scan barcode | WiFi devices needing automated setup | High - automatic after scan | 
| SS (Simple Setup) | Scan QR \$1 manual pairing | Protocol-specific devices (Zigbee, Z-Wave) | Medium - requires pairing steps | 
| ZTS (Zero Touch) | None (pre-registered) | Enterprise deployments with fulfillment integration | Highest - fully automatic | 
| UGS (User Guided) | Button presses \$1 manual steps | Fallback when automation fails | Low - manual intervention | 

### When to choose WSS
<a name="managedintegrations-sdk-v2-cookbook-wss-when-to-choose"></a>
+ Device requires WiFi connectivity
+ Hub or provisioner available in household
+ Streamlined setup experience desired
+ Mobile app has barcode scanning capability

### When to use alternatives
<a name="managedintegrations-sdk-v2-cookbook-wss-when-alternatives"></a>
+ **ZTS:** Enterprise deployments with fulfillment center pre-registration
+ **SS:** Protocol-specific devices (Zigbee, Z-Wave) with different pairing requirements
+ **UGS:** Fallback when WSS unavailable or fails

## Prerequisites
<a name="managedintegrations-sdk-v2-cookbook-wss-prerequisites"></a>

### For provisioner devices (hubs)
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-prereqs"></a>
+ Hub SDK integration with WiFi connectivity
+ Software access point (SoftAP) creation capability
+ Access to local WiFi credentials via customer-provided API
+ Registered as managed integrations CONTROLLER role with credential locker

### For provisionee devices
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-prereqs"></a>
+ Managed integrations End device SDK integration with WiFi capability
+ Hardware security module (HSM) or Trusted Platform Module (TPM)
+ Claim certificate and private key securely stored
+ Unique Serial Number (SN: 12-50 characters) and UPC/EAN
+ Barcode labels on device or packaging

**Note**  
**EAN Support:** Provisioners currently support UPC only. EAN support is planned for future releases.

### For customer implementation
<a name="managedintegrations-sdk-v2-cookbook-wss-customer-prereqs"></a>
+ Managed integrations account configured
+ Fleet Provisioning setup (custom endpoint, provisioning profile, template)
+ Mobile application with barcode scanning capability
+ Customer API for WiFi credential access

## How WSS works
<a name="managedintegrations-sdk-v2-cookbook-wss-how-it-works"></a>

### Architecture overview
<a name="managedintegrations-sdk-v2-cookbook-wss-architecture"></a>

The following diagram shows the WSS architecture with cloud services, provisioner hub, and provisionee device components:

![\[WSS architecture diagram showing cloud services (Provisioning Service, LPWSS, AWS IoT Core), hub device with WiFi Provisioner Plugin (SoftAP Manager, SOCKS5 Proxy, TLS Server, Credentials Manager), and end device with WSS module (WiFi Scanner, SOCKS5/TLS Clients, Secure Storage)\]](http://docs.aws.amazon.com/iot-mi/latest/devguide/images/wifi-simple-setup-architecture.png)


### Key components
<a name="managedintegrations-sdk-v2-cookbook-wss-key-components"></a>

**Cloud services:** Coordinate authentication, manage device lifecycle, and distribute session tokens for secure credential exchange.

**Provisioner (Hub):** WiFi-connected device that creates temporary access point and shares WiFi credentials with new devices.

**Provisionee (Device):** New WiFi device requiring network access for initial setup and operation.

**Mobile application:** Customer-provided app that initiates setup via barcode scanning.

## WSS workflow
<a name="managedintegrations-sdk-v2-cookbook-wss-workflow"></a>

The following diagram shows the complete WiFi Simple Setup workflow from barcode scanning through device activation:

![\[The complete WiFi Simple Setup workflow diagram\]](http://docs.aws.amazon.com/iot-mi/latest/devguide/images/wifi-simple-setup-flow.png)


### Workflow phases
<a name="managedintegrations-sdk-v2-cookbook-wss-workflow-phases"></a>

**Phase 1: Account linking**

End-user scans device barcode (SN \$1 UPC), activating a 15-minute setup window. Cloud notifies all eligible provisioners in the household.

**Important**  
Only one provisionee can be onboarded at a time. If you scan multiple devices at a time, only the latest one will be onboarded. If you want to onboard devices that were already scanned, you need to run `UpdateManagedThing`.

**Phase 2: Device discovery**

Device powers on, calculates temporary credentials, and automatically connects to provisioner's hidden temporary network.

**Phase 3: Cloud authentication**

Device completes Fleet Provisioning via provisioner's restricted proxy, obtaining permanent certificate. Cloud validates device and provisioner relationship, then distributes session tokens.

**Phase 4: Credential exchange**

Device establishes secure TLS connection to provisioner using session token. Provisioner shares WiFi credentials. Provisioner reports credential sharing for security monitoring.

**Phase 5: Network connection**

Device connects to WiFi network and reports success to cloud. Setup complete—device is operational.

**Fallback:** If any phase fails, device automatically falls back to User Guided Setup with mobile app guidance.

## Deployment scenarios
<a name="managedintegrations-sdk-v2-cookbook-wss-deployment-scenarios"></a>

### Scenario 1: Standard hub with WiFi access
<a name="managedintegrations-sdk-v2-cookbook-wss-scenario-1"></a>

Hub connected to WiFi with access to credentials via customer API. Hub shares credentials directly with provisionee without cloud WiFi storage.

### Scenario 2: Multiple provisioners
<a name="managedintegrations-sdk-v2-cookbook-wss-scenario-2"></a>

Multiple hubs in household provide redundancy. First provisioner to respond serves the device. Automatic load distribution improves reliability.

### Scenario 3: Automatic fallback
<a name="managedintegrations-sdk-v2-cookbook-wss-scenario-3"></a>

If provisioner unavailable or connection fails, device automatically falls back to User Guided Setup. Mobile app guides user through manual setup. Fallback is transparent to end-user.

# Configure provisioners for WiFi Simple Setup
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-config"></a>

**On this page:**
+ [Provisioner requirements](#managedintegrations-sdk-v2-cookbook-wss-provisioner-requirements)
+ [Enable provisioner capability](#managedintegrations-sdk-v2-cookbook-wss-enable-provisioner)
+ [Provisioner setup workflow](#managedintegrations-sdk-v2-cookbook-wss-provisioner-setup-workflow)
+ [WiFi credential access](#managedintegrations-sdk-v2-cookbook-wss-wifi-credential-access)
+ [Verify provisioner status](#managedintegrations-sdk-v2-cookbook-wss-verify-provisioner-status)
+ [Disable provisioner capability](#managedintegrations-sdk-v2-cookbook-wss-disable-provisioner)

## Provisioner requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-requirements"></a>

Provisioner devices must meet these requirements to support WiFi Simple Setup.

### Hardware and connectivity
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-hardware"></a>
+ Hub SDK integration completed
+ WiFi connectivity to network
+ Software access point (SoftAP) creation capability
+ Sufficient system resources for temporary network services

### Software and security
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-software"></a>
+ Access to local WiFi credentials via customer-provided API
+ Ability to create restricted SOCKS5 proxy (port 1080)
+ TLS 1.2/1.3 with Pre-Shared Key (PSK) support for credential exchange (port 4433)

### Registration requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-registration"></a>
+ Registered as managed integrations CONTROLLER role
+ Associated with a credential locker
+ Device status: DISCOVERED or ACTIVATED

## Enable provisioner capability
<a name="managedintegrations-sdk-v2-cookbook-wss-enable-provisioner"></a>

Enable WSS provisioner functionality using CreateManagedThing or UpdateManagedThing APIs.

### For new devices
<a name="managedintegrations-sdk-v2-cookbook-wss-enable-new-devices"></a>

```
{
  "role": "CONTROLLER",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:12345679012;UPC:987654321012",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": true
  }
}
```

### For existing devices
<a name="managedintegrations-sdk-v2-cookbook-wss-enable-existing-devices"></a>

```
{
  "managedThingId": "existing-hub-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": true
  }
}
```

**Parameters:**
+ `enableAsProvisioner`: Boolean flag enabling WSS provisioner capability (default: false)

## Provisioner setup workflow
<a name="managedintegrations-sdk-v2-cookbook-wss-provisioner-setup-workflow"></a>

Configure a hub as WSS provisioner following these steps:

### Step 1: Register and enable
<a name="managedintegrations-sdk-v2-cookbook-wss-register-enable"></a>

Register hub with CreateManagedThing API:
+ Set role as "CONTROLLER"
+ Specify credential locker ID for household association
+ Include `wiFiSimpleSetupConfiguration` with `enableAsProvisioner: true`
+ Or use UpdateManagedThing for existing devices

### Step 2: Configure WiFi credentials path
<a name="managedintegrations-sdk-v2-cookbook-wss-configure-wifi-credentials"></a>

Configure the path to your WiFi credentials file in iotmi\$1config.json to enable the provisioner to access WiFi credentials (SSID and password) for sharing with new devices.

Add the `wss_local_wifi_cred_path` parameter to the `ro` (read-only) section of your iotmi\$1config.json file:

```
{
  "ro": {
    "wss_local_wifi_cred_path": "/etc/wpa_supplicant/wpa_supplicant-wlan0.conf"
  }
}
```

**Parameters:**
+ `wss_local_wifi_cred_path`: File path to the wpa\$1supplicant configuration file containing WiFi credentials

This configuration is required for the Hub SDK to access your WiFi credentials during the provisioning process.

### Step 3: Capability reporting
<a name="managedintegrations-sdk-v2-cookbook-wss-capability-reporting"></a>

Hub SDK automatically evaluates and reports capabilities:
+ Hub assesses WiFi credential access
+ Hub validates SoftAP creation capability
+ Hub reports `supportAsProvisioner` status to cloud
+ Cloud validates hub can function as provisioner

### Step 4: Activation
<a name="managedintegrations-sdk-v2-cookbook-wss-activation"></a>

Cloud confirms provisioner status:
+ Hub becomes ready to receive provisioning requests
+ Hub receives notifications for pending devices in same credential locker
+ Hub can begin provisioning new devices

## WiFi credential access
<a name="managedintegrations-sdk-v2-cookbook-wss-wifi-credential-access"></a>

Provisioners must provide access to WiFi credentials for sharing with provisionee devices.

### Implementation requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-implementation-requirements"></a>

Implement a customer API that returns WiFi SSID and password:
+ API accessible by Hub SDK components
+ Read from system configuration files (e.g., `/etc/wpa_supplicant/wpa_supplicant.conf`)
+ Handle appropriate file permissions

### Security controls
<a name="managedintegrations-sdk-v2-cookbook-wss-security-controls"></a>

**Access restrictions:**
+ SSH access from SoftAP disabled by default
+ WiFi credentials transmitted only over TLS 1.2/1.3 with PSK (port 4433)
+ Session tokens are cryptographically secure (256-bit entropy), device-pair specific, single-use (5-minute validity)
+ Session tokens distributed via cloud MQTT messaging for mutual authentication
+ Credential access logged for security audit

**Implementation approaches:**
+ Direct file system access with appropriate permissions
+ System API calls for network configuration
+ Custom credential management service with secure retrieval

## Verify provisioner status
<a name="managedintegrations-sdk-v2-cookbook-wss-verify-provisioner-status"></a>

Monitor two configuration states to ensure proper provisioner functionality.

### Configuration states
<a name="managedintegrations-sdk-v2-cookbook-wss-configuration-states"></a>

WSS provisioners have two critical state values that determine functionality:


**Provisioner configuration states**  

| State | Description | Source | Purpose | 
| --- | --- | --- | --- | 
| enableAsProvisioner | Customer's configuration intent | Set via CreateManagedThing/UpdateManagedThing API | Enables WSS provisioner role for device | 
| supportAsProvisioner | Actual device capability | Self-reported by hub after capability assessment | Indicates if device can technically function as provisioner | 

**Key distinction:**
+ `enableAsProvisioner=true` \$1 `supportAsProvisioner=false` = WSS will not work (device configured but incapable)
+ `enableAsProvisioner=true` \$1 `supportAsProvisioner=true` = WSS ready and functional
+ Both must be true for successful provisioning operations

**Default values:**
+ `enableAsProvisioner`: false (must be explicitly enabled)
+ `supportAsProvisioner`: true for hub controllers, false for standard WiFi devices (determined by device assessment)

**Troubleshooting:** If `enableAsProvisioner=true` but `supportAsProvisioner=false`, check WiFi credential access and SoftAP capability.

### Status notifications
<a name="managedintegrations-sdk-v2-cookbook-wss-status-notifications"></a>

**Supported:**

```
{
  "notificationType": "WSS_SUPPORTED",
  "managedThingId": "hub-device-id",
  "timestamp": "2025-06-04T20:22:04Z",
  "message": "Device can function as WSS provisioner"
}
```

**Not supported:**

```
{
  "notificationType": "WSS_NOT_SUPPORTED",
  "managedThingId": "hub-device-id",
  "timestamp": "2025-06-04T20:22:04Z",
  "reason": "NO_WIFI_CREDENTIAL_ACCESS",
  "message": "Device cannot function as WSS provisioner"
}
```

### Common unsupported reasons
<a name="managedintegrations-sdk-v2-cookbook-wss-common-unsupported-reasons"></a>
+ No WiFi credential access configured
+ Customer WiFi API not implemented
+ Cannot create SoftAP
+ Ethernet-only connection without WiFi radio
+ Insufficient system resources

### Verification steps
<a name="managedintegrations-sdk-v2-cookbook-wss-verification-steps"></a>

1. **Call GetManagedThing API** to check configuration and status:

   ```
   {
     "managedThingId": "hub-device-id",
     "role": "CONTROLLER",
     "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
     "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
     "authenticationMaterial": "SN:12345679012;UPC:987654321012",
     "wiFiSimpleSetupConfiguration": {
       "enableAsProvisioner": true,
       "supportAsProvisioner": true,
       "enableAsProvisionee": false,
       "wssExpirationTimeStamp": null
     }
   }
   ```

   **Key fields:**
   + `enableAsProvisioner`: Customer configuration setting
   + `supportAsProvisioner`: Device-reported capability status
   + `wssExpirationTimeStamp`: Present only for provisionee devices with active WSS window

1. **Review cloud notifications** for capability reporting

1. **Verify WiFi credential API** returns valid credentials

1. **Check hub logs** for capability assessment details

## Disable provisioner capability
<a name="managedintegrations-sdk-v2-cookbook-wss-disable-provisioner"></a>

Disable WSS provisioner functionality when no longer needed. Using UpdateManagedThing API.

```
{
  "managedThingId": "hub-device-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": false
  }
}
```

### Impact of disabling
<a name="managedintegrations-sdk-v2-cookbook-wss-disable-impact"></a>
+ Cloud updates `enableAsProvisioner` to false
+ Hub stops receiving new provisioning notifications
+ Pending provisioning operations cancelled
+ Existing connections complete normally
+ Hub no longer creates SoftAPs for new devices

### Common use cases
<a name="managedintegrations-sdk-v2-cookbook-wss-disable-use-cases"></a>
+ Security concerns or suspicious activity detected
+ Hub being relocated or decommissioned
+ Temporary maintenance or troubleshooting
+ Customer preference changes

**Note:** Disabling provisioner does not affect hub's other functionality or existing provisionee devices.

# Configure provisionees for WiFi Simple Setup
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-config"></a>

**On this page:**
+ [Provisionee requirements](#managedintegrations-sdk-v2-cookbook-wss-provisionee-requirements)
+ [Manufacturing requirements](#managedintegrations-sdk-v2-cookbook-wss-manufacturing-requirements)
+ [Enable provisionee capability](#managedintegrations-sdk-v2-cookbook-wss-enable-provisionee)
+ [Barcode scanning workflow](#managedintegrations-sdk-v2-cookbook-wss-barcode-scanning-workflow)
+ [Activation window and timeouts](#managedintegrations-sdk-v2-cookbook-wss-activation-window-timeouts)
+ [Retry WSS setup](#managedintegrations-sdk-v2-cookbook-wss-retry-setup)
+ [Disable provisionee capability](#managedintegrations-sdk-v2-cookbook-wss-disable-provisionee)

## Provisionee requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-requirements"></a>

Provisionee devices must meet these requirements to support WiFi Simple Setup.

### Hardware and security
<a name="managedintegrations-sdk-v2-cookbook-wss-provisionee-hardware"></a>
+ Managed integrations End device SDK integration completed with build flag `IOTMI_USE_WSS_PROVISIONEE` enabled
+ Hardware security module (HSM) or Trusted Platform Module (TPM) for secure storage
+ WiFi connectivity capability
+ Sufficient processing power for cryptographic operations (SHA-384, HKDF)

### Authentication materials
<a name="managedintegrations-sdk-v2-cookbook-wss-authentication-materials"></a>
+ Claim certificate and private key stored securely in HSM/TPM
+ Unique Serial Number (SN): 12-50 characters alphanumeric
+ Universal Product Code (UPC): 12 digits OR European Article Number (EAN): 13 digits
+ Barcode labels displaying SN and UPC/EAN (on device or packaging)

**Note**  
**EAN Support:** Provisioners currently support UPC only. EAN support is planned for future releases. Provisionees support both UPC and EAN.

**Important:** SN paired with UPC/EAN must be unique per managed thing within customer AWS account.

### Software components
<a name="managedintegrations-sdk-v2-cookbook-wss-software-components"></a>
+ corePKCS11 Platform Abstraction Layer (PAL) implementation connecting PKCS\$111 API to HSM/TPM
+ TLS 1.2/1.3 client with Pre-Shared Key (PSK) capability (port 4433, cipher suite: TLS\$1AES\$1256\$1GCM\$1SHA384 or equivalent)
+ SOCKS5 proxy client support (port 1080)
+ Cryptographic functions for SHA-384 and HKDF

**Note:** corePKCS11 PAL must interface with actual HSM/TPM hardware, not software-only implementation.

## Manufacturing requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-manufacturing-requirements"></a>

Device manufacturers must provision secure materials and identifiers during manufacturing.

### Secure material provisioning
<a name="managedintegrations-sdk-v2-cookbook-wss-secure-material-provisioning"></a>

**Claim certificate and private key:**
+ Generate during manufacturing process
+ Store in HSM or TPM (required for production devices)
+ Never expose private key outside secure storage
+ Access via corePKCS11 PAL interface

**Device identifiers:**
+ Serial Number (SN): 12-50 character unique identifier
+ Universal Product Code (UPC): 12-digit product code OR European Article Number (EAN): 13-digit product code
+ Store securely alongside claim certificate in HSM/TPM

### Barcode requirements
<a name="managedintegrations-sdk-v2-cookbook-wss-barcode-requirements"></a>

**Physical labels must include:**
+ SN barcode on device or packaging (Code 128 format recommended)
+ UPC/EAN barcode on device or packaging (UPC-A or EAN-13 format)
+ Easily scannable labels (well-lit, focused, unobstructed)
+ Labels that survive shipping and handling

### Fleet Provisioning setup
<a name="managedintegrations-sdk-v2-cookbook-wss-fleet-provisioning-setup"></a>

**AWS account configuration:**

1. Create custom endpoint using GetCustomEndpoint API

1. Create provisioning profile using CreateProvisioningProfile API

1. Obtain claim certificate and private key for device family

1. Configure Fleet Provisioning template with required fields:
   + `deviceSerialNumber` (SN)
   + `universalProductCode` (UPC) or `europeanArticleNumber` (EAN)
   + Device certificate generation support
   + Thing registration in AWS IoT Core

## Enable provisionee capability
<a name="managedintegrations-sdk-v2-cookbook-wss-enable-provisionee"></a>

Enable WSS for devices using CreateManagedThing API during account linking.

### Device registration
<a name="managedintegrations-sdk-v2-cookbook-wss-device-registration"></a>

```
{
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

**Parameters:**
+ `role`: Must be "DEVICE" for provisionee devices
+ `credentialLockerId`: Associates device with household (same as provisioner)
+ `authenticationMaterialType`: Use "WIFI\$1SETUP\$1QR\$1BAR\$1CODE" for WSS
+ `authenticationMaterial`: SN and UPC/EAN from device barcodes
+ `enableAsProvisionee`: Set to true to activate WSS
+ `timeoutInMinutes`: Activation window duration (5-15 minutes, default 15)

### Retry or reactivate
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-reactivate"></a>

Use UpdateManagedThing to retry after initial failure:

```
{
  "managedThingId": "existing-device-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

## Barcode scanning workflow
<a name="managedintegrations-sdk-v2-cookbook-wss-barcode-scanning-workflow"></a>

Complete end-to-end workflow from barcode scanning to device activation.

### Step 1: Preparation
<a name="managedintegrations-sdk-v2-cookbook-wss-preparation"></a>
+ Ensure mobile application installed and authenticated
+ Verify provisioner device (hub) is powered on and connected
+ Have device and packaging accessible for scanning

### Step 2: Scan and register
<a name="managedintegrations-sdk-v2-cookbook-wss-scan-register"></a>

1. Open mobile application and navigate to device setup

1. Scan device Serial Number (SN) barcode

1. Scan Universal Product Code (UPC) or European Article Number (EAN) barcode

1. Mobile app validates scanned data

1. Mobile app calls CreateManagedThing API with scanned data and WSS configuration

**Important**  
**Single provisionee onboarding limitation:** Only one provisionee can be onboarded at a time. If you scan multiple devices simultaneously, only the latest scanned device will be onboarded. To onboard devices that were previously scanned but not activated, you must run `UpdateManagedThing` to reactivate their setup window.

### Step 3: Cloud activation
<a name="managedintegrations-sdk-v2-cookbook-wss-cloud-activation"></a>

Cloud processing automatically:

1. Creates managed thing record with WSS configuration

1. Activates 15-minute setup window

1. Identifies eligible provisioners (same credential locker, `enableAsProvisioner=true`, `supportAsProvisioner=true`)

1. Sends provisioning notifications to all eligible provisioners

1. Provisioners create temporary SoftAPs and prepare for device connection

**GetManagedThing response example:**

```
{
  "managedThingId": "device-id", 
  "role": "DEVICE",
  "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e",
  "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE",
  "authenticationMaterial": "SN:123456789331;UPC:123456789331",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisioner": false,
    "supportAsProvisioner": false,
    "enableAsProvisionee": true,
    "wssExpirationTimeStamp": "2025-06-04T20:22:04.069610Z"
  }
}
```

**Key fields:**
+ `enableAsProvisionee`: Device configured for WSS provisioning
+ `wssExpirationTimeStamp`: Active setup window end time (null if expired)

### Step 4: Device power-on
<a name="managedintegrations-sdk-v2-cookbook-wss-device-power-on"></a>

1. Mobile app displays "Power on your device now" message

1. User powers on provisionee device

1. WSS workflow proceeds automatically:
   + Device discovers provisioner SoftAP
   + Authentication and credential exchange complete
   + Device connects to WiFi
   + Mobile app receives success notification

## Activation window and timeouts
<a name="managedintegrations-sdk-v2-cookbook-wss-activation-window-timeouts"></a>

WSS uses time-limited windows and operation timeouts to enhance security and manage provisioning.

### Activation window
<a name="managedintegrations-sdk-v2-cookbook-wss-activation-window"></a>

**Default:** 15 minutes from barcode scan to device activation

**Configuration:**
+ Set via `timeoutInMinutes` parameter (range: 5-15 minutes)
+ Default: 15 minutes balances convenience and security

**Expiration behavior:**
+ Provisioners remove device from allowlist after timeout
+ Device cannot connect via WSS after expiration
+ User must rescan barcodes or call UpdateManagedThing to reactivate

### Operation timeouts
<a name="managedintegrations-sdk-v2-cookbook-wss-operation-timeouts"></a>


**WSS operation timeouts**  

| Operation | Timeout | Behavior | 
| --- | --- | --- | 
| SoftAP discovery | 30 seconds | Retries up to 5 times, then falls back to User Guided Setup | 
| Fleet Provisioning | 30 seconds | Retries with exponential backoff if fails | 
| WiFi connection | 60 seconds | Reports error and suggests troubleshooting if fails | 

### Best practices
<a name="managedintegrations-sdk-v2-cookbook-wss-best-practices"></a>
+ Power on device within 5 minutes of barcode scan and place the device near provisioner's softap WiFi range
+ Ensure provisioner is powered on and connected before scanning
+ Use default 15-minute timeout unless specific requirements dictate otherwise

## Retry WSS setup
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-setup"></a>

If initial WSS setup fails, retry using UpdateManagedThing API.

### Retry workflow
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-workflow"></a>

**Step 1: Identify failure**
+ Mobile app receives WSS failure notification
+ Timeout expires without successful activation
+ User sees "Setup failed" or "Try again" message

**Step 2: Retry via UpdateManagedThing**

```
{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": true,
    "timeoutInMinutes": 15
  }
}
```

**Step 3: Reactivation**
+ Cloud reactivates 15-minute setup window
+ Provisioners recreate SoftAP and allowlist entry
+ User powers on device (if not already powered on)
+ WSS workflow proceeds

### Common retry scenarios
<a name="managedintegrations-sdk-v2-cookbook-wss-retry-scenarios"></a>


**WSS retry scenarios**  

| Scenario | Solution | 
| --- | --- | 
| Device not powered on in time | Call UpdateManagedThing and power on device promptly | 
| Provisioner unavailable | Ensure hub online, then retry | 
| Network connectivity issues | Verify network stable, then retry | 
| User error | Retry with correct device | 

**Important:** Each UpdateManagedThing call creates a new 15-minute window. After 3-4 failures, consider checking provisioner status, verifying device functionality, or using User Guided Setup.

## Disable provisionee capability
<a name="managedintegrations-sdk-v2-cookbook-wss-disable-provisionee"></a>

Disable or permanently remove WSS for a provisionee device.

### Using UpdateManagedThing API
<a name="managedintegrations-sdk-v2-cookbook-wss-using-update"></a>

```
{
  "managedThingId": "device-managed-thing-id",
  "wiFiSimpleSetupConfiguration": {
    "enableAsProvisionee": false
  }
}
```

### Using DeleteManagedThing API
<a name="managedintegrations-sdk-v2-cookbook-wss-using-delete"></a>

```
{
  "managedThingId": "device-managed-thing-id"
}
```

### Comparison
<a name="managedintegrations-sdk-v2-cookbook-wss-comparison"></a>


**Disable vs Delete comparison**  

| Action | UpdateManagedThing | DeleteManagedThing | 
| --- | --- | --- | 
| Device record | Retained in cloud | Permanently removed | 
| Device status | Changed to disabled | No longer exists | 
| Reactivation | Re-enable WSS anytime | Must re-register device | 
| Use case | Temporary disable, testing | Device retired, security incident | 

### Security considerations
<a name="managedintegrations-sdk-v2-cookbook-wss-security-considerations"></a>

Use disable/delete when:
+ Suspicious activity detected
+ Device reported stolen
+ Security incident investigation required
+ Device decommissioned or returned

After disabling/deleting, consider:
+ Changing WiFi password if credentials may have been compromised
+ Reviewing security notifications for unusual activity
+ Checking other devices in household for similar issues