Matter Simple Setup for Wi-Fi Overview

• Overview
  • Definitions
  • Getting Started
    • Prerequisites
    • Requirements
  • BLE Beaconing
  • Rotating Device Identifier (Rotating ID)
  • Packaging Barcode
  • Certification

Overview

Matter Simple Setup (MSS) leverages the Matter protocol to facilitative the automated setup of smart home and connected devices. Matter, formerly Connected Home over IP (CHIP), is an open-standard provisioning and command-and-control protocol running on IP networks like Wi-Fi and ethernet and other lower-level transports such as Bluetooth Low Energy (BLE) and Thread.

MSS for Wi-Fi specifically runs via Wi-Fi and ethernet networks to commission to a customer's Amazon account. This differs from MSS for Thread, which uses Thread networks for customer account commissioning.

If MSS prerequisites are met, a device can automatically join the network of a Matter-enabled Amazon Echo device. The high-level experience for the end customer for MSS for Wi-Fi is as follows:

1. Customer purchases a Matter-enabled device (purchased via Amazon or another retailer).

2. The device is powered on.

3. The device (acting as “commissionee”) begins to emit a BLE beacon requesting setup assistance from a nearby Matter-enabled Amazon Echo device (acting as “commissioner”) also owned by the customer.

4. If the commissionee was purchased from Amazon.com, then the commissioner will have all the information needed to automatically detect the commissionee’s BLE beacon, ensure its legitimacy, and then provide the commissionee with credentials to a Wi-Fi network and commissions it to the customer's account so that it can be managed and controlled by Alexa.

   1. If the commissionee was purchased from another retailer, then the customer will need to confirm connecting the device to their account and may be asked to verify the device using a simplified proof of possession check. You will need to provide Amazon the proof of possession code in order for the customer to achieve this. (See the proofOfPossessionCode and challengeScheme fields in the control log spec below.)

5. After the device has been set up via MSS for Wi-Fi, it will not be eligible for ZTS again, but it can be reset and set up again manually, if needed.

Definitions

• FFS - Frustration-Free Setup. The umbrella term for Amazon's setup technologies, including MSS.

• ZTS - Zero Touch Setup. When the customer doesn’t need to do anything but power on the newly purchased device for it to be fully set up. In some circumstances, such as a non-Amazon device sale, the customer may need to briefly interact with an app to confirm ownership of your device.

• Commissionee - The Matter-enabled device to be set up (referred to as a “provisionee” in other non-MSS Amazon documentation)

• Commissioner - The Matter-enabled Amazon Echo device that is already set up and that will assist in setting up a commissionee (referred to as a “provisioner” in other non-MSS Amazon documentation)

Getting Started

Prerequisites

Ensure your device meets the minimum hardware and software requirements from the Matter specification, including support for the Matter SDK.

Requirements

In the context of MSS for Wi-Fi, the provisionee, or commissionee, is the device that is to be automatically set up. If you want to make your device eligible to be an MSS commissionee, you must satisfy the following:

1. Configure your device to beacon over BLE with specific fields needed for MSS for Wi-Fi (detailed below)

2. Onboard your device via the FFS developer portal by creating a Matter new device type. On the developer portal, you will manage your FFS onboarding lifecycle tasks, like managing your test devices and manufacturing data and submitting for certification.

3. Integrate a unique barcode on your device packaging. You can also use an existing unique barcode on your packaging, such as a serial number, or MAC address.

4. Share your device control log data with Amazon services. Control Logs are a mechanism that allows manufacturers to provide Amazon with unique device identifiers and authentication material, such as the Matter passcode, that are critical to ensure a frictionless customer setup. The unique package barcode is associated with your device identifier through the control logs. See the Matter Control Logs section for more details.

5. Complete Frustration-Free Setup certification and Amazon ASIN onboarding. Review the certification section below for more information.

BLE Beaconing

The commissionee must beacon over BLE to initiate the Matter commissioning workflow. Here are the required fields for MSS:

