# WiFi Simple Setup to onboard and operate devices WiFi Simple Setup to onboard and operate devices 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 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 + 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 + 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 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 ### Comparison of onboarding methods **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 + Device requires WiFi connectivity + Hub or provisioner available in household + Streamlined setup experience desired + Mobile app has barcode scanning capability ### When to use alternatives + **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 ### For provisioner devices (hubs) + 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 + 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 + 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 ### Architecture overview 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 **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 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 **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 ### Scenario 1: Standard hub with WiFi access 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 Multiple hubs in household provide redundancy. First provisioner to respond serves the device. Automatic load distribution improves reliability. ### Scenario 3: Automatic fallback 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 Configure provisioners for WiFi Simple Setup **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 Provisioner devices must meet these requirements to support WiFi Simple Setup. ### Hardware and connectivity + Hub SDK integration completed + WiFi connectivity to network + Software access point (SoftAP) creation capability + Sufficient system resources for temporary network services ### Software and security + 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 + Registered as managed integrations CONTROLLER role + Associated with a credential locker + Device status: DISCOVERED or ACTIVATED ## Enable provisioner capability Enable WSS provisioner functionality using CreateManagedThing or UpdateManagedThing APIs. ### For new devices ``` { "role": "CONTROLLER", "credentialLockerId": "ad5cdc9f786b4dbe9490e57c0b1d900e", "authenticationMaterialType": "WIFI_SETUP_QR_BAR_CODE", "authenticationMaterial": "SN:12345679012;UPC:987654321012", "wiFiSimpleSetupConfiguration": { "enableAsProvisioner": true } } ``` ### For existing devices ``` { "managedThingId": "existing-hub-id", "wiFiSimpleSetupConfiguration": { "enableAsProvisioner": true } } ``` **Parameters:** + `enableAsProvisioner`: Boolean flag enabling WSS provisioner capability (default: false) ## Provisioner setup workflow Configure a hub as WSS provisioner following these steps: ### Step 1: Register and enable 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 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 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 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 Provisioners must provide access to WiFi credentials for sharing with provisionee devices. ### Implementation requirements 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 **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 Monitor two configuration states to ensure proper provisioner functionality. ### Configuration states 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 **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 + No WiFi credential access configured + Customer WiFi API not implemented + Cannot create SoftAP + Ethernet-only connection without WiFi radio + Insufficient system resources ### Verification steps 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 Disable WSS provisioner functionality when no longer needed. Using UpdateManagedThing API. ``` { "managedThingId": "hub-device-id", "wiFiSimpleSetupConfiguration": { "enableAsProvisioner": false } } ``` ### Impact of disabling + 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 + 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 Configure provisionees for WiFi Simple Setup **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 Provisionee devices must meet these requirements to support WiFi Simple Setup. ### Hardware and security + 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 + 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 + 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 Device manufacturers must provision secure materials and identifiers during manufacturing. ### Secure material provisioning **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 **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 **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 Enable WSS for devices using CreateManagedThing API during account linking. ### Device registration ``` { "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 Use UpdateManagedThing to retry after initial failure: ``` { "managedThingId": "existing-device-id", "wiFiSimpleSetupConfiguration": { "enableAsProvisionee": true, "timeoutInMinutes": 15 } } ``` ## Barcode scanning workflow Complete end-to-end workflow from barcode scanning to device activation. ### Step 1: Preparation + 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 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 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 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 WSS uses time-limited windows and operation timeouts to enhance security and manage provisioning. ### Activation window **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 **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 + 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 If initial WSS setup fails, retry using UpdateManagedThing API. ### Retry workflow **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 **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 Disable or permanently remove WSS for a provisionee device. ### Using UpdateManagedThing API ``` { "managedThingId": "device-managed-thing-id", "wiFiSimpleSetupConfiguration": { "enableAsProvisionee": false } } ``` ### Using DeleteManagedThing API ``` { "managedThingId": "device-managed-thing-id" } ``` ### Comparison **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 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