mattandClaude
f6630c547c
Target broker is EMQX 5.x at 192.168.1.31. Probed its current state and documented it in docs/MQTT_SETUP.md: all listeners up, retained messages working, management API protected (401), but the MQTT data plane has no authenticator -- anonymous connects are accepted, and so are arbitrary made-up credentials. Until an authenticator exists, the broker account values in the local config header are decorative and a successful connection proves nothing about them. The guide covers creating the password-based authenticator, separate soil-node and homeassistant accounts, per-account ACLs (including setting no-match to Deny, without which the rules are cosmetic), pointing the HA MQTT integration at EMQX, and a CONNACK/PubSubClient troubleshooting table. tools/mqtt_watch.py watches the broker directly during bring-up. It answers what the HA UI cannot: whether the retained discovery configs are actually on the broker. Those are what HA rebuilds entities from after a restart, so a node can look healthy today and disappear on the next HA restart if they are missing. It reads its broker account secret from a file or environment variable rather than argv, which is visible process-wide. The broker IP is deliberately kept out of the committed template header, since the Gitea repo is public. Co-Authored-By: Claude <noreply@anthropic.com>
146 lines
6.4 KiB
Markdown
146 lines
6.4 KiB
Markdown
# ESP32-S3 Soil Moisture Node
|
||
|
||
Six HW-390 v2.0 capacitive soil probes on one Cat5 run, read by an ESP32-S3,
|
||
published to Home Assistant over MQTT with auto-discovery. Multi-node safe.
|
||
|
||
Implements [ESP32_Soil_Moisture_Node_PRD.md](ESP32_Soil_Moisture_Node_PRD.md).
|
||
|
||
- **Board:** VCC-GND Studio YD-ESP32-S3 (ESP32-S3-DevKitC-1 clone, WROOM-1)
|
||
- **Framework:** Arduino via PlatformIO
|
||
- **Transport:** MQTT + Home Assistant auto-discovery
|
||
|
||
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
cp include/secrets.h.example include/secrets.h
|
||
$EDITOR include/secrets.h # Wi-Fi + broker credentials
|
||
|
||
pio run -e mains -t upload -t monitor
|
||
```
|
||
|
||
The node appears in Home Assistant under **Settings → Devices → MQTT** as
|
||
*Soil Node XXXXXX* within a few seconds. No YAML.
|
||
|
||
Broker and Home Assistant setup — including EMQX authentication and ACLs — is
|
||
in [docs/MQTT_SETUP.md](docs/MQTT_SETUP.md). Read it before flashing: the
|
||
broker at 192.168.1.31 currently accepts anonymous connections, so a node that
|
||
connects successfully proves nothing about your credentials being right.
|
||
|
||
Then calibrate the probes — see [docs/CALIBRATION.md](docs/CALIBRATION.md).
|
||
The shipped calibration constants are placeholders and will read wrong.
|
||
|
||
## Build targets
|
||
|
||
| Command | Profile | Behaviour |
|
||
|---------|---------|-----------|
|
||
| `pio run -e mains` | Continuous (PRD §4.1) | Always on, publishes every 60 s |
|
||
| `pio run -e battery` | Solar/battery (PRD §4.2) | Wake → sample → publish → deep sleep, 15 min |
|
||
|
||
The profile is a compile-time switch; `include/config.h` fails the build if
|
||
neither or both are defined.
|
||
|
||
|
||
|
||
## Pin map
|
||
|
||
All six probes sit on **ADC1**. This is forced, not stylistic: ADC2 is owned by
|
||
the Wi-Fi radio on the ESP32-S3, and reading an ADC2 pin with the radio up
|
||
returns garbage. ADC1 is GPIO1–10, which is exactly enough for six probes plus
|
||
a battery divider.
|
||
|
||
| Function | GPIO | Channel |
|
||
|----------|------|---------|
|
||
| Moisture 1–6 | 4, 5, 6, 7, 8, 9 | ADC1_CH3–CH8 |
|
||
| Battery divider | 10 | ADC1_CH9 |
|
||
| Sensor rail MOSFET gate | 14 | — |
|
||
| Status RGB LED | 48 | onboard |
|
||
|
||
Avoided on this board: GPIO0/3/45/46 (strapping), GPIO19/20 (native USB),
|
||
GPIO33–37 (octal flash/PSRAM on N\*R8 variants), GPIO43/44 (UART0).
|
||
|
||
Full harness details, RC filter values and the MOSFET circuit are in
|
||
[docs/WIRING.md](docs/WIRING.md).
|
||
|
||
## Layout
|
||
|
||
```
|
||
include/config.h Pin map, calibration, timing — the file you edit
|
||
include/secrets.h Credentials (gitignored; copy from .example)
|
||
src/main.cpp Boot flow, sample/publish cycle, sleep
|
||
src/adc_sampler.* Oversampling, outlier trim, two-point curve
|
||
src/power.* Sensor rail, battery sense, deep sleep, awake budget
|
||
src/net.* Wi-Fi + MQTT session, LWT
|
||
src/ha_discovery.* HA auto-discovery payloads
|
||
src/node_id.* MAC-derived unique node identity
|
||
docs/img/*.svg Architecture, schematics and flow diagrams
|
||
docs/MQTT_SETUP.md EMQX auth/ACL + Home Assistant wiring
|
||
tools/mqtt_watch.py Broker-side bring-up watcher
|
||
```
|
||
|
||
## Diagrams
|
||
|
||
| Diagram | What it covers |
|
||
|---------|----------------|
|
||
| [System architecture](docs/img/system-architecture.svg) | End-to-end: probes → Cat5 → breakout → MCU → HA |
|
||
| [RJ45 breakout](docs/img/rj45-breakout.svg) | Per-pin schematic with the six mandatory RC filters |
|
||
| [High-side P-FET switch](docs/img/power-switch.svg) | Sensor rail switching and the 2N7002 inverting stage |
|
||
| [Solar / battery topology](docs/img/battery-solar.svg) | Panel, charger, cell, boost, battery sense divider |
|
||
| [Firmware flow](docs/img/firmware-flow.svg) | Both power profiles side by side |
|
||
|
||
## How the PRD's mitigations are implemented
|
||
|
||
**ADC non-linearity (§3.3).** Readings go through `analogReadMilliVolts()`,
|
||
which applies the chip's eFuse ADC calibration, rather than scaling raw counts.
|
||
|
||
**Signal smoothing (§3.3).** 16 samples per probe per cycle, spaced 2 ms apart,
|
||
sorted, top and bottom 10% discarded, remainder averaged.
|
||
|
||
**Two-point calibration (§3.3).** Per-probe air/water endpoints in `config.h`.
|
||
Note the HW-390 is **inverted** — dry reads high — so the curve maps
|
||
`air → 0%`, `water → 100%`. The firmware refuses an inverted config rather
|
||
than silently producing a backwards curve.
|
||
|
||
**Multi-node identity (§5.1).** Node ID is derived from the factory MAC, so two
|
||
boards flashed with the same binary get distinct topics and distinct HA
|
||
entities. Nothing is per-node in the build.
|
||
|
||
**Auto-discovery (§5.2).** Retained config topics under `homeassistant/sensor/`
|
||
published on startup, so nodes populate the dashboard with no manual YAML.
|
||
|
||
## Design decisions worth knowing
|
||
|
||
**Faults are reported, not clamped.** A probe reading well outside its
|
||
calibrated window is published as `null` → *unknown* in HA, rather than being
|
||
clamped to 0% or 100%. A cut Cat5 pair reads ~0 mV, which clamps to a perfectly
|
||
believable "very dry" — and believable wrong data is worse than a gap, because
|
||
it will drive irrigation. Tune with `SENSOR_FAULT_MARGIN_MV`.
|
||
|
||
**Availability is handled differently per profile.** The mains node uses an
|
||
MQTT availability topic plus a last-will, so a crash greys out its entities. A
|
||
sleeping node is "offline" almost all the time, so that approach would leave it
|
||
permanently greyed; the battery profile uses `expire_after` (2.5× the sleep
|
||
interval) instead.
|
||
|
||
**Discovery is republished only on cold boot.** The config topics are retained,
|
||
so the broker replays them to HA on every HA restart. Republishing on each
|
||
15-minute wake would be radio time spent for nothing. A cold boot is the one
|
||
event that may mean new firmware and a changed entity set.
|
||
|
||
**Every wake is guaranteed to end in sleep.** The per-step network timeouts
|
||
don't cover an AP that associates but never issues a DHCP lease, or a broker
|
||
that completes the TCP handshake but never sends CONNACK. `AWAKE_BUDGET_MS`
|
||
arms a one-shot timer before anything that can block, and forces deep sleep if
|
||
the cycle overruns. Without it, one misbehaving broker flattens the cell.
|
||
|
||
**One state topic, not fourteen.** All entities read from a single retained
|
||
JSON payload via `value_template`. On the battery profile this is roughly the
|
||
difference between a 3 s and a 6 s wake.
|
||
|
||
## Status
|
||
|
||
Both build profiles compile clean under `-Wall`. **Not yet run on hardware** —
|
||
the pin map, the MOSFET circuit and the calibration defaults are all unverified
|
||
against a physical board. Bring it up on mains first with one probe.
|