Getting started with the MCUHome CLI

For CLI version 0.1. MCUHome is pre-1.0 — commands and flags may still change between minor versions.

MCUHome builds Zephyr-based smart-home firmware from a YAML device description. Devices speak Matter over Thread or WiFi and work with any Matter controller, such as Home Assistant.

1. Create a project

mkdir my-home && cd my-home
mcuhome init

A project directory holds your device configurations (devices/), your secrets (secrets/, never committed), and build output (build/).

2. Describe a device

mcuhome device new living-room-climate --board nrf7002dk/nrf5340/cpuapp --name "Living Room Climate"

This scaffolds devices/living-room-climate/main.yaml with a complete, commented example to uncomment and adjust. mcuhome device boards lists the boards you can build for (see also supported boards).

3. Draw the pairing identity

mcuhome device matter-pairing --new living-room-climate

Every Matter device needs commissioning credentials of its own, and they are drawn exactly once so that every build is byte-identical. The values go to the device's own secrets/devices/<name>.yaml (never committed); the configuration carries !secret references. The bare command — without --new — shows the pairing codes again whenever you need them.

4. Validate and build

mcuhome device validate living-room-climate
mcuhome device build living-room-climate

Validation resolves the configuration and reports every problem at once. A build compiles inside the MCUHome build container — the only host requirements are git and Docker; pull the container once with the docker pull command the build prints when it is missing.

5. Flash and commission

Flashing over USB and the first-time board setup are being built out in this release line; mcuhome device --help shows the current state. Once flashed, the device is commissioned into your Matter controller with the pairing code mcuhome device matter-pairing shows.

Where to go next