Getting Started with Matter Simple Setup

Overview
Pre-requisites
New Product Creation
- Create Your Product
- Your FFS Products Page
Rotating ID Configuration
- Updating Device Firmware
- Validating Rotating ID
  - Using the Rotating ID Verification Tool
Control Logs
Test Devices
Device Certification
- Step 1 - Testing MSS through self certification
- Step 2 - Amazon Certification
Barcode Validation
- Using the Barcode Verification Tool
ASIN Management

Overview

Matter Simple Setup (MSS) leverages the Matter protocol to facilitate the automated setup of smart home and connected devices. Matter, formerly known as Connected Home Over IP or CHIP, is an Open Source communication protocol for smart home devices aimed at interoperability between devices from different manufacturers. To learn more about Matter itself, visit the Connectivity Standards Alliance and the Matter SDK Repository

MSS supports the following network connectivity options:

Matter over Wi-Fi: runs via Wi-Fi and Ethernet networks to commission to a customer's Amazon account.
Matter over Thread: uses Thread networks for customer account commissioning. Thread operates via low-energy IEEE 802.15.4 protocol based networks.

Pre-requisites

Matter devices shall be in compliance with standard Matter requirements, and registered on CSA-IOT-Matter.
Alexa controllers that support Matter in production are listed in FAQ#2 here.

New Product Creation

Start by onboarding your product to Frustration-Free Setup (FFS) located under the Products section in your Frustrating-Free Setup console on the Amazon Developer Portal.

Create Your Product

Select Create New Product
Enter your Contact Information and Product Information
- Under the FFS Protocol Support section, select Matter Simple Setup (MSS) for Wi-Fi or Thread
- Confirm if your device is Matter certified
- If you used a FFS reference design from a Solution Provider, select Yes.
Select Submit when you are finished

Entering Product FFS Information Example

Your FFS Products Page

Important: As part of product creation process the FFS team will create a public/private key pair for this product. Once the product is created,
the key can be downloaded from the Product Details page under the Device Cryptographic Material section. This key will be used to generate the matter_data in the device control logs.

Newly created products are listed under Your FFS Products under the FFS Products section.

Once your product is onboarded to FFS, you can select it from your FFS Products list.

Product Details Page Example

Rotating ID Configuration

Updating Device Firmware

To enable Matter Simple Setup over Wi-Fi or Thread, you’ll have to make the following firmware changes:

Enable the CHIP_ENABLE_ROTATING_DEVICE_ID and CHIP_ENABLE_ADDITIONAL_DATA flags within the build configuration
1. See BUILD.gn in the src->setup_payload directory of the Matter SDK Github project
Implement required platform methods to support operations required to generate the Rotating ID. Consult the example platform implementations within the Matter SDK for specific examples on how to implement these
- GetLifetimeCounter
- IncrementLifetimeCounter
- SetRotatingDeviceIdUniqueId
- GetRotatingDeviceIdUniqueId

Warning: For testing, you can initialize the uniqueDeviceID by updating the value and corresponding size in the CHIPDeviceConfig.h in the Matter SDK Github project. Please ensure that the device SDK is not overwriting this value by reading the config from internal memory. For production, configure the uniqueDeviceId in secure storage ensuring it’s protected against reading or writing from over the air updates and stays fixed during the lifetime of the device.

Validating Rotating ID

First, get the Rotating ID you would like to validate:

With the device in commissioning mode, connect to the device to read the C3 characteristic, which has the rotating ID.
- The C3 characteristic is included by enabling CHIP_ENABLE_ADDITIONAL_DATA flag
- The C3 characteristic UUID is 64630238-8772-45F2-B87D-748A83218F04
For a sample C3 characteristic value of 0x1530001201005fdb39737473fb22b819cebb1084afd518:
- 0x15300012 and 0x18 - Header and Footer respectively
- 0x0100 - Lifetime Counter value
- 0x5fdb39737473fb22b819cebb1084afd5 - Rotating ID function output
- 0x01005fdb39737473fb22b819cebb1084afd5 - Rotating ID (Lifetime Counter + Function Output concatenation)

Next, get the Unique ID you would like to validate against

If you have already uploaded a control log for the device, this should be the Unique ID contained in the control log.
- See here for more information on Matter control logs
If you have not, get with your device firmware team to see how you can get the Unique ID programmed in your device

Using the Rotating ID Verification Tool

Important: When using the Rotating ID Verification Tool, input values can be either in Base64 encoded format or Hex, and format need not match. For Hex values, the 0x header must be included, or else it will be treated as Base64 encoded leading to invalid results.

To use the tool:

Go to the FFS console's Manage Products page
Select your Matter enabled product
Select "Verify Rotating IDs" on the product-specific management page Verify Barcode example
Enter the Rotating ID and Unique ID information to test
Select Verify to see your results

Success Example
Failure Example

Match Successfully Found

No Match Found

Control Logs

Control Logs provide a mechanism for mapping manufactured devices or bundles to authentication information related to the device. These log files have two forms:

