erdilrf-lrf 0.2.0__tar.gz

erdilrf_lrf-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ERDILRF
+
+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.

erdilrf_lrf-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: erdilrf-lrf
+Version: 0.2.0
+Summary: Host-side UART driver for ERDI 905 nm laser rangefinder modules (LR1000E2 protocol family)
+License-Expression: MIT
+Project-URL: Homepage, https://erdilrf.com
+Project-URL: Repository, https://github.com/erdilrf/erdilrf-drivers
+Project-URL: Documentation, https://github.com/erdilrf/erdilrf-drivers/blob/main/protocol/PROTOCOL.md
+Keywords: laser-rangefinder,lidar,dtof,905nm,uart,embedded,robotics,drone,industrial-automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Python host driver
+
+Host-side UART driver for **ERDI 905 nm laser rangefinder modules** — the LR1000E2 protocol family.
+
+**Zero core dependencies** — framing and decoding are pure standard library, so the whole driver
+runs and is testable on any machine, including one with no hardware attached. `pyserial` is optional
+and only needed to actually open a port.
+
+```bash
+pip install -e .            # from this directory (python/)
+pip install -e python/      # from the repository root — same thing
+pip install pyserial        # only needed to open a real port
+```
+
+## Command line
+
+Every command below runs with **no hardware and no serial port** except the last three:
+
+```bash
+erdilrf frames                             # print the whole command table
+erdilrf decode "55 AA 88 01 FF 27 10 BE"   # decode a captured frame
+erdilrf ports
+erdilrf measure --port COM3 --count 5
+erdilrf stream  --port COM3
+erdilrf selftest --port COM3               # run immediately after power-on
+```
+
+## Library
+
+```python
+from erdilrf_lrf import Rangefinder, SerialTransport
+
+with Rangefinder(SerialTransport("COM3")) as rf:
+    print(rf.single_shot())                 # 123.4 metres, or None if the shot failed
+    for distance in rf.stream(count=10):    # 3-10 Hz adaptive continuous ranging
+        print(distance)
+```
+
+## Protocol in one table
+
+Fixed 8-byte frames. The checksum is the low byte of a sum — and **the two directions use different
+ranges**, which is the single most common integration mistake.
+
+```text
+offset   0     1     2      3    4    5     6      7
+        0x55  0xAA  FUNC   D1   D2   D3    D4     SUM
+
+host  -> module   SUM = (FUNC + D1 + D2 + D3 + D4) & 0xFF
+module -> host    SUM = (0x55 + 0xAA + FUNC + D1 + D2 + D3 + D4) & 0xFF
+```
+
+| Command | Transmit | Response |
+|---|---|---|
+| Single-shot ranging | `55 AA 88 FF FF FF FF 84` | `55 AA 88 STA FF DIS_H DIS_L SUM` |
+| Continuous ranging | `55 AA 89 FF FF FF FF 85` | `55 AA 89 STA FF DIS_H DIS_L SUM` |
+| Stop ranging | `55 AA 8E FF FF FF FF 8A` | `55 AA 8E STA FF FF FF SUM` |
+| Angle measurement † | `55 AA 8A FF FF FF FF 86` | `55 AA 8A STA FF ANG_H ANG_L SUM` |
+| LD constant-on on / off | `55 AA 86 FF FF FF 01 84` / `… 00 83` | see known gap below |
+| Set baud rate | `55 AA TYPE FF FF FF FF SUM` | `55 AA TYPE STA FF FF FF SUM` |
+
+Distance and angle are both scaled by 10 — the 16-bit register holds tenths, so
+`((DIS_H << 8) | DIS_L) / 10` gives metres.
+
+† Angle measurement is available **only on modules fitted with an angle sensor**.
+
+Default link: **115200 bps, 8 data bits, 8-byte frame**. The manufacturer documents 115200 and 8 data
+bits; it is **silent on parity and stop bits**, so this driver assumes 8N1 and says so. If a module
+stays silent, try `--parity E` or `--parity O` before assuming a wiring fault.
+
+## Tests
+
+50 tests, no hardware and no serial port required — serial I/O is injected as a two-method
+transport, so the whole driver runs against a scripted fake link.
+
+```bash
+python -m pytest -q
+```
+
+The suite has already caught real defects in this repository: a `FrameReader` that validated
+*transmitted* frames with the *response* checksum rule, and a pre-command flush that silently ate
+the answer to the command it had just sent (a wrong distance with no error — the worst failure this
+driver can produce).
+
+Golden vectors assert that all six transmit frames printed in the manufacturer's manual are
+reproduced byte for byte, and that each printed checksum is reproducible from the stated rule.
+
+## What the tests do not cover
+
+No test in this repository has ever run against a real module. The framing is verified against the
+manual and against itself, **not against silicon**. A capture from real hardware outranks every
+table above — if your module disagrees, open an issue with the raw bytes.
+
+## Known gaps we did not paper over
+
+* **The LD constant-on response frame is incomplete in the published manual** — section 8 prints
+  only `55` for that row. This driver sends the command and does not validate a reply. It does not
+  guess the missing bytes.
+* **Cable wire colours are not documented.** The manual gives pin numbers only:
+  1 GND, 2 VCC, 3 I/O (reserved), 4 TXD, 5 RXD, 6 SW-SHOT.
+* **SW-SHOT polarity is configuration-dependent.** The manual says "function enable (active high)"
+  and in the same row "compatible with active-low control requirements". Confirm per unit.
+* **UART logic-level tolerance is not specified.** Only the 3.3–5 V supply figure is given.
+
+---
+
+## About this file
+
+This is the **PyPI long description** for the `erdilrf-lrf` distribution. The packaging toolchain
+cannot read a file outside the project directory, so this file lives here rather than reusing the
+repository root `README.md`. It mirrors the Python-relevant sections of that root README; the root
+README remains authoritative for the repository as a whole (protocol reference, Arduino driver,
+wiring notes).
+
+Installable package name: **`erdilrf-lrf`** · import name: **`erdilrf_lrf`** · CLI: **`erdilrf`**.
+Note that the package name differs from the import name and from the CLI name — see
+[`pyproject.toml`](pyproject.toml) for the single source of truth.
+
+Part of [erdilrf/erdilrf-drivers](https://github.com/erdilrf/erdilrf-drivers) · MIT ·
+modules documented at [erdilrf.com](https://erdilrf.com)

erdilrf_lrf-0.2.0/README.md

@@ -0,0 +1,119 @@
+# Python host driver
+
+Host-side UART driver for **ERDI 905 nm laser rangefinder modules** — the LR1000E2 protocol family.
+
+**Zero core dependencies** — framing and decoding are pure standard library, so the whole driver
+runs and is testable on any machine, including one with no hardware attached. `pyserial` is optional
+and only needed to actually open a port.
+
+```bash
+pip install -e .            # from this directory (python/)
+pip install -e python/      # from the repository root — same thing
+pip install pyserial        # only needed to open a real port
+```
+
+## Command line
+
+Every command below runs with **no hardware and no serial port** except the last three:
+
+```bash
+erdilrf frames                             # print the whole command table
+erdilrf decode "55 AA 88 01 FF 27 10 BE"   # decode a captured frame
+erdilrf ports
+erdilrf measure --port COM3 --count 5
+erdilrf stream  --port COM3
+erdilrf selftest --port COM3               # run immediately after power-on
+```
+
+## Library
+
+```python
+from erdilrf_lrf import Rangefinder, SerialTransport
+
+with Rangefinder(SerialTransport("COM3")) as rf:
+    print(rf.single_shot())                 # 123.4 metres, or None if the shot failed
+    for distance in rf.stream(count=10):    # 3-10 Hz adaptive continuous ranging
+        print(distance)
+```
+
+## Protocol in one table
+
+Fixed 8-byte frames. The checksum is the low byte of a sum — and **the two directions use different
+ranges**, which is the single most common integration mistake.
+
+```text
+offset   0     1     2      3    4    5     6      7
+        0x55  0xAA  FUNC   D1   D2   D3    D4     SUM
+
+host  -> module   SUM = (FUNC + D1 + D2 + D3 + D4) & 0xFF
+module -> host    SUM = (0x55 + 0xAA + FUNC + D1 + D2 + D3 + D4) & 0xFF
+```
+
+| Command | Transmit | Response |
+|---|---|---|
+| Single-shot ranging | `55 AA 88 FF FF FF FF 84` | `55 AA 88 STA FF DIS_H DIS_L SUM` |
+| Continuous ranging | `55 AA 89 FF FF FF FF 85` | `55 AA 89 STA FF DIS_H DIS_L SUM` |
+| Stop ranging | `55 AA 8E FF FF FF FF 8A` | `55 AA 8E STA FF FF FF SUM` |
+| Angle measurement † | `55 AA 8A FF FF FF FF 86` | `55 AA 8A STA FF ANG_H ANG_L SUM` |
+| LD constant-on on / off | `55 AA 86 FF FF FF 01 84` / `… 00 83` | see known gap below |
+| Set baud rate | `55 AA TYPE FF FF FF FF SUM` | `55 AA TYPE STA FF FF FF SUM` |
+
+Distance and angle are both scaled by 10 — the 16-bit register holds tenths, so
+`((DIS_H << 8) | DIS_L) / 10` gives metres.
+
+† Angle measurement is available **only on modules fitted with an angle sensor**.
+
+Default link: **115200 bps, 8 data bits, 8-byte frame**. The manufacturer documents 115200 and 8 data
+bits; it is **silent on parity and stop bits**, so this driver assumes 8N1 and says so. If a module
+stays silent, try `--parity E` or `--parity O` before assuming a wiring fault.
+
+## Tests
+
+50 tests, no hardware and no serial port required — serial I/O is injected as a two-method
+transport, so the whole driver runs against a scripted fake link.
+
+```bash
+python -m pytest -q
+```
+
+The suite has already caught real defects in this repository: a `FrameReader` that validated
+*transmitted* frames with the *response* checksum rule, and a pre-command flush that silently ate
+the answer to the command it had just sent (a wrong distance with no error — the worst failure this
+driver can produce).
+
+Golden vectors assert that all six transmit frames printed in the manufacturer's manual are
+reproduced byte for byte, and that each printed checksum is reproducible from the stated rule.
+
+## What the tests do not cover
+
+No test in this repository has ever run against a real module. The framing is verified against the
+manual and against itself, **not against silicon**. A capture from real hardware outranks every
+table above — if your module disagrees, open an issue with the raw bytes.
+
+## Known gaps we did not paper over
+
+* **The LD constant-on response frame is incomplete in the published manual** — section 8 prints
+  only `55` for that row. This driver sends the command and does not validate a reply. It does not
+  guess the missing bytes.
+* **Cable wire colours are not documented.** The manual gives pin numbers only:
+  1 GND, 2 VCC, 3 I/O (reserved), 4 TXD, 5 RXD, 6 SW-SHOT.
+* **SW-SHOT polarity is configuration-dependent.** The manual says "function enable (active high)"
+  and in the same row "compatible with active-low control requirements". Confirm per unit.
+* **UART logic-level tolerance is not specified.** Only the 3.3–5 V supply figure is given.
+
+---
+
+## About this file
+
+This is the **PyPI long description** for the `erdilrf-lrf` distribution. The packaging toolchain
+cannot read a file outside the project directory, so this file lives here rather than reusing the
+repository root `README.md`. It mirrors the Python-relevant sections of that root README; the root
+README remains authoritative for the repository as a whole (protocol reference, Arduino driver,
+wiring notes).
+
+Installable package name: **`erdilrf-lrf`** · import name: **`erdilrf_lrf`** · CLI: **`erdilrf`**.
+Note that the package name differs from the import name and from the CLI name — see
+[`pyproject.toml`](pyproject.toml) for the single source of truth.
+
+Part of [erdilrf/erdilrf-drivers](https://github.com/erdilrf/erdilrf-drivers) · MIT ·
+modules documented at [erdilrf.com](https://erdilrf.com)

erdilrf_lrf-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "erdilrf-lrf"
+version = "0.2.0"
+description = "Host-side UART driver for ERDI 905 nm laser rangefinder modules (LR1000E2 protocol family)"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+  "laser-rangefinder", "lidar", "dtof", "905nm", "uart",
+  "embedded", "robotics", "drone", "industrial-automation",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Manufacturing",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator",
+  "Topic :: System :: Hardware :: Hardware Drivers",
+]
+
+# Core framing and decoding are pure standard library on purpose: this code is meant to be
+# readable and testable on any machine, including one with no hardware attached.
+dependencies = []
+
+[project.optional-dependencies]
+serial = ["pyserial>=3.5"]
+dev = ["pytest>=7"]
+
+[project.scripts]
+erdilrf = "erdilrf_lrf.cli:main"
+
+[project.urls]
+Homepage = "https://erdilrf.com"
+Repository = "https://github.com/erdilrf/erdilrf-drivers"
+Documentation = "https://github.com/erdilrf/erdilrf-drivers/blob/main/protocol/PROTOCOL.md"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

erdilrf_lrf-0.2.0/setup.cfg

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

erdilrf_lrf-0.2.0/src/erdilrf_lrf/__init__.py

@@ -0,0 +1,63 @@
+"""
+erdilrf_lrf — host-side driver for ERDI 905 nm laser rangefinder modules.
+
+Framing and protocol: [`frames`][erdilrf_lrf.frames].
+High-level device access: [`device`][erdilrf_lrf.device].
+
+The protocol implemented here is documented in `protocol/PROTOCOL.md` and was derived from
+the manufacturer's LR1000E2 user manual v1.2, with every published frame recomputed from the
+stated checksum rule before release.
+"""
+
+from __future__ import annotations
+
+from .frames import (
+    BAUD_BY_CODE,
+    BAUD_CODES,
+    CMD_ANGLE,
+    CMD_CONTINUOUS,
+    CMD_LD_OFF,
+    CMD_LD_ON,
+    CMD_SINGLE_SHOT,
+    CMD_STOP,
+    FRAME_LEN,
+    Frame,
+    FrameReader,
+    ProtocolError,
+    build_command,
+    checksum_response,
+    checksum_send,
+    decode_angle,
+    decode_distance,
+    decode_distance_or_none,
+    parse_frame,
+    set_baud_command,
+    summarise,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BAUD_BY_CODE",
+    "BAUD_CODES",
+    "CMD_ANGLE",
+    "CMD_CONTINUOUS",
+    "CMD_LD_OFF",
+    "CMD_LD_ON",
+    "CMD_SINGLE_SHOT",
+    "CMD_STOP",
+    "FRAME_LEN",
+    "Frame",
+    "FrameReader",
+    "ProtocolError",
+    "build_command",
+    "checksum_response",
+    "checksum_send",
+    "decode_angle",
+    "decode_distance",
+    "decode_distance_or_none",
+    "parse_frame",
+    "set_baud_command",
+    "summarise",
+    "__version__",
+]

erdilrf_lrf-0.2.0/src/erdilrf_lrf/cli.py

@@ -0,0 +1,216 @@
+"""
+erdilrf_lrf.cli — command-line access to an ERDI 905 nm rangefinder module.
+
+Two of these commands need no hardware at all, which is deliberate:
+
+    erdilrf frames            print the documented command table
+    erdilrf decode <hex>      decode one captured frame
+
+Support engineers spend a lot of time asking customers "paste me the bytes you saw". `decode`
+answers that without a module, a driver install, or a working serial port.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from . import __version__
+from . import frames as F
+from .device import DeviceTimeout, Rangefinder, SerialTransport
+
+
+def _hex(b: bytes) -> str:
+    return b.hex(" ").upper()
+
+
+# ---------------------------------------------------------------- offline commands
+
+
+def cmd_frames(_args: argparse.Namespace) -> int:
+    rows = [
+        ("single-shot ranging", F.CMD_SINGLE_SHOT, "55 AA 88 STA FF DIS_H DIS_L SUM"),
+        ("continuous ranging", F.CMD_CONTINUOUS, "55 AA 89 STA FF DIS_H DIS_L SUM"),
+        ("stop ranging", F.CMD_STOP, "55 AA 8E STA FF FF FF SUM"),
+        ("angle measurement", F.CMD_ANGLE, "55 AA 8A STA FF ANG_H ANG_L SUM"),
+        ("LD constant-on: enable", F.CMD_LD_ON, "(response frame not published)"),
+        ("LD constant-on: disable", F.CMD_LD_OFF, "(response frame not published)"),
+    ]
+    print(f"ERDI 905 nm rangefinder protocol - erdilrf-lrf {__version__}\n")
+    print(f"{'command':26s} {'transmit (8 bytes)':26s} response")
+    print("-" * 92)
+    for name, tx, rx in rows:
+        print(f"{name:26s} {_hex(tx):26s} {rx}")
+    print()
+    print("checksum, host -> module : (FUNC + D1 + D2 + D3 + D4) & 0xFF")
+    print("checksum, module -> host : (55 + AA + FUNC + D1 + D2 + D3 + D4) & 0xFF")
+    print("distance                 : ((DIS_H << 8) | DIS_L) / 10 metres")
+    print()
+    print("set baud rate            : 55 AA TYPE FF FF FF FF SUM")
+    print("  " + "  ".join(f"{c:02X}={b}" for b, c in sorted(F.BAUD_CODES.items(), key=lambda kv: kv[1])))
+    return 0
+
+
+def cmd_decode(args: argparse.Namespace) -> int:
+    text = " ".join(args.hex).replace(",", " ").replace("0x", " ").replace("0X", " ")
+    try:
+        data = bytes(int(tok, 16) for tok in text.split())
+    except ValueError as exc:
+        print(f"error: could not read hex bytes: {exc}", file=sys.stderr)
+        return 2
+    direction = args.direction
+    try:
+        frame = F.parse_frame(data, direction=direction, verify_checksum=not args.no_checksum)
+    except F.ProtocolError as exc:
+        print(f"INVALID: {exc}", file=sys.stderr)
+        if len(data) == F.FRAME_LEN and not args.no_checksum:
+            alt = "command" if direction == "response" else "response"
+            try:
+                F.parse_frame(data, direction=alt)
+            except F.ProtocolError:
+                pass
+            else:
+                print(f"hint: this frame is valid as a {alt} frame. "
+                      f"Re-run with --direction {alt}.", file=sys.stderr)
+        return 1
+
+    s = F.summarise(frame)
+    print(f"raw        : {_hex(frame.raw)}")
+    print(f"direction  : {frame.direction}")
+    print(f"func       : 0x{frame.func:02X}  ({s.name})")
+    print(f"D1..D4     : {frame.d1:02X} {frame.d2:02X} {frame.d3:02X} {frame.d4:02X}")
+    print(f"checksum   : 0x{frame.checksum:02X}  (recomputed 0x{frame.expected_checksum:02X}) "
+          f"{'OK' if frame.checksum_ok else 'MISMATCH'}")
+    print(f"STA        : 0x{s.sta:02X}  {s.sta_meaning}")
+    if s.detail:
+        print(f"detail     : {s.detail}")
+    if frame.is_self_test and frame.sta != F.STA_SUCCESS:
+        print(f"error code : 0x{frame.error_code:02X}")
+    return 0
+
+
+# ---------------------------------------------------------------- hardware commands
+
+
+def _open(args: argparse.Namespace) -> Rangefinder:
+    return Rangefinder(SerialTransport(args.port, args.baud, parity=args.parity,
+                                       stopbits=args.stopbits),
+                       timeout=args.timeout)
+
+
+def cmd_ports(_args: argparse.Namespace) -> int:
+    ports = SerialTransport.list_ports()
+    if not ports:
+        print("no serial ports found (or pyserial is not installed: pip install pyserial)")
+        return 1
+    for p in ports:
+        print(p)
+    return 0
+
+
+def cmd_measure(args: argparse.Namespace) -> int:
+    with _open(args) as rf:
+        for i in range(args.count):
+            try:
+                d = rf.single_shot()
+            except DeviceTimeout as exc:
+                print(f"error: {exc}", file=sys.stderr)
+                return 1
+            print("no return (shot failed)" if d is None else f"{d:.1f} m")
+            if i + 1 < args.count:
+                import time
+                time.sleep(args.interval)
+    return 0
+
+
+def cmd_stream(args: argparse.Namespace) -> int:
+    with _open(args) as rf:
+        try:
+            for d in rf.stream(count=args.count):
+                print("--" if d is None else f"{d:.1f} m")
+        except (DeviceTimeout, KeyboardInterrupt):
+            print("\nstopped")
+    return 0
+
+
+def cmd_selftest(args: argparse.Namespace) -> int:
+    """
+    Read the unsolicited power-on self-test.
+
+    It is emitted once, at power-on, so this is only meaningful on a freshly powered module. If it
+    returns nothing, power-cycle the module and run this again — that is the documented cause, not
+    a defect in the tool.
+    """
+    with _open(args) as rf:
+        frame = rf.read_self_test()
+        if frame is None:
+            print("no self-test frame seen. It is sent once at power-on: "
+                  "power-cycle the module and retry immediately.", file=sys.stderr)
+            return 1
+        s = F.summarise(frame)
+        print(f"{s.name}: {s.sta_meaning} {s.detail}".rstrip())
+        return 0 if frame.sta == F.STA_SUCCESS else 1
+
+
+# ---------------------------------------------------------------- wiring
+
+
+def _add_serial_opts(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--port", required=True, help="serial port, e.g. COM3 or /dev/ttyUSB0")
+    p.add_argument("--baud", type=int, default=115200)
+    p.add_argument("--parity", default="N", choices=["N", "E", "O"],
+                   help="the manual does not state parity; 8N1 is an assumption")
+    p.add_argument("--stopbits", type=float, default=1, choices=[1, 1.5, 2])
+    p.add_argument("--timeout", type=float, default=1.0)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="erdilrf",
+        description="Host driver for ERDI 905 nm laser rangefinder modules.")
+    ap.add_argument("--version", action="version", version=f"erdilrf-lrf {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("frames", help="print the documented command table (no hardware)") \
+        .set_defaults(func=cmd_frames)
+
+    d = sub.add_parser("decode", help="decode captured hex bytes (no hardware)")
+    d.add_argument("hex", nargs="+", help="8 hex bytes, e.g. '55 AA 88 01 FF 00 64 8A'")
+    d.add_argument("--direction", default="response", choices=list(F.DIRECTIONS))
+    d.add_argument("--no-checksum", action="store_true", help="decode even if the checksum is bad")
+    d.set_defaults(func=cmd_decode)
+
+    sub.add_parser("ports", help="list serial ports").set_defaults(func=cmd_ports)
+
+    m = sub.add_parser("measure", help="trigger single-shot measurements")
+    _add_serial_opts(m)
+    m.add_argument("--count", type=int, default=1)
+    m.add_argument("--interval", type=float, default=0.3)
+    m.set_defaults(func=cmd_measure)
+
+    s = sub.add_parser("stream", help="continuous ranging until stopped")
+    _add_serial_opts(s)
+    s.add_argument("--count", type=int, default=None)
+    s.set_defaults(func=cmd_stream)
+
+    t = sub.add_parser("selftest", help="read the power-on self-test frame")
+    _add_serial_opts(t)
+    t.set_defaults(func=cmd_selftest)
+
+    return ap
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except ImportError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())