This README is also available as an interactive documentation.

nRF Matter for Mobile is a commissioning and control companion app by Nordic Semiconductor for the Matter protocol. The app is available for Android and iOS. It is built with Kotlin Multiplatform and Compose Multiplatform, with the iOS-specific implementation written in Swift.

For Matter developer documentation from Nordic Semiconductor, see the nRF Connect SDK and Matter add-on documentation.

Contents: KMM Library · Features · Minimum OS Requirements · Supported Matter device types · Working with the app

This repository also contains an alpha version of a Compose Multiplatform Matter library.

Add the following line to the commonMain dependencies to include it:

api("no.nordicsemi.nrf.matter:matter-support:0.1.1")

See the library documentation for setup, commissioning, and device control.

The app acts as a Matter controller and administrator on its own local fabric. It commissions accessories, keeps their node IDs and credentials, reads and writes their clusters, and writes Access Control List and Binding Cluster entries on them.

The application supports the following features:

• Commissioning new Matter devices onto your fabric:
  • Android — through the Android Home API and Google Play Services, provisioning the device onto both the Google Home fabric and the app's local fabric.
  • iOS — through Apple's MatterSupport framework (MatterAddDeviceRequest), onto a local fabric managed directly by the app itself (using Matter.framework and MTRDeviceController), with a bundled app extension providing the system QR-code scanning UI.
• Controlling commissioned devices — door locks, light bulbs (dimmable light bulb), switches, smoke/CO alarms, and manufacturer-specific clusters.
• Managing bindings between devices, for example a light switch controlling a light bulb directly.
• Viewing logs for diagnosing commissioning and cluster interactions.

The app is built in Compose Multiplatform, the user interface provides identical screens, labels, and controls across both Android and iOS. The app automatically adapts to the system theme on both platforms. The only platform-specific behavior occurs during commissioning, where execution is handed off to the native operating system — Google Play Services on Android and Apple’s MatterSupport on iOS.

Upon launch, the app opens to the Dashboard. If no accessories have been commissioned, a Getting Started screen appears with options to begin setup, access Matter documentation, and view the app version. Once a device is commissioned, the Dashboard dynamically updates to display the list of commissioned devices.

To download and run the nRF Matter application, your device must meet the following OS requirements:

• Android OS: Android 8.1 (API level 27) or newer.

• iOS / iPadOS:

  • iOS 26.0 or newer. Both the vendored /ios-matter package and the Xcode targets set that as their minimum, because the Apple Matter and MatterSupport APIs the app relies on are only available there.
  • Xcode: Building requires Xcode 26+, recent enough for swift-tools-version: 6.3.

The application implements controls for the following Matter device types. Accessories reporting any other device type can still be commissioned and inspected, but not controlled.

Contents: Requirements · Preparing a Matter device · Thread network credentials · Commissioning devices · Checking device information · Configuring bindings · Viewing logs · Removing a device

This section lists additional OS-specific requirements for working with the app and Matter devices.

To use the nRF Matter application with Matter devices, make sure you meet the following hardware and software requirements for your operating system. These are separate from Minimum OS requirements for running the app.

• Android APIs

• Google Play Services: Required, specifically with access to Google's Home API (used for local fabric and ecosystem device commissioning).

• Hardware & Architecture

  • Physical Device Required: The nRF Matter app requires a physical device to perform commissioning. It will not run on Android Emulators.
  • 64-bit Architecture Only (arm64-v8a): The app relies on compiled native CHIP/Matter libraries (libCHIPController.so) built specifically for 64-bit ARM processors.

• Permissions & Device Profiles

  • Local Network & Bluetooth Permissions: The app requires explicit user permission for Camera and Bluetooth (for initial Bluetooth LE commissioning).

• Thread & Network Prerequisites

  • Thread Border Router (for Thread devices): If you are commissioning Matter-over-Thread hardware using the app, a Thread Border Router (such as a Nest Hub or Google TV Streamer 4K) must be configured on the same Wi-Fi subnet. For more information, see Thread network credentials.
  • Wi-Fi Subnet: The Android device must be connected to a Wi-Fi network that supports IPv6 and allows mDNS traffic without client isolation.
  • Bluetooth Low Energy (Bluetooth LE): Required for initial Matter device discovery and Bluetooth LE commissioning.

• Account and Companion Prerequisites

  • Google Account: An active Google account signed in on the phone (required for Google Home API/Play Services authentication during commissioning). For Thread devices, the same Google Home app account is used to share Thread network credentials with the nRF Matter app once a border router is on the network.

To run the nRF Matter app on an Apple device, the hardware and software must meet the following requirements:

• Hardware & Architecture

  • 64-bit iOS Device: Requires an iPhone or iPad powered by a 64-bit Apple Silicon chip (A-series) with physical Bluetooth LE capabilities.
  • Simulator vs. Physical Device: While app UI can run in the Xcode simulator, device commissioning requires a physical iPhone or iPad to handle Bluetooth LE scanning and local network multicast discovery.

