Understanding Frustration-Free Setup
Frustration Free Setup Overview
Frustration-Free Setup (FFS) technology lowers the complexities of set up for connected devices by using a peer-assisted model for set up. Under this model, a device connected to the internet (provisioner) aids a new device (provisionee) in setting up its internet connection. To do all this, FFS registers the device to a customer’s Amazon account, configures the device based on account preferences, and connects it with the Alexa services. FFS does not replace your device’s normal setup procedure. If FFS does not work for a specific customer, your normal setup procedure should be the fall back mechanism. The high-level steps of the FFS process are:
- The provisionee, a participating device that requires set up, broadcasts a 'need for setup' message with its identity information.
- Provisioner devices, Amazon devices already registered to the customer account or non-Amazon routers with FFS, continually scan for such messages and forward them to the Amazon Device Setup Service, the cloud service that drives FFS.
- The Amazon Device Setup Service identifies the provisionee device and attempts to confirm its association to the customer.
-
If the Amazon Device Setup Service can confirm the association of the new device to the customer, the Device Setup Service sends the following data to the provisioner device:
a. A challenge test to confirm provisionee device identity.
b. The customer's Wi-Fi credentials.
c. Configuration parameters
Understanding the Different FFS Modes
Frustration-Free Setup has two different modes of operation: Zero-Touch Setup (ZTS) and Barcode Setup (BCS). The FFS process first attempts ZTS to setup a device, and falls back to BCS if ZTS is not possible.
If your device is not able to successfully setup using BCS, it should fallback to your own native setup method for connecting to the customer's Wi-Fi network.
Zero-Touch Setup
Zero-Touch Setup (ZTS), a mode of FFS, requires the customer to purchase the device for themselves from a participating retailer, such as Amazon.com, provide Amazon their Wi-Fi credentials as part of the setup process of another device, and have a provisioner device within range during the setup process. The customer must also have an Alexa skill linked to their account. This linkage associates the customer account on your side with their Amazon account. In environments that meet these criteria, FFS attempts to configure the device for use with no customer intervention. The customer takes the device out of its packaging, and powers it on to initiate FFS.
Prerequisites for ZTS:
-
The customer purchased the your provisionee device from Amazon.com.
-
The customer did not purchase or receive your provisionee device as a gift.
-
The customer's Wi-Fi Credentials are available in the Amazon Wi-Fi Locker.
-
An Amazon approved barcode is clearly visible on your provisionee device’s packaging
-
The customer has an Alexa Skill linked to their Amazon account.
-
You have implemented Login with Amazon
Barcode Setup
Barcode Setup (BCS) is a mode of Frustration-Free Setup, where the customer uses an app on their mobile device to scan the device's barcode and trigger the setup process. When a customer purchases a device offline or as a gift when purchased on Amazon.com, Amazon is not able to pre-associate the device with a customer's account. By scanning the device barcode with their mobile device, the customer establishes the association between the device and their Amazon account. Successful barcode scanning associates the device with the customer’s account and enables the continuation of the setup process. triggers the setup process and it continues in the same way as ZTS. To use Barcode Setup, the customer plugs in the device and uses a mobile app to scan a special 2D barcode printed on the device.
Prerequisites for Barcode Setup::
-
The customer's Wi-Fi Credentials are available in the Amazon Wi-Fi Locker.
-
The product barcode is clearly visible on the device
-
You have implemented Login with Amazon
-
You have implemented App to App linking
Barcode Setup is optional; however, excluding this functionality prevents ZTS
for products purchased as a gift or not purchased from a participating retailer (e.g. Amazon.com).
Barcode Setup enables the customer to benefit from the Frustration-Fee Setup experience in following situations where ZTS is not possible:
-
The Zero-Touch Setup flow fails.
-
The customer purchases the device from an off-line retailer.
-
The customer receives the device as a gift.
Implementing Frustration-Free Setup
There are a number of other steps required to implement with Frustration-Free Setup on your device:
- Review the documentation
- Download the SDK
- Get a device Key
- Integrate with the SDK
- Generate your device's barcode
- Start the Certification Process
You perform each of these steps from the Frustration-Free Setup developer portal.
Frustration-Free Setup Technical Documentation
The technical documentation contains important information about implementing Frustration-Free Setup. Amazon recommends that you review all the documentation for your specific needs. The following technical documents are available:
Understanding Frustration-Free Setup - This Guide
Provisionee C SDK Integration Guide - Integrating the FFS Provisionee SDK into your firmware
Provisionee App and Backend Integration Guide - Mobile application and cloud APIs required to complete post Wi-Fi and account association with the customer.
Provisionee Manufacturing - The provisioning of DHA/barcode material during the manufacturing of devices
Provisionee Certification - Information necessary for getting your FFS Provisionee certified from Amazon
Downloading the SDK
Device manufacturers implement Frustration-Free Setup by integrating with the Provisionee SDK. Amazon makes the SDK available for download from https://developer.amazon.com/frustration-free-setup. The Provisionee SDK handles most of the device-server communication on behalf of device manufacturers. Device manufacturers only need to implement the various compatibility-layer functions within SDK. For example, one function enables the SDK to make an HTTPS request to an endpoint. Another function provides a list of network credentials to the integrator's code so that they can hand the credentials off to their Wi-Fi connectivity layer and connect the device to the network.
Getting a Device Key
A device key enables authenticated and encrypted communications between your device and the Amazon Frustration-Free Setup backend. You requests devices keys through the Amazon Frustration-Free Setup developer portal.
Integrating with the SDK
The Provisionee SDK handles most of the device-server communication on behalf of device manufacturers. Device manufacturers only need to implement the various compatibility-layer functions within SDK. For example, one function enables the SDK to make an HTTPS request to an endpoint. Another function provides a list of network credentials to the integrator's code so that they can hand the credentials off to their Wi-Fi connectivity layer and connect the device to the network.
After the device has successfully connected to the customer's home Wi-Fi network, the Simple Setup Provisionee SDK provides the device with a Session Token. The provisionee uses this token to complete Post-Wi-Fi Workflows. You must also complete an account association using two Smart Home APIs, Skill Device Association Event (SDAE) and Customer Device Association Directive (CDAD). The App & Backend Integration Guide provides detailed API specs. For more information, see the Provisionee App and Backend Integration Guide.
Testing Your Device
The following are recommended products you can use for testing your FFS capable devices. All devices must be setup and associated to an Amazon account before FFS is enabled.
Provisioner devices that can be used to test your provisionee device:
| Provisioner Device | Supported Protocols |
|---|---|
| Echo (3rd Gen) | WSS over BLE and ZSS / BSS |
| Echo Dot (3rd Gen) any color will work | WSS over Wi-Fi and WSS over BLE |
| Amazon eero Pro mesh Wi-Fi system | WSS over Wi-Fi |
| TP-Link AC1750 Smart Wi-Fi Router | WSS over Wi-Fi |
| Asus RT-AX88U AX6000 Dual-Band Wi-Fi Router | WSS over Wi-Fi |
Provisionee devices that can be used to test your provisioner device:
| Provisionee Device | Supported Protocols |
|---|---|
| Amazon Smart Plug | WSS over BLE |
| Kasa Smart Plug Mini (HS105) | WSS over Wi-Fi |
| Philips Hue White 2-Pack A19 | ZSS / BSS |
Manufacturing Requirements for Amazon barcode specification
In addition to integrating the Provisionee SDK into your device, there are important manufacturing considerations required to support the Frustration-Free Setup functionality. These require firmware changes on the device that allow you to install unique chained certificates per device and physical changes on the device and associated printed material (including exterior packaging) to support the inclusion of a specific 2D barcode. The Manufacturing Guide provides detailed guidance on 2D Barcode and installing certificates into your device firmware. For more information, see Provisionee Manufacturing.
Starting the Certification Process
Amazon requires your devices (and application if applicable) to go through our simple setup certification process. This certification process is different than other Amazon certifications, such as Works with Alexa and Built for Alexa. For more information, see Provisionee Certification.
| Version | Date | Author | Description |
|---|---|---|---|
| 1.0 | Sept 25, 2019. | Amazon. | General Availability |
| 1.1 | Apr 20, 2020. | Amazon. | New Testing Your Device Section listing devices that can be test provisionees and provisioners |
| 1.2 | Sept 18, 2020. | Amazon. | Updated list of provisionee and provisioner devices |
Last updated: Nov 02, 2020