rtlamr-python 1.0.0__py3-none-any.whl

rtlamr_python/sdr.py

@@ -0,0 +1,102 @@
+"""SDR sample sources.
+
+Two implementations share the SampleSource protocol:
+  UsbSdr        — live RTL-SDR dongle via pyrtlsdr
+  FileSampleSource — reads raw IQ bytes from a file (loops on EOF)
+
+Select via the --sample-file CLI flag; omit it for live USB.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SampleSource(Protocol):
+    def read_block(self, n_bytes: int) -> bytes:
+        """Return exactly *n_bytes* of raw uint8 IQ data."""
+        ...
+
+    def set_center_freq(self, freq: int) -> None:
+        """Retune the source to *freq* Hz."""
+        ...
+
+    def close(self) -> None:
+        ...
+
+
+class UsbSdr:
+    """Live RTL-SDR dongle via pyrtlsdr."""
+
+    def __init__(self, center_freq: int, sample_rate: int, gain: str | float = "auto", ppm: int = 0) -> None:
+        try:
+            # pyrtlsdr ≤ 0.3.0 does `import pkg_resources` at module level for
+            # version detection. setuptools ≥ 80 removed pkg_resources, so
+            # inject a minimal stub when the real module is absent.
+            import sys
+            if 'pkg_resources' not in sys.modules:
+                import importlib.util
+                import types
+                if importlib.util.find_spec('pkg_resources') is None:
+                    sys.modules['pkg_resources'] = types.ModuleType('pkg_resources')
+            from rtlsdr import RtlSdr
+        except ImportError:
+            raise ImportError(
+                "pyrtlsdr is required for live hardware. "
+                "Install it with: pip install 'rtlamr-python'"
+            )
+        self._sdr = RtlSdr()
+        self._sdr.center_freq = center_freq
+        self._sdr.sample_rate = sample_rate
+        self._sdr.ppm_error = ppm
+        if gain == "auto":
+            self._sdr.gain = "auto"
+        else:
+            self._sdr.gain = float(gain)
+
+    def read_block(self, n_bytes: int) -> bytes:
+        """Read *n_bytes* uint8 IQ samples from the dongle."""
+        return bytes(self._sdr.read_bytes(n_bytes))
+
+    def set_center_freq(self, freq: int) -> None:
+        self._sdr.center_freq = freq
+
+    def close(self) -> None:
+        self._sdr.close()
+
+
+class FileSampleSource:
+    """Read raw IQ bytes from a binary file; loop on EOF for continuous testing."""
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._fh = open(path, "rb")
+
+    def read_block(self, n_bytes: int) -> bytes:
+        data = self._fh.read(n_bytes)
+        if len(data) < n_bytes:
+            # Loop back to the start of the file.
+            self._fh.seek(0)
+            data = self._fh.read(n_bytes)
+        return data
+
+    def set_center_freq(self, freq: int) -> None:
+        pass  # no-op; file captures are frequency-agnostic
+
+    def close(self) -> None:
+        self._fh.close()
+
+
+def open_source(
+    center_freq: int,
+    sample_rate: int,
+    gain: str | float = "auto",
+    ppm: int = 0,
+    sample_file: str | None = None,
+) -> SampleSource:
+    """Return the appropriate SampleSource based on whether a file path was given."""
+    if sample_file:
+        return FileSampleSource(sample_file)
+    return UsbSdr(center_freq, sample_rate, gain, ppm)

rtlamr_python-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+rtlamr_python/__init__.py,sha256=zJf0EA8egm-vibQMLYCQJbQb5QIxRg-LNnhWrGv2a28,290
+rtlamr_python/__main__.py,sha256=ND39a5xe1Uq9cGh-ZJpfsOYIN8rFxcGASw6kz9Id44Q,92
+rtlamr_python/cli.py,sha256=tm59q0lIIPuhRXRZ7zzMH8kMsv3r6Fck9VE_aFpAWuc,6860
+rtlamr_python/crc.py,sha256=nXPLxCxE9CYC8t-PJ7zBg8Z1fweSL4kC_su9rmNb0cE,2157
+rtlamr_python/decoder.py,sha256=tnvf_Hk3Q3u938tL-ggy-FNynucOY9w_fhCqWhyO5O0,10427
+rtlamr_python/listener.py,sha256=KaHS2FeUFjz6Z7zEMaL-YK6MT0J3Au7Cbait5nNwdRQ,12568
+rtlamr_python/poster.py,sha256=Y1mN5mhVv1GZiZL2sg5qMH7DqofIapa7sVZEAAROXYI,3382
+rtlamr_python/r900_decoder.py,sha256=U3psGQlRtNqxjyCpQ2Ve14k4jHYFCW9HDVAkeWkYc2E,11667
+rtlamr_python/sdr.py,sha256=uiLRQy_mCPWS_nD_qiEBME5el4QOaOomT_J5ARXiYoE,3217
+rtlamr_python/protocols/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rtlamr_python/protocols/commodity.py,sha256=_AIZFvhgkHArHXh1Ti6AnLcddhdYhqXDoMghy5kP-mA,1196
+rtlamr_python/protocols/idm.py,sha256=OmDrBhdtjrzvqv369Vfyz30mxUFs94CCTShx2Ogjyqo,4616
+rtlamr_python/protocols/netidm.py,sha256=9KoKfuo7DCkmXQRZQM2TbcM9eS180xtOMBlLES8Ywtw,3884
+rtlamr_python/protocols/r900.py,sha256=W-eGGc0rl28_yhKOCFP31GQbIxX8Hkug3e4VkSxDJcM,2044
+rtlamr_python/protocols/scm.py,sha256=FmZnXL2-ft8kOKuqA1-Fc46dn30kphdfI826zPdbRfU,2348
+rtlamr_python/protocols/scmplus.py,sha256=Qr4HOUKtBdFrG3ZndnW3LfXL_jD_mFz4YdZSRRi-zuQ,2405
+rtlamr_python-1.0.0.dist-info/licenses/LICENSE,sha256=xzcGj3DR_4EbJer9xFCahm4Q2n1ud8C8C9CnmEr7NPw,1069
+rtlamr_python-1.0.0.dist-info/METADATA,sha256=KmBEx4jNlyq0otiPXBRHKw8j7lBc0NH3AU0C_h8m6eU,4783
+rtlamr_python-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rtlamr_python-1.0.0.dist-info/entry_points.txt,sha256=8LqK70DFQWCZTjeKsqMXZVd_UxTed4Q-HKmjHk8PWUs,50
+rtlamr_python-1.0.0.dist-info/top_level.txt,sha256=GX1_wGjMfRbIUgHQjdY-tKIfm6u446OrI7-DCTsyRtk,14
+rtlamr_python-1.0.0.dist-info/RECORD,,

rtlamr_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rtlamr_python-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rtlamr = rtlamr_python.cli:main

rtlamr_python-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+rtlamr_python