• Permissions & Device Profiles

  • Local Network & Bluetooth Permissions: The app requires explicit user permission for Local Network (to discover mDNS nodes) and camera and Bluetooth (for initial Bluetooth LE commissioning).
  • iCloud Account: An active Apple ID/iCloud account signed in to the iPhone is required to sync and manage local Matter fabric keys securely.

• Thread & Network Prerequisites

  • Thread Border Router (for Thread devices): If you are commissioning Matter-over-Thread hardware using the app, a Thread Border Router (such as a Nest Hub or Google TV Streamer 4K) must be configured on the same Wi-Fi subnet. For more information, see Thread network credentials.
  • Wi-Fi Subnet: The iOS device must be connected to a Wi-Fi network that supports IPv6 and allows mDNS traffic without client isolation.

To work with the application you need a Matter-enabled accessory device. Use one of the following ways of getting one:

• Using Matter Virtual Device. It works over a local network and is easier to set up.
• Using one of Nordic Semiconductor development kits. This requires a working Thread Border Router accessible on the local network.

Both approaches are explained in the following sections.

If you do not have a Thread Border Router or a physical accessory at hand, Google's Matter Virtual Device (MVD) tool lets you commission a simulated Matter accessory from a Mac or Linux machine instead.

The nRF Matter implementation currently supports only a subset of the device types available in the Matter Virtual Device application:

• Dimmable Light
• Door Lock

To explore and test additional device types, a compatible Nordic development kit is required.

To test without a hub, complete the following steps:

1. Make sure that the Mac/Linux running MVD and the phone must be on the same Wi-Fi network.

2. Download the MVD .dmg for your Mac (Apple Silicon or Intel) and drag it into Applications. You can download the Matter Virtual Device from the official Google Home developer resources.

3. Launch MVD and configure the simulated accessory: device type, name, discriminator, Matter port, and test VID/PID.

   After launching the application, the initial screen looks as follows:

   

4. Commission the simulated accessory from this app like a real device.

   The accessory shows a QR code and joins over the existing Wi-Fi® connection of the macOS host.

   

Once commissioned, you can control the simulated accessory device from the MVD dashboard.

You can configure a Nordic Semiconductor development kit to act as a Matter device using one of the available Matter samples:

• Matter Door Lock
• Matter Light Bulb
• Matter Light Switch
• Matter Manufacturer-specific clusters

For the authoritative, up-to-date list of supported hardware, see Nordic's Matter hardware and memory requirements page - new development kits and SoCs are added there as they gain Matter support. You can also check the sample documentation for the list of development kits supported by each sample.

These samples can be installed using the Matter Quick Start app, which is a part of nRF Connect for Desktop. Alternatively, you can install them from the Matter add-on to the nRF Connect SDK.

Note: If your accessory does not use Thread, go to Commissioning devices.

Commissioning a Thread Matter device requires a Thread Border Router already running on the local network, and Thread network credentials available on the phone.

This setup is not part of the application. It relies on the home hub infrastructure provided by the operating system, which is configured once per network before the app is used.

Matter samples installed on development kits require a Thread Border Router connected to the same local network as the app. In addition, the iPhone must already have the corresponding Thread network credentials installed. The credentials are installed through the system API and are available to all apps on the phone.

The process for obtaining these credentials depends on the Thread ecosystem being used. In most cases, when the Thread network is provided by a device such as a TV or a dedicated hub, the manufacturer's companion app must be used to download and install the Thread network credentials on the iPhone. This can be for example Samsung's SmartThings app or Google's Google Home app.

For detailed instructions, refer to the documentation provided by the device manufacturer. In general, the required credentials are installed after signing in to the companion app, adding the Thread-enabled device to the home, and enabling its Thread Border Router functionality.

If the credentials are not immediately available, commissioning a Matter device using the corresponding companion app may trigger the download and installation of the Thread network credentials.

Note: The app has been tested with the Google TV Streamer 4K. At the time of writing, Google does not provide any alternative method for installing or sharing Thread network credentials on iPhone other than through the Google Home app.

Set up a Thread Border Router, such as a Nest Hub (2nd generation) or a Google TV Streamer 4K, through the Google Home app. Google Play Services, by way of the Home API, then makes the credentials available to this app in the same way.

Keep in mind the following requirements:

Commissioning adds a Matter accessory to the app's fabric so it can be controlled. Before you start, make sure you have a prepared Matter device and, for Thread accessories, set up Thread network credentials.

If commissioning a Thread accessory, an active Thread Border Router (such as Google TV Streamer 4K) must be present on the local network and the Thread network credentials must be known to the phone.

For information about Matter commissioning stages, see Matter network commissioning in the Matter add-on documentation.

When you add a new device in the app on your phone and scan the device’s QR code or manually enter the setup payload (discriminator and PIN), the following happens:

1. The app scans for the accessory's Bluetooth LE advertising signal to establish an initial secure connection.
2. Once connected over Bluetooth LE, the app authenticates the accessory, provisions your local network credentials (Thread or Wi-Fi), and adds the device to your Matter fabric.
3. Once network credentials are provisioned and the fabric is bound, the app reads the accessory's Descriptor (0x001D) and Basic Information (0x0028) clusters. This allows the app to determine the device type, render the correct UI controls, and extract hardware metadata like the Product Name and Vendor ID.

