# 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)