radeye-b20 0.1.0__tar.gz

radeye_b20-0.1.0/LICENSE

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

radeye_b20-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: radeye-b20
+Version: 0.1.0
+Summary: Python driver for the Thermo Scientific RadEye B20 radiation survey meter (reverse-engineered serial protocol).
+Author: Navya Sharma
+License: MIT
+Project-URL: Homepage, https://github.com/navyasharmabits/radeye-b20
+Keywords: radeye,radiation,survey-meter,serial,geiger,dosimetry,instrument-driver
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.4
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# radeye-b20
+
+A small Python driver for the **Thermo Scientific RadEye B20** handheld
+radiation survey meter.
+
+The RadEye B20 streams live readings over its infrared read-head, but the serial
+protocol is undocumented and — as far as I can tell — no public library speaks
+it. This one does. It was **reverse-engineered** by watching the wire and
+checking decoded values against the meter's own display, so it's honest about
+what it can and can't do (see [Limitations](#limitations)).
+
+```python
+from radeye_b20 import RadEye
+
+with RadEye() as meter:            # auto-detects the IR-USB cable
+    for reading in meter.stream():
+        print(reading.value, reading.unit)   # e.g. 3.51 cps
+```
+
+## Install
+
+```bash
+pip install radeye-b20
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/navyasharmabits/radeye-b20
+cd radeye-b20
+pip install -e .
+```
+
+Requires Python 3.8+ and `pyserial`. Works on Linux, macOS, and Windows (the
+meter appears as a normal USB serial port).
+
+## Command line
+
+```bash
+radeye ports                 # list serial ports, flag the likely RadEye
+radeye stream                # live readings until Ctrl+C
+radeye stream --csv          # timestamp,value,unit  (pipe to a file)
+radeye stream --port /dev/ttyUSB0 --scale-cps 0.01
+```
+
+## Library
+
+```python
+from radeye_b20 import RadEye, find_port
+
+print(find_port())                       # '/dev/ttyUSB0' or None
+
+with RadEye(port="auto", scale_cps=0.01, scale_cpm=0.1) as meter:
+    r = meter.read()                     # one reading, or None on a skipped frame
+    if r:
+        print(r.value, r.unit, r.timestamp, r.checksum)
+```
+
+Each `Reading` carries the scaled `value`, the `unit` (`"cps"`, `"cpm"`, or
+`"code:<n>"` for anything unverified), a unix `timestamp` taken at decode time,
+the raw integer `digits`, the unit `code`, the trailing `checksum` token, and
+the cleaned `raw` frame text.
+
+## How it works
+
+The meter sends fixed ASCII frames at **9600 baud, 7 data bits, even parity, 1
+stop bit (7E1)**, each framed by `STX … ETX CR LF`. A decoded frame looks like:
+
+```
+351 5  0 0 04 FH41B2  0 42
+ |   |            |       └─ checksum (algorithm unknown — exposed, not verified)
+ |   |            └───────── device / probe tag
+ |   └────────────────────── unit code: 5 = cps, 3 = cpm
+ └────────────────────────── value digits (decimal point implied by the unit)
+```
+
+There's no decimal point on the wire, so the integer is scaled per unit
+(`cps × 0.01`, `cpm × 0.1`). The cable is a Prolific PL2303, which the driver
+auto-detects by USB vendor ID / `by-id` symlink, and whose occasional
+zero-length-read glitches it tolerates without dropping the connection.
+
+## Limitations
+
+I'd rather you know these up front than discover them:
+
+- **Reverse-engineered, not from a spec.** Verified against one meter's display.
+- **Only cps and cpm are trusted.** Other unit/range modes are surfaced as
+  `code:<n>` and passed through **unscaled** — the meter has modes I couldn't
+  test, and I won't pretend the scaling for those is right.
+- **The checksum is not verified.** The algorithm is unknown; the field is
+  exposed so you can experiment, but frames aren't validated against it.
+- **Scaling may be meter-dependent.** If readings are off by a constant factor,
+  check against the display and set `scale_cps` / `scale_cpm` accordingly.
+
+## ⚠️ Not for safety-critical use
+
+This is a hobbyist/research convenience for logging and visualisation. It is
+**not** calibrated, validated, or certified, and must not be relied on for
+radiation-safety decisions, dose assessment, or any situation where a wrong or
+missing reading could harm someone. For that, use the instrument's own display
+and your organisation's approved procedures.
+
+## Contributing
+
+If you have a RadEye B20 and can capture frames in a mode this doesn't handle
+(especially dose-rate / µSv·h⁻¹ modes), a sample of raw frames alongside the
+displayed value is exactly what's needed to extend it. Open an issue or PR.
+
+## License
+
+MIT © Navya Sharma

