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
`ACE_DEVICE_INFO_DEVICE_SERIAL`	Device serial number
`ACE_DEVICE_INFO_DEVICE_TYPE_ID`	Device type
`ACE_DEVICE_INFO_PRODUCT_ID`	FFS ID obtained during FFS onboarding for the device
`ACE_DEVICE_INFO_MANUFACTURING`	Name of the device manufacturer
`ACE_DEVICE_INFO_MANUFACTURING`	Software version
`ACE_DEVICE_INFO_DEV_HW_REV`	Hardware revision number
`ACE_DEVICE_INFO_DSS_PUB_KEY`	FFS device setup service public key (product specific). Obtained after the device onboarding process.
`ACE_DEVICE_INFO_BT_DEVICE_NAME`	A short, user-friendly and unique product name to display during beaconing. The device name appears as `BT_DEVICE_NAME-xyz`, where `xyz` is the last three characters of the DSN.
`ACE_DEVICE_INFO_CLIENT_ID`	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: • MBEDTLS_ECDH_C • MBEDTLS_ECDSA_C • MBEDTLS_ECJPAKE_C and all dependencies	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.

Last updated: May 07, 2021