mattandClaude
ad9c457ea7
Implements ESP32_Soil_Moisture_Node_PRD.md on the VCC-GND Studio
YD-ESP32-S3 (ESP32-S3-WROOM-1) using Arduino via PlatformIO, publishing
to Home Assistant over MQTT with auto-discovery.
Two power profiles behind a compile-time switch (PRD 4):
-e mains always on, publishes every 60s
-e battery RTC wake, sample, publish, deep sleep 15min
PRD mitigations:
- All six probes on ADC1 (GPIO4-9); ADC2 is unusable while Wi-Fi is up.
- analogReadMilliVolts() for eFuse ADC calibration rather than raw counts.
- 16 samples per probe, sorted, 10% trimmed from each end, averaged.
- Per-probe two-point calibration; HW-390 output is inverted (dry reads
high), and an inverted config is rejected rather than silently producing
a backwards curve.
- MAC-derived node ID so identical binaries never collide on topics.
Design decisions that diverge from a literal reading of the PRD:
- Out-of-range probes publish null (HA "unknown") instead of clamping to
0%/100%. A cut Cat5 pair reads ~0mV, which clamps to a believable "very
dry" and would drive irrigation on wrong data.
- The battery profile uses expire_after rather than an availability topic;
a sleeping node is offline most of the time and would sit greyed out.
- AWAKE_BUDGET_MS forces deep sleep if a wake cycle overruns, covering
failure modes the per-step network timeouts miss (DHCP never issued,
CONNACK never sent) that would otherwise flatten the cell.
- docs/WIRING.md notes the 18650 cannot feed the probes directly: the
XC6206 LDO needs ~3.4V headroom, so a boost converter is required on the
switched side of the MOSFET.
Both profiles compile clean under -Wall. Not yet run on hardware; pin map,
MOSFET circuit and calibration defaults are unverified against a board.
Co-Authored-By: Claude <noreply@anthropic.com>
79 lines
5.8 KiB
Markdown
79 lines
5.8 KiB
Markdown
# Product Requirements Document (PRD)
|
|
**Project:** Scalable ESP32 Soil Moisture Monitoring Node
|
|
**Target Audience:** AI Engineering Agents (Firmware, Hardware Design, Home Assistant Integration)
|
|
|
|
## 1. System Overview
|
|
A modular, distributed soil moisture monitoring system designed to interface up to six HW-390 (v2.0) capacitive soil moisture sensors per local microcontroller node. The system utilizes Cat5 cabling for consolidated power distribution and analog signal collection. Data is gathered by an ESP32-class microcontroller and broadcasted over Wi-Fi for ingestion, recording, and automation by a Home Assistant server. The architecture supports multi-node deployments with conflict-free network identification and accommodates both continuous (mains) and remote (solar/battery) power profiles.
|
|
|
|
## 2. Hardware Architecture & Wiring Specifications
|
|
|
|
### 2.1 Microcontroller Unit (MCU)
|
|
* **Supported Platforms:** ESP32-S3 (Primary), ESP32-C3, ESP32-S2, or standard ESP32.
|
|
* **Requirements:** Must have at least 6 accessible ADC (Analog-to-Digital Converter) channels capable of reading 0-3.3V, Wi-Fi capabilities, and deep-sleep support for battery operations.
|
|
|
|
### 2.2 Cabling & Breakout
|
|
* **Cable Type:** Standard 24 AWG solid-core Cat5/Cat5e cable.
|
|
* **Pinout/Pairing Strategy:**
|
|
* **Pair 1 (e.g., Orange/Orange-White):** `5V VCC` and `Shared GND`. (Crucial to keep power and ground on the same twisted pair to minimize loop area).
|
|
* **Pair 2, 3, 4 (e.g., Green, Blue, Brown pairs):** Assigned to `Analog Signal 1` through `Analog Signal 6`.
|
|
* **Termination:** Cat5 cable terminates at an RJ45 receiver/breakout board at the MCU enclosure.
|
|
|
|
### 2.3 Sensor Wiring & Protection (HW-390 v2.0)
|
|
* **Power:** Sensors are supplied with 5V over the Cat5 cable. The HW-390 v2.0 onboard XC6206 LDO regulates this to a clean 3.3V locally at the sensor.
|
|
* **Environmental Protection:** The upper PCB of all HW-390 sensors (components, exposed edges, and spliced connections) MUST be sealed with marine epoxy or conformal coating to prevent rapid outdoor degradation. Only the capacitive prongs remain unsealed.
|
|
|
|
## 3. Required Mitigations: Pitfalls & Solutions
|
|
|
|
To ensure system stability, subsequent AI agents designing the PCB/breadboard layout and firmware must implement the following solutions.
|
|
|
|
### 3.1 Hardware Mitigation: Signal Integrity & EMI
|
|
* **Issue:** Cat5 is unshielded and tightly twisted, causing capacitive coupling (crosstalk) and EMI susceptibility for DC analog signals.
|
|
* **Solution (Mandatory Hardware):** Implement an RC Low-Pass Filter on the RJ45 receiver board for every analog input line before it reaches the ESP32 ADC pin.
|
|
* *Component Values:* 10kΩ inline resistor, 0.1µF to 1µF ceramic capacitor bridging the ADC pin to GND.
|
|
|
|
### 3.2 Hardware Mitigation: Ground Bounce
|
|
* **Issue:** Six sensors sharing one Cat5 GND wire can cause the ground potential to float, altering analog readings.
|
|
* **Solution:** All spliced connections on the sensor end must be soldered/heat-shrunk or secured with high-retention Wago connectors. Limit total sensor draw to ~30mA (5mA per sensor).
|
|
|
|
### 3.3 Software Mitigation: ESP32 ADC Non-Linearity & Signal Smoothing
|
|
* **Issue:** ESP32 ADCs are non-linear, especially at extreme voltage ranges, and sandy/fast-draining soil creates rapid micro-fluctuations in moisture distribution.
|
|
* **Solution (Mandatory Firmware):**
|
|
* Employ the ESP32 hardware ADC calibration API.
|
|
* **Oversampling:** The firmware must take an array of 10-20 readings per sensor per cycle, discard the highest and lowest 10% (outliers), and average the remaining values.
|
|
* **Calibration:** Implement a two-point software calibration curve (Air = 0%, Water = 100%) to map the raw ADC integers to a percentage value.
|
|
|
|
## 4. Power Profiles & Management
|
|
|
|
The system must support two power topologies, determinable at compilation or runtime configuration:
|
|
|
|
### 4.1 Continuous Power (Mains)
|
|
* Supplied via 5V USB or dedicated 5V buck converter.
|
|
* MCU remains active, broadcasting updates at a set interval (e.g., every 60 seconds).
|
|
|
|
### 4.2 Solar / Battery Power (Remote Nodes)
|
|
* **Hardware:** Integrates a LiPo/Li-Ion battery (e.g., 18650 cell) and a solar charge controller (e.g., TP4056 with protection circuitry) paired with a 5V/6V solar panel. (Highly compatible with automated solar drip irrigation setups).
|
|
* **Firmware Deep Sleep:**
|
|
1. Wake up based on RTC timer (e.g., every 15-30 minutes).
|
|
2. Power on sensors (via a GPIO-controlled MOSFET switching the 5V line to save idle current).
|
|
3. Stabilize (wait 500ms).
|
|
4. Oversample, average, and map ADC readings.
|
|
5. Connect to Wi-Fi, publish MQTT/ESPHome payload.
|
|
6. Return to deep sleep.
|
|
|
|
## 5. Network Architecture & Home Assistant Integration
|
|
|
|
### 5.1 Multi-Node Identification (Conflict Prevention)
|
|
* **Unique Addressing:** Firmware must dynamically generate a unique Node ID based on the ESP32's internal MAC address (e.g., `soil-node-A1B2C3`).
|
|
* **Data Tagging:** All broadcasted data payloads must be tagged with this Node ID.
|
|
|
|
### 5.2 Communication Protocol
|
|
* **Recommended Framework:** ESPHome is the primary recommended framework for seamless, native Home Assistant integration via the ESPHome API.
|
|
* **Alternative:** Standard MQTT (via PubSubClient or similar). If using MQTT, the firmware must publish Home Assistant MQTT Auto-Discovery configuration payloads on startup so nodes populate automatically in the HA dashboard without manual YAML configuration.
|
|
|
|
### 5.3 Data Payload Requirements
|
|
The node must expose the following entities to Home Assistant per cycle:
|
|
* `sensor.node_[ID]_moisture_1` through `6` (Value: 0-100%, Unit: %, Device Class: Moisture)
|
|
* `sensor.node_[ID]_battery_level` (If using solar profile, mapped from battery voltage via voltage divider)
|
|
* `sensor.node_[ID]_wifi_signal` (RSSI)
|
|
* `sensor.node_[ID]_uptime` (or last seen timestamp)
|