wirelink 0.1.0__py3-none-any.whl

wirelink/__init__.py

@@ -0,0 +1,4 @@
+from .link import Link, LinkError, NotConnected, RemoteError
+
+__all__ = ["Link", "LinkError", "NotConnected", "RemoteError"]
+__version__ = "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/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/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/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.dist-info/METADATA

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

@@ -0,0 +1,10 @@
+wirelink/__init__.py,sha256=1nNRii967Ohz9cJF5C2AiTdq-BS2EWEEUjBBsxl47as,147
+wirelink/cobs.py,sha256=jW-8XFLZGN4vr0_xV5LcZ5Z_bhrSlninoU6r9hETQLA,1193
+wirelink/codec.py,sha256=Lln4mD6mk1eppkaZwEzs4AbVjxts4-5o-p37QCibrMQ,4288
+wirelink/crc.py,sha256=JHbOZ1sZY8ZUJwalEuMPWDgeqxOt9tkzz5Zn2KkxE3A,364
+wirelink/link.py,sha256=TQmpzkf8v2ZGTegVUaZ3keCxJ8kbshy99LXbJUeMUDA,9817
+wirelink-0.1.0.dist-info/licenses/LICENSE,sha256=97Jp1syvtZ9RqzaKXJsquTEuPZ068tyb2xvPGUX3hSo,1066
+wirelink-0.1.0.dist-info/METADATA,sha256=CCkG6OxZrqtAfSEjI2f2kjhp0vfvuN3lkErDyAVCl3M,1448
+wirelink-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wirelink-0.1.0.dist-info/top_level.txt,sha256=HgMZoSd-75pcm8qdAva9U1zaaohkL1cpnsuy9vSPE7c,9
+wirelink-0.1.0.dist-info/RECORD,,

wirelink-0.1.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
+

wirelink-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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