erdilrf-lrf 0.2.0__py3-none-any.whl

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/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())

erdilrf_lrf/device.py

@@ -0,0 +1,274 @@
+"""
+erdilrf_lrf.device — high-level host access to an ERDI 905 nm rangefinder module.
+
+The module deliberately depends on nothing but the standard library. Serial I/O is injected as a
+small duck-typed transport, which means:
+
+* the whole device layer is testable without hardware (see `tests/test_device.py`);
+* you can bring your own link — pyserial, a socket, an MCU bridge, a recorded capture.
+
+`SerialTransport` is provided for the common case and imports pyserial lazily, so importing this
+module never requires it.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from typing import Iterable, Protocol, runtime_checkable
+
+from . import frames as F
+
+__all__ = ["Transport", "SerialTransport", "Rangefinder", "DeviceTimeout"]
+
+
+class DeviceTimeout(TimeoutError):
+    """No matching frame arrived within the timeout."""
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Minimal link the driver needs. Implement these two methods and nothing else."""
+
+    def write(self, data: bytes) -> int:
+        """Send bytes to the module. Return the number accepted."""
+
+    def read(self, size: int) -> bytes:
+        """Return up to `size` bytes, blocking only as long as your own timeout allows."""
+
+
+class SerialTransport:
+    """
+    pyserial-backed transport.
+
+    Defaults are 115200 8N1 — the manual documents 115200 and 8 data bits but is silent on parity
+    and stop bits, so 8N1 is an assumption recorded in PROTOCOL.md, not a documented fact. If a
+    module stays silent, try `parity="E"` or `parity="O"` before assuming a wiring fault.
+    """
+
+    def __init__(self, port: str, baudrate: int = 115200, *, parity: str = "N",
+                 stopbits: float = 1, read_timeout: float = 0.2) -> None:
+        try:
+            import serial  # type: ignore
+        except ImportError as exc:  # pragma: no cover - depends on environment
+            raise ImportError(
+                "pyserial is required to open a serial port. "
+                "Install it with:  pip install pyserial"
+            ) from exc
+        self._serial_mod = serial
+        self.port = port
+        self.baudrate = baudrate
+        self._ser = serial.Serial(
+            port=port, baudrate=baudrate, bytesize=serial.EIGHTBITS,
+            parity={"N": serial.PARITY_NONE, "E": serial.PARITY_EVEN,
+                    "O": serial.PARITY_ODD}[parity.upper()],
+            stopbits={1: serial.STOPBITS_ONE, 1.5: serial.STOPBITS_ONE_POINT_FIVE,
+                      2: serial.STOPBITS_TWO}[float(stopbits)],
+            timeout=read_timeout,
+        )
+
+    def write(self, data: bytes) -> int:
+        return self._ser.write(data)
+
+    def read(self, size: int) -> bytes:
+        return self._ser.read(size)
+
+    def close(self) -> None:
+        try:
+            self._ser.close()
+        except Exception:  # noqa: BLE001 - closing must never mask the real error
+            pass
+
+    def __enter__(self) -> "SerialTransport":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    @staticmethod
+    def list_ports() -> list[str]:
+        try:
+            from serial.tools import list_ports  # type: ignore
+        except ImportError:
+            return []
+        return [p.device for p in list_ports.comports()]
+
+
+class Rangefinder:
+    """
+    Blocking, single-threaded host driver.
+
+    Every call reads from the transport until it sees the frame it is waiting for or the deadline
+    passes. Unrelated and self-test frames are recorded in `self.unsolicited` rather than
+    discarded, because on a real module the power-on self-test arrives when it feels like it and
+    swallowing it hides real faults.
+    """
+
+    def __init__(self, transport: Transport, *, timeout: float = 1.0, chunk: int = 64) -> None:
+        self.transport = transport
+        self.timeout = timeout
+        self.chunk = chunk
+        self.reader = F.FrameReader()
+        self.unsolicited: list[F.Frame] = []
+        self.self_test: F.Frame | None = None
+        # Frames already parsed but not yet consumed. This queue is why the driver cannot lose a
+        # response: an earlier draft flushed by *consuming* a frame and discarding the rest of the
+        # parsed batch, which silently ate the answer to the very command it had just sent.
+        self._pending: deque[F.Frame] = deque()
+
+    # ---------------------------------------------------------------- plumbing
+
+    def _fill(self, deadline: float) -> None:
+        """Block until at least one frame is pending, or the deadline passes."""
+        while not self._pending:
+            chunk = self.transport.read(self.chunk)
+            if chunk:
+                self._pending.extend(self.reader.feed(chunk))
+            if self._pending:
+                return
+            if time.monotonic() >= deadline:
+                return
+
+    def _flush(self) -> list[F.Frame]:
+        """
+        Drop everything already sitting in the link *before* a command is sent.
+
+        On a real port a previous command's answer, or a burst of unrelated frames, can still be
+        buffered. Accepting one of those as the answer to the next command yields a wrong distance
+        with no error — the worst outcome this driver can produce. So they are discarded, and
+        recorded in the returned list for anyone who wants to see them.
+        """
+        dropped: list[F.Frame] = list(self._pending)
+        self._pending.clear()
+        while True:
+            chunk = self.transport.read(self.chunk)
+            if not chunk:
+                break
+            dropped.extend(self.reader.feed(chunk))
+        return dropped
+
+    def _pump(self, deadline: float, want: Iterable[int] | None) -> F.Frame | None:
+        wanted = set(want) if want is not None else None
+        while True:
+            self._fill(deadline)
+            if not self._pending:
+                return None
+            f = self._pending.popleft()
+            if f.is_self_test:
+                self.self_test = f
+                if wanted is None or F.FUNC_SELF_TEST in wanted:
+                    return f
+                self.unsolicited.append(f)
+                continue
+            if wanted is None or f.func in wanted:
+                return f
+            # a frame for some other command: keep it visible, do not return it
+            self.unsolicited.append(f)
+            if time.monotonic() >= deadline:
+                return None
+
+    def _exchange(self, command: bytes, expect: Iterable[int], timeout: float | None = None) -> F.Frame:
+        budget = self.timeout if timeout is None else timeout
+        self._flush()
+        self.transport.write(command)
+        frame = self._pump(time.monotonic() + budget, expect)
+        if frame is None:
+            raise DeviceTimeout(
+                f"no response to {command.hex(' ').upper()} within {budget}s "
+                f"(wanted func {[hex(x) for x in expect]})")
+        return frame
+
+    # ---------------------------------------------------------------- measurements
+
+    def single_shot(self) -> float | None:
+        """
+        Trigger one measurement and return metres.
+
+        Returns None when the module answers but reports a failed measurement (STA != 1), which is
+        a normal outcome against a poor target. Raises DeviceTimeout when it does not answer at all.
+        """
+        frame = self._exchange(F.CMD_SINGLE_SHOT, (F.FUNC_SINGLE_SHOT,))
+        return F.decode_distance_or_none(frame)
+
+    def start_continuous(self) -> None:
+        self.transport.write(F.CMD_CONTINUOUS)
+
+    def stop_continuous(self, *, timeout: float | None = None) -> bool:
+        frame = self._exchange(F.CMD_STOP, (F.FUNC_STOP,), timeout)
+        return frame.sta == F.STA_SUCCESS
+
+    def stream(self, count: int | None = None, *, settle: float = 0.05) -> Iterable[float | None]:
+        """
+        Start continuous ranging and yield distances in metres.
+
+        Yields `count` samples (or forever when count is None). Stops continuous mode on exit.
+        Frames arriving before the first valid range are yielded as None rather than dropped, so a
+        caller can see how long the module took to lock on.
+        """
+        self.start_continuous()
+        time.sleep(settle)
+        produced = 0
+        try:
+            while count is None or produced < count:
+                frame = self._pump(time.monotonic() + self.timeout, (F.FUNC_CONTINUOUS,))
+                if frame is None:
+                    raise DeviceTimeout("continuous ranging went quiet")
+                yield F.decode_distance_or_none(frame)
+                produced += 1
+        finally:
+            try:
+                self.stop_continuous(timeout=0.5)
+            except (DeviceTimeout, F.ProtocolError):
+                pass
+
+    def angle(self) -> float | None:
+        """
+        Angle in degrees. Only available on modules fitted with an angle sensor — the manual says so
+        explicitly. On a rangefinder-only module expect a timeout, not a wrong number.
+        """
+        frame = self._exchange(F.CMD_ANGLE, (F.FUNC_ANGLE,))
+        if frame.sta != F.STA_SUCCESS:
+            return None
+        return F.decode_angle(frame)
+
+    def read_self_test(self, timeout: float | None = None) -> F.Frame | None:
+        """
+        Wait for the unsolicited power-on self-test frame.
+
+        Best called immediately after opening the port, *before* anything else: the frame is emitted
+        once at power-on, so if you have already sent other commands you have probably missed it and
+        will get None. That is not a fault.
+        """
+        return self._pump(time.monotonic() + (self.timeout if timeout is None else timeout),
+                          (F.FUNC_SELF_TEST,))
+
+    # ---------------------------------------------------------------- configuration
+
+    def set_baud(self, baud: int, *, timeout: float | None = None) -> bool:
+        """
+        Request a new baud rate. Returns True when the module accepted it.
+
+        The change takes effect only after the module is restarted. This method does **not**
+        reconfigure the transport — do that yourself after the restart, otherwise the accepted
+        setting and the open port will disagree.
+        """
+        frame = self._exchange(F.set_baud_command(baud), (F.BAUD_CODES[baud],), timeout)
+        return frame.sta == F.STA_SUCCESS
+
+    def ld_constant_on(self, enable: bool) -> None:
+        """
+        Turn the laser diode constant-on mode on or off.
+
+        Fire-and-forget: the manual's response row for this command is incomplete (it prints only
+        `55`), so this library does not invent a frame layout to validate against. See
+        PROTOCOL.md section 3.6. The manufacturer warns against leaving it enabled for long periods.
+        """
+        self.transport.write(F.CMD_LD_ON if enable else F.CMD_LD_OFF)
+
+    def __enter__(self) -> "Rangefinder":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        close = getattr(self.transport, "close", None)
+        if callable(close):
+            close()

