Skip to content

Plain-language guides to iot development

Date

Monday, November 16, 2026

Posted by

Date

Designing Smooth Setup and Onboarding for Smart Devices

iot device onboarding ux

If you’re building a smart device, your first-run setup shapes how people feel about it. Strong iot device onboarding ux makes pairing mode obvious, keeps steps few, and gives a clear way back when setup fails.

This guide sits within our broader coverage of iot user experience design and zooms in on the first-run moment.

Item Value
Commissioning flows defined by the Matter specification Three: standard, user-intent and custom
Methods for adding a device to a second Matter fabric Two: Basic and Enhanced Commissioning Method
Temporary code the Enhanced method shows the customer 11-digit manual pairing code (or a dynamic QR code)
How long the commissioning window stays open Several minutes
Discovery support a Thread device must include Bluetooth LE (BLE)

These figures come from Amazon’s Alexa developer documentation and Silicon Labs’ Matter commissioning guide. Specifications and documentation can change, so check the sources before you rely on them.

Where customers get stuck during setup

Amazon’s developer documentation says that customers often struggle to commission Matter-enabled devices to their home network (Amazon Alexa developer docs). The same page groups the pain into four themes.

  • Pairing mode confusion: some devices need button presses or power cycling, while others use menus on the device or in a manufacturer app.
  • Multi-step complexity: any step can fail without clear customer guidance and consistent screens across different smart home apps.
  • Factory reset uncertainty: when setup fails, people can’t tell how or when to reset the device.
  • Multi-Admin setup: adding an already-configured device to a second app is unfamiliar and often ends in frustration.

Timing adds pressure. The commissioning window closes after several minutes, and customers often miss it, which ends in a failed setup, according to the same Amazon page. Your interface should show whether the device is still listening and what to do once the window has lapsed.

Choose the setup flow that fits your device

The Matter specification defines three commissioning flows, each designed for different product architectures (Amazon Alexa developer docs). Pick the one that matches how much interaction your product can support.

  • Standard: the device enters commissioning mode and starts advertising by itself when it’s powered on in a factory-new state. It suits plugs and bulbs that are ready to pair once plugged or screwed in.
  • User-intent: the customer must perform a physical action, such as pressing a button or navigating a menu. Door locks, window coverings and thermostats use it where security or battery preservation takes priority.
  • Custom: setup in a manufacturer app or service has to happen before commissioning can proceed. Hubs and complex appliances such as dishwashers, coffee makers and refrigerators fall here.

Silicon Labs’ developer guide draws a similar line between standard and user-directed scenarios. It calls the user-directed scenario helpful for devices that have user interfaces or for which commissioning should not start without a user present (Silicon Labs Matter docs).

The flow you choose decides what your instructions must say. For a user-intent device, name the exact button action; for a custom flow, tell people up front that the maker’s app comes first. Our guide to iot companion app design covers how to shape that app experience.

A typical Matter setup, step by step

Silicon Labs describes an example flow where the onboarding payload is a QR code and discovery runs over BLE beaconing (Silicon Labs Matter docs). In that example, a mobile phone usually serves as the administrator.

  1. The device enters commissioning mode and starts advertising over BLE.
  2. The customer scans the QR code on the device with the phone.
  3. The phone and device open a BLE connection to exchange setup information.
  4. Both sides secure the connection, using a passcode derived from the QR code.
  5. The phone checks that the device is a certified Matter device, a step called device attestation.
  6. The commissioner installs operational credentials so the device can join the network.

Customers only see a fraction of this. Amazon’s page lists scanning a QR code or entering a numeric code, BLE discovery, secure channel establishment, attestation and credential provisioning as steps that can fail without clear guidance (Amazon Alexa developer docs). Design the visible moments (scan, wait, confirm) and turn each hidden failure into a plain-language message with a next action.

Network type changes the picture. Wi-Fi and Thread devices must have credentials configured before they can join the operational network, and a Thread device must also support BLE for discovery and commissioning (Silicon Labs Matter docs). Ethernet devices, by contrast, are normally already on the network before setup begins.

iot device onboarding ux Phone interaction
A person holds a smartphone with a dark screen and touches it with one finger.

Adding a device to a second app

Multi-Admin support is a key Matter feature, but most customers don’t realise they must first open the original administrator app to generate a temporary pairing code. Each app also places that feature in a different spot, so people struggle to find it (Amazon Alexa developer docs).

Matter supports two methods for secondary commissioning. The Basic method reuses the original QR or numeric code and is optional for manufacturers and commissioners, while the Enhanced method needs a fresh code and is required of all Matter devices and commissioners, per Amazon’s documentation.

With the Enhanced method, the current administrator presents a temporary 11-digit manual pairing code or a dynamically generated QR code in an app or on screen (Amazon Alexa developer docs). Give that screen an obvious entry point in your app, and explain why the sticker code on the box may not be the one to use.

To learn where real households hesitate in these handoffs, see our overview of iot user research methods.

A practical checklist for onboarding screens

The sources describe problems rather than prescribe screens, so treat this list as editorial guidance built on those problems. Each item answers one of the failure points above.

  • Name the pairing action for this exact model, with a photo of the button or menu path.
  • Show clearly when the device is listening, and what to do if the wait runs out.
  • Offer a numeric code entry beside the camera scan, since customers can scan the printed QR code or type a numeric code (Amazon Alexa developer docs).
  • Make retry one tap, and explain in plain words when a factory reset is needed and how to do it.
  • Put “add to another app” help inside the original app, where the code has to be generated.

Test the whole path with someone who has never seen your product, using a factory-new unit each time. The first failure they hit is usually the one to fix first.

Frequently asked questions

Do customers always have to scan a QR code?

Show answer

No. Per Amazon’s documentation, a customer can scan the code printed on the device or packaging, type a numeric code, or follow instructions in the manufacturer’s app or service (Amazon Alexa developer docs). Supporting more than one route helps when a camera can’t read a worn label.

Why does a Thread device also need Bluetooth?

Show answer

Silicon Labs explains that a Thread-based device can’t rely on Thread alone for discovery and commissioning, so it must include BLE as well (Silicon Labs Matter docs). For your design, that means Bluetooth permissions and prompts belong in the setup journey.

What does device attestation mean for the customer?

Show answer

It’s the check that confirms the device is a certified Matter device, and it happens after the secure session is in place (Silicon Labs Matter docs). Customers never see it directly, so an attestation failure needs a human-readable explanation instead of a raw error.

Who finds and adds the device during setup?

Show answer

A commissioner does. Amazon’s page describes Alexa acting as the commissioner that discovers a device advertising in pairing mode and adds it to the Alexa Matter fabric (Amazon Alexa developer docs). Other smart home apps play the same role for their own fabrics.