Skip to main content

Matter Controller Example

examples/matter_controller/ in the firmware repo. The default agent is matter_controller — voice chat plus the ability to control your Matter smart-home devices.

What it does​

Everything Voice Chat does, plus:

  • Acts as a Matter controller — keeps a fabric of commissioned Matter devices.
  • Optionally acts as a Thread Border Router (on the M5Stack CoreS3 + H2 Gateway board) — required to bring Thread-based Matter devices into the fabric.
  • Exposes two extra tools to the agent: get_device_list and control_device.

The user says "turn off the kitchen light", the agent translates that to a Matter command, the device sends it.

Local tools​

In addition to the Voice Chat tools (set_volume, set_emotion, set_reminder, get_local_time):

ToolWhat it does
get_device_listReturns the Matter nodes currently in the controller's fabric, with their cluster info.
control_deviceSends a Matter command. Args: node_id (hex), cluster_id (number), command_id (number), command_args (JSON string).

The agent typically calls get_device_list first to discover what's available, then control_device with the right IDs.

Supported clusters today​

ClusterWhat it does
OnOffOn/off — switches, plugs, lights.
LevelControlBrightness — dimmable lights.
ColorControlColor — color-tunable bulbs.

Locks, thermostats, sensors, and other clusters aren't wired up yet at the tool level. Adding more clusters is a code change in the firmware.

Hardware​

Any of the four supported boards works for Wi-Fi-only Matter. Thread Matter devices need the M5Stack CoreS3 + H2 Gateway variant (the H2 module provides the IEEE 802.15.4 radio).

Setup flow​

Matter Controller setup is more involved than plain voice chat — the controller has to be commissioned and then accessories have to be commissioned into its fabric.

The full step-by-step is in Mobile App → Matter Setup. High level:

  1. Flash the Matter Controller firmware on the board.
  2. Use the legacy ESP RainMaker app (not Home) to do the initial controller commissioning.
  3. Pick a group ("Home").
  4. (Thread only) Update Thread Dataset in the device tile.
  5. Commission your Matter accessories via the same legacy app.
  6. Update Device List to sync the controller's view.
  7. (Optional) Switch to a custom agent via Assign an Agent in ESP RainMaker Home.

Why two apps? Matter commissioning support in ESP RainMaker Home is in progress. Until it's done, the legacy ESP RainMaker app handles commissioning; Home handles agent assignment.

How a voice command flows end-to-end​

Level 77 is 30% of 254 (Matter's MoveToLevel range is 0–254).

On-device behavior​

Same as Voice Chat — wake word "Hi, ESP", tap-to-wake, 15-second sleep timeout, factory reset by long-touch.

Where to look in the code​

PathWhat's there
examples/matter_controller/main/app_main.cEntry point.
examples/matter_controller/main/app_tools.cTool registration (get_device_list, control_device).
examples/matter_controller/main/matter/Matter init, commissioning, Thread config.
examples/matter_controller/main/controller_rest_apis/matter_device.cWhere Matter commands are actually sent.
examples/matter_controller/agent_config.jsonThe default agent's definition.

Adding more clusters​

control_device is generic — it just takes any cluster/command IDs. Adding support for a new cluster is mostly about teaching the agent (in its system prompt or via a tool description) which cluster/command IDs to use for the user's intent.

For things that aren't a single cluster command (multi-step setup, sensor reads, etc.), you may want a new dedicated local tool. See Local Tools → Adding a tool.

On this page