Water Meter Gateway
The Gateway is the seam between the radio mesh and the IP network. It listens on 433 MHz for readings forwarded by Node devices, holds them in a local queue, and POSTs them as JSON to a Windows ingest service running elsewhere on the LAN. If that service is offline, the queue keeps growing until it comes back, and no data is dropped.
It also runs the management plane: a client roster of every Node it's heard from, daily "By Node" usage emails, and a small command surface for poking nodes remotely: set a default meter, clear a database, ping for connectivity, reboot.
What it does, in plain English
A Node decodes a meter and sends a packet to the Gateway over the 433 MHz CC1101 mesh. The Gateway receives it, adds it to a per-meter ledger (so it can compute interval flow rates even when meters don't report flow themselves), and queues it for upload. A background task drains the queue by POSTing batched JSON to a FastAPI ingest service on the local PC at port 41290, which writes the readings into MySQL.
If the PC is rebooting, on a different network, or just busy, the gateway keeps the queue and retries. The dashboard shows the queue depth, last HTTP response code, and a running drop counter so you can see at a glance whether the pipe is healthy.
Key features
- CC1101 mesh hub. Receives readings and events from up to 32 nodes over a 433 MHz 2-FSK mesh, with multi-hop relay and ACKs. Auto-tracks a client roster: chip, firmware version, RSSI, LQI, last-seen.
- HTTP ingest with retry buffer. Batches readings and events into JSON payloads and POSTs them to a FastAPI endpoint at
http://<pc-ip>:41290/ingest. Buffers locally when the PC is offline and drains on reconnect, so no readings are lost. - "Record to Database" toggle. A persistent on/off switch on the
/setuppage, right inside the Database Host card next to the ingest service IP and port. Default is off: the mesh still runs, the dashboard still shows readings, and the daily email still goes out, but nothing is written to MySQL until you opt in. Setting survives reboots. - Optional W5500 Ethernet. Compile with
#define HAVE_W5500to use a wired uplink on the SPI bus (CS=5, RST=22). Falls back to WiFi if the link is down. - Fallback WiFi AP. Always broadcasts a dedicated access point so distant Nodes that can't see the home AP can still associate and relay their readings via the Gateway. Credentials are shown on the Gateway's own
/setuppage once you're on the LAN. - Live dashboard. Client roster, ingest status, queue depth, dropped counts, mesh TX/ACK counters, all visible at the gateway's IP.
- Remote mesh commands. Send
set-default-meter,clear-db,reboot,ping,query-status,set-samplingto any node by ID, over the mesh, without needing direct WiFi reach. - Daily "By Node" email. Each morning, sends a summary of each Node's default-meter reading to multiple recipients via SMTP. Supports add/remove recipients without rebuild.
- Keepalive pings. Pings every known client every 60 seconds to keep CC1101 PLLs warm and surface dead nodes early.
- Flow synthesis. Computes interval-average gallons-per-minute at the gateway from consecutive volume readings, handy when meters themselves don't transmit flow.
Specs
| MCU | ESP32 dual-core (Heltec CT62 footprint) |
|---|---|
| Mesh radio | CC1101 @ 433.92 MHz, 2-FSK, multi-hop, ACKed |
| Uplink | WiFi 802.11 b/g/n + optional W5500 Ethernet (compile flag) |
| Ingest target | HTTP POST to Windows / FastAPI service on LAN port 41290 |
| Fallback AP | Dedicated SSID for stranded nodes during commissioning; credentials shown on the Gateway's /setup page |
| Firmware | 0.1.52 (observable at /api/gw-diag) |
| OTA | POST /update with new .bin; HTTP-only (no PuTTY needed) |
Web endpoints
All endpoints are HTTP on port 80 of the Gateway's WiFi (or Ethernet) IP.
GET / | Dashboard: client roster, ingest status, queue, mesh stats. |
|---|---|
GET /setup | Configuration page: WiFi credentials, ingest target, email settings, command cards. |
POST /update | Firmware upload (multipart). |
GET /api/gw-diag | JSON: gateway firmware, Ethernet link, ingest health, queue depth, mesh counters. |
GET /api/clients | JSON of connected nodes (id, chip, fw, RSSI, LQI, packet count, last seen). |
POST /api/cmd/<op> | Remote mesh commands: reboot, clear-db, set-default-meter, ping, query-status, set-sampling. Optional {"node_id": N} in the body to target a single node. |
GET /api/email | JSON: schedule config; POST to update interval / send time. |
GET /api/email/preview | JSON: live per-(node, meter) registry with the exact numbers the email uses, raw wire units plus floored display gallons, baseline, interval delta, RSSI, age. For diffing the in-RAM state against the database. |
POST /api/email/add_recip | Add an email recipient. |
POST /api/email/del_recip | Remove an email recipient. |
POST /api/email/send_now | Trigger immediate "By Node" report. |
Setup page
The /setup endpoint is the Gateway's management console. From a single page you point it at a PC ingest service, toggle MySQL recording on or off, set the timezone, change the protocol on any remote node over the mesh, set the default meter, clear a node's database, ping or reboot a wedged node, run per-field queries to recover edge-of-range nodes, and schedule the daily "By Node" email, all without leaving the gateway's web UI.
http://<gateway-ip>/setup · the Database Host card houses the new Record to Database checkbox · sensitive values maskedSample "By Node" email
Every morning the Gateway sends each recipient a short usage summary, one line per Node showing the latest reading from that Node's default meter, plus daily and monthly volume. Recipients receive the same content directly in their inbox, no login required.
For agents
A structured spec of this device is available at /api/gateway.json. The page above is also annotated with schema.org/Product JSON-LD in <head>.