rtlamr-python 1.0.0__tar.gz

rtlamr_python-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Bagwell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rtlamr_python-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: rtlamr-python
+Version: 1.0.0
+Summary: Python implementation of RTLAMR-go — a multi-protocol ERT smart meter receiver
+Author-email: Ryan Bagwell <ryan@ryanbagwell.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ryanbagwell/rtlamr-python
+Project-URL: Repository, https://github.com/ryanbagwell/rtlamr-python
+Project-URL: Issues, https://github.com/ryanbagwell/rtlamr-python/issues
+Keywords: rtlamr,rtl-sdr,sdr,ert,smart-meter,scm,idm,r900
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyrtlsdr==0.3.0
+Requires-Dist: pyusb>=1.3.1
+Requires-Dist: setuptools
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# rtlamr-python
+
+A Python implementation of [rtlamr](https://github.com/bemasher/rtlamr) — a multi-protocol
+ERT (Encoder Receiver Transmitter) smart meter receiver. Reads IQ samples from an RTL-SDR
+dongle (or a raw sample file), decodes ERT packets, and prints each message as a JSON line
+to stdout.
+
+## Supported protocols
+
+| Protocol  | Description                                                    |
+|-----------|-----------------------------------------------------------------|
+| `scmplus` | Standard Consumption Message Plus (16 bytes, most electric meters) |
+| `scm`     | Standard Consumption Message (12 bytes, older electric meters)  |
+| `idm`     | Interval Data Message (92 bytes, hourly interval data)          |
+| `netidm`  | Net Meter Interval Data Message (92 bytes, net-metering variant)|
+| `r900`    | Neptune R900 water meters (different center freq: 912.38 MHz)   |
+
+By default, all Manchester-encoded protocols (`scmplus`, `scm`, `idm`, `netidm`) are decoded
+simultaneously. `r900` uses a different center frequency and must be selected explicitly
+(alone, or alternated with the Manchester set).
+
+## Installation
+
+Requires Python 3.11+ and an RTL-SDR dongle (or [librtlsdr](https://github.com/librtlsdr/librtlsdr) installed) for live capture.
+
+```bash
+pip install rtlamr-python
+```
+
+This installs an `rtlamr` command on your `PATH`.
+
+## Usage
+
+```bash
+# All Manchester protocols on live hardware
+rtlamr
+
+# Single protocol
+rtlamr --protocol scmplus
+
+# From a recorded capture file
+rtlamr --sample-file /path/to/capture.bin
+
+# Filter to specific meters
+rtlamr --meter-id 12345678
+
+# Alternate between Manchester and R900 (different center frequencies)
+rtlamr --protocol scmplus r900
+```
+
+Run `rtlamr --help` for the full list of options (gain, frequency correction, chip length,
+posting readings to a REST API, etc.).
+
+### Configuration file
+
+Options can also be supplied via a TOML config file with `--config path/to/rtlamr.toml`.
+Command-line flags always take precedence over the config file. Example:
+
+```toml
+meter_ids = [12345678, 87654321]
+protocol = ["scmplus", "scm"]
+gain = "auto"
+api_url = "http://localhost:8000/api"
+api_key = "secret"
+switch_timeout = 60.0
+```
+
+## Library usage
+
+`rtlamr-python` can also be used as a library rather than a CLI, e.g. to decode readings
+from within another application. All three forms below share the same options as the CLI
+(`protocols`, `meter_id`, `chip_length`, `gain`, `freq_correction`, `sample_file`,
+`switch_timeout`, `duration`, `verbose`).
+
+### Iterate over readings as they arrive
+
+```python
+from rtlamr_python import listen
+
+for reading in listen(protocols=["scmplus"], meter_id=[12345678]):
+    print(reading)
+    # break whenever you've got what you need — the SDR is closed on exit
+```
+
+### Block until a single reading decodes
+
+```python
+from rtlamr_python import listen_once
+
+reading = listen_once(protocols=["scmplus"], meter_id=[12345678])
+print(reading)  # SDR is already closed here
+```
+
+### Run in the background with a callback
+
+```python
+from rtlamr_python import start_listening
+
+def on_message(reading):
+    print(reading)
+
+handle = start_listening(on_message, protocols=["scmplus"])
+...
+handle.stop()  # signals the background thread and waits for it to exit
+```
+
+Each reading is a dict, e.g.:
+
+```json
+{"time": "2026-01-01T00:00:00Z", "type": "SCM+", "endpoint_id": 12345678,
+ "endpoint_type": 4, "consumption": 112233, "tamper": "0x0000", "packet_crc": "0x972F"}
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rtlamr_python-1.0.0/README.md

@@ -0,0 +1,123 @@
+# rtlamr-python
+
+A Python implementation of [rtlamr](https://github.com/bemasher/rtlamr) — a multi-protocol
+ERT (Encoder Receiver Transmitter) smart meter receiver. Reads IQ samples from an RTL-SDR
+dongle (or a raw sample file), decodes ERT packets, and prints each message as a JSON line
+to stdout.
+
+## Supported protocols
+
+| Protocol  | Description                                                    |
+|-----------|-----------------------------------------------------------------|
+| `scmplus` | Standard Consumption Message Plus (16 bytes, most electric meters) |
+| `scm`     | Standard Consumption Message (12 bytes, older electric meters)  |
+| `idm`     | Interval Data Message (92 bytes, hourly interval data)          |
+| `netidm`  | Net Meter Interval Data Message (92 bytes, net-metering variant)|
+| `r900`    | Neptune R900 water meters (different center freq: 912.38 MHz)   |
+
+By default, all Manchester-encoded protocols (`scmplus`, `scm`, `idm`, `netidm`) are decoded
+simultaneously. `r900` uses a different center frequency and must be selected explicitly
+(alone, or alternated with the Manchester set).
+
+## Installation
+
+Requires Python 3.11+ and an RTL-SDR dongle (or [librtlsdr](https://github.com/librtlsdr/librtlsdr) installed) for live capture.
+
+```bash
+pip install rtlamr-python
+```
+
+This installs an `rtlamr` command on your `PATH`.
+
+## Usage
+
+```bash
+# All Manchester protocols on live hardware
+rtlamr
+
+# Single protocol
+rtlamr --protocol scmplus
+
+# From a recorded capture file
+rtlamr --sample-file /path/to/capture.bin
+
+# Filter to specific meters
+rtlamr --meter-id 12345678
+
+# Alternate between Manchester and R900 (different center frequencies)
+rtlamr --protocol scmplus r900
+```
+
+Run `rtlamr --help` for the full list of options (gain, frequency correction, chip length,
+posting readings to a REST API, etc.).
+
+### Configuration file
+
+Options can also be supplied via a TOML config file with `--config path/to/rtlamr.toml`.
+Command-line flags always take precedence over the config file. Example:
+
+```toml
+meter_ids = [12345678, 87654321]
+protocol = ["scmplus", "scm"]
+gain = "auto"
+api_url = "http://localhost:8000/api"
+api_key = "secret"
+switch_timeout = 60.0
+```
+
+## Library usage
+
+`rtlamr-python` can also be used as a library rather than a CLI, e.g. to decode readings
+from within another application. All three forms below share the same options as the CLI
+(`protocols`, `meter_id`, `chip_length`, `gain`, `freq_correction`, `sample_file`,
+`switch_timeout`, `duration`, `verbose`).
+
+### Iterate over readings as they arrive
+
+```python
+from rtlamr_python import listen
+
+for reading in listen(protocols=["scmplus"], meter_id=[12345678]):
+    print(reading)
+    # break whenever you've got what you need — the SDR is closed on exit
+```
+
+### Block until a single reading decodes
+
+```python
+from rtlamr_python import listen_once
+
+reading = listen_once(protocols=["scmplus"], meter_id=[12345678])
+print(reading)  # SDR is already closed here
+```
+
+### Run in the background with a callback
+
+```python
+from rtlamr_python import start_listening
+
+def on_message(reading):
+    print(reading)
+
+handle = start_listening(on_message, protocols=["scmplus"])
+...
+handle.stop()  # signals the background thread and waits for it to exit
+```
+
+Each reading is a dict, e.g.:
+
+```json
+{"time": "2026-01-01T00:00:00Z", "type": "SCM+", "endpoint_id": 12345678,
+ "endpoint_type": 4, "consumption": 112233, "tamper": "0x0000", "packet_crc": "0x972F"}
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rtlamr_python-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rtlamr-python"
+version = "1.0.0"
+description = "Python implementation of RTLAMR-go — a multi-protocol ERT smart meter receiver"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+  { name = "Ryan Bagwell", email = "ryan@ryanbagwell.com" },
+]
+keywords = ["rtlamr", "rtl-sdr", "sdr", "ert", "smart-meter", "scm", "idm", "r900"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications",
+  "Topic :: Home Automation",
+]
+dependencies = [
+  "numpy>=1.24",
+  "pyrtlsdr==0.3.0",
+  "pyusb>=1.3.1",
+  "setuptools",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+]
+
+[project.urls]
+Homepage = "https://github.com/ryanbagwell/rtlamr-python"
+Repository = "https://github.com/ryanbagwell/rtlamr-python"
+Issues = "https://github.com/ryanbagwell/rtlamr-python/issues"
+
+[project.scripts]
+rtlamr = "rtlamr_python.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 80

rtlamr_python-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rtlamr_python-1.0.0/src/rtlamr_python/__init__.py

@@ -0,0 +1,17 @@
+from rtlamr_python.listener import (
+    ALL_PROTOCOLS,
+    DEFAULT_PROTOCOLS,
+    ListenerHandle,
+    listen,
+    listen_once,
+    start_listening,
+)
+
+__all__ = [
+    "ALL_PROTOCOLS",
+    "DEFAULT_PROTOCOLS",
+    "ListenerHandle",
+    "listen",
+    "listen_once",
+    "start_listening",
+]

rtlamr_python-1.0.0/src/rtlamr_python/__main__.py

@@ -0,0 +1,4 @@
+from rtlamr_python.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rtlamr_python-1.0.0/src/rtlamr_python/cli.py

@@ -0,0 +1,233 @@
+"""rtlamr-python — Multi-protocol ERT smart meter receiver.
+
+Reads IQ samples from an RTL-SDR dongle (or a raw sample file for testing),
+decodes ERT packets, and prints each message as a JSON line to stdout.
+
+Supported protocols (use --protocol to select; defaults to all Manchester ones):
+  scmplus — Standard Consumption Message Plus (16 bytes, most electric meters)
+  scm     — Standard Consumption Message (12 bytes, older electric meters)
+  idm     — Interval Data Message (92 bytes, hourly interval data)
+  netidm  — Net Meter Interval Data Message (92 bytes, net-metering variant)
+  r900    — Neptune R900 water meters (different center freq: 912.38 MHz)
+
+Usage:
+  # All Manchester protocols on live hardware
+  rtlamr
+
+  # Single protocol
+  rtlamr --protocol scmplus
+
+  # From a recorded capture file
+  rtlamr --sample-file /path/to/capture.bin
+
+  # Filter to specific meters
+  rtlamr --meter-id 12345678
+
+  # Alternate between Manchester and R900 (different center frequencies)
+  rtlamr --protocol scmplus r900
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import signal
+import sys
+import threading
+
+from rtlamr_python.listener import ALL_PROTOCOLS, DEFAULT_PROTOCOLS, listen
+from rtlamr_python.poster import ApiPoster
+
+LOG = logging.getLogger(__name__)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Multi-protocol ERT smart meter receiver")
+    p.add_argument(
+        "--config",
+        default=None,
+        metavar="PATH",
+        help="TOML config file (default: none)",
+    )
+    p.add_argument(
+        "--verbose",
+        action="store_true",
+        default=None,
+        help="print per-decoder stats to stderr every 500 blocks",
+    )
+    p.add_argument(
+        "--chip-length",
+        type=int,
+        default=None,
+        metavar="N",
+        help="chip length in samples (default: 72 → ~2.36 MHz sample rate)",
+    )
+    p.add_argument(
+        "--gain",
+        default=None,
+        metavar="GAIN",
+        help='tuner gain in dB or "auto" (default: auto)',
+    )
+    p.add_argument(
+        "--freq-correction",
+        type=int,
+        default=None,
+        metavar="PPM",
+        dest="freq_correction",
+        help="frequency correction for the RTL-SDR oscillator in parts per million "
+             "(negative if signals appear below their expected frequency)",
+    )
+    p.add_argument(
+        "--meter-id",
+        type=int,
+        nargs="+",
+        default=None,
+        metavar="ID",
+        dest="meter_id",
+        help="only forward readings from these endpoint IDs (space-separated); "
+             "overrides meter_ids in the config file",
+    )
+    p.add_argument(
+        "--sample-file",
+        default=None,
+        metavar="PATH",
+        help="read raw IQ bytes from a file instead of live hardware",
+    )
+    p.add_argument(
+        "--duration",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="stop after this many seconds (0 = run forever)",
+    )
+    p.add_argument(
+        "--protocol",
+        nargs="+",
+        choices=list(ALL_PROTOCOLS),
+        default=None,
+        metavar="PROTO",
+        help="protocols to decode (space-separated); default: all Manchester",
+    )
+    p.add_argument(
+        "--api-url",
+        default=None,
+        metavar="URL",
+        help='base URL of the REST API (e.g. "http://localhost:8000/api"); '
+             "if omitted, readings are only written to stdout",
+    )
+    p.add_argument(
+        "--api-key",
+        default=None,
+        metavar="KEY",
+        help="value for the X-API-Key header (only needed when the API requires auth)",
+    )
+    p.add_argument(
+        "--switch-timeout",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="alternating mode: switch frequency after this many seconds without "
+             "a message (default: 60)",
+    )
+    return p.parse_args(argv)
+
+
+def _load_config(path: str | None) -> dict:
+    if path is None:
+        return {}
+    import tomllib
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except FileNotFoundError:
+        return {}
+
+
+_DEFAULTS: dict = {
+    "chip_length": 72,
+    "gain": "auto",
+    "freq_correction": 0,
+    "duration": 0.0,
+    "verbose": False,
+    "switch_timeout": 60.0,
+}
+
+_CONFIG_KEYS = {
+    "api_url", "api_key", "meter_id", "meter_ids", "protocol", "switch_timeout",
+    "gain", "freq_correction", "chip_length", "duration", "verbose",
+}
+
+
+def _apply_config(args: argparse.Namespace, cfg: dict) -> None:
+    """Back-fill args still at None from cfg, then apply built-in defaults."""
+    # Normalize meter ID to list[int] or None.
+    if args.meter_id is None:
+        if "meter_ids" in cfg:
+            args.meter_id = list(cfg["meter_ids"])
+        elif "meter_id" in cfg:
+            args.meter_id = [cfg["meter_id"]]  # legacy single-int key
+
+    # Normalize protocol to list[str] or None.
+    if args.protocol is None and "protocol" in cfg:
+        raw = cfg["protocol"]
+        if isinstance(raw, list):
+            args.protocol = raw
+        else:
+            args.protocol = [p.strip() for p in str(raw).split(",")]
+
+    for key in _CONFIG_KEYS - {"meter_id", "meter_ids", "protocol"}:
+        if getattr(args, key) is None and key in cfg:
+            setattr(args, key, cfg[key])
+    for key, default in _DEFAULTS.items():
+        if getattr(args, key) is None:
+            setattr(args, key, default)
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+        stream=sys.stderr,
+    )
+
+    args = parse_args(argv)
+    _apply_config(args, _load_config(args.config))
+
+    poster = ApiPoster(args.api_url, args.api_key) if args.api_url else None
+
+    # Graceful shutdown on SIGINT.
+    stop_event = threading.Event()
+
+    def _stop(signum, frame):
+        LOG.info("Received signal %s, stopping.", signum)
+        stop_event.set()
+
+    signal.signal(signal.SIGINT, _stop)
+
+    try:
+        for record in listen(
+            protocols=args.protocol or list(DEFAULT_PROTOCOLS),
+            meter_id=args.meter_id,
+            chip_length=args.chip_length,
+            gain=args.gain,
+            freq_correction=args.freq_correction,
+            sample_file=args.sample_file,
+            switch_timeout=args.switch_timeout,
+            duration=args.duration,
+            verbose=args.verbose,
+            stop_event=stop_event,
+        ):
+            sys.stdout.write(json.dumps(record) + "\n")
+            sys.stdout.flush()
+            if poster:
+                poster.submit(record)
+    except ValueError as exc:
+        LOG.error(str(exc))
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rtlamr_python-1.0.0/src/rtlamr_python/crc.py

@@ -0,0 +1,75 @@
+"""CCITT-16 CRC used by the SCM+ protocol (CRC-16/GENIBUS variant).
+
+Port of rtlamr-go/crc/crc.go.
+
+Polynomial : 0x1021
+Init value : 0xFFFF
+XOR-out    : 0xFFFF  (meters complement the CRC before embedding it as PacketCRC)
+Valid residue: 0x1D0F  (checksum over bytes[2:] of a valid SCM+ packet equals this)
+
+To embed a valid PacketCRC when constructing a packet:
+    pkt_crc = checksum(bytes[2:14]) ^ 0xFFFF
+
+To verify a received packet:
+    valid(packet)  — checks checksum(packet[2:]) == RESIDUE
+"""
+
+_POLY = 0x1021
+_INIT = 0xFFFF
+RESIDUE = 0x1D0F
+
+# Build 256-entry lookup table once at import time.
+_table: list[int] = []
+for _i in range(256):
+    _crc = _i << 8
+    for _ in range(8):
+        if _crc & 0x8000:
+            _crc = (_crc << 1) ^ _POLY
+        else:
+            _crc <<= 1
+        _crc &= 0xFFFF
+    _table.append(_crc)
+
+
+def checksum(data: bytes | bytearray, init: int = _INIT) -> int:
+    """Return the CCITT-16 CRC of *data* starting from *init*."""
+    crc = init
+    for byte in data:
+        crc = ((crc << 8) ^ _table[(crc >> 8) ^ byte]) & 0xFFFF
+    return crc
+
+
+def valid(packet: bytes | bytearray) -> bool:
+    """Return True when the CRC of packet[2:] equals the expected residue."""
+    return checksum(packet[2:]) == RESIDUE
+
+
+# ---------------------------------------------------------------------------
+# BCH-16 CRC used by the SCM protocol
+# ---------------------------------------------------------------------------
+
+_BCH_POLY = 0x6F63
+
+_bch_table: list[int] = []
+for _i in range(256):
+    _crc = _i << 8
+    for _ in range(8):
+        if _crc & 0x8000:
+            _crc = (_crc << 1) ^ _BCH_POLY
+        else:
+            _crc <<= 1
+        _crc &= 0xFFFF
+    _bch_table.append(_crc)
+
+
+def bch_checksum(data: bytes | bytearray, init: int = 0) -> int:
+    """Return the BCH-16 CRC of *data* (poly=0x6F63, init=0, xorout=0)."""
+    crc = init
+    for byte in data:
+        crc = ((crc << 8) ^ _bch_table[(crc >> 8) ^ byte]) & 0xFFFF
+    return crc
+
+
+def bch_valid(packet: bytes | bytearray) -> bool:
+    """Return True when bch_checksum(packet[2:12]) == 0 (SCM validation)."""
+    return bch_checksum(packet[2:12]) == 0