radeye_b20-0.1.0/README.md

@@ -0,0 +1,111 @@
+# radeye-b20
+
+A small Python driver for the **Thermo Scientific RadEye B20** handheld
+radiation survey meter.
+
+The RadEye B20 streams live readings over its infrared read-head, but the serial
+protocol is undocumented and — as far as I can tell — no public library speaks
+it. This one does. It was **reverse-engineered** by watching the wire and
+checking decoded values against the meter's own display, so it's honest about
+what it can and can't do (see [Limitations](#limitations)).
+
+```python
+from radeye_b20 import RadEye
+
+with RadEye() as meter:            # auto-detects the IR-USB cable
+    for reading in meter.stream():
+        print(reading.value, reading.unit)   # e.g. 3.51 cps
+```
+
+## Install
+
+```bash
+pip install radeye-b20
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/navyasharmabits/radeye-b20
+cd radeye-b20
+pip install -e .
+```
+
+Requires Python 3.8+ and `pyserial`. Works on Linux, macOS, and Windows (the
+meter appears as a normal USB serial port).
+
+## Command line
+
+```bash
+radeye ports                 # list serial ports, flag the likely RadEye
+radeye stream                # live readings until Ctrl+C
+radeye stream --csv          # timestamp,value,unit  (pipe to a file)
+radeye stream --port /dev/ttyUSB0 --scale-cps 0.01
+```
+
+## Library
+
+```python
+from radeye_b20 import RadEye, find_port
+
+print(find_port())                       # '/dev/ttyUSB0' or None
+
+with RadEye(port="auto", scale_cps=0.01, scale_cpm=0.1) as meter:
+    r = meter.read()                     # one reading, or None on a skipped frame
+    if r:
+        print(r.value, r.unit, r.timestamp, r.checksum)
+```
+
+Each `Reading` carries the scaled `value`, the `unit` (`"cps"`, `"cpm"`, or
+`"code:<n>"` for anything unverified), a unix `timestamp` taken at decode time,
+the raw integer `digits`, the unit `code`, the trailing `checksum` token, and
+the cleaned `raw` frame text.
+
+## How it works
+
+The meter sends fixed ASCII frames at **9600 baud, 7 data bits, even parity, 1
+stop bit (7E1)**, each framed by `STX … ETX CR LF`. A decoded frame looks like:
+
+```
+351 5  0 0 04 FH41B2  0 42
+ |   |            |       └─ checksum (algorithm unknown — exposed, not verified)
+ |   |            └───────── device / probe tag
+ |   └────────────────────── unit code: 5 = cps, 3 = cpm
+ └────────────────────────── value digits (decimal point implied by the unit)
+```
+
+There's no decimal point on the wire, so the integer is scaled per unit
+(`cps × 0.01`, `cpm × 0.1`). The cable is a Prolific PL2303, which the driver
+auto-detects by USB vendor ID / `by-id` symlink, and whose occasional
+zero-length-read glitches it tolerates without dropping the connection.
+
+## Limitations
+
+I'd rather you know these up front than discover them:
+
+- **Reverse-engineered, not from a spec.** Verified against one meter's display.
+- **Only cps and cpm are trusted.** Other unit/range modes are surfaced as
+  `code:<n>` and passed through **unscaled** — the meter has modes I couldn't
+  test, and I won't pretend the scaling for those is right.
+- **The checksum is not verified.** The algorithm is unknown; the field is
+  exposed so you can experiment, but frames aren't validated against it.
+- **Scaling may be meter-dependent.** If readings are off by a constant factor,
+  check against the display and set `scale_cps` / `scale_cpm` accordingly.
+
+## ⚠️ Not for safety-critical use
+
+This is a hobbyist/research convenience for logging and visualisation. It is
+**not** calibrated, validated, or certified, and must not be relied on for
+radiation-safety decisions, dose assessment, or any situation where a wrong or
+missing reading could harm someone. For that, use the instrument's own display
+and your organisation's approved procedures.
+
+## Contributing
+
+If you have a RadEye B20 and can capture frames in a mode this doesn't handle
+(especially dose-rate / µSv·h⁻¹ modes), a sample of raw frames alongside the
+displayed value is exactly what's needed to extend it. Open an issue or PR.
+
+## License
+
+MIT © Navya Sharma

