How do you build a Matter controller app?

A Matter controller app has to take a device from a setup code to a trusted member of a fabric, then talk to it securely. Google’s Matter primer lists the commissioning steps, and every controller app, whatever toolkit it uses, performs them:

1. Open a setup session. The app reads the QR code or numeric code and uses the setup passcode to establish a secure session (PASE) with the new device, usually over Bluetooth LE.
2. Check that the device is genuine. The device presents its Device Attestation Certificate. The app checks the chain up to a Product Attestation Authority (PAA) it trusts and checks the product’s Certification Declaration.
3. Issue operational credentials. The device generates a key pair and a certificate signing request, and the fabric’s certificate authority signs a Node Operational Certificate (NOC) for it.
4. Put it on the network. For Wi-Fi and Thread devices, the app provides the network credentials.
5. Connect as a controller. The app finds the device on the operational network with DNS-SD, opens a certificate-based session (CASE) and from then on reads attributes, writes settings, invokes commands and subscribes to changes.

Espressif’s ESP-Matter documentation adds what makes a node a controller: it holds a complete chain of operational credentials in its fabric, and its node ID or CASE Authenticated Tag must be in the access control list of the devices it controls, with administer or operator privilege.

A controller app should use an ecosystem’s fabric unless you are building an ecosystem. When devices join Google’s or Apple’s fabric, that company runs the certificate authority, attestation and credential storage, and your app works through its APIs. When devices join your own fabric, all of that is yours.

Google’s own sample code is blunt about the second path. Its sample apps for Matter supported only a demo fabric based on the Matter SDK, and the repository warns that an app made available in production has to deal with the complexity of managing its own Matter fabric securely. That means protecting the fabric’s root key, issuing certificates, keeping the trusted PAA list current from the Distributed Compliance Ledger (DCL), and storing each device’s credentials.

Matter’s multi-admin feature means this is not all or nothing. A device can belong to several fabrics at once, so an app with its own fabric can still let users add the same device to Google Home or Apple Home. What is a Matter fabric? explains how that sharing works.

Matter controller toolkits exist for every common platform, and each makes a different choice about whose fabric you get. Facts below are from each project’s documentation, checked on 21 October 2026.

On Android, start with the Google Home APIs, then add your own commissioning service if you run a fabric. Google’s Commissioning API on Android commissions a device either to your fabric and the Google fabric, or only to the Google fabric. To include your fabric, the app sets a commissioning service: a service the app implements and exports, which is told when commissioning is requested, performs the commissioning steps for your fabric and reports completion or an error back to Google Play services. Your app still needs a Matter stack to do that work, which in Google’s samples was the Matter SDK.

Two more pieces matter on Android:

• Thread credentials. Google’s Thread Network SDK lets an app request the preferred Thread network credentials from Google Play services, and add its own when it sets up a Thread border router.
• Development tools. The Matter SDK’s Android CHIPTool app scans QR codes, reads NFC onboarding tags, commissions devices and sends on/off commands. It is a sample, not a product, but it shows the SDK’s Android controller API end to end.

On iOS, use Apple’s MatterSupport framework to add devices, and the Matter framework to commission and control them. Apple says apps pair Matter accessories through MatterSupport, iOS asks the user for permission, and iOS then returns a pairing code so the app can set up its administrator fabric on the accessory over IP. MatterSupport is available from iOS and iPadOS 16.1 and macOS 14.

The work happens in an app extension that subclasses MatterAddDeviceExtensionRequestHandler. Apple’s documentation lists its jobs: perform verification and attestation checks on the device’s credentials, offer the visible Wi-Fi or Thread networks, commission the device with the onboarding payload, and configure its name and room. Apple says Xcode includes the certified Matter SDK in its entirety and encourages ecosystem apps to use it.

There are two simpler paths. Apple says apps that do not run their own ecosystem can control Matter accessories through the HomeKit API, where a HomeKit entitlement reaches every accessory the user added to Apple Home. And the Google Home APIs on iOS commission into Google’s fabric through a Matter hub, using the same Apple extension, with entitlements for Thread network credentials (which Google says requires Thread Group membership verification) and for Wi-Fi information.

Matter controllers can run in Python, JavaScript or on a server. The Matter SDK has two controllers for desktops and servers:

• chip-tool, a command-line controller that commissions devices and sends Matter messages. It builds on Linux and macOS, and on Ubuntu and other Linux distributions with snapd it installs as a snap.
• The Matter Python REPL, an IPython shell around a Python-wrapped version of the C++ Matter stack, which acts as a controller. Its source is in the SDK’s src/controller/python.

For a long-running controller, Home Assistant’s history is instructive. Its Matter support was built on the Open Home Foundation Matter Server, a certified software component over the Matter SDK, which exposed a controller over WebSockets. That Python server is now archived at version 8.1.2, and its replacement, the Open Home Foundation Matter(.js) Server, does the same job on matter.js and supports Matter 1.6.0. matter.js is a TypeScript implementation of Matter for devices, bridges and controllers. Its README says the library is not certified by the Connectivity Standards Alliance and that using it does not certify a product.

An ESP32 can be a Matter controller. Espressif’s esp_matter_controller component builds Matter controllers and commissioners on Espressif chips. Its basic commissioner example commissions devices into its own fabric and sends cluster commands, attribute reads and writes, and subscriptions from a device console. Built together with the OpenThread border router option, the example runs on an ESP32-S3 and pairs a Thread device over Bluetooth LE. Espressif’s RainMaker examples add controllers that join a RainMaker-managed fabric instead of running their own.

A controller app checks a device’s attestation certificates against the Product Attestation Authorities published in the CSA’s Distributed Compliance Ledger. The CSA says every Matter device carries a Device Attestation Certificate that proves it is authentic and certified, and that manufacturers must put their product data into the DCL. The DCL is permissionless for reads, so any controller can use it, and the Matter SDK ships a script that fetches PAA root certificates from it.

Development tools do not do this by default. The chip-tool guide says that without a PAA trust store path, chip-tool uses its built-in test PAA certificate, and that it accepts Certification Declarations signed with the test key unless told to allow only trusted keys. That is why test devices commission fine in chip-tool. A production controller has to load the real trust store and refuse the test keys.

Offline Protocol is not a Matter controller or commissioner and contains no Matter stack; Offline Protocol vs Matter explains what each one standardises and when a team would use each.