meter-reader

Tools for passively receiving and plotting Neptune R900 water-meter readings captured with an RTL-SDR dongle and the rtlamr decoder. See the knowledge base for background on the Neptune MACH 10 R900i, the R900 protocol, and the hardware/software setup.

Requirements

• Python ≥ 3.12.2
• uv for dependency management
• An RTL-SDR dongle and rtlamr to capture readings (see R900 Passive Monitoring)

Install

uv sync

This installs meter-reader as a console script along with its dependencies (click, seaborn, matplotlib, pandas).

Capturing readings

The plotting utility consumes NDJSON output from rtlamr. To capture a file:

# Terminal A — expose the dongle over TCP
rtl_tcp

# Terminal B — decode Neptune R900 packets to NDJSON
rtlamr -msgtype=r900 -format=json > readings.ndjson

# If consumption values look wrong, your meter may use BCD encoding:
rtlamr -msgtype=r900bcd -format=json > readings.ndjson

# To lock onto a single meter once you know its MIU ID:
rtlamr -msgtype=r900 -format=json -filterid=<MIU_ID> > readings.ndjson

Each line in the file is a JSON object with the meter data nested under Message:

{"Time":"2026-08-19T12:54:10.231823-07:00","Offset":0,"Length":65536,"Type":"R900","Message":{"ID":1578876706,"Unkn1":163,"NoUse":34,"BackFlow":0,"Consumption":309200,"Unkn3":0,"Leak":1,"LeakNow":0}}

See the knowledge base for how to identify your meter's MIU ID.

Plotting readings

The meter-reader command reads an NDJSON file and produces a seaborn line plot of consumption over time, with one colored line per meter ID.

Usage

Usage: meter-reader [OPTIONS] PATH

  Plot Consumption over Time for each meter ID in an rtlamr NDJSON file.

Options:
  -o, --output FILE  Save the plot to this file instead of showing it.
  --id INTEGER       Plot only this meter ID. Omit to plot every meter in the
                     file.
  --help             Show this message and exit.

Examples

Plot all meters and display the chart in a window:

uv run meter-reader readings.ndjson

Save the chart to a file instead of opening a window:

uv run meter-reader readings.ndjson -o readings.png

Plot a single meter by its MIU ID:

uv run meter-reader readings.ndjson --id 1578876706 -o my_meter.png

Notes

• Lines that are not valid JSON (e.g. stray shell output captured before the first record) are silently skipped, so a raw redirect works without cleanup.
• The output format is determined by the file extension (.png, .svg, .pdf, etc.).
• Consumption values are plotted as-is from the rtlamr output. The raw units depend on the meter configuration (US gallons, cubic feet, cubic metres) and may need scaling — see the knowledge base for details.