Frustration-Free Setup (FFS) for AVS Requirements
The following sections list the various requirements for implementing Frustration-Free Setup (FFS) on an Alexa Voice Service (AVS) device.
Device requirements for FFS
The following table lists the device requirements and recommendations for FFS:
Guideline | Description |
---|---|
Bluetooth Low Energy (BLE) 4.1+, Wi-Fi |
Required by the Alexa app to communicate with the device. |
BLE Wi-Fi Simple Setup SDK implemented on the device |
Common API used by Alexa app and Wi-Fi Simple Setup. |
Button on device to start user-guided setup (UGS). |
Required to connect the device to the Alexa app for UGS. |
Device Terms and Conditions on packaging |
Device terms and conditions for use. |
Generation of a device-specific key, and flash key on device. |
Each device must have a unique client certificate that must be on the device. For more details, see Manufacturing Device Hardware Authentication. |
Memory and secure storage |
Each device must have 100 KB of flash memory and 100 KB of heap memory. Highly recommended that you have secure storage for device private authentication material or the ability to encrypt/decrypt the material. |
Manufacturing and production requirements for FFS
Production devices implementing FFS have specific manufacturing requirements related to user security and device packaging:
- Device Attestation Keys (DAK) – You must create a DAK and burn the DAK onto your device. For more details, see Wi-Fi Provisionee Manufacturing.
- Barcode – Your device packaging must include a 1D barcode to enable ZTS. For barcode specifications, see Provisionee Barcode Specification.
- Control logs – For device security, upload a set of control logs to supplement the 1D barcode scan. For control log specifications and examples, see Device Control Log Specification.
Recommended AVS interfaces for Alexa app compatibility
One advantage of implementing FFS is that you don't need to have a separate companion app for device setup. The Alexa app provides the functionality that non-FFS devices require for device setup and registration. Because the Alexa app is dependent on certain AVS interfaces for various app settings, your FFS device should implement these AVS interfaces to maintain compatibility between your device and the app.
The following table shows how the relevant AVS interfaces map to their equivalent Alexa app settings:
Required AVS interface | Alexa app setting |
---|---|
EqualizerController 1.0+ |
Audio Settings (Bass, Midrange, Treble) |
Speaker 1.0+ |
Volume Slider (in the main Audio section) |
Alerts 1.3+ |
Volume Slider (Alarms) |
Alerts 1.3+ |
Sound Settings (ascending alarms) |
Speech Recognizer 2.3+ |
Sound Settings (start/end of request) |
System 2.0+ |
Language |
N/A |
Wi-Fi network change |
ACS for FFS requirements
The following sections list the various ACS-specific requirements for implementing FFS on an AVS device.
Device requirements for implementing the ACS package for FFS
The following table lists the device requirements and recommendations for using the ACS package for FFS.
Requirement | Description |
---|---|
Operating system |
Embedded Linux or Amazon FreeRTOS |
Wi-Fi |
Wi-Fi support |
Bluetooth |
Bluetooth Low Energy v4.1+ |
Development environment |
Compatible with the C programming language |
Memory and secure storage |
Each device must have 100 KB of flash memory and 100 KB of heap memory. |
Transport Layer Security (TLS) support |
Support for mbedTLS or similar TLS library |
Signed certificates |
Obtain signed certificates through Device Access Keys (DAK). For more details, see Provision AVS devices for FFS. |
Storage |
Amazon highly recommends using secure or encrypted storage. |
Hardware Abstraction Layer (HAL) APIs
The following table lists the required Hardware Abstraction Layer (HAL) APIs for implementing ACS with FFS.
HAL API | Usage |
---|---|
Device Hardware Authentication (DHA) |
Provides device authentication services, such as key generation, signing of a blob of data, verifying or authenticating a blob of data using the key, returning a public key. |
Device Info |
Accesses device information. |
Key-Value (KV) Storage |
Persistently stores and retrieves data on a target platform. |
Wi-Fi |
Performs network and connectivity management. |
Bluetooth |
Integrates the underlying Bluetooth stack to the ACS Bluetooth Middleware. |
Logging |
Provides log reading, writing, control, and other functionalities to the upper ACS Log manager. |
Metric |
Enables platform components to pass metrics to the middleware metrics component and upload metrics to the backend. |
The Device Info API requires accurate values in the following fields:
Name | Description |
---|---|
|
Device serial number |
|
Device type |
|
FFS ID obtained during FFS onboarding for the device |
|
Name of the device manufacturer |
|
Software version |
|
Hardware revision number |
|
FFS device setup service public key (product specific). Obtained after the device onboarding process. |
|
A short, user-friendly and unique product name to display during beaconing. The device name appears as |
|
Your client ID |
ACS middleware requirements
The FFS for ACS software package includes the following required ACS middleware components. To download the FFS with the ACS package, see Obtain the FFS with ACS software package.
Name | Description |
---|---|
ACS Bluetooth Middleware |
Provides a set of APIs to use BLE on your device. |
ACS Bluetooth Middleware: BLE Beacon Manager APIs |
Provide BLE beaconing support with custom beacon data. |
ACS Bluetooth Middleware: GATT Server APIs |
Performs BLE GATT server creation and tear-down. Implements GATT characteristic read/write/send-notification/prepare-execute-write support. |
ACS Wi-Fi Manager Middleware |
Performs Wi-Fi scan, retrieves the scan result, connects/disconnects from Wi-Fi, and saves/removes user profiles. |
ACS Connectivity Manager Middleware |
HTTP client for uploading DSS metrics. |
ACS MAP Middleware |
Performs device registration on the backend. |
Logging APIs |
Provides logging functionality to help with debugging. |
Metrics APIs (Optional) |
Helps with uploading user metrics for the device. |
Required open-source software (OSS) libraries
Name | Description |
---|---|
Mbedtls:
|
Generates FFS session keys and validates payload. |
Libwebsocket |
Provides network protocols. |
Wi-Fi Simple Setup for BLE (WSS-BLE) user requirements
The ACS package for FFS uses Wi-Fi Simple Setup over Bluetooth Low Energy (WSS-BLE) to configure the Wi-Fi connection for a new device's Wi-Fi connection. This module is included when you download the ACS package from the Amazon developer portal as part of FFS. WSS-BLE has the following user requirements:
- A registered Echo device or the Alexa app physically nearby and connected to the internet
- Credentials for the local Wi-Fi network stored in the Amazon Device Setup Service
For more details about the WSS-BLE APIs, see FFS Provisionable APIs.
Related topics
- About FFS for AVS
- Get Started with Frustration-Free Setup (FFS)
- Provision an AVS-enabled device for Frustration-Free Setup (FFS)
- Self-test your Frustration-Free Setup (FFS) implementation
Last updated: May 07, 2021