Both field-test units live in this planter.
Open source Matter over Thread firmware for the Seeed Studio XIAO Soil Moisture Sensor, a capacitive soil sensor built on the XIAO ESP32-C6 that sells for about $12. The stock firmware is ESPHome over WiFi. This firmware reconfigures the C6's 802.15.4 radio to run Thread instead, and the sensor speaks directly to your Matter ecosystem (if supported).
The Soil Sensor device type was added in Matter 1.5 and controllers are only now gaining support for it. Very few Matter over Thread soil sensors exist, commercial or DIY, and this firmware is an attempt to be a useful one.
✅ Reversible: Flashing is a two-way door. The XIAO has native USB-C with a built-in bootloader, no UART wiring or disassembly is needed, and Seeed publishes the stock ESPHome firmware with a browser flasher. Returning to stock takes a few minutes.
⚠️ Disclaimer: This firmware uses Matter test credentials (vendor ID0xFFF1, product ID0x8010) and is not CSA-certified. Ecosystems will warn about an uncertified device during commissioning. That warning is expected. You assume all responsibility for any damage, data loss, or device failure.
- Status
- Quick start
- Features
- Button & LEDs
- Compatibility
- Documentation
- Repository layout
- Why?
- About
- Other projects from Automatous
- Related projects
- License
Current release: v0.4.0 (beta).
| ✅ Works | Thread commissioning over BLE, soil moisture reporting to Home Assistant, cell voltage, battery percentage and charge level with a replace-battery flag, battery health via internal-resistance (sag) measurement, button-triggered calibration persisted to NVS, Identify from a controller, sleepy end device (LIT ICD) operation with light sleep, multi-fabric, brownout diagnostics, Matter OTA over Thread |
| 🔬 Collecting data | Real-world battery life (see POWER.md), calibration defaults across soil types, border router and ecosystem coverage |
| AA battery life is on pace for weeks per cell, not months. The first cell dropped about 30 points on the battery gauge in its first week, though that gauge is linear in voltage rather than in capacity and overstates the early decline (POWER.md). The radio is no longer the obvious bottleneck, and the investigation into what is going on happens in POWER.md. USB-powered operation is solid. |
Battery life is an open experiment run in public. Two units are in the field, their data lives in POWER.md, and if you flash a unit of your own, an issue with your battery data adds a row. Contributions of any kind are welcome: CONTRIBUTING.md.
- Download the latest firmware from Releases, or build it yourself.
- Flash over USB-C. No UART or soldering is needed. See FLASHING.md.
- Commission into your ecosystem with the QR code printed on the serial console. See COMMISSIONING.md.
Later updates can go over the air via Matter OTA, or over the same USB cable.
- Matter over Thread: native, local, no cloud, no WiFi, no ESPHome dependency
- Soil Sensor device type (0x0045) with the Matter 1.5 SoilMeasurement cluster, not a humidity-sensor workaround
- Sleepy end device: Thread MTD running as a LIT intermittently connected device, light sleep between samples
- Cell voltage in millivolts, battery percentage, charge level (Ok / Warning / Critical), and a
BatReplacementNeededflag driven by cell health rather than voltage alone - Battery health via sag measurement: the firmware briefly loads the cell with its own LEDs about once a day and reads voltage sag as an internal-resistance proxy that flags worn cells before they die
- On-device calibration: triple-press the button and follow the LED prompts with dry air and a glass of water; calibration persists across reboots and reflashes
- Identify from the controller: the status LED blinks yellow so you can tell which sensor you are looking at when several are paired
- Local sampling with delta reporting: the probe is sampled every 15 minutes (configurable) and the radio is only used when the reading changes
- TX power capped at +10 dBm instead of the driver's +20 dBm default, cutting peak battery draw roughly 3x
- Brownout diagnostics: brownout resets blink red at boot and increment a lifetime counter in NVS
- Matter OTA requestor with A/B app partitions: updates arrive over Thread with no cable and keep commissioning, verified from v0.2.0 to v0.3.0 (see UPDATING.md)
- Multi-fabric: pair with more than one Matter controller at the same time
The full reference is in TROUBLESHOOTING.md.
| Action | Result |
|---|---|
| Single press | Sample now; LED shows moisture class (red dry, yellow almost dry, green normal) |
| Any press | Wakes the sleepy device; controllers can reach it immediately |
| Triple press | Start calibration (LED-guided, about 30 s) |
| Hold 10 s | Factory reset (red blinks 10 times) |
| LED pattern | Meaning |
|---|---|
| Yellow slow blink | Commissioning window open |
| Yellow medium blink | Identify; a controller asked the device to point itself out |
| Green, 3 blinks | Commissioning complete |
| Red, 5 blinks at boot | Brownout reset detected; check the power source |
Commissioning needs a Thread border router and a Matter controller that understands the Matter 1.5 Soil Sensor device type. Tested so far:
| Component | Status |
|---|---|
| Home Assistant 2026.7 or newer (Matter server with Matter 1.5 soil sensor support) | ✅ Tested |
| Apple HomePod mini as border router | ✅ Tested |
| Apple Home app | ⏳ No Soil Sensor device type support in the ecosystem yet |
| Google Home app | ⏳ No Soil Sensor device type support in the ecosystem yet |
As of August 2026, Home Assistant is the only major ecosystem that understands the Soil Sensor device type. Apple and Google devices work fine as Thread border routers, but their apps do not show soil moisture yet; a controller that predates the device type will commission the sensor and display nothing. Reports welcome when those ecosystems catch up.
- Flashing Guide — flashing over USB-C and back to stock
- Commissioning Guide — pairing with Home Assistant and other ecosystems
- Calibration Guide — LED-guided dry and wet calibration
- Updating Guide — Matter OTA and USB updates that keep commissioning
- Power & Battery — power design decisions and field data
- Hardware Notes — pin map, probe drive, battery sensing, antenna
- Building from Source — dev container, ESP-IDF, release artifacts
- Troubleshooting — LED reference and common issues
- Roadmap — known limitations and planned work
- Contributing — commit, branch, and release conventions
- Changelog — release history by version
├── source/ # Self-contained ESP-IDF project
│ ├── main/ # Firmware: soil probe, battery health, button, LEDs, Matter data model
│ ├── partitions.csv # A/B OTA layout, 4 MB flash
│ └── sdkconfig.defaults
├── scripts/ # Release asset builders (.bin and .ota)
├── docs/ # Guides and images
├── .github/ # Release workflow
└── .devcontainer/ # Pinned build environment (ESP-IDF v5.5.5)
The stock firmware works, but WiFi is a poor fit for a AA-powered sensor, and it ties the device to your WiFi network and an ESPHome workflow. The ESP32-C6 already carries an 802.15.4 radio, and Thread is designed for exactly this class of device: a battery-powered sensor that sleeps most of the time, wakes briefly, and reports one number to a low-power mesh. Matter on top of Thread makes the sensor a native device in any ecosystem, with no YAML, no bridge, and no cloud account.
Whether Thread delivers the battery life this hardware should be capable of is an open question, and POWER.md is where it gets answered in public.
This project comes from the same hands as the Shelly Gen4 Matter over Thread firmware, built because a $12 sensor with a Thread-capable radio deserved better than WiFi on a AA cell. If this firmware is useful to you, a ⭐ helps other people find it, and a coffee helps keep it developed.
| Project | What it is |
|---|---|
| Shelly Gen4 Matter over Thread | The first third-party open source Matter over Thread firmware for Shelly Gen4 devices |
| Shelly Gen4 ESPHome | ESPHome for Shelly Gen4 devices |
| T1N Smart Lock | Open source Matter over Thread smart lock for the factory central locking on a 2005 Dodge Sprinter 2500 |
| Project | What it is |
|---|---|
| xiao-esphome-projects | Seeed's stock ESPHome firmware for this sensor, restorable any time via the browser flasher |
| XIAO Soil Moisture Sensor wiki | Seeed's official documentation for the hardware |
Apache 2.0. Portions derived from Espressif esp-matter examples (Apache 2.0). Probe excitation parameters and the battery voltage mapping match the stock ESPHome firmware to keep readings comparable.