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:

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.

Was this page helpful?

Last updated: May 07, 2021