# Flower Watering Project Context ## Goal Build a reliable home-plant watering controller that: - measures soil moisture; - exposes readings over Wi-Fi; - integrates with Home Assistant; - provides a simple local web interface during development; - allows safe manual timed watering; - later supports automatic watering with configurable thresholds; - avoids overwatering and pump lock-on conditions; - can eventually be expanded to multiple plants. --- ## Hardware currently selected ### Controller - Wemos D1 mini - ESP8266 - Logic level: 3.3 V ### Soil moisture sensor - Capacitive Soil Moisture Sensor v1.2 - Analog output - Powered from Wemos 3.3 V - Signal goes to A0 ### Pump - 5 V DC water pump from GyverKIT EXTRA ### Pump driver - MOSFET module HW-517 - Controlled by Wemos GPIO - Used instead of driving the pump directly from ESP8266 ### Flyback protection - 1N4007 diode - Connected in parallel with the pump - Cathode / striped side goes to pump + - Anode goes to pump - ### Power - One external 5 V power supply - 5 V is distributed using breadboard power rails - Wemos is powered through its 5V pin - Pump/MOSFET power comes from the same 5 V source - All grounds must be common ### Prototyping - Breadboard - Jumper wires --- ## Current wiring plan ### Wemos D1 mini | Wemos pin | Connection | |---|---| | 5V | +5 V breadboard rail | | G / GND | GND breadboard rail | | 3V3 | Soil sensor VCC | | A0 | Soil sensor analog OUT | | D5 / GPIO14 | HW-517 control input / SIG / PWM | ### Soil sensor | Sensor pin | Connection | |---|---| | VCC | Wemos 3V3 | | GND | Common GND | | AOUT / OUT | Wemos A0 | ### HW-517 MOSFET module Expected connections: | HW-517 terminal | Connection | |---|---| | VIN+ / POWER+ | +5 V rail | | VIN- / POWER- | GND rail | | SIG / PWM | Wemos D5 / GPIO14 | | GND / SIG- | Common GND | | OUT+ / VOUT+ | Pump + | | OUT- / VOUT- | Pump - | Before final wiring, verify terminal labels on the actual HW-517 board because similar modules may use slightly different printed labels. ### Pump protection diode 1N4007 across the pump: - striped side / cathode -> pump + - non-striped side / anode -> pump - The diode is reverse-biased during normal pump operation and suppresses the inductive voltage spike when the pump switches off. --- ## Power architecture Use one 5 V supply for the whole prototype. ```text 5 V PSU | +---- +5 V breadboard rail ---- Wemos 5V | | | +---- HW-517 VIN+ | +---- GND breadboard rail ---- Wemos GND | +---- HW-517 GND / VIN- | +---- soil sensor GND ``` The soil sensor itself should be powered from Wemos 3.3 V, not directly from the 5 V rail. During USB flashing/debugging, disconnect the external 5 V supply unless the exact Wemos board power-path behavior has been verified. Avoid connecting two independent 5 V sources together unintentionally. --- ## Why the MOSFET module is used The ESP8266 GPIO must not power the pump directly. The MOSFET acts as an electronic switch: ```text +5 V | pump | MOSFET | GND ``` Wemos D5 only controls the MOSFET gate. The high pump current flows through the power supply, pump and MOSFET, not through the ESP8266 GPIO. HW-517 is electrically oversized for this small pump, but it is useful for the prototype because it already provides: - power MOSFETs; - gate resistor network; - convenient screw terminals; - input connection; - indicator LED; - a robust high-current switch. A future compact PCB can replace HW-517 with a single logic-level N-channel MOSFET plus gate resistors and the flyback diode. --- ## Software architecture Use ESPHome instead of writing a custom Arduino sketch initially. Reasons: - native Home Assistant integration; - easy OTA updates later; - easy analog sensor support; - easy GPIO pump control; - configurable template buttons and automations; - optional built-in web server; - straightforward logs and diagnostics. Target device: ```yaml esp8266: board: d1_mini ``` --- ## Initial ESPHome functionality The first usable firmware should provide: 1. Wi-Fi connection. 2. Home Assistant native API. 3. OTA update support. 4. Local web server during development. 5. Raw soil moisture sensor reading. 6. Wi-Fi signal strength. 7. Uptime. 8. A safe manual watering button. 9. Pump output with forced timeout. --- ## Pump safety model Do NOT expose the pump initially as a normal unlimited ON/OFF switch. The first Home Assistant control should be a timed action such as: ```text Water for 1 second ``` Expected behavior: ```text button pressed | pump ON | 1 second | pump OFF ``` Pump must turn OFF automatically even if: - Home Assistant disconnects; - browser closes; - user forgets about it; - automation fails. Also configure the pump GPIO so it defaults to OFF on boot. --- ## Soil moisture calibration Do not trust generic Internet values. Calibrate this specific sensor and this specific soil. Record at least: 1. sensor in air; 2. sensor in dry soil; 3. sensor in normally watered soil; 4. optionally fully saturated/wet soil. Initially expose the raw A0 value. Later convert the calibrated range to a relative 0-100% moisture value. Important: this is a practical relative soil-moisture scale, not a laboratory volumetric water content measurement. --- ## Planned Home Assistant entities Initial device could expose: ```text Flower Watering - Soil moisture raw - Soil moisture % - Water for 1 second - Wi-Fi RSSI - Uptime ``` Later: ```text - Minimum moisture threshold - Target moisture threshold - Automatic watering enabled - Last watering time - Last watering duration - Estimated water volume - Daily watering total - Pump fault / safety lockout ``` --- ## Planned automatic watering logic Do not run the pump continuously until the sensor reaches the target. Use short watering pulses. Example: ```text if moisture < MIN: run pump for N seconds wait 30-60 seconds measure again if still too dry: repeat stop when target is reached ``` Reason: Water needs time to spread through the soil. Continuous feedback without settling time can cause severe overwatering. Add safety limits such as: - maximum pump runtime per pulse; - maximum number of pulses per watering cycle; - maximum total pump runtime per day; - minimum delay between watering cycles; - reject obviously invalid sensor readings; - disable automatic watering if sensor is disconnected or faulty. --- ## Pump calibration Before automatic watering: 1. Put the pump inlet in a water container. 2. Run the pump for a known duration, e.g. 5 or 10 seconds. 3. Measure the delivered volume. 4. Calculate approximate ml/s. Then watering can be expressed in approximate milliliters instead of only seconds. --- ## Future sensors from GyverKIT IOT Possible later additions: ### HTU21D Measure: - air temperature; - relative humidity. ### Light sensor Measure: - approximate plant illumination. ### TFT 160x128 Optional later replacement for the OLED/local display. The current prototype intentionally does not use a physical display because readings will be available through Wi-Fi and Home Assistant. --- ## Future expansion Possible next versions: ### Multi-plant system For each plant: - independent capacitive moisture sensor; - independent pump or valve; - separate moisture thresholds; - separate watering statistics. Home Assistant view example: ```text Ficus 46% OK Lemon 31% WATER Spathiphyllum 58% OK Palm 39% OK ``` ### Reliability improvements - water tank level sensor; - dry-run protection; - leak sensor; - pump current monitoring; - watchdog; - persistent watering counters; - fail-safe mode after reboot; - physical manual-water button. ### Mechanical - printed electronics enclosure; - pump/tube holders; - drip nozzle; - strain relief; - moisture-resistant connectors. --- ## Recommended project structure Codex can create something like: ```text flower-watering/ ├── README.md ├── PROJECT_CONTEXT.md ├── esphome/ │ └── flower-watering.yaml ├── docs/ │ ├── wiring.md │ └── calibration.md └── home-assistant/ └── dashboard-notes.md ``` --- ## Immediate next task for Codex Read this file completely. Then: 1. Create the project structure above. 2. Create the initial ESPHome YAML for Wemos D1 mini. 3. Configure: - Wi-Fi placeholders/secrets; - Home Assistant API; - OTA; - development web server; - A0 soil sensor raw reading; - D5 / GPIO14 pump output; - a safe `Water for 1 second` button; - pump OFF by default at boot; - Wi-Fi RSSI; - uptime. 4. Do not implement automatic watering yet. 5. Keep all pin mappings and safety assumptions documented in README.md. 6. If ESPHome is not installed, install the required local tooling. 7. Run a config validation / compile check and fix errors. 8. Do not flash hardware until explicitly asked.