Device Control Logs - defines individual devices
Bundle Control Logs - define a group of devices sold as a single unit in a multi-device package.

A control log endpoint is required for uploading information about manufactured devices to Amazon. See here for more information on Control Log Endpoints

Creating Control Log Endpoints

Before creating a control log endpoint, you must first onboard your business information in the Control Logs section of the FFS console.

Partner Control Log Mechanism Onboarding Example

Once onboarding is completed, you will be taken to a new page. Use this page to create new upload and feedback endpoints.

Follow these steps to do so:

Generate an RSA key pair. Name the key control_log_key.
```
ssh-keygen -t rsa -b 2048 -m PEM -f control_log_key
```
- Be sure to create a passphrase for your key pair
- This command will output a control_log_key and control_log_key.pub file
- This key will be used to upload control logs to the control log endpoint created in the next step
Create a new control log endpoint by uploading the control_log_key.pub file from the previous step
Find the recently generated SFTP endpoints in the table at the top of this page

Generating Control Logs

Important: The Unique Device ID used to generate the control logs must be Base64 encoded. While Base64 encoding, ensure the input is selected as hex but not text. You can use the command line utility as well to generate the Base64 encoded data. In example below, ABEiM0RVZneImaq7zN3u/w== is the Base64 encoded version of Unique Device ID 0x00112233445566778899aabbccddeeff


        $ echo "00112233445566778899aabbccddeeff" | xxd -r -p | base64
        $ ABEiM0RVZneImaq7zN3u/w==

There are two options to generate Control Log files:

Option 1 (preferred) - Using the FFN Control Log Toolkit sample code

Start by downloading the FFN Control Log toolkit sample code from the Downloads section of the FFS Console
- You can use this sample code as a part of your production line or as a reference to implement it in the language of your choice
Install Gradle on your machine
Run gradle build

Run the following command to generate the control logs

gradle run --args="-apid APID -dsn DeviceSerialNumber -vid MatterVendorID -pid MatterProductID -p MatterDevicePasscode -a MATTER_V0 -d MatterDeviceDiscriminator -udid Base64EncodedUniqueDeviceId -pk \"-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEUcRMzEQe4s8ATkxcCM/RvrAiN9TYMmWI\nBL4MOEoNFdUHtwIk35VW9TpsPQaUoJJRLi3aTWXPf97M6t2xQUCk3oaADnx8mX5+\nVaOEen5S3KwyciOcnlXLAgM0ZWXrkSA5\n-----END PUBLIC KEY-----\n\""

-pk - This is the public key shared by Amazon when the product type was created here

Option 2 - Implementing your own library to generate the Control Logs

Encrypt matter Data [ref]
Generate the control logs as per the schema defined here

Uploading Control Logs

There are two options for uploading control logs to Amazon:

Option 1 (preferred) - Upload a control log file via the Toolkit

To upload via the Toolkit, you just need to run this command:

ffn-manufacturing-toolkit controllog upload -e {Upload endpoint without the port} -k control_log_key -p {control_log_key_passphrase} -l {Control log file name} -t {device/bundle}

Option 2 - Upload a control log file via SFTP directly

Connect via SFTP to the endpoint

 sftp -oIdentityFile=control_log_key -oHostKeyAlgorithms=+ssh-dss sftp://{Upload endpoint}/To_Amazon
 # Alternatively connect via:
 sftp -P 2222 -oIdentityFile=control_log_key -oHostKeyAlgorithms=+ssh-dss sftp://{Upload endpoint without :2222}:To_Amazon

Upload the control file
```
  put {local_control_log_file_path}  
```
Close the SFTP connection
```
  exit
```

Once control logs are uploaded, check for the control log feedback file to ensure the control logs have been uploaded correctly.

Important: It can take up to 15 minutes for the feedback file to be available for download.

Getting Control Log Feedback Files

There are two options for downloading control log feedback files from Amazon:

To retrieve via the Toolkit, run:

ffn-manufacturing-toolkit controllog download -e {Feedback endpoint without :2222} -k control_log_key -p {control_log_key_passphrase}

Downloading via SFTP directly

Connect via SFTP to the endpoint

sftp -oIdentityFile=control_log_key -oHostKeyAlgorithms=+ssh-dss sftp://{Feedback endpoint}/From_Amazon
# Alternatively connect via:
sftp -P 2222 -oIdentityFile=control_log_key -oHostKeyAlgorithms=+ssh-dss sftp://{Feedback endpoint without :2222}:To_Amazon

List feedback files in the folder and locate a feedback file with a file name containing the file name of the uploaded file
```
 ls 
```
Download the file
```
 get {feedback_file_name}
```
Remove the feedback file – Feedback files must be deleted right away if a control log is successfully processed. If a control log is invalid, an email will be sent with details that may help investigating the failure.
```
 rm {feedback_file_name}
```
Close the SFTP connection
```
 exit
```

Test Devices

Important: You can only pre-register the device to the developer account you’re logged into. If you want to pre-register the device to allow another developer access to your account devices, you can add another developer account as an allowed user by visiting the Amazon Developer Console, and then have them request for pre-registration from their account.