radeye_b20-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "radeye-b20"
+version = "0.1.0"
+description = "Python driver for the Thermo Scientific RadEye B20 radiation survey meter (reverse-engineered serial protocol)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Navya Sharma" }]
+keywords = ["radeye", "radiation", "survey-meter", "serial", "geiger", "dosimetry", "instrument-driver"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Hardware :: Hardware Drivers",
+]
+dependencies = ["pyserial>=3.4"]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.scripts]
+radeye = "radeye_b20.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/navyasharmabits/radeye-b20"
+
+[tool.setuptools.packages.find]
+include = ["radeye_b20*"]

radeye_b20-0.1.0/radeye_b20/__init__.py

@@ -0,0 +1,33 @@
+"""
+radeye-b20 -- a small Python driver for the Thermo Scientific RadEye B20
+handheld radiation survey meter.
+
+The meter's serial protocol is undocumented; this library talks to it using a
+reverse-engineered decoding that is verified for counts-per-second (cps) and
+counts-per-minute (cpm). See the README for what is and isn't trustworthy.
+
+Quick start::
+
+    from radeye_b20 import RadEye
+
+    with RadEye() as meter:          # auto-detects the IR-USB cable
+        for reading in meter.stream():
+            print(reading.value, reading.unit)
+"""
+
+from .device import RadEye, RadEyeError, find_port, list_serial_ports
+from .protocol import Decoder, Reading, UNIT_CODES, DEFAULT_SCALES
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RadEye",
+    "RadEyeError",
+    "Reading",
+    "Decoder",
+    "find_port",
+    "list_serial_ports",
+    "UNIT_CODES",
+    "DEFAULT_SCALES",
+    "__version__",
+]

radeye_b20-0.1.0/radeye_b20/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

radeye_b20-0.1.0/radeye_b20/cli.py