Note: the product, vendor, and rotating ID are optional fields to include in the BLE advertisement in the Matter specification. However they are required to be implemented for your device to be compatible with Matter Simple Setup.

Rotating Device Identifier (Rotating ID)

A key requirement for your device being compatible with Amazon Matter Simple Setup is that a Matter Rotating Device Identifier (Rotating ID) must be implemented by your Commissionee (device). The Rotating ID is a non trackable identifier that is used to uniquely identify your device (see section 5.4.2.4.5 “Rotating Device Identifier” in the Matter spec). During provisioning the Amazon commissioner will use Rotating ID to retrieve the device’s specific passcode if the Commissionee is determined to be eligible for MSS at runtime.

The Rotating ID is generated based on the Unique ID that is securely programmed into your Commissionee and also sent to Amazon via Control Logs. Additionally, a RotatingIdAlgorithm (also known as Key Derivation Function, see section 3.8 “Key Derivation Function (KDF)” in the Matter Spec) must be provided in the Control Log corresponding to the KDF used on the device. During provisioning Amazon will use the discovered Rotating ID in addition to information about the algorithm used by the Commissionee to identify your device and retrieve its passcode, enabling Matter Simple Setup. More information about data required to be sent via Control Logs can be found here.

Enabling the usage of Rotating ID within the Matter SDK to be compatible with Matter Simple Setup requires the following:

1. Enable the CHIP_ENABLE_ROTATING_DEVICE_ID flag within the build configuration. See BUILD.gn in the Matter SDK Github project

2. Implement required platform methods to support operations required during usage of Rotating ID. See ConfigurationManager.h in the Matter SDK Github project. Consult the example platform implementations within the Matter SDK for specific examples on how to implement these.
   1. GetLifetimeCounter
   2. IncrementLifetimeCounter
   3. SetRotatingDeviceIdUniqueId
   4. GetRotatingDeviceIdUniqueId
3. Take note of the RotatingIdAlgorithm (KDF) utilized by the Matter SDK version used in your Commissionee. Amazon supports two options that can be used, we refer to them as MATTER_V0 and MATTER_V1. Note this naming is Amazon-specific and not something defined in the spec. The algorithm name will be sent to Amazon in your device’s Control Logs. Which algorithm to choose will depend on what is implemented in the Matter SDK when it’s incorporated in your device. The function implementation of the Rotating ID Algorithm can be found in AdditionalDataPayloadGenerator.cpp
   1. MATTER_V0 refers to an algorithm that SHA256 hashes the LifetimeCounter with the device’s Unique ID. As of Nov 17, 2022 this what is currently implemented in the Matter SDK and as a Matter device developer this is most likely what you are already using. This implementation was based on a previous version of the Matter Spec but is fully compatible with Amazon Matter Simple Setup.
   2. MATTER_V1 refers to a new HMAC-based algorithm that is defined in the current version of the Matter Spec (see ref Matter Spec 3.8, HMAC-based KDF) but is not currently implemented in the SDK as of Nov 17, 2022.

Therefore, when onboarding your device or upgrading to a new version of Matter SDK, take care to inspect the algorithm used/change history of project and if its utilizing HMAC then you are using MATTER_V1 and not MATTER_V0. You are also free to implement the HMAC-based KDF into the Matter SDK in-case no updates are made to Github project but you want to utilize the spec-based definition.

Packaging Barcode

FFS technology relies on your device's package barcode to identify a specific device. Amazon scans your device's package barcode during order fulfillment and pre-registers the device with the Amazon customer's account. Pre-registration enables FFS to authenticate device ownership and gives the customer's account and provisioners control over the new device. Our packaging barcode documentation provides details on how to implement and share these codes with our service via control logs.

Certification

Amazon will require your devices (and application if applicable) to go through our Frustration-Free Setup Certification. The Provisionee Certification Guide provides more information on Certification testing and provides links to self certification testing plans.

Last updated: Dec 01, 2022