meter-reader knowledge base
Bundle OKF 0.2 · 6 conceitos · geoffjay/water-meter
Open source Repository Open in the app JSON README (API)
About
# meter-reader knowledge base
This is the working knowledge base for the meter-reader project, conforming to the
[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
It consolidates working knowledge about the project: what meter-reader is, how it is
structured, decisions and their rationale, recurring patterns, and plans.
It is authored by people and agents and meant to be read by both.
## For agents (policy)
This section is the single source of truth for how agents should use this knowledge
base. Tooling injects it into context automatically, so it does not depend on
`CLAUDE.md`/`AGENTS.md` being picked up. The following agents are wired to this KB:
* **Claude Code** — via a SessionStart hook (`.claude/hooks/kb-inject.py`) that injects
this index, plus PostToolUse/Stop reminder hooks (`.claude/hooks/kb-reminder.py`).
* **opencode** — via the `instructions` array in `.opencode/opencode.jsonc`.
* **oh-my-pi** — via the
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- geoffjay
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-09-03T17:19:40Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-09-09 12:03:57
- Updated
- 2026-09-09 12:03:57
- Origin id
geoffjay/water-meter:docs/knowledgebase/index.md
README
# meter-reader
Tools for passively receiving and plotting Neptune R900 water-meter readings
captured with an RTL-SDR dongle and the [rtlamr](https://github.com/bemasher/rtlamr)
decoder. See the [knowledge base](docs/knowledgebase/) for background on the
Neptune MACH 10 R900i, the R900 protocol, and the hardware/software setup.
## Requirements
- Python ≥ 3.12.2
- [uv](https://docs.astral.sh/uv/) for dependency management
- An RTL-SDR dongle and `rtlamr` to capture readings (see
[R900 Passive Monitoring](docs/knowledgebase/concepts/r900-passive-monitoring.md))
## Install
```bash
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:
```bash
# 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`:
```json
{"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](docs/knowledgebase/concepts/r900-passive-monitoring.md#identifying-your-meters-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:
```bash
uv run meter-reader readings.ndjson
```
Save the chart to a file instead of opening a window:
```bash
uv run meter-reader readings.ndjson -o readings.png
```
Plot a single meter by its MIU ID:
```bash
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](docs/knowledgebase/concepts/r900-passive-monitoring.md#consumption-encoding-binary-vs-bcd)
for details.