@@ -0,0 +1,89 @@
+"""Command-line front-end: ``radeye`` (or ``python -m radeye_b20``)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .device import RadEye, RadEyeError, find_port, list_serial_ports
+
+
+def _cmd_ports(_args: argparse.Namespace) -> int:
+    detected = find_port()
+    ports = list_serial_ports()
+    if not ports:
+        print("No serial ports found.")
+        return 0
+    for p in ports:
+        mark = "  <-- looks like the RadEye" if p.device == detected else ""
+        print(f"{p.device:20s} {p.description}{mark}")
+    if detected is None:
+        print("\nCould not auto-detect a RadEye cable; pass --port explicitly.")
+    return 0
+
+
+def _cmd_stream(args: argparse.Namespace) -> int:
+    try:
+        meter = RadEye(
+            port=args.port,
+            scale_cps=args.scale_cps,
+            scale_cpm=args.scale_cpm,
+        ).open()
+    except RadEyeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    if args.csv:
+        print("timestamp,value,unit")
+
+    try:
+        with meter:
+            for r in meter.stream(skip_unknown_units=args.known_only):
+                if args.csv:
+                    print(f"{r.timestamp:.6f},{r.value:.4f},{r.unit}", flush=True)
+                elif args.raw:
+                    print(r.raw, flush=True)
+                else:
+                    print(f"[{r.timestamp:.3f}] {r.value:8.2f} {r.unit}", flush=True)
+    except KeyboardInterrupt:
+        pass
+    except RadEyeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="radeye",
+        description="Talk to a Thermo Scientific RadEye B20 survey meter.",
+    )
+    p.add_argument("--version", action="version", version=f"radeye-b20 {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sp = sub.add_parser("ports", help="list serial ports and flag the likely RadEye")
+    sp.set_defaults(func=_cmd_ports)
+
+    ss = sub.add_parser("stream", help="print live readings until interrupted")
+    ss.add_argument("--port", default="auto",
+                    help="serial device, or 'auto' to auto-detect (default)")
+    ss.add_argument("--csv", action="store_true", help="emit CSV (timestamp,value,unit)")
+    ss.add_argument("--raw", action="store_true", help="print decoded frame text instead")
+    ss.add_argument("--known-only", action="store_true",
+                    help="drop readings whose unit is not verified cps/cpm")
+    ss.add_argument("--scale-cps", type=float, default=0.01,
+                    help="decimal scale for cps frames (default 0.01)")
+    ss.add_argument("--scale-cpm", type=float, default=0.1,
+                    help="decimal scale for cpm frames (default 0.1)")
+    ss.set_defaults(func=_cmd_stream)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

radeye_b20-0.1.0/radeye_b20/device.py

@@ -0,0 +1,210 @@
+"""
+Serial device access for the Thermo Scientific RadEye B20.
+
+The meter connects through an infrared read-head on a Prolific PL2303 IR-USB
+cable, so from the host it is just a USB serial port at 9600 baud, 7E1.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator, List, Optional
+
+import serial
+import serial.tools.list_ports
+
+from .protocol import Decoder, Reading, clean_frame
+
+# Prolific Technology Inc. USB vendor ID -- the chip inside the RadEye's
+# IR-USB cable. Used as the most specific auto-detection signal.
+PROLIFIC_VID = 0x067B
+
+# Fallback substrings matched against a port's description/manufacturer when
+# the vendor-ID match is unavailable (e.g. inside some containers).
+AUTO_DETECT_HINTS = ("prolific", "radeye")
+
+# The read-head's fixed line settings.
+BAUD = 9600
+BYTESIZE = serial.SEVENBITS
+PARITY = serial.PARITY_EVEN
+STOPBITS = serial.STOPBITS_ONE
+
+
+def list_serial_ports() -> List[serial.tools.list_ports_common.ListPortInfo]:
+    """All serial ports the OS currently sees (thin wrapper, handy for CLIs)."""
+    return list(serial.tools.list_ports.comports())
+
+
+def find_port(verbose: bool = False) -> Optional[str]:
+    """Best-effort auto-detection of the RadEye's IR-USB cable.
+
+    Tries, in decreasing order of reliability:
+
+    1. ``/dev/serial/by-id`` -- a udev symlink whose name embeds the chip
+       vendor string. Most reliable, and works even where pyserial's
+       vid/pid come back empty.
+    2. pyserial vendor-ID match against Prolific.
+    3. pyserial description / manufacturer text match.
+    4. A lone ``ttyUSB`` device -- only if exactly one is present. With
+       several it refuses to guess and returns ``None``.
+
+    Returns the device path, or ``None`` if nothing could be identified.
+    """
+    def log(msg: str) -> None:
+        if verbose:
+            print(msg)
+
+    by_id = "/dev/serial/by-id"
+    if os.path.isdir(by_id):
+        for name in os.listdir(by_id):
+            if any(hint in name.lower() for hint in AUTO_DETECT_HINTS):
+                resolved = os.path.realpath(os.path.join(by_id, name))
+                log(f"radeye: matched by-id {name} -> {resolved}")
+                return resolved
+
+    ports = list_serial_ports()
+
+    for p in ports:
+        if p.vid == PROLIFIC_VID:
+            log(f"radeye: matched Prolific VID at {p.device}")
+            return p.device
+
+    for p in ports:
+        desc = f"{p.description} {p.manufacturer or ''}".lower()
+        if any(hint in desc for hint in AUTO_DETECT_HINTS):
+            log(f"radeye: matched description at {p.device} ({p.description})")
+            return p.device
+
+    usb = [p for p in ports if "ttyUSB" in p.device]
+    if len(usb) == 1:
+        log(f"radeye: no hardware match; using the only ttyUSB, {usb[0].device}")
+        return usb[0].device
+    return None
+
+
+class RadEyeError(RuntimeError):
+    """Raised for unrecoverable device problems (e.g. port not found)."""
+
+
+class RadEye:
+    """A connection to a RadEye B20 survey meter.
+
+    Typical use::
+
+        from radeye_b20 import RadEye
+
+        with RadEye() as meter:            # auto-detects the cable
+            for reading in meter.stream():
+                print(reading.value, reading.unit)
+
+    Args:
+        port:      serial device path, or ``"auto"`` to auto-detect.
+        scale_cps: decimal scale for cps frames (default 0.01).
+        scale_cpm: decimal scale for cpm frames (default 0.1).
+        timeout:   per-read serial timeout, seconds.
+
+    Note:
+        Values are reverse-engineered and only cps/cpm are verified. Always
+        sanity-check a live reading against the meter's own display before
+        trusting the numbers, and adjust ``scale_cps`` / ``scale_cpm`` if
+        they disagree by a constant factor.
+    """
+
+    def __init__(
+        self,
+        port: str = "auto",
+        scale_cps: float = 0.01,
+        scale_cpm: float = 0.1,
+        timeout: float = 0.2,
+    ):
+        self.port = port
+        self.timeout = timeout
+        self.decoder = Decoder({"cps": scale_cps, "cpm": scale_cpm})
+        self._ser: Optional[serial.Serial] = None
+        self._resolved_port: Optional[str] = None
+
+    # -- lifecycle --------------------------------------------------------
+    def open(self) -> "RadEye":
+        """Open the serial port, auto-detecting if ``port == 'auto'``."""
+        port = self.port
+        if port == "auto":
+            port = find_port()
+            if port is None:
+                raise RadEyeError(
+                    "Could not auto-detect a RadEye cable. Pass an explicit "
+                    "port, e.g. RadEye(port='/dev/ttyUSB0')."
+                )
+        try:
+            # exclusive=True stops another process opening the same port,
+            # which otherwise causes spurious read errors.
+            self._ser = serial.Serial(
+                port, BAUD,
+                bytesize=BYTESIZE, parity=PARITY, stopbits=STOPBITS,
+                timeout=self.timeout, exclusive=True,
+            )
+        except serial.SerialException as e:
+            raise RadEyeError(f"Could not open {port}: {e}") from e
+        self._resolved_port = port
+        return self
+
+    def close(self) -> None:
+        if self._ser is not None and self._ser.is_open:
+            self._ser.close()
+        self._ser = None
+
+    def __enter__(self) -> "RadEye":
+        return self.open()
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    @property
+    def resolved_port(self) -> Optional[str]:
+        """The actual device path in use (after auto-detection)."""
+        return self._resolved_port
+
+    # -- reading ----------------------------------------------------------
+    def read(self) -> Optional[Reading]:
+        """Read the next decoded measurement, or ``None`` on a skipped frame.
+
+        Returns ``None`` (rather than blocking forever) when a read times out
+        with no data or a frame is unparseable -- call again to keep trying.
+        Tolerates the PL2303's transient zero-length reads without dropping
+        the connection; only a genuinely vanished device raises.
+        """
+        if self._ser is None or not self._ser.is_open:
+            raise RadEyeError("Port is not open; call open() first.")
+
+        try:
+            raw = self._ser.readline()          # frames terminate in LF
+        except serial.SerialException as e:
+            # The PL2303 occasionally reports a zero-length read as a
+            # SerialException on a brief IR misalignment -- not a real
+            # disconnect. Only treat it as fatal if the device file is gone.
+            if self._resolved_port and os.path.exists(self._resolved_port):
+                return None
+            self.close()
+            raise RadEyeError(f"Serial device disconnected: {e}") from e
+
+        if not raw:
+            return None
+
+        text = clean_frame(raw)
+        if not text:
+            return None
+        return self.decoder.decode(text)
+
+    def stream(self, skip_unknown_units: bool = False) -> Iterator[Reading]:
+        """Yield readings continuously until the connection ends.
+
+        Args:
+            skip_unknown_units: if True, drop readings whose unit code is not
+                one of the verified ones (cps/cpm) instead of yielding them.
+        """
+        while True:
+            reading = self.read()
+            if reading is None:
+                continue
+            if skip_unknown_units and not reading.is_known_unit:
+                continue
+            yield reading