erdilrf_lrf/frames.py

@@ -0,0 +1,340 @@
+"""
+erdilrf_lrf.frames — ERDI 905 nm laser rangefinder UART framing.
+
+Pure standard library. No serial dependency, so this module is testable anywhere.
+
+Frame layout (8 bytes, fixed):
+
+    offset   0     1     2      3    4    5    6      7
+            0x55  0xAA  FUNC   D1   D2   D3   D4    SUM
+
+Checksum — and this is the part people get wrong:
+
+    host -> module   SUM = (FUNC + D1 + D2 + D3 + D4) & 0xFF
+    module -> host   SUM = (0x55 + 0xAA + FUNC + D1 + D2 + D3 + D4) & 0xFF
+
+The two directions use different ranges. The manufacturer's manual states this in its own
+notes; this module encodes it as two separate functions so it cannot be confused.
+
+Source: LR1000E2 User Manual v1.2 (2025.10, ERDI TECH LTD) section 8.
+See protocol/PROTOCOL.md for the full reference and protocol/verification.md for the
+checksum arithmetic re-derived independently of the manual's printed values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NamedTuple
+
+HEADER_H = 0x55
+HEADER_L = 0xAA
+FRAME_LEN = 8
+PAD = 0xFF
+
+# ---------------------------------------------------------------- function codes
+
+FUNC_SELF_TEST = 0x80          # module -> host, unsolicited, at power-on
+FUNC_LD_CONSTANT_ON = 0x86     # host -> module, D4 selects enable/disable
+FUNC_SINGLE_SHOT = 0x88
+FUNC_CONTINUOUS = 0x89
+FUNC_ANGLE = 0x8A
+FUNC_STOP = 0x8E
+# NOTE: set-baud has no separate function code. The manual's `TYPE` selector occupies the
+# FUNCTION position itself (frame is `55 AA TYPE FF FF FF FF SUM`), so its "func" byte is
+# one of BAUD_BY_CODE's keys. Do not invent a distinct constant for it.
+
+#: Baud-rate selector codes, from the manual's TYPE table.
+BAUD_CODES: dict[int, int] = {
+    9600: 0x01,
+    14400: 0x02,
+    19200: 0x03,
+    38400: 0x04,
+    56000: 0x05,
+    57600: 0x06,
+    115200: 0x07,
+    128000: 0x08,
+    230400: 0x09,
+}
+BAUD_BY_CODE: dict[int, int] = {v: k for k, v in BAUD_CODES.items()}
+
+#: LD constant-on selector (goes in D4).
+LD_ON = 0x01
+LD_OFF = 0x00
+
+#: STA values are per-command, not global. See PROTOCOL.md section 6.
+STA_SUCCESS = 0x01
+STA_FAILURE = 0x00
+
+
+class ProtocolError(ValueError):
+    """Raised when bytes cannot be interpreted as a valid ERDI frame."""
+
+
+# ---------------------------------------------------------------- checksums
+
+
+def checksum_send(func: int, d1: int = PAD, d2: int = PAD, d3: int = PAD, d4: int = PAD) -> int:
+    """Checksum for a host -> module frame: low byte of FUNC + D1 + D2 + D3 + D4."""
+    return (func + d1 + d2 + d3 + d4) & 0xFF
+
+
+def checksum_response(frame: bytes) -> int:
+    """
+    Checksum for a module -> host frame: low byte of
+    HEADER_H + HEADER_L + FUNC + D1 + D2 + D3 + D4.
+
+    Accepts the first 7 bytes, or a full 8-byte frame (byte 7 is ignored).
+    """
+    if len(frame) < 7:
+        raise ProtocolError(f"need at least 7 bytes to checksum a response, got {len(frame)}")
+    return sum(frame[:7]) & 0xFF
+
+
+# ---------------------------------------------------------------- building
+
+
+def build_command(func: int, d1: int = PAD, d2: int = PAD, d3: int = PAD, d4: int = PAD) -> bytes:
+    """Build an 8-byte host -> module frame with the correct send-side checksum."""
+    for name, val in (("func", func), ("d1", d1), ("d2", d2), ("d3", d3), ("d4", d4)):
+        if not 0 <= val <= 0xFF:
+            raise ProtocolError(f"{name}=0x{val:X} does not fit in one byte")
+    return bytes([HEADER_H, HEADER_L, func, d1, d2, d3, d4,
+                  checksum_send(func, d1, d2, d3, d4)])
+
+
+# ---------------------------------------------------------------- the command set
+
+CMD_SINGLE_SHOT = build_command(FUNC_SINGLE_SHOT)   # 55 AA 88 FF FF FF FF 84
+CMD_CONTINUOUS = build_command(FUNC_CONTINUOUS)     # 55 AA 89 FF FF FF FF 85
+CMD_STOP = build_command(FUNC_STOP)                 # 55 AA 8E FF FF FF FF 8A
+CMD_ANGLE = build_command(FUNC_ANGLE)               # 55 AA 8A FF FF FF FF 86
+CMD_LD_ON = build_command(FUNC_LD_CONSTANT_ON, PAD, PAD, PAD, LD_ON)    # ... FF FF FF 01 84
+CMD_LD_OFF = build_command(FUNC_LD_CONSTANT_ON, PAD, PAD, PAD, LD_OFF)  # ... FF FF FF 00 83
+
+
+def set_baud_command(baud: int) -> bytes:
+    """
+    Build the set-baud frame. The selector is carried in D1 (the manual calls this field TYPE).
+
+    Reminder: the new rate applies only after the module is restarted.
+    """
+    if baud not in BAUD_CODES:
+        raise ProtocolError(
+            f"unsupported baud {baud}; supported: {sorted(BAUD_CODES)}")
+    return build_command(BAUD_CODES[baud])
+
+
+# ---------------------------------------------------------------- parsing
+
+
+class Frame(NamedTuple):
+    func: int
+    d1: int
+    d2: int
+    d3: int
+    d4: int
+    checksum: int
+    raw: bytes
+    #: which checksum rule this frame is subject to: "response" (module -> host) or
+    #: "command" (host -> module). The two rules genuinely differ, so a frame that does not
+    #: record its direction cannot be validated. This field exists because omitting it was a
+    #: real bug: FrameReader validated TX frames with the RX rule and rejected every one.
+    direction: str = "response"
+
+    @property
+    def expected_checksum(self) -> int:
+        if self.direction == "command":
+            return checksum_send(self.func, self.d1, self.d2, self.d3, self.d4)
+        return checksum_response(self.raw)
+
+    @property
+    def checksum_ok(self) -> bool:
+        return self.checksum == self.expected_checksum
+
+    @property
+    def sta(self) -> int:
+        return self.d1
+
+    @property
+    def is_self_test(self) -> bool:
+        return self.func == FUNC_SELF_TEST
+
+    @property
+    def error_code(self) -> int | None:
+        """Self-test error code, present in D4 of a `55 AA 80` frame."""
+        return self.d4 if self.is_self_test else None
+
+
+DIRECTIONS = ("response", "command")
+
+
+def parse_frame(data: bytes, *, direction: str = "response", verify_checksum: bool = True) -> Frame:
+    """
+    Parse exactly 8 bytes into a Frame.
+
+    `direction` selects the checksum rule: "response" for module -> host frames (the default,
+    matching what a host reads from the port) or "command" for host -> module frames.
+
+    Raises ProtocolError on wrong length, wrong header, or (unless disabled) a bad checksum.
+    """
+    if direction not in DIRECTIONS:
+        raise ProtocolError(f"direction must be one of {DIRECTIONS}, got {direction!r}")
+    if len(data) != FRAME_LEN:
+        raise ProtocolError(f"expected {FRAME_LEN} bytes, got {len(data)}: {data.hex(' ')}")
+    if data[0] != HEADER_H or data[1] != HEADER_L:
+        raise ProtocolError(f"bad header {data[0]:02X} {data[1]:02X}, expected 55 AA")
+    f = Frame(data[2], data[3], data[4], data[5], data[6], data[7], bytes(data), direction)
+    if verify_checksum and not f.checksum_ok:
+        raise ProtocolError(
+            f"checksum mismatch: frame says 0x{f.checksum:02X}, "
+            f"{'SUM[3:7]' if direction == 'command' else 'SUM[1:7]'} sums to "
+            f"0x{f.expected_checksum:02X}")
+    return f
+
+
+class FrameReader:
+    """
+    Byte-stream reassembler.
+
+    Feed it arbitrary chunks from a serial port; it yields complete, checksum-valid Frame
+    objects. Resynchronises on the 55 AA header, so a truncated or corrupted frame costs at
+    most one frame and never poisons the stream.
+
+    Use the default `direction="response"` for bytes read from the module. Switch to
+    "command" only when replaying frames you transmitted.
+    """
+
+    def __init__(self, *, direction: str = "response", verify_checksum: bool = True,
+                 collect_errors: bool = True) -> None:
+        if direction not in DIRECTIONS:
+            raise ProtocolError(f"direction must be one of {DIRECTIONS}, got {direction!r}")
+        self._buf = bytearray()
+        self._direction = direction
+        self._verify = verify_checksum
+        self._collect_errors = collect_errors
+        self.errors: list[str] = []
+
+    def feed(self, chunk: bytes) -> list[Frame]:
+        if chunk:
+            self._buf.extend(chunk)
+        return list(self._drain())
+
+    def _drain(self):
+        while True:
+            # drop leading bytes until the header aligns
+            i = self._buf.find(bytes([HEADER_H, HEADER_L]))
+            if i < 0:
+                # keep only a possible half-header at the tail
+                if self._buf[-1:] == bytes([HEADER_H]):
+                    del self._buf[:-1]
+                else:
+                    self._buf.clear()
+                return
+            if i:
+                if self._collect_errors:
+                    self.errors.append(f"discarded {i} non-header byte(s): {bytes(self._buf[:i]).hex(' ')}")
+                del self._buf[:i]
+            if len(self._buf) < FRAME_LEN:
+                return
+            candidate = bytes(self._buf[:FRAME_LEN])
+            try:
+                yield parse_frame(candidate, direction=self._direction,
+                                  verify_checksum=self._verify)
+            except ProtocolError as exc:
+                if self._collect_errors:
+                    self.errors.append(str(exc))
+                # a bad frame can still hide the real header one byte in; step forward by 1
+                del self._buf[:1]
+                continue
+            del self._buf[:FRAME_LEN]
+
+
+# ---------------------------------------------------------------- decoding
+
+
+def decode_distance(frame: Frame) -> float:
+    """
+    Measured distance in **metres**.
+
+    The manual states: reported value = measured value x 10, so the 16-bit register holds
+    tenths of a metre. DIS_H is D3, DIS_L is D4.
+    """
+    if frame.d2 != PAD:
+        raise ProtocolError(
+            f"expected 0xFF in D2 of a ranging response, got 0x{frame.d2:02X}")
+    if frame.sta != STA_SUCCESS:
+        raise ProtocolError(f"measurement failed (STA=0x{frame.sta:02X})")
+    raw = (frame.d3 << 8) | frame.d4
+    return raw / 10.0
+
+
+def decode_angle(frame: Frame) -> float:
+    """Measured angle in degrees, same x10 scaling. Only on modules with an angle sensor."""
+    if frame.sta != STA_SUCCESS:
+        raise ProtocolError(f"angle measurement failed (STA=0x{frame.sta:02X})")
+    raw = (frame.d3 << 8) | frame.d4
+    return raw / 10.0
+
+
+def decode_distance_or_none(frame: Frame) -> float | None:
+    """Convenience for polling loops: metres, or None when STA reports a failed measurement."""
+    try:
+        return decode_distance(frame)
+    except ProtocolError:
+        return None
+
+
+# ---------------------------------------------------------------- human-readable helpers
+
+
+@dataclass(frozen=True)
+class FrameSummary:
+    func: int
+    name: str
+    sta: int
+    sta_meaning: str
+    detail: str
+
+
+_NAMES = {
+    FUNC_SELF_TEST: "power-on self-test",
+    FUNC_LD_CONSTANT_ON: "LD constant-on mode",
+    FUNC_SINGLE_SHOT: "single-shot ranging",
+    FUNC_CONTINUOUS: "continuous ranging",
+    FUNC_ANGLE: "angle measurement",
+    FUNC_STOP: "stop ranging",
+}
+
+
+def summarise(frame: Frame) -> FrameSummary:
+    name = _NAMES.get(frame.func, f"unknown function 0x{frame.func:02X}")
+    sta, meaning, detail = frame.sta, "", ""
+
+    if frame.direction == "command":
+        # A transmitted frame's D1 is a parameter, not a status byte. Reporting "measurement
+        # failed" here would invent a fault out of a field that has no such meaning.
+        return FrameSummary(frame.func, name, sta,
+                            "n/a (transmitted frame — D1 is a parameter, not STA)", "")
+
+    if frame.func in BAUD_BY_CODE:
+        name = f"set baud to {BAUD_BY_CODE[frame.func]} bps"
+        meaning = "setting successful" if sta == STA_SUCCESS else "setting failed"
+        detail = "takes effect after restart"
+    elif frame.func in (FUNC_SINGLE_SHOT, FUNC_CONTINUOUS):
+        meaning = "measurement successful" if sta == STA_SUCCESS else "measurement failed"
+        if sta == STA_SUCCESS:
+            detail = f"{(frame.d3 << 8 | frame.d4) / 10.0:.1f} m"
+    elif frame.func == FUNC_STOP:
+        meaning = "stopped" if sta == STA_SUCCESS else "failed to stop"
+    elif frame.func == FUNC_ANGLE:
+        meaning = "measurement successful" if sta == STA_SUCCESS else "measurement failed"
+        if sta == STA_SUCCESS:
+            detail = f"{(frame.d3 << 8 | frame.d4) / 10.0:.1f} deg"
+    elif frame.func == FUNC_SELF_TEST:
+        meaning = "init succeeded" if sta == STA_SUCCESS else "init FAILED"
+        if sta != STA_SUCCESS:
+            detail = f"ErrCode=0x{frame.d4:02X}"
+    else:
+        meaning = "n/a"
+
+    return FrameSummary(frame.func, name, sta, meaning, detail)

erdilrf_lrf-0.2.0.dist-info/METADATA

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

@@ -0,0 +1,10 @@
+erdilrf_lrf/__init__.py,sha256=Z7lbPjr9ZeVRNwsCetW1_aflgQnzLzQxZqQa0-01HMA,1402
+erdilrf_lrf/cli.py,sha256=sryxrtVVVCIVgAGvhpGXA_n2pUK3Ms6fqrZiPIZxHEI,8249
+erdilrf_lrf/device.py,sha256=jjoFy0EiNfH-opCgWNtnhRLLlgV3jI7gYHWc3J7YHHw,11037
+erdilrf_lrf/frames.py,sha256=PYzSbF06rQJnCT-LpMTvghc7O7YDxV40LtcGrJqWFH8,12513
+erdilrf_lrf-0.2.0.dist-info/licenses/LICENSE,sha256=-FIBvvm0m06snuARfXI8GKBfblyjFcpnf9Uw3fkg16A,1064
+erdilrf_lrf-0.2.0.dist-info/METADATA,sha256=yU25yzTHsgVtW3E-gpFMjutINJFtjO4gkzBDdESygGA,6587
+erdilrf_lrf-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+erdilrf_lrf-0.2.0.dist-info/entry_points.txt,sha256=BVUC2zEsTORISCInQ9hIvrdzHNxmA1aN1EaIu6ilWcA,49
+erdilrf_lrf-0.2.0.dist-info/top_level.txt,sha256=pjWQrigX0HrBNc0wc6JMekl7x3k6nVi2Ksjul-hW9hg,12
+erdilrf_lrf-0.2.0.dist-info/RECORD,,

erdilrf_lrf-0.2.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
+

erdilrf_lrf-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+erdilrf = erdilrf_lrf.cli:main

erdilrf_lrf-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+erdilrf_lrf