Matter Setup

Matter Controller agents let you say things like "turn off the kitchen light" and have the device send the right Matter command to your smart bulb. Setting up a Matter Controller is more involved than a regular voice agent.

Two apps required, today. Initial commissioning of the Matter Controller is done in the legacy ESP RainMaker app (not Home). Once commissioned, agent assignment and day-to-day management happen in ESP RainMaker Home. This split is temporary while Home gets full Matter support.

What you need

• A Matter-Controller-capable board — typically the M5Stack CoreS3 + M5Stack Module Gateway H2 (the H2 module provides Thread radio for Thread-based Matter devices). See Supported Boards.
• The legacy ESP RainMaker app:
  • iOS: App Store
  • Android: Play Store
• ESP RainMaker Home (for agent assignment, after commissioning).
• A "Home" group already created in your RainMaker account.

Steps

1. Install the legacy ESP RainMaker app

Sign in with your Espressif account.

2. Pair the controller board

• Power on the board → it shows a QR code.
• In ESP RainMaker, tap + at the top right.
• Scan the QR.

3. Pick a group

The app prompts you to pick a group. Choose Home (or create one). The Matter Controller becomes part of that group's Matter fabric.

4. Wi-Fi

Enter SSID and password. The device joins.

5. Re-login (controller setup)

After provisioning, the app asks you to re-log-in as part of the controller configuration.

On Android: if the re-login screen doesn't appear automatically, tap the device tile in the home screen first.

6. Configure Thread Border Router (if you have Thread devices)

The device tile exposes a button Update Thread Dataset. Click it before pairing any Thread-based Matter device — this configures the on-board Thread radio.

7. Commission Matter accessories

Use the standard Matter commissioning flow in ESP RainMaker (typically: tap the QR scanner, scan the Matter accessory's setup code, follow prompts). The Matter Controller adds the accessory to its fabric.

After commissioning, click Update Device List on the controller's device tile. This syncs the controller's view of available devices.

8. Assign an agent (in ESP RainMaker Home)

This step is identical to non-Matter devices. See Assign an Agent.

The agent you assign needs Matter-aware tools — get_device_list and control_device. The default matter_controller agent ships with these.

Supported Matter clusters today

Cluster	What it does
OnOff	On/off switches, lights, plugs.
LevelControl	Dimmable lights and similar.
ColorControl	Color-tunable bulbs.

Locks, thermostats, sensors, and other clusters aren't wired up yet.

How a voice command flows

Troubleshooting

Symptom	Likely cause
Update Device List shows nothing	No accessories commissioned yet, or the controller hasn't re-logged-in.
Thread device won't pair	Update Thread Dataset wasn't clicked first.
"This example must be commissioned via legacy app"	You tried to set up via Home. Switch to the legacy app for commissioning.
Voice command says "I don't see that device"	Run Update Device List; the agent's view is cached.