radeye_b20-0.1.0/radeye_b20/protocol.py

@@ -0,0 +1,141 @@
+"""
+Wire protocol for the Thermo Scientific RadEye B20 survey meter.
+
+The meter has no documented public serial protocol, so this was
+reverse-engineered by observing the stream and comparing decoded values
+against the instrument's own display. Treat it accordingly: it is known to
+work for the two unit modes that were verified (cps, cpm), and everything
+else is a best-effort guess that is passed through rather than trusted.
+
+Frame format (7 data bits, EVEN parity, 1 stop bit, 9600 baud)::
+
+    STX(0x02) <ascii payload> ETX(0x03) CR LF
+
+with the payload decoding to whitespace-separated tokens, e.g.::
+
+    "351 5  0 0 04 FH41B2  0 42"
+     |   |            |       |
+     |   |            |       +-- checksum (2 hex chars; algorithm unknown, NOT verified)
+     |   |            +---------- device / probe tag (constant for a given meter)
+     |   +----------------------- unit code: 5 = cps, 3 = cpm
+     +--------------------------- value digits (decimal point is implied by the unit)
+
+The stream carries no decimal point, so the integer value is scaled per unit:
+
+    cps:  digits * 0.01   ->  frame "351"  = 3.51 cps
+    cpm:  digits * 0.1    ->  frame "2290" = 229.0 cpm
+
+Those scale factors were confirmed against the display for one meter. If your
+readings are off by a constant factor, adjust the scales (see ``Decoder``).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+# Control bytes that frame each payload.
+STX = 0x02
+ETX = 0x03
+
+# Unit code -> canonical name. Only 5/3 have been verified against the display.
+# Anything else is surfaced as "code:<n>" so it is visible but never silently
+# mis-scaled.
+UNIT_CODES: Dict[str, str] = {
+    "5": "cps",
+    "3": "cpm",
+}
+
+# Default decimal scaling, verified against the meter's display for one unit.
+DEFAULT_SCALES: Dict[str, float] = {
+    "cps": 0.01,
+    "cpm": 0.1,
+}
+
+
+@dataclass(frozen=True)
+class Reading:
+    """A single decoded measurement.
+
+    Attributes:
+        value:     scaled physical reading (``digits * scale``).
+        unit:      "cps", "cpm", or "code:<n>" for an unrecognised unit code.
+        timestamp: unix seconds, taken the instant the frame was decoded.
+        digits:    the raw integer before scaling.
+        code:      the raw unit code from the frame.
+        checksum:  the trailing checksum token, if present. NOT verified --
+                   the algorithm is unknown; exposed for callers who want it.
+        raw:       the cleaned frame text the reading was decoded from.
+    """
+
+    value: float
+    unit: str
+    timestamp: float
+    digits: int
+    code: str
+    checksum: Optional[str] = None
+    raw: str = field(default="", repr=False)
+
+    @property
+    def is_known_unit(self) -> bool:
+        """True if the unit code was one of the verified ones (cps/cpm)."""
+        return not self.unit.startswith("code:")
+
+    def __str__(self) -> str:
+        return f"{self.value:g} {self.unit}"
+
+
+def clean_frame(raw: bytes) -> str:
+    """Turn a raw byte line off the wire into clean frame text.
+
+    Masks off any stray parity bit (harmless if the bytes are already 7-bit),
+    drops non-printable control chars (STX/ETX/CR), and trims whitespace.
+    Returns "" if nothing printable remains.
+    """
+    text = bytes(b & 0x7F for b in raw).decode("ascii", "replace")
+    text = "".join(c for c in text if c.isprintable()).strip()
+    return text
+
+
+class Decoder:
+    """Stateless frame decoder. Holds only the per-unit scale factors.
+
+    Args:
+        scales: optional overrides for the decimal scaling, e.g.
+            ``{"cps": 0.01, "cpm": 0.1}``. Missing units fall back to the
+            verified defaults, and unknown units are scaled by 1.0.
+    """
+
+    def __init__(self, scales: Optional[Dict[str, float]] = None):
+        self.scales: Dict[str, float] = dict(DEFAULT_SCALES)
+        if scales:
+            self.scales.update(scales)
+
+    def decode(self, text: str, timestamp: Optional[float] = None) -> Optional[Reading]:
+        """Decode one cleaned frame into a :class:`Reading`.
+
+        Returns ``None`` for frames that do not look like a measurement
+        (too few tokens, or a non-numeric leading value) rather than raising,
+        so a garbled frame just gets skipped by a streaming caller.
+        """
+        tokens = text.split()
+        if len(tokens) < 2 or not tokens[0].isdigit():
+            return None
+
+        digits = int(tokens[0])
+        code = tokens[1]
+        unit = UNIT_CODES.get(code, f"code:{code}")
+        scale = self.scales.get(unit, 1.0)
+
+        checksum = tokens[-1] if len(tokens) >= 3 else None
+
+        return Reading(
+            value=digits * scale,
+            unit=unit,
+            timestamp=time.time() if timestamp is None else timestamp,
+            digits=digits,
+            code=code,
+            checksum=checksum,
+            raw=text,
+        )

radeye_b20-0.1.0/radeye_b20.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: radeye-b20
+Version: 0.1.0
+Summary: Python driver for the Thermo Scientific RadEye B20 radiation survey meter (reverse-engineered serial protocol).
+Author: Navya Sharma
+License: MIT
+Project-URL: Homepage, https://github.com/navyasharmabits/radeye-b20
+Keywords: radeye,radiation,survey-meter,serial,geiger,dosimetry,instrument-driver
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.4
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# radeye-b20
+
+A small Python driver for the **Thermo Scientific RadEye B20** handheld
+radiation survey meter.
+
+The RadEye B20 streams live readings over its infrared read-head, but the serial
+protocol is undocumented and — as far as I can tell — no public library speaks
+it. This one does. It was **reverse-engineered** by watching the wire and
+checking decoded values against the meter's own display, so it's honest about
+what it can and can't do (see [Limitations](#limitations)).
+
+```python
+from radeye_b20 import RadEye
+
+with RadEye() as meter:            # auto-detects the IR-USB cable
+    for reading in meter.stream():
+        print(reading.value, reading.unit)   # e.g. 3.51 cps
+```
+
+## Install
+
+```bash
+pip install radeye-b20
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/navyasharmabits/radeye-b20
+cd radeye-b20
+pip install -e .
+```
+
+Requires Python 3.8+ and `pyserial`. Works on Linux, macOS, and Windows (the
+meter appears as a normal USB serial port).
+
+## Command line
+
+```bash
+radeye ports                 # list serial ports, flag the likely RadEye
+radeye stream                # live readings until Ctrl+C
+radeye stream --csv          # timestamp,value,unit  (pipe to a file)
+radeye stream --port /dev/ttyUSB0 --scale-cps 0.01
+```
+
+## Library
+
+```python
+from radeye_b20 import RadEye, find_port
+
+print(find_port())                       # '/dev/ttyUSB0' or None
+
+with RadEye(port="auto", scale_cps=0.01, scale_cpm=0.1) as meter:
+    r = meter.read()                     # one reading, or None on a skipped frame
+    if r:
+        print(r.value, r.unit, r.timestamp, r.checksum)
+```
+
+Each `Reading` carries the scaled `value`, the `unit` (`"cps"`, `"cpm"`, or
+`"code:<n>"` for anything unverified), a unix `timestamp` taken at decode time,
+the raw integer `digits`, the unit `code`, the trailing `checksum` token, and
+the cleaned `raw` frame text.
+
+## How it works
+
+The meter sends fixed ASCII frames at **9600 baud, 7 data bits, even parity, 1
+stop bit (7E1)**, each framed by `STX … ETX CR LF`. A decoded frame looks like:
+
+```
+351 5  0 0 04 FH41B2  0 42
+ |   |            |       └─ checksum (algorithm unknown — exposed, not verified)
+ |   |            └───────── device / probe tag
+ |   └────────────────────── unit code: 5 = cps, 3 = cpm
+ └────────────────────────── value digits (decimal point implied by the unit)
+```
+
+There's no decimal point on the wire, so the integer is scaled per unit
+(`cps × 0.01`, `cpm × 0.1`). The cable is a Prolific PL2303, which the driver
+auto-detects by USB vendor ID / `by-id` symlink, and whose occasional
+zero-length-read glitches it tolerates without dropping the connection.
+
+## Limitations
+
+I'd rather you know these up front than discover them:
+
+- **Reverse-engineered, not from a spec.** Verified against one meter's display.
+- **Only cps and cpm are trusted.** Other unit/range modes are surfaced as
+  `code:<n>` and passed through **unscaled** — the meter has modes I couldn't
+  test, and I won't pretend the scaling for those is right.
+- **The checksum is not verified.** The algorithm is unknown; the field is
+  exposed so you can experiment, but frames aren't validated against it.
+- **Scaling may be meter-dependent.** If readings are off by a constant factor,
+  check against the display and set `scale_cps` / `scale_cpm` accordingly.
+
+## ⚠️ Not for safety-critical use
+
+This is a hobbyist/research convenience for logging and visualisation. It is
+**not** calibrated, validated, or certified, and must not be relied on for
+radiation-safety decisions, dose assessment, or any situation where a wrong or
+missing reading could harm someone. For that, use the instrument's own display
+and your organisation's approved procedures.
+
+## Contributing
+
+If you have a RadEye B20 and can capture frames in a mode this doesn't handle
+(especially dose-rate / µSv·h⁻¹ modes), a sample of raw frames alongside the
+displayed value is exactly what's needed to extend it. Open an issue or PR.
+
+## License
+
+MIT © Navya Sharma

radeye_b20-0.1.0/radeye_b20.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+radeye_b20/__init__.py
+radeye_b20/__main__.py
+radeye_b20/cli.py
+radeye_b20/device.py
+radeye_b20/protocol.py
+radeye_b20.egg-info/PKG-INFO
+radeye_b20.egg-info/SOURCES.txt
+radeye_b20.egg-info/dependency_links.txt
+radeye_b20.egg-info/entry_points.txt
+radeye_b20.egg-info/requires.txt
+radeye_b20.egg-info/top_level.txt
+tests/test_protocol.py

radeye_b20-0.1.0/radeye_b20.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

radeye_b20-0.1.0/radeye_b20.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+radeye = radeye_b20.cli:main

radeye_b20-0.1.0/radeye_b20.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyserial>=3.4
+
+[test]
+pytest>=7.0

radeye_b20-0.1.0/radeye_b20.egg-info/top_level.txt

@@ -0,0 +1 @@
+radeye_b20

radeye_b20-0.1.0/setup.cfg

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

radeye_b20-0.1.0/tests/test_protocol.py

@@ -0,0 +1,54 @@
+"""Protocol tests -- run without any hardware: `python -m pytest` or `python tests/test_protocol.py`."""
+
+from radeye_b20.protocol import Decoder, clean_frame
+
+
+def test_decodes_cps_frame():
+    r = Decoder().decode("351 5  0 0 04 FH41B2  0 42", timestamp=1000.0)
+    assert r is not None
+    assert r.unit == "cps"
+    assert r.digits == 351
+    assert abs(r.value - 3.51) < 1e-9
+    assert r.checksum == "42"
+    assert r.is_known_unit
+
+
+def test_decodes_cpm_frame():
+    r = Decoder().decode("2290 3  0 0 04 FH41B2  0 7A", timestamp=1000.0)
+    assert r is not None
+    assert r.unit == "cpm"
+    assert abs(r.value - 229.0) < 1e-9
+
+
+def test_unknown_unit_passthrough_not_scaled():
+    r = Decoder().decode("100 9 x x x TAG x 00", timestamp=1000.0)
+    assert r is not None
+    assert r.unit == "code:9"
+    assert r.value == 100.0          # scale 1.0 for unknown units
+    assert not r.is_known_unit
+
+
+def test_custom_scale_override():
+    r = Decoder({"cps": 0.1}).decode("351 5  0 0 04 TAG 0 42", timestamp=1000.0)
+    assert abs(r.value - 35.1) < 1e-9
+
+
+def test_rejects_garbage():
+    assert Decoder().decode("", timestamp=1.0) is None
+    assert Decoder().decode("not a frame", timestamp=1.0) is None
+    assert Decoder().decode("5", timestamp=1.0) is None
+
+
+def test_clean_frame_masks_parity_and_strips_control():
+    raw = bytes([0x02]) + b"351 5 TAG 42" + bytes([0x03, 0x0D, 0x0A])
+    assert clean_frame(raw) == "351 5 TAG 42"
+
+
+if __name__ == "__main__":
+    import sys
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    for fn in fns:
+        fn()
+        print(f"ok  {fn.__name__}")
+    print(f"\n{len(fns)} passed")
+    sys.exit(0)