wirelink 0.1.0__tar.gz

wirelink-0.1.0/LICENSE

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

wirelink-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: wirelink
+Version: 0.1.0
+Summary: Typed, framed messaging between Python and an Arduino-compatible board
+Author: Azad Khan
+License: MIT
+Project-URL: Homepage, https://github.com/yourname/wirelink
+Project-URL: Issues, https://github.com/yourname/wirelink/issues
+Keywords: arduino,esp32,serial,microcontroller,cobs,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# wirelink (Python host)
+
+Host side of [WireLink](https://github.com/yourname/wirelink): typed, framed, CRC-checked
+messaging with an Arduino-compatible board. The matching board library is `WireLink` in the
+Arduino Library Manager.
+
+```python
+from wirelink import Link
+
+link = Link.autodetect(name="demo-board")   # found by handshake, not by port number
+link.call("setLed", 255, 40, 0)
+print(link.request("uptime")[0])
+
+@link.on("temp")
+def show(celsius):
+    print(celsius)
+```
+
+The link reconnects on its own when a board resets or is unplugged, including when it comes
+back under a different port name. See the project README for the wire format.

wirelink-0.1.0/README.md

@@ -0,0 +1,20 @@
+# wirelink (Python host)
+
+Host side of [WireLink](https://github.com/yourname/wirelink): typed, framed, CRC-checked
+messaging with an Arduino-compatible board. The matching board library is `WireLink` in the
+Arduino Library Manager.
+
+```python
+from wirelink import Link
+
+link = Link.autodetect(name="demo-board")   # found by handshake, not by port number
+link.call("setLed", 255, 40, 0)
+print(link.request("uptime")[0])
+
+@link.on("temp")
+def show(celsius):
+    print(celsius)
+```
+
+The link reconnects on its own when a board resets or is unplugged, including when it comes
+back under a different port name. See the project README for the wire format.

wirelink-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wirelink"
+version = "0.1.0"
+description = "Typed, framed messaging between Python and an Arduino-compatible board"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Azad Khan" }]
+keywords = ["arduino", "esp32", "serial", "microcontroller", "cobs", "protocol"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Hardware :: Hardware Drivers",
+]
+dependencies = ["pyserial>=3.5"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/yourname/wirelink"
+Issues = "https://github.com/yourname/wirelink/issues"
+
+[tool.setuptools.packages.find]
+include = ["wirelink*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wirelink-0.1.0/setup.cfg

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

wirelink-0.1.0/tests/test_codec.py

@@ -0,0 +1,41 @@
+import pytest
+
+from wirelink import codec
+from wirelink.cobs import decode, encode
+
+
+@pytest.mark.parametrize("payload", [
+    b"", b"\x00", b"\x00" * 300, b"\xff" * 300, bytes(range(256)),
+    b"hello\x00world",
+])
+def test_cobs_round_trip(payload):
+    assert decode(encode(payload)) == payload
+
+
+def test_cobs_output_has_no_zero_bytes():
+    assert 0 not in encode(b"\x00" * 100 + b"\x01\x02")
+
+
+@pytest.mark.parametrize("values", [
+    [], [True, False], [0, -1, 2147483647], [3.5], ["hi"], [b"\x00\x01"],
+    [1, 2.5, "x", True],
+])
+def test_frame_round_trip(values):
+    frame = codec.build(codec.REQ, 42, "doThing", values)
+    assert frame.endswith(b"\x00")
+    msg_type, seq, name, out = codec.parse(frame[:-1])
+    assert (msg_type, seq, name) == (codec.REQ, 42, "doThing")
+    for got, want in zip(out, values):
+        assert got == pytest.approx(want) if isinstance(want, float) else got == want
+
+
+def test_corrupt_frame_is_rejected():
+    frame = bytearray(codec.build(codec.EVENT, 1, "temp", [24.5])[:-1])
+    frame[-1] ^= 0xFF
+    with pytest.raises(codec.ProtocolError):
+        codec.parse(bytes(frame))
+
+
+def test_oversized_frame_refused():
+    with pytest.raises(ValueError):
+        codec.build(codec.EVENT, 1, "x", ["y" * 255, "z" * 255])

wirelink-0.1.0/tests/test_link.py

@@ -0,0 +1,148 @@
+"""Link state-machine tests against a fake board, no hardware needed."""
+
+import threading
+import time
+
+import pytest
+
+from wirelink import Link, NotConnected, codec, link as link_mod
+
+
+class FakeBoard:
+    """Minimal WireLink device: answers HELLO and 'ping', can be yanked."""
+
+    def __init__(self, name="fake-board", answer_hello=True):
+        self.name = name
+        self.answer_hello = answer_hello
+        self.out = bytearray()
+        self.rx = bytearray()
+        self.alive = True
+        self.is_open = True
+        self.lock = threading.Lock()
+
+    # -- pyserial surface ------------------------------------------------
+    def read(self, n=1):
+        if not self.alive:
+            raise OSError("device disappeared")
+        with self.lock:
+            chunk, self.out = bytes(self.out[:n]), self.out[n:]
+        if not chunk:
+            time.sleep(0.005)
+        return chunk
+
+    def write(self, data):
+        if not self.alive:
+            raise OSError("device disappeared")
+        self.rx.extend(data)
+        while True:
+            idx = self.rx.find(b"\x00")
+            if idx < 0:
+                break
+            frame, self.rx = bytes(self.rx[:idx]), self.rx[idx + 1:]
+            if frame:
+                self._handle(frame)
+        return len(data)
+
+    def reset_input_buffer(self):
+        with self.lock:
+            self.out.clear()
+
+    def close(self):
+        self.is_open = False
+
+    # -- device behaviour ------------------------------------------------
+    def _handle(self, frame):
+        msg_type, seq, name, values = codec.parse(frame)
+        if msg_type == codec.HELLO and self.answer_hello:
+            self._send(codec.HELLO_ACK, seq, "", [self.name, "0.1.0"])
+        elif msg_type == codec.REQ and name == "ping":
+            self._send(codec.REPLY, seq, name, ["pong"])
+        elif msg_type == codec.REQ:
+            self._send(codec.ERR, seq, name, ["no handler for this message"])
+
+    def _send(self, msg_type, seq, name, values):
+        with self.lock:
+            self.out.extend(codec.build(msg_type, seq, name, values))
+
+    def emit(self, name, *values):
+        self._send(codec.EVENT, 0, name, list(values))
+
+    def yank(self):
+        """Simulate the cable being pulled."""
+        self.alive = False
+
+
+@pytest.fixture
+def bench(monkeypatch):
+    """Patch pyserial so Link talks to whatever board is on a given port."""
+    boards = {}
+
+    def fake_serial(port, baud, timeout=None):
+        board = boards.get(port)
+        if board is None or not board.alive:
+            raise OSError(f"cannot open {port}")
+        return board
+
+    class Port:
+        def __init__(self, device):
+            self.device = device
+
+    monkeypatch.setattr(link_mod.serial, "Serial", fake_serial)
+    monkeypatch.setattr(link_mod.list_ports, "comports",
+                        lambda: [Port(p) for p in boards])
+    return boards
+
+
+def test_autodetect_skips_silent_ports(bench):
+    bench["COM1"] = FakeBoard("mute", answer_hello=False)
+    bench["COM2"] = FakeBoard("real-board")
+    with Link.autodetect(name="real-board", connect_timeout=3.0,
+                         boot_delay=0, handshake_timeout=0.5) as link:
+        assert link.port == "COM2"
+        assert link.device_name == "real-board"
+
+
+def test_request_and_error(bench):
+    bench["COM3"] = FakeBoard()
+    with Link.autodetect(connect_timeout=3.0, boot_delay=0) as link:
+        assert link.request("ping") == ["pong"]
+        with pytest.raises(link_mod.RemoteError):
+            link.request("nope")
+
+
+def test_events_reach_handlers(bench):
+    board = bench.setdefault("COM4", FakeBoard())
+    got = []
+    with Link.autodetect(connect_timeout=3.0, boot_delay=0) as link:
+        link.on("temp")(lambda v: got.append(v))
+        board.emit("temp", 24.5)
+        deadline = time.time() + 2
+        while not got and time.time() < deadline:
+            time.sleep(0.01)
+    assert got == [pytest.approx(24.5)]
+
+
+def test_reconnects_after_the_cable_is_pulled(bench):
+    bench["COM5"] = FakeBoard("demo")
+    events = []
+    with Link.autodetect(connect_timeout=3.0, boot_delay=0,
+                         reconnect_interval=0.05,
+                         on_connect=lambda l: events.append("up"),
+                         on_disconnect=lambda l: events.append("down")) as link:
+        assert link.request("ping") == ["pong"]
+
+        bench["COM5"].yank()
+        deadline = time.time() + 2
+        while link.connected and time.time() < deadline:
+            time.sleep(0.01)
+        assert not link.connected
+        with pytest.raises(NotConnected):
+            link.request("ping")
+
+        # board comes back, possibly on a different port name
+        del bench["COM5"]
+        bench["COM9"] = FakeBoard("demo")
+        assert link.wait_connected(3.0)
+        assert link.port == "COM9"
+        assert link.request("ping") == ["pong"]
+    assert events[:3] == ["up", "down", "up"]

wirelink-0.1.0/wirelink/__init__.py

@@ -0,0 +1,4 @@
+from .link import Link, LinkError, NotConnected, RemoteError
+
+__all__ = ["Link", "LinkError", "NotConnected", "RemoteError"]
+__version__ = "0.1.0"

wirelink-0.1.0/wirelink/cobs.py

@@ -0,0 +1,47 @@
+"""Consistent Overhead Byte Stuffing.
+
+Removes 0x00 from the payload so a single 0x00 byte can mark end-of-frame.
+Worst case overhead is 1 byte per 254 bytes of payload.
+"""
+
+
+def encode(data: bytes) -> bytes:
+    out = bytearray()
+    code_idx = 0
+    out.append(0)  # placeholder for the first code byte
+    code = 1
+    for byte in data:
+        if byte == 0:
+            out[code_idx] = code
+            code_idx = len(out)
+            out.append(0)
+            code = 1
+        else:
+            out.append(byte)
+            code += 1
+            if code == 0xFF:
+                out[code_idx] = code
+                code_idx = len(out)
+                out.append(0)
+                code = 1
+    out[code_idx] = code
+    return bytes(out)
+
+
+def decode(data: bytes) -> bytes:
+    out = bytearray()
+    i = 0
+    n = len(data)
+    while i < n:
+        code = data[i]
+        if code == 0:
+            raise ValueError("zero code byte inside frame")
+        i += 1
+        end = i + code - 1
+        if end > n:
+            raise ValueError("truncated frame")
+        out.extend(data[i:end])
+        i = end
+        if code != 0xFF and i < n:
+            out.append(0)
+    return bytes(out)

wirelink-0.1.0/wirelink/codec.py

@@ -0,0 +1,125 @@
+"""Message framing and the type-tagged argument codec.
+
+Frame on the wire:   COBS(body) 0x00
+body:                type(1) seq(1) nlen(1) name(nlen) argc(1) args... crc16(2, LE)
+arg:                 tag(1) value(...)
+
+Both sides implement exactly this. Keep it in sync with WireLink.cpp.
+"""
+
+import struct
+
+from .cobs import decode as cobs_decode
+from .cobs import encode as cobs_encode
+from .crc import crc16
+
+# message types
+CALL = 0x01       # host -> device, no reply expected
+REQ = 0x02        # host -> device, reply expected
+REPLY = 0x03      # device -> host, answers a REQ with the same seq
+EVENT = 0x04      # device -> host, unsolicited
+ERR = 0x05        # either direction, payload is a single str
+HELLO = 0x10      # host -> device, discovery probe
+HELLO_ACK = 0x11  # device -> host, [str device_name, str lib_version]
+
+# argument tags
+T_BOOL = 0x01
+T_I32 = 0x02
+T_U32 = 0x03
+T_F32 = 0x04
+T_STR = 0x05
+T_BYTES = 0x06
+
+MAX_FRAME = 192  # must not exceed WIRELINK_MAX_FRAME on the device
+
+
+class ProtocolError(Exception):
+    pass
+
+
+def pack_args(values) -> bytes:
+    out = bytearray([len(values)])
+    for v in values:
+        if isinstance(v, bool):
+            out += bytes([T_BOOL, 1 if v else 0])
+        elif isinstance(v, int):
+            if -2147483648 <= v <= 2147483647:
+                out += bytes([T_I32]) + struct.pack("<i", v)
+            elif 0 <= v <= 4294967295:
+                out += bytes([T_U32]) + struct.pack("<I", v)
+            else:
+                raise ValueError(f"integer out of range for the wire format: {v}")
+        elif isinstance(v, float):
+            out += bytes([T_F32]) + struct.pack("<f", v)
+        elif isinstance(v, str):
+            raw = v.encode("utf-8")
+            if len(raw) > 255:
+                raise ValueError("string argument longer than 255 bytes")
+            out += bytes([T_STR, len(raw)]) + raw
+        elif isinstance(v, (bytes, bytearray)):
+            if len(v) > 255:
+                raise ValueError("bytes argument longer than 255 bytes")
+            out += bytes([T_BYTES, len(v)]) + bytes(v)
+        else:
+            raise TypeError(f"unsupported argument type: {type(v).__name__}")
+    return bytes(out)
+
+
+def unpack_args(buf: bytes):
+    if not buf:
+        raise ProtocolError("missing argc byte")
+    argc = buf[0]
+    i = 1
+    values = []
+    for _ in range(argc):
+        if i >= len(buf):
+            raise ProtocolError("truncated argument list")
+        tag = buf[i]
+        i += 1
+        if tag == T_BOOL:
+            values.append(bool(buf[i]))
+            i += 1
+        elif tag == T_I32:
+            values.append(struct.unpack_from("<i", buf, i)[0])
+            i += 4
+        elif tag == T_U32:
+            values.append(struct.unpack_from("<I", buf, i)[0])
+            i += 4
+        elif tag == T_F32:
+            values.append(struct.unpack_from("<f", buf, i)[0])
+            i += 4
+        elif tag in (T_STR, T_BYTES):
+            n = buf[i]
+            i += 1
+            chunk = buf[i:i + n]
+            i += n
+            values.append(chunk.decode("utf-8", "replace") if tag == T_STR else chunk)
+        else:
+            raise ProtocolError(f"unknown argument tag 0x{tag:02x}")
+    return values
+
+
+def build(msg_type: int, seq: int, name: str, values=()) -> bytes:
+    raw_name = name.encode("ascii")
+    if len(raw_name) > 255:
+        raise ValueError("message name longer than 255 bytes")
+    body = bytes([msg_type, seq & 0xFF, len(raw_name)]) + raw_name + pack_args(values)
+    body += struct.pack("<H", crc16(body))
+    frame = cobs_encode(body) + b"\x00"
+    if len(frame) > MAX_FRAME:
+        raise ValueError(f"frame of {len(frame)} bytes exceeds MAX_FRAME ({MAX_FRAME})")
+    return frame
+
+
+def parse(frame: bytes):
+    """Return (msg_type, seq, name, values) for one de-stuffed frame."""
+    body = cobs_decode(frame)
+    if len(body) < 6:
+        raise ProtocolError("frame too short")
+    payload, got = body[:-2], struct.unpack("<H", body[-2:])[0]
+    want = crc16(payload)
+    if got != want:
+        raise ProtocolError(f"crc mismatch (got 0x{got:04x}, want 0x{want:04x})")
+    msg_type, seq, nlen = payload[0], payload[1], payload[2]
+    name = payload[3:3 + nlen].decode("ascii", "replace")
+    return msg_type, seq, name, unpack_args(payload[3 + nlen:])

wirelink-0.1.0/wirelink/crc.py

@@ -0,0 +1,12 @@
+"""CRC-16/CCITT-FALSE: poly 0x1021, init 0xFFFF, no reflection, no final xor."""
+
+
+def crc16(data: bytes, crc: int = 0xFFFF) -> int:
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            if crc & 0x8000:
+                crc = ((crc << 1) ^ 0x1021) & 0xFFFF
+            else:
+                crc = (crc << 1) & 0xFFFF
+    return crc

wirelink-0.1.0/wirelink/link.py

@@ -0,0 +1,293 @@
+"""Host side of WireLink.
+
+The connection is a state machine owned by one background thread:
+
+    DISCONNECTED --open+handshake--> CONNECTED --IO error/timeout--> DISCONNECTED
+
+Boards reset when the port opens, get unplugged, and come back under a
+different port name. So the thread owns opening as well as reading, and a
+Link object stays valid across all of that.
+"""
+
+import queue
+import threading
+import time
+
+import serial
+from serial.tools import list_ports
+
+from . import codec
+from .codec import ProtocolError
+
+
+class LinkError(Exception):
+    pass
+
+
+class NotConnected(LinkError):
+    pass
+
+
+class RemoteError(LinkError):
+    """The device answered a request with an ERR message."""
+
+
+class Link:
+    def __init__(self, port=None, baud=115200, timeout=1.0, name=None,
+                 auto_reconnect=True, reconnect_interval=1.0, boot_delay=0.3,
+                 handshake_timeout=1.0, connect_timeout=None,
+                 on_connect=None, on_disconnect=None):
+        """
+        port      fixed port, or None to search every serial port
+        name      accept only a device reporting this name in its HELLO_ACK
+        boot_delay  seconds to wait after opening, for boards that reset on DTR
+        connect_timeout  if set, block here until connected or raise LinkError
+        """
+        self.port = None
+        self.requested_port = port
+        self.baud = baud
+        self.timeout = timeout
+        self.match_name = name
+        self.device_name = None
+        self.device_version = None
+        self.auto_reconnect = auto_reconnect
+        self.reconnect_interval = reconnect_interval
+        self.boot_delay = boot_delay
+        self.handshake_timeout = handshake_timeout
+        self.on_connect = on_connect
+        self.on_disconnect = on_disconnect
+
+        self._ser = None
+        self._buf = bytearray()
+        self._seq = 0
+        self._handlers = {}
+        self._pending = {}
+        self._connected = threading.Event()
+        self._stop = threading.Event()
+        self._tx_lock = threading.Lock()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="wirelink-rx")
+        self._thread.start()
+
+        if connect_timeout is not None and not self.wait_connected(connect_timeout):
+            self.close()
+            raise LinkError(f"no WireLink device found within {connect_timeout}s")
+
+    # ---------------------------------------------------------------- lifecycle
+
+    @classmethod
+    def autodetect(cls, baud=115200, name=None, connect_timeout=5.0, **kw):
+        """Open the first port whose board answers a HELLO probe."""
+        return cls(port=None, baud=baud, name=name, connect_timeout=connect_timeout, **kw)
+
+    @property
+    def connected(self):
+        return self._connected.is_set()
+
+    def wait_connected(self, timeout=None):
+        return self._connected.wait(timeout)
+
+    def close(self):
+        self._stop.set()
+        self._thread.join(timeout=2.0)
+        self._close_port()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ------------------------------------------------------------------ sending
+
+    def _next_seq(self):
+        with self._tx_lock:
+            self._seq = (self._seq + 1) & 0xFF
+            return self._seq
+
+    def _write(self, frame):
+        ser = self._ser
+        if ser is None:
+            raise NotConnected("not connected to a device")
+        try:
+            with self._tx_lock:
+                ser.write(frame)
+        except (OSError, serial.SerialException) as exc:
+            raise NotConnected(f"write failed: {exc}") from exc
+
+    def call(self, name, *args):
+        """Fire and forget."""
+        self._write(codec.build(codec.CALL, self._next_seq(), name, args))
+
+    def request(self, name, *args, timeout=None):
+        """Send and block until the device replies. Returns the list of values."""
+        seq = self._next_seq()
+        box = queue.Queue(maxsize=1)
+        self._pending[seq] = box
+        try:
+            self._write(codec.build(codec.REQ, seq, name, args))
+            try:
+                msg_type, values = box.get(timeout=timeout or self.timeout)
+            except queue.Empty:
+                raise LinkError(f"timed out waiting for a reply to {name!r}")
+            if msg_type is None:
+                raise NotConnected(f"link dropped while waiting for {name!r}")
+            if msg_type == codec.ERR:
+                raise RemoteError(values[0] if values else "unspecified device error")
+            return values
+        finally:
+            self._pending.pop(seq, None)
+
+    # ---------------------------------------------------------------- receiving
+
+    def on(self, name):
+        """Decorator registering a handler for an event the device emits."""
+        def wrap(fn):
+            self._handlers.setdefault(name, []).append(fn)
+            return fn
+        return wrap
+
+    # ------------------------------------------------------------- the rx thread
+
+    def _run(self):
+        first = True
+        while not self._stop.is_set():
+            if self._ser is None:
+                if not first and not self.auto_reconnect:
+                    return
+                if not self._try_connect():
+                    self._stop.wait(self.reconnect_interval)
+                    continue
+                first = False
+            if not self._pump(0.05):
+                self._drop()
+
+    def _candidates(self):
+        if self.requested_port:
+            return [self.requested_port]
+        return [p.device for p in list_ports.comports()]
+
+    def _try_connect(self):
+        for port in self._candidates():
+            try:
+                ser = serial.Serial(port, self.baud, timeout=0.05)
+            except (OSError, serial.SerialException):
+                continue
+            self._ser = ser
+            self._buf.clear()
+            time.sleep(self.boot_delay)     # the board may be rebooting
+            try:
+                ser.reset_input_buffer()
+            except Exception:
+                pass
+            name, version = self._handshake()
+            if name is None or (self.match_name and name != self.match_name):
+                self._close_port()
+                continue
+            self.port = port
+            self.device_name = name
+            self.device_version = version
+            self._connected.set()
+            self._notify(self.on_connect)
+            return True
+        return False
+
+    def _handshake(self):
+        """Send HELLO and pump frames until the ACK comes back."""
+        seq = self._next_seq()
+        box = queue.Queue(maxsize=1)
+        self._pending[seq] = box
+        try:
+            self._write(codec.build(codec.HELLO, seq, ""))
+        except LinkError:
+            self._pending.pop(seq, None)
+            return None, None
+        deadline = time.time() + self.handshake_timeout
+        try:
+            while time.time() < deadline:
+                if not self._pump(0.05):
+                    return None, None
+                try:
+                    msg_type, values = box.get_nowait()
+                except queue.Empty:
+                    continue
+                if msg_type == codec.HELLO_ACK:
+                    values += ["", ""]
+                    return values[0], values[1]
+                return None, None
+            return None, None
+        finally:
+            self._pending.pop(seq, None)
+
+    def _pump(self, _unused=None):
+        """Read whatever is available and dispatch complete frames.
+
+        Returns False if the port died, which is the signal to reconnect.
+        """
+        ser = self._ser
+        if ser is None:
+            return False
+        try:
+            chunk = ser.read(256)
+        except (OSError, serial.SerialException, TypeError):
+            return False
+        if chunk:
+            self._buf.extend(chunk)
+            while True:
+                idx = self._buf.find(b"\x00")
+                if idx < 0:
+                    break
+                frame = bytes(self._buf[:idx])
+                del self._buf[:idx + 1]
+                if frame:
+                    self._dispatch(frame)
+        return True
+
+    def _dispatch(self, frame):
+        try:
+            msg_type, seq, name, values = codec.parse(frame)
+        except (ProtocolError, ValueError):
+            return  # a corrupt frame is dropped, not fatal
+        if msg_type in (codec.REPLY, codec.ERR, codec.HELLO_ACK):
+            box = self._pending.get(seq)
+            if box is not None:
+                try:
+                    box.put_nowait((msg_type, values))
+                except queue.Full:
+                    pass
+            if msg_type != codec.ERR or box is not None:
+                return
+        for fn in self._handlers.get(name, ()):
+            try:
+                fn(*values)
+            except Exception as exc:  # a bad handler must not kill the reader
+                print(f"[wirelink] handler for {name!r} raised: {exc!r}")
+
+    def _drop(self):
+        was = self._connected.is_set()
+        self._connected.clear()
+        self._close_port()
+        # Unblock anyone waiting on a reply instead of letting them time out.
+        for box in list(self._pending.values()):
+            try:
+                box.put_nowait((None, None))
+            except queue.Full:
+                pass
+        if was:
+            self._notify(self.on_disconnect)
+
+    def _close_port(self):
+        ser, self._ser = self._ser, None
+        self._buf.clear()
+        if ser is not None:
+            try:
+                ser.close()
+            except Exception:
+                pass
+
+    def _notify(self, cb):
+        if cb is None:
+            return
+        try:
+            cb(self)
+        except Exception as exc:
+            print(f"[wirelink] connection callback raised: {exc!r}")

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

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: wirelink
+Version: 0.1.0
+Summary: Typed, framed messaging between Python and an Arduino-compatible board
+Author: Azad Khan
+License: MIT
+Project-URL: Homepage, https://github.com/yourname/wirelink
+Project-URL: Issues, https://github.com/yourname/wirelink/issues
+Keywords: arduino,esp32,serial,microcontroller,cobs,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# wirelink (Python host)
+
+Host side of [WireLink](https://github.com/yourname/wirelink): typed, framed, CRC-checked
+messaging with an Arduino-compatible board. The matching board library is `WireLink` in the
+Arduino Library Manager.
+
+```python
+from wirelink import Link
+
+link = Link.autodetect(name="demo-board")   # found by handshake, not by port number
+link.call("setLed", 255, 40, 0)
+print(link.request("uptime")[0])
+
+@link.on("temp")
+def show(celsius):
+    print(celsius)
+```
+
+The link reconnects on its own when a board resets or is unplugged, including when it comes
+back under a different port name. See the project README for the wire format.

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

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_codec.py
+tests/test_link.py
+wirelink/__init__.py
+wirelink/cobs.py
+wirelink/codec.py
+wirelink/crc.py
+wirelink/link.py
+wirelink.egg-info/PKG-INFO
+wirelink.egg-info/SOURCES.txt
+wirelink.egg-info/dependency_links.txt
+wirelink.egg-info/requires.txt
+wirelink.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+pyserial>=3.5
+
+[test]
+pytest>=7

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

@@ -0,0 +1 @@
+wirelink