{"id":51772672,"url":"https://github.com/qppd/wmldad","last_synced_at":"2026-07-20T03:32:38.586Z","repository":{"id":370594909,"uuid":"1295575881","full_name":"qppd/wmldad","owner":"qppd","description":"ESP32-based smart water meter monitoring system","archived":false,"fork":false,"pushed_at":"2026-07-13T08:14:03.000Z","size":405,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-13T10:08:37.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qppd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-09T17:09:04.000Z","updated_at":"2026-07-13T08:14:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qppd/wmldad","commit_stats":null,"previous_names":["qppd/water-meter","qppd/wmldad"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/qppd/wmldad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fwmldad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fwmldad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fwmldad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fwmldad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qppd","download_url":"https://codeload.github.com/qppd/wmldad/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qppd%2Fwmldad/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35672442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-20T03:32:38.016Z","updated_at":"2026-07-20T03:32:38.578Z","avatar_url":"https://github.com/qppd.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# WMLDAD — Smart Water Monitoring System\n\n\u003e **A Research Project** — Smart Water Monitoring System that detects leaks, anomalies, and per-fixture consumption using ESP32, Raspberry Pi, USB Serial communication, and Machine Learning (XGBoost + Isolation Forest).\n\n---\n\n## Developer Quick-Start: Step-by-Step Process\n\nFollow these steps **in order**. Each step links to the detailed guide.\n\n### Phase 1: Prepare (Do First)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 1 | **Buy parts** — Order from BOM (Makerlab Electronics on Shopee/Lazada) | [BOM.md](./docs/bom.md) | 1–2 weeks shipping |\n| 2 | **Flash Raspberry Pi OS** — Trixie 64-bit, enable SSH + WiFi in Imager | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 30 min |\n| 3 | **Clone project repo** — Get code on Pi and your computer | [setup.md](./docs/setup.md#phase-2-software-installation) | 5 min |\n\n\u003e ⚠️ **Do Step 1–2 in parallel.** Hardware shipping takes longest.\n\n---\n\n### Phase 2: Hardware Assembly\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 4 | **Wire ESP32 + 4× YF-S201** on expansion board (GPIO 26, 25, 33, 32) | [block-diagram.md](./docs/block-diagram.md) | 1 hr |\n| 5 | **Plumbing** — Install sensors in-line with check valves (arrow = flow direction) | [setup.md](./docs/setup.md#phase-4-hardware-assembly) | 2–4 hrs |\n| 6 | **Enclosure** — Mount in IP67 box with cable glands + USB cable gland | [block-diagram.md](./docs/block-diagram.md) | 1 hr |\n\n---\n\n### Phase 3: ESP32 Firmware (USB Serial)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 7 | **Install Arduino IDE 2.x** via `pip install arduino` on RPi (or Windows/macOS) | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 15 min |\n| 8 | **Add ESP32 board support** — Board Manager URL + install `esp32 by Espressif Systems` | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 10 min |\n| 9 | **Install library** — `ArduinoJson` (for JSON serialization) | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 5 min |\n| 10 | **Configure `config.h`** — WiFi (for OTA only), device ID, sensor pins, PPL calibration | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 10 min |\n| 11 | **Upload firmware** — Select ESP32 Dev Module, correct port, Upload (Ctrl+U) | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 5 min |\n| 12 | **Verify** — Serial Monitor (115200): JSON sensor data streaming every 5 sec | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | 5 min |\n\n---\n\n### Phase 4: Sensor Calibration (Required Before ML)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 13 | **Bucket test each sensor** — 5L measured, calculate PPL, update `config.h` | [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md#sensor-calibration-bucket-test) | 30 min/sensor |\n\n\u003e 🎯 Target: \u003c 3% error per sensor. Uncalibrated sensors = false leaks / missed leaks.\n\n---\n\n### Phase 5: Raspberry Pi Backend (with 800×480 Touchscreen LCD)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 14 | **SSH into RPi** — `ssh pi@water-meter.local` | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 5 min |\n| 15 | **Clone repo + create venv + install deps** | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 10 min |\n| 16 | **Configure serial port** — udev rule for `/dev/ttyESP32` symlink | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 5 min |\n| 17 | **Run Flask** — `python app.py`, verify dashboard at `http://water-meter.local:5000/` | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 5 min |\n| 18 | **Enable systemd service** for auto-start on boot | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 5 min |\n| 19 | **Configure 800×480 Touchscreen** — Auto-launch Chromium kiosk to dashboard | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 10 min |\n\n---\n\n### Phase 6: ML Model (Can Defer)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 20 | **Train XGBoost + Isolation Forest** — Use Google Colab (GPU) | [ml-complete-guide.md](./docs/ml-complete-guide.md) | 30 min |\n| 21 | **Export models** — `xgboost_model.json`, `isolation_forest.pkl`, `scaler.pkl` to `rpi/models/` | [ml-complete-guide.md](./docs/ml-complete-guide.md) | 5 min |\n| 22 | **Verify inference** — Dashboard shows leak classifications | [ml-complete-guide.md](./docs/ml-complete-guide.md) | 5 min |\n\n\u003e 💡 **Skip for initial bring-up.** System works with local ESP32 rules (inlet balance, continuous flow, drip detection) without ML. Add ML after hardware + data pipeline verified.\n\n---\n\n### Phase 7: Remote Access (Optional)\n\n| Step | Action | Guide | Est. Time |\n|------|--------|-------|-----------|\n| 23 | **Router port forward** — External 8443 → RPi:5000 | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 10 min |\n| 24 | **DDNS** (DuckDNS free) or **Cloudflare Tunnel** (HTTPS) | [pi-complete-setup.md](./docs/pi-complete-setup.md) | 15 min |\n\n---\n\n## Essential Guides Only (Bookmark These)\n\n| Guide | Purpose |\n|-------|---------|\n| [BOM.md](./docs/bom.md) | Parts list with Shopee links, prices |\n| [pi-complete-setup.md](./docs/pi-complete-setup.md) | **Complete Pi OS → Backend deployment** (Flash → SSH/VNC → Venv → Deps → Backend files → ML models → Systemd → Touchscreen) |\n| [block-diagram.md](./docs/block-diagram.md) | Pinout, wiring, enclosure layout, 3D models |\n| [setup.md](./docs/setup.md) | Full phased walkthrough (reference) |\n| [esp32-firmware-complete-guide.md](./docs/esp32-firmware-complete-guide.md) | **Complete ESP32 firmware** (Arduino IDE → ESP32 Board → ArduinoJson → Config → Upload → Verify → Calibration) |\n| [esp32-rpi-communication.md](./docs/esp32-rpi-communication.md) | USB serial auto-detection on `/dev/ttyUSB0/1`, JSON protocol |\n| [troubleshooting.md](./docs/troubleshooting.md) | Serial commands, LED codes, common fixes |\n\n---\n\n## Hardware Summary\n\n| Component | Qty | Key Spec |\n|-----------|-----|----------|\n| ESP32 38-pin Dev Module | 1 | CP2102/CH340 USB-UART, 4 MB Flash |\n| ESP32 Expansion Board | 1 | Screw terminals |\n| YF-S201 Flow Sensor | 4 | 1/2\" NPT, Hall effect |\n| Check Valve 1/2\" | 3 | Brass/PVC, prevent backflow |\n| 12V 5A PSU + LM2596S buck | 1 | 220V → 12V → 5V |\n| IP67 ABS Enclosure | 1 | 175×125×75mm |\n| **7\" Touchscreen LCD** | **1** | **800×480, HDMI + USB touch** |\n| JST-XH 3-pin M/F | 4 each | Pre-crimped, no crimp tool needed |\n| Perf board 20×80mm | 2 | Soldered connections |\n\n---\n\n## Quick Verification Checklist\n\nAfter each phase, verify:\n\n- [ ] **Phase 1:** Pi boots, `ssh pi@water-meter.local` works\n- [ ] **Phase 2:** All 4 sensors show pulses in Serial Monitor when water flows\n- [ ] **Phase 3:** JSON data streaming every 5 sec on Serial Monitor (115200 baud)\n- [ ] **Phase 4:** 5L bucket test → \u003c 3% error on each sensor\n- [ ] **Phase 5:** Dashboard at `:5000` shows live flow rates per fixture on **touchscreen LCD**\n- [ ] **Phase 6:** Leak simulation (slow drip) → alert appears in dashboard\n- [ ] **Phase 7:** Remote URL (DDNS:8443 or Cloudflare) loads dashboard\n\n---\n\n## License\n\nMIT\n\n## Author\n\n[qppd](https://github.com/qppd) — Quezon Province, Philippines","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqppd%2Fwmldad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqppd%2Fwmldad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqppd%2Fwmldad/lists"}