The accessory is then added to the dashboard for further control or inspection as a functional Device Card.

Note: The pairing UI belongs to the operating system. Scanning the QR code, choosing the network, and naming the device are all handled by the operating system, not by this app.

To commission on Android:

1. Ensure your Android device is connected to the same network you plan to commission the Matter accessory onto and that Bluetooth is turned on.

2. Start the nRF Matter for Mobile app on your Android device.

   

3. Tap + Add New Device on the Getting Started screen (or the floating + button if devices are already present).

4. If you have not done so before, grant the app camera and Bluetooth permissions.

5. Provide the required setup information using one of the following options:

   • Scan the accessory's Matter QR Code using the on-screen viewfinder
   • Tap Setup with Code to manually enter the 11-digit or 21-digit setup payload (Discriminator and PIN Code).

The app initiates the Matter network commissioning stages. Once done, the device is added to the Matter fabric and the app is updated with the new device card. For example, the Matter Light Bulb in the following image.

To commission on iOS:

1. Ensure your iOS device is connected to the same network you plan to commission the Matter accessory onto and that Bluetooth is turned on.

2. Start the nRF Matter for Mobile app on your iOS device.

   

3. Tap + Add New Device on the Getting Started screen (or the floating + button if devices are already present).

4. If you have not done so before, grant the app camera and Bluetooth permissions.

5. Scan the accessory's Matter QR Code using the on-screen viewfinder to provide the required setup information.

The app initiates the Matter network commissioning stages. Once done, the device is added to the Matter fabric and the app is updated with the new device card. For example, the Test_Product (Matter Light Bulb) in the following image.

If the onboarding process encounters an error such as an invalid setup payload, timeout, or failed network authentication, the app halts the setup and displays a Connection Failed screen with suggested steps to troubleshoot the connection and the following information:

Once commissioned, your accessory is added to the app dashboard as a dedicated device card. Tap the device card to display information about the device read from the device's Basic Information cluster (0x0028).

This information is available for all commissioned accessories.

Bindings are used to assign a target or targets of a client cluster on the node, so that the device knows which remote device it should act upon.

In the app, the Bindings screen configures the Binding Cluster (0x001E) to allow a source node, such as a light switch, to control a target node directly over the Matter fabric, without routing each command through the app. For example, once the binding is established, a light switch can communicate directly with and control a connected light bulb.

Note: Only unicast binding is currently supported.

For more information about bindings and other Matter network concepts, see the Matter add-on documentation.

To write a binding, you need to fill in information in the Write Matter Binding Cluster (0x001E) section.

Note: Binding is currently supported only for the On/Off Cluster (0x0006).

Complete the following steps:

1. Make sure you have commissioned at least one accessory device before creating a binding.
2. Open the Bindings screen.
3. Under Select Client / Source Node (Write Client), select the source node that will send commands (for example, a light switch). Nodes are listed by product name and Node ID.
4. Under Select Server / Target Node (Control Target), select the target node that you want to control. Only light bulbs that are not already bound to the selected source node are available for selection.
5. Tap Write Binding to initiate binding operation between the selected source and target nodes.

While the binding operation is in progress, keep the app open and avoid closing it. You can check the log for information about the binding operation and its progress.

Writing a binding involves operations on the following accessories:

• An operate privilege is granted in the target node's Access Control List, so the switch is allowed to command it.
• A binding entry is written into the source node's Binding Table.

If the binding operation succeeds, the active bindings list is updated automatically. Otherwise, a Binding Failed dialog is displayed and you can troubleshoot and retry the operation.

The Active Binding Table Entries section displays a list of active bindings, including the source and target node IDs and the cluster associated with each binding.

The binding entry is automatically updated when either of the referenced devices is decommissioned or removed from the network.

The Logs Panel shows a single combined log for the whole app.

The logs cover commissioning, cluster reads and writes, and binding operations.

The entries are persisted locally, ensuring they remain available after the application restart.

• On Android, logs are saved to a local database.
• On iOS, logging is managed via the Pulse library, which stores logs in a file configured using App Groups, making them available to both the main app and its app extension.

The log cannot currently be cleared or exported from the app. To share a trace, capture it from the device using the platform tooling, such as adb logcat on Android or the Console app on macOS for iOS.

To remove an accessory device, tap the Remove / Decommission Device button on the dashboard. This removes the accessory from the app's fabric and clears all associated bindings.

Once decommissioned, the device is ready to be re-commissioned at any time by scanning its QR code or entering the setup code.

On Android only, since the device is commissioned through Android's Google Play services and Home API, the device is linked across all integrated fabrics. Decommissioning disassociates the device across these APIs, returning it to a factory-ready state.

If removing the fabric from the device fails (for example, if the device is offline), a prompt will give you the option to Force Remove it. Force-removing deletes the device from the app's repository immediately without waiting to unlink the fabric directly on the device.

Note: Force-removing a device only clears the app's own records. The accessory keeps the fabric credentials it was given, so it may need to be factory reset before it can be commissioned again.