Once the control log file has been uploaded successfully, you can pre-register (associate) the device to your account by submitting the test device.

To request pre-registration:

Navigate to the Product page for the product in the FFS console and select Submit Devices
Type in the device identifier. For example: PID:RLm2;SERNUM:ABCD1234
- PID:RLm2 - Key:Value pair for the FFS Advertised Product ID. This is not the Matter PID
- SERNUM:ABCD1234 - Key:Value pair for the device serial number. This must be the serial number used while generating the control log for the device
Click on submit
- You should receive an on-screen success message that the device has been successfully associated to the account

Device Certification

Warning: Without a confirmation from FFS that certification is complete, your devices will not connect to the FFS backend services in production.

Amazon requires that all FFS-compatible devices are validated and certified. Device compliance with the FFS specification and implementation helps ensure a consistent and secure experience for our customers. Amazon performs device certification testing after you have completed self-certification and submitted it through the developer portal.

Please allow 3 weeks in your product development process for Amazon’s certification testing (after submitting your certification results to the developer portal). This time frame is dependent on your product readiness and preparation prior to certification submission.

Step 1 - Testing MSS through self certification

Start by downloading the appropriate protocol specific certification test plan.

Test Plan Type	Use Case
Default	For standard products or for the creation of a reference design
Simplified	For products using a certified reference design

Amazon has open sourced a set of Python based automation scripts to control the Alexa App and help facilitate automated performance testing. These scripts help execute the self certification tests and shorten the product certification time. Support for other protocols will be made available in future updates.

View GitHub for more details.
Run certification tests in clean network environment. More guidance around this will be shared at a later date.

Step 2 - Amazon Certification

Log into the developer portal and request certification:
1. Select the test devices from the list
2. Upload self-test results and user guide
3. Complete other info
4. Generate the FFS project ID (for Works With Alexa)
The Amazon device certification team will check your self-test results to approve/reject the certification and contact you if additional information is required. You DO NOT need to ship your test devices to Amazon.

Barcode Validation

Frustration-Free Setup (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.

You can utilize one-dimensional (1D) barcode for device identification. See 1D Barcode Requirements here.

1D barcode example

Using the Barcode Verification Tool

To enable a better onboarding experience for our partners, the FFS team hosts a barcode verification tool in the FFS Console.

To use the tool:

Go to the FFS console's Manage Products page
Select the product you want to configure a barcode
Select "Verify Barcode" on the product-specific management page Verify Barcode example
Enter the barcode information
(Optional) Enter the ASIN and Marketplace
1. This is optional but encouraged. Adding this information will provide extra verification checks on the barcode

Important: Package samples delivery or design files/pictures uploads are included in the Certification stage.

ASIN Management

Frustration-Free Setup (FFS) technology requires pre-registration of the device with the account of Amazon customer who purchased the device on amazon.com. In order to enable this process a corresponding Amazon product identified by Amazon Standard Identification Number (ASIN) should be configured to link it to the provisionee device type. This linking adds FFS UI elements on the products Amazon.com product details page and enables FFS barcode scan as part of the order fulfillment process.

Warning: In Step 4 below, Partners have the option of providing custom Regular Expressions for their barcodes. If you plan on having other barcodes besides a UPC/EAN barcode on your packaging, we recommend using a custom regular expression that will also exclude other possible barcode values. Define an expression which will differentiate identification barcode value from other barcodes on the packaging (e.g. UPC or EAN, etc.), so a wrong barcode cannot be scanned for FFS by mistake leading to a failed customer pre-registration and no FFS experience for this customer.

To manage the ASIN for your product:

Go to the FFS console's Products page
Select the product you want to configure an ASIN for
Select "Manage ASINs" on the product-specific management page
Complete the ASIN configuration form per the ASIN configuration parameters:
- ASIN - Only ASINs owned by your company can be configured for FFS
- Marketplace - ASINs are configured for FFS per marketplace, submit multiple requests if devices sales are launched in multiple marketplaces
- Barcode Type - Select 1D barcode type, see Provisionee Barcode Specification for more details.
- Barcode verification regular expression - The default regular expression for 1D barcodes will exclude the UPC/EAN value you have set for your ASIN.
- FFS related product page elements - Depending on the device partner program it can be required to provide three additional properties per marketplace language which will be shown on your products details page:
  - Brand name - Name of your device brand. e.g. My company
  - Privacy policy label - Brand's privacy policy label. e.g. My company's Privacy Policy
  - Privacy policy link - HTTP link to the brand's privacy policy page, e.g. https://us.mycompany.com/pages/privacy-policy.
- For more information, see ASIN Configuration Parameters
ASIN Configuration Form Example
Click "Submit"
Repeat these steps for each ASIN and marketplace combination for which you wish to enable FFS for your product
- Amazon can translate brand name and privacy policy labels for requested marketplaces. You can modify the translated language if necessary.

FFS will associate the ASIN with your certified device type. Once the ASIN is associated, you can check the ASIN configuration status from the FFS console and Amazon.com (by locale).

Last updated: Aug 31, 2023