# Flower Watering

Prototype controller for a single house plant based on a Wemos D1 mini
(ESP8266), a capacitive soil-moisture sensor and a 5 V pump switched through
an HW-517 MOSFET module.

Project recap formats:

- [`PROJECT_OVERVIEW.md`](PROJECT_OVERVIEW.md) — component photos, Mermaid
  wiring diagram and checklist for VS Code Markdown Preview;
- [`project-page/index.html`](project-page/index.html) — extended interactive
  version with a browser-saved checklist.

The first firmware intentionally supports **manual timed watering only**.
Automatic watering is not implemented until the sensor and pump have been
calibrated and additional safety limits have been chosen.

## Home-network project page

The Raspberry Pi 5 serves the project catalog at
<https://p.nadzorov.com/> and this project's HTML recap at
<https://p.nadzorov.com/flower-watering/project-page/>. The direct LAN fallback
is <http://192.168.88.24:8088/>; local DNS names are `rpi.home.arpa` and
`laptop.home.arpa`.

Published files live in `/data/projects/flower-watering`. The `projects-web`
nginx container is defined in the main `/data/compose.yaml` and mounts
`/data/projects` read-only. The real `esphome/secrets.yaml` is not published.

### Updating the Raspberry Pi copy

The private Git repository is cloned to
`/data/project-repos/flower-watering`. It is separate from the public web root,
so `.git`, local build files and credentials cannot be served by nginx.

After pushing changes to `main`, deploy them on the Raspberry Pi with:

```bash
/data/projects-deploy/update-flower-watering
```

The script uses a repository-specific read-only GitHub deploy key, performs a
fast-forward-only pull, refuses to continue if `esphome/secrets.yaml` is in the
clone, publishes only the allow-listed documentation and web files, and checks
that the page returns HTTP 200 while the secret path returns 404.

## Hardware and pin mapping

| Wemos D1 mini pin | Connection | Notes |
|---|---|---|
| `5V` | +5 V breadboard rail | External regulated 5 V supply |
| `G` / `GND` | GND breadboard rail | All grounds must be common |
| `3V3` | Soil sensor `VCC` | Do not power the sensor from 5 V |
| `A0` | Soil sensor `AOUT` / `OUT` | Raw ADC reading |
| `D5` / `GPIO14` | HW-517 `SIG` / `PWM` | Active-high pump control |

Expected HW-517 power connections:

| HW-517 terminal | Connection |
|---|---|
| `VIN+` / `POWER+` | +5 V rail |
| `VIN-` / `POWER-` | Common GND |
| `SIG` / `PWM` | Wemos `D5` / `GPIO14` |
| `GND` / `SIG-` | Common GND |
| `OUT+` / `VOUT+` | Pump + |
| `OUT-` / `VOUT-` | Pump - |

Board labels vary between HW-517 revisions. Verify the labels on the actual
module before applying power.

Connect a 1N4007 flyback diode directly across the pump: striped cathode to
pump + and non-striped anode to pump -. The pump must never be powered from an
ESP8266 GPIO.

## Power and safety assumptions

- Use one external regulated 5 V supply for the Wemos and pump circuit.
- The Wemos `5V`, HW-517 power input and pump share that supply.
- Wemos, sensor, HW-517 and supply grounds are common.
- The soil sensor is powered only from Wemos `3V3`.
- Disconnect external 5 V while USB is connected unless the exact Wemos board
  power-path behavior has been verified. Never join two independent 5 V
  sources unintentionally.
- `D5` is assumed to drive the HW-517 input active-high. Verify this with the
  pump disconnected before a wet test.
- The pump switch is internal to ESPHome, restores as `ALWAYS_OFF`, and is
  explicitly turned off at boot and shutdown.
- Home Assistant exposes only `Water for 1 second`; it does not expose an
  unlimited pump switch.
- The watering sequence runs on the ESP itself. Closing Home Assistant or the
  browser does not interrupt the local one-second timeout.
- Repeated button presses while a pulse is running are ignored.
- A controller crash cannot guarantee a software turn-off before reset, so the
  wiring, stable power supply and boot-default OFF behavior remain essential.

## ESPHome setup

The configuration is [`esphome/flower-watering.yaml`](esphome/flower-watering.yaml).

ESPHome 2026.8.1 is installed in the project-local `.venv`. To recreate that
environment with Python 3.12:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

1. If `esphome/secrets.yaml` is absent, copy `esphome/secrets.yaml.example` to
   it. The local file is ignored by version control.
2. Replace all validation/placeholder Wi-Fi, API encryption and OTA values. Do
   this before any future flash. Generate the
   API key with `openssl rand -base64 32` or ESPHome's key generator.
3. Validate the configuration:

   ```powershell
   $env:PLATFORMIO_CORE_DIR = "$PWD\.platformio"
   .\.venv\Scripts\esphome.exe config esphome\flower-watering.yaml
   ```

4. Compile it without flashing:

   ```powershell
   $env:PLATFORMIO_CORE_DIR = "$PWD\.platformio"
   .\.venv\Scripts\esphome.exe compile esphome\flower-watering.yaml
   ```

Do not flash the Wemos until the wiring and HW-517 terminal labels have been
checked. This repository does not perform flashing automatically.

## Exposed entities

- `Soil Moisture Raw` — uncalibrated A0 ADC counts.
- `Water for 1 second` — safe local timed pump pulse.
- `Wi-Fi RSSI` — signal strength in dBm.
- `Uptime` — device uptime.

The development web server is enabled on port 80. Home Assistant uses ESPHome's
native encrypted API.

## Calibration and next steps

See [`docs/calibration.md`](docs/calibration.md) before adding a moisture
percentage or automatic watering. Dashboard notes are in
[`home-assistant/dashboard-notes.md`](home-assistant/dashboard-notes.md).