Your Setup Console
Sign In
Sign In
Your Setup Console

Getting Started with Matter Simple Setup

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

  1. Select Create New Product
  2. 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.
  3. Select Submit when you are finished

Entering Product FFS Information Example

Your FFS Products Page

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:

  1. 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
  2. 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

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

To use the tool:

  1. Go to the FFS console's Manage Products page
  2. Select your Matter enabled product
  3. Select "Verify Rotating IDs" on the product-specific management page Verify Barcode example
  4. Enter the Rotating ID and Unique ID information to test
  5. Select Verify to see your results
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:

  1. 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
  2. Create a new control log endpoint by uploading the control_log_key.pub file from the previous step
  3. Find the recently generated SFTP endpoints in the table at the top of this page

Generating Control Logs

There are two options to generate Control Log files:

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

  1. 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
  2. Install Gradle on your machine
  3. Run gradle build
  4. 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

  1. Encrypt matter Data [ref]
  2. 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

  1. 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
  2. Upload the control file 
      put {local_control_log_file_path}
  3. 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.

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

  1. 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
  2. List feedback files in the folder and locate a feedback file with a file name containing the file name of the uploaded file 
     ls
  3. Download the file 
     get {feedback_file_name}
  4. 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}
  5. Close the SFTP connection 
     exit

Test Devices

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:

  1. Navigate to the Product page for the product in the FFS console and select Submit Devices
  2. 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
  3. Click on submit
    • You should receive an on-screen success message that the device has been successfully associated to the account

Device Certification

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

  1. 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)
  2. 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:

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

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.

To manage the ASIN for your product:

  1. Go to the FFS console's Products page
  2. Select the product you want to configure an ASIN for

  3. Select "Manage ASINs" on the product-specific management page

  4. 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

  5. Click "Submit"
  6. 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