Wi-Fi Provisionee C SDK Integration Guide

• Understanding Wi-Fi Simple Setup
• Prerequisites
• Getting WSS Provisionee SDK
• Integrating the SDK
• WSS C SDK API
• Fallback and Failure Cases
  • Error codes
  • Retry, timeout, and factory reset guidance
  • Device factory reset recommendation
• Supported Networks
• Local Discovery
• Internationalization Support

Understanding Wi-Fi Simple Setup

The following sections show you how to integrate the Wi-Fi Simple Setup (WSS) provisionee software development kit (SDK) with your firmware. In the WSS process, the provisionee is the device that WSS automatically sets up. A provisioner is an Amazon device registered to a customer's account and has an internet connection. In WSS, the provisioner provides a pre-defined hidden Wi-Fi network to which the provisionee connects to gain access to Amazon Device Setup Service (DSS). When the user powers on the provisionee for the first time, the provisionee attempts to locate, and connect to, the provisioner’s hidden Wi-Fi network. The Service Set Identifier (SSID) of this hidden Wi-Fi network is defined in the specification. Once connected to the provisioner’s Wi-Fi network, the provisionee then attempts to establish a connection the DSS. If successful, the provisionee associates itself with an Amazon Customer Account. The provisionee then attempts to retrieve Wi-Fi credentials from DSS for SSIDs matching those that it can currently detect within the local Wi-Fi environment. The DSS limits the set of SSIDs to those associated with the Amazon Customer Account. This process enables the provisionee to connect to the customer's existing Wi-Fi network. After connected, the provisionee continues with the post-Wi-Fi workflow. You must complete the following key phases to successfully integrate the setup flow.

Prerequisites

Provisionee devices must meet the following specifications:

• Embedded Linux or RTOS

• Wi-Fi Radio

• C-Compatible development environment

• 64KB of flash memory available Recommended

• 64KB of heap memory available Recommended

• Support for mbedTLS https://tls.mbed.org (or similar TLS library)

• Device key from the FFS developer console

• Secure storage for device private authentication material or ability to encrypt/decrypt them is highly recommended but optional.

Getting WSS Provisionee SDK

The WSS provisionee SDK is available as C source code. Amazon makes the SDK available for download from https://developer.amazon.com/frustration-free-setup

Integrating the SDK

To integrate the SDK with your platform, you need to implement the SDK’s compatibility layer. This compatibility layer is a set of C function prototypes defined by the SDK and used to abstract functions that may vary across platforms. Examples of compatibility functions include Wi-Fi management, HTTP operations, and cryptography. When the SDK needs to run a commodity task such as Wi-Fi network scanning, signature verification, it calls your implementation of these functions. This minimizes extra dependencies, yielding a smaller overall footprint for your firmware. The source code package includes documentation detailing how to integrate the SDK with your device. The WSS provisionee SDK has only standard dependencies, and compiles on most platforms.

The SDK can be consumed as a static library or as source. Flash and RAM allocation is dependent on your implementation.

Please note, WSS uses a certificate chain and a private key stored on the device. These are used to authenticate the device to the Amazon cloud in the TLS handshake. The details of the TLS implementation (including how the certificate chain and private key are handled) depend on your device and are hidden behind the compatibility layer abstractions. This information must be securely stored on your device and never directly exposed to the SDK.

Amazon also provides an additional public key specific to your device type when you onboard a new device type with Amazon. This public key is used to validate data your device receives from the Amazon Device Setup Service. In practice, the SDK calls a compatibility layer signature verification function with a payload and signature.

Please see more implementation details and API reference in the Doxygen provided in the SDK package. The Readme file in the SDK provides step-by-step instructions for creating the binary.

WSS C SDK API

The WSS C SDK uses an abstract Wi-Fi manager API to perform Wi-Fi operations. Implementing this Wi-Fi manager is a critical part of integrating with Wi-Fi Simple Setup.

• ffsLog
  • Add a line to the log at the specified logging level (info, debug, warning or error)
• ffsRandomBytes
  • Generate cryptographic-quality random bytes up to the capacity of the output stream.
• ffsSha256
  • Calculate a SHA256 hash. The input and output buffers can overlap. The input stream is not affected otherwise.
• ffsComputeMACSHA265
  • Calculate a HMAC-SHA256 hmac using the given key and data.
• ffsComputeECDHKey
  • Calculate a shared secret key using ECDH. The public key is the cloud public key. The private key should be of the provisionee. It is expected that the provisionee has access to it's own private key.
• ffsSetConfigurationValue
  • Set a configuration value (e.g., country code).
• ffsGetConfigurationValue
  • Retrieve a configuration value. Not used in all flows. For non-stream values (integer and boolean), the destination map object is simply updated. For stream values (bytes and string), the function updates the type field of the destination object and writes the payload to the corresponding stream field. If the stream field is not writable the function returns ref FFS_ERROR. If the value is not available, this function should return ref FFS_NOT_IMPLEMENTED.
• ffsSetRegistrationToken
  • Set the registration token (session ID).
• ffsGetRegistrationToken
  • Get the registration token. Copy the registration token into the given output stream. Not used in all flows.
• ffsGetRegistrationDetails
  • Get the current registration status.
• ffsVerifyCloudSignature
  • Verify a cloud signature. Verify a signature obtained by the provisioner from the cloud. The public key is assumed to be known by the provisionee.
• ffsHttpExecute
  • Run an HTTP operation.
• ffsGetWifiScanResult
  • Copy the next Wi-Fi scan result from the scan list. Depending on what sort of data structure you use for your scan list, you may need to store an index, likely in your user context implementation.
• ffsAddWifiConfiguration
  • Add a new Wi-Fi configuration, with an SSID and password. If your device cannot store any more configurations, discard the information and return success. The SDK provides networks in descending order of priority.
• ffsRemoveWifiConfiguration
  • Remove networks with the given SSID from your configured networks. If you are currently connected to this SSID, disconnect.
• ffsConnectToWifi
  • Connect to the configured network(s). Networks are provided in descending order of priority - you should attempt to connect to the highest priority network first.
• ffsGetWifiConnectionDetails
  • Get the current Wi-Fi connection state and SSID.
• ffsGetWifiConnectionAttempt
  • Every network you attempt to connect to as part of FFS should have connection attempt information stored in some data structure, including all setup networks and user networks. Copy the next Wi-Fi connection attempt from that list. Depending on what sort of data structure you use, you may need to store an index, likely in your user context implementation.

Fallback and Failure Cases

Error codes

Error codes are used by the FFS cloud to determine Wi-Fi connection failure reasons. Each connection attempt representing a failure is expected to have these error details. The standard FFS codes are as follows:

const FfsErrorDetails_t ffsErrorDetailsAuthenticationFailed = {
 .operation = "CONNECTING_TO_NETWORK",
 .cause = "Authentication failed",
 .details = "Authentication failed",
 .code = "3:2:0:1"
};

Create similar structures using the given error codes. The expectation is that each connection attempt structure representing a failure contains one of these error details. Please see the FfsWifiConnectionAttempt_t structure for reference.

Retry, timeout, and factory reset guidance

1. If you encounter a network connectivity error, Amazon recommends that you retry the call 3 times with an exponential back-off starting at 2 seconds. This allows you to recover from transient network issues.

2. At any state during the FFS process if you receive a 5XX fault from the Amazon server, you can choose to retry 3 times, which gives the service a chance to recover. The timeout between retries should be kept as low as possible, while still allowing time for recovery (e.g. 2-5 seconds).

3. At any state if you receive a 4XX error from Amazon server, it most likely means that something was wrong with the input. You should NOT retry the same input. There are various steps you can take based on the specific 4XX response from the cloud. If you want to retry, then your code should inspect the problem, correct the input and then try the request with the new input.

Device factory reset recommendation

The following is suggested for factory reset logic.

• If any errors happened before your device connects to the customer's home router during set up, your device should fall back to soft AP mode with FFS disabled. Your device should not require the user to reset the device.

• In case device connects to customer’s router, but your application or Alexa app are not able discover the device, your app should prompt the user to press a specific button on the device for a specific number of seconds. This user action should clear the setup settings, disable FFS and return you device to its soft AP setup mode.

• When the user power cycles the device or long presses a specific button for more than 10 seconds to factory reset the device, the device returns to the original factory settings with both AP and FFS modes enabled.

Supported Networks

Amazon discourages the use of WEP and open networks. However, the Amazon Device Setup Service returns any matches between the customer’s stored Wi-Fi networks and the provided Wi-Fi scan data. If your device does not support a specific security protocol (e.g. WEP), you device can filer out those networks in the ffsGetWifiScanResult implementation.

In response to ffsGetWifiScanResult, your device receives a prioritized list of Wi-Fi network and credentials that match the initial list of networks that you provided. These networks are sorted in priority order based on the most secure networks (WPA) to the least secure networks. Your device should attempt to connect to the highest priority network first.

Local Discovery

There are instances when a device is successfully connected to a user’s network, but not registered to any customer in your backend. Amazon suggests you use local discovery (UDP) from your mobile application and ingress the Simple Setup flow to the customer. See Wi-Fi Provisionee App & Backend Integration Guide for more details on app implementation.

Internationalization Support

WSS and the SDK are internationalized. Specific internationalization required for your device or mobile SDK remains your responsibility.