pyserial-pyusb 0.1.0__tar.gz

pyserial_pyusb-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: pyserial-pyusb
+Version: 0.1.0
+Summary: Pyserial backend for USB serial devices via pyusb (CDC ACM and CP210x)
+Requires-Python: >=3.9
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyusb>=1.3.1
+Provides-Extra: usbip
+Requires-Dist: pyusb-usbip-backend>=0.1.0; extra == "usbip"

pyserial_pyusb-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyserial-pyusb"
+version = "0.1.0"
+description = "Pyserial backend for USB serial devices via pyusb (CDC ACM and CP210x)"
+requires-python = ">=3.9"
+dependencies = [
+    "pyserial>=3.5",
+    "pyusb>=1.3.1",
+]
+
+[project.optional-dependencies]
+usbip = ["pyusb-usbip-backend>=0.1.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyserial_pyusb-0.1.0/setup.cfg

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

pyserial_pyusb-0.1.0/src/pyserial_pyusb.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: pyserial-pyusb
+Version: 0.1.0
+Summary: Pyserial backend for USB serial devices via pyusb (CDC ACM and CP210x)
+Requires-Python: >=3.9
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyusb>=1.3.1
+Provides-Extra: usbip
+Requires-Dist: pyusb-usbip-backend>=0.1.0; extra == "usbip"

pyserial_pyusb-0.1.0/src/pyserial_pyusb.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+pyproject.toml
+src/pyserial_pyusb.egg-info/PKG-INFO
+src/pyserial_pyusb.egg-info/SOURCES.txt
+src/pyserial_pyusb.egg-info/dependency_links.txt
+src/pyserial_pyusb.egg-info/requires.txt
+src/pyserial_pyusb.egg-info/top_level.txt
+src/serial_pyusb/__init__.py
+src/serial_pyusb/serial.py
+src/serial_pyusb/drivers/__init__.py
+src/serial_pyusb/drivers/base.py
+src/serial_pyusb/drivers/cdc_acm.py
+src/serial_pyusb/drivers/cp210x.py
+src/serial_pyusb/urlhandler/__init__.py
+src/serial_pyusb/urlhandler/protocol_pyusb.py
+src/serial_pyusb/urlhandler/protocol_usbip.py

pyserial_pyusb-0.1.0/src/pyserial_pyusb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyserial_pyusb-0.1.0/src/pyserial_pyusb.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pyserial>=3.5
+pyusb>=1.3.1
+
+[usbip]
+pyusb-usbip-backend>=0.1.0

pyserial_pyusb-0.1.0/src/pyserial_pyusb.egg-info/top_level.txt

@@ -0,0 +1 @@
+serial_pyusb

pyserial_pyusb-0.1.0/src/serial_pyusb/__init__.py

@@ -0,0 +1,15 @@
+"""Pyserial backend for USB serial devices via pyusb.
+
+Supports local USB devices (via libusb) and remote devices (via USB/IP).
+"""
+
+from serial_pyusb.serial import Serial
+
+# Auto-register the pyusb:// URL handler with pyserial on import.
+import importlib as _importlib
+_serial_pkg = _importlib.import_module("serial")
+_HANDLER_PACKAGE = "serial_pyusb.urlhandler"
+if _HANDLER_PACKAGE not in _serial_pkg.protocol_handler_packages:
+    _serial_pkg.protocol_handler_packages.append(_HANDLER_PACKAGE)
+
+__all__ = ["Serial"]

pyserial_pyusb-0.1.0/src/serial_pyusb/drivers/__init__.py

@@ -0,0 +1,7 @@
+"""USB serial device drivers."""
+
+from serial_pyusb.drivers.base import USBSerialDriver
+from serial_pyusb.drivers.cdc_acm import CDCACMDriver
+from serial_pyusb.drivers.cp210x import CP210xDriver
+
+__all__ = ["USBSerialDriver", "CDCACMDriver", "CP210xDriver"]

pyserial_pyusb-0.1.0/src/serial_pyusb/drivers/base.py

@@ -0,0 +1,85 @@
+"""Base class for USB serial drivers."""
+
+import usb.core
+import usb.util
+
+
+class USBSerialDriver:
+    """Abstract base for USB serial device drivers.
+
+    Subclasses implement the vendor-specific USB control transfers needed to
+    configure baud rate, line parameters, and modem control signals for a
+    particular USB-to-serial chip.
+    """
+
+    def __init__(self, dev: usb.core.Device):
+        self.dev = dev
+        self.logger = None
+        self._ep_in = None
+        self._ep_out = None
+        self._find_endpoints()
+
+    def _find_endpoints(self):
+        """Locate bulk IN and OUT endpoints on the data interface."""
+        cfg = self.dev.get_active_configuration()
+        intf = self._get_data_interface(cfg)
+        for ep in intf:
+            direction = usb.util.endpoint_direction(ep.bEndpointAddress)
+            ep_type = usb.util.endpoint_type(ep.bmAttributes)
+            if ep_type == usb.util.ENDPOINT_TYPE_BULK:
+                if direction == usb.util.ENDPOINT_IN:
+                    self._ep_in = ep.bEndpointAddress
+                elif direction == usb.util.ENDPOINT_OUT:
+                    self._ep_out = ep.bEndpointAddress
+        if self._ep_in is None or self._ep_out is None:
+            raise usb.core.USBError("Could not find bulk IN/OUT endpoints")
+
+    def _get_data_interface(self, cfg):
+        """Return the USB interface that carries serial data.
+
+        Override in subclasses if the data interface is not interface 0.
+        """
+        return cfg[(0, 0)]
+
+    # -- Methods subclasses must implement --
+
+    def open(self):
+        """Enable the serial interface on the device."""
+        raise NotImplementedError
+
+    def close(self):
+        """Disable the serial interface on the device."""
+        raise NotImplementedError
+
+    def set_baudrate(self, baudrate: int):
+        raise NotImplementedError
+
+    def set_line_params(self, bytesize: int, parity: str, stopbits: float):
+        """Configure data bits, parity, and stop bits."""
+        raise NotImplementedError
+
+    def set_dtr(self, state: bool):
+        raise NotImplementedError
+
+    def set_rts(self, state: bool):
+        raise NotImplementedError
+
+    def get_modem_status(self) -> dict:
+        """Return dict with bool keys: cts, dsr, ri, cd."""
+        return {"cts": True, "dsr": True, "ri": False, "cd": True}
+
+    def set_break(self, state: bool):
+        pass
+
+    # -- Data transfer --
+
+    def write(self, data: bytes, timeout: int = 0) -> int:
+        return self.dev.write(self._ep_out, data, timeout=timeout)
+
+    def read(self, size: int, timeout: int = 0) -> bytes:
+        return bytes(self.dev.read(self._ep_in, size, timeout=timeout))
+
+    @classmethod
+    def matches(cls, dev: usb.core.Device) -> bool:
+        """Return True if this driver can handle the given USB device."""
+        raise NotImplementedError

pyserial_pyusb-0.1.0/src/serial_pyusb/drivers/cdc_acm.py

@@ -0,0 +1,140 @@
+"""Standard USB CDC ACM serial driver."""
+
+import struct
+
+import usb.core
+import usb.util
+
+from serial_pyusb.drivers.base import USBSerialDriver
+
+# CDC class requests
+_SET_LINE_CODING = 0x20
+_GET_LINE_CODING = 0x21
+_SET_CONTROL_LINE_STATE = 0x22
+_SEND_BREAK = 0x23
+
+# Line coding: parity
+_PARITY = {"N": 0, "O": 1, "E": 2, "M": 3, "S": 4}
+
+# Line coding: stop bits
+_STOP_BITS = {1: 0, 1.5: 1, 2: 2}
+
+# USB CDC interface class/subclass
+_CDC_CLASS = 0x02
+_CDC_ACM_SUBCLASS = 0x02
+_CDC_DATA_CLASS = 0x0A
+
+
+class CDCACMDriver(USBSerialDriver):
+    """Driver for standard USB CDC ACM serial devices."""
+
+    def __init__(self, dev: usb.core.Device):
+        self._ctrl_intf = 0
+        self._data_intf = 1
+        self._dtr = False
+        self._rts = False
+        self._baudrate = 9600
+        self._stop_val = 0
+        self._parity_val = 0
+        self._data_bits = 8
+        super().__init__(dev)
+        self._detect_interfaces()
+
+    def _detect_interfaces(self):
+        """Find the CDC control and data interfaces from descriptors."""
+        try:
+            cfg = self.dev.get_active_configuration()
+        except usb.core.USBError:
+            self.dev.set_configuration()
+            cfg = self.dev.get_active_configuration()
+        for intf in cfg:
+            if (intf.bInterfaceClass == _CDC_CLASS and
+                    intf.bInterfaceSubClass == _CDC_ACM_SUBCLASS):
+                self._ctrl_intf = intf.bInterfaceNumber
+            elif intf.bInterfaceClass == _CDC_DATA_CLASS:
+                self._data_intf = intf.bInterfaceNumber
+
+    def _get_data_interface(self, cfg):
+        return cfg[(self._data_intf, 0)]
+
+    def _send_line_state(self):
+        """Send SET_CONTROL_LINE_STATE with current DTR/RTS."""
+        value = (int(self._dtr)) | (int(self._rts) << 1)
+        if self.logger:
+            self.logger.debug("cdc_acm SET_CONTROL_LINE_STATE val=0x%04x (DTR=%s RTS=%s)", value, self._dtr, self._rts)
+        self.dev.ctrl_transfer(
+            0x21, _SET_CONTROL_LINE_STATE, value, self._ctrl_intf, timeout=1000
+        )
+
+    def open(self):
+        self._dtr = True
+        self._rts = True
+        self._send_line_state()
+
+    def close(self):
+        self._dtr = False
+        self._rts = False
+        self._send_line_state()
+
+    def _send_line_coding(self):
+        """Send SET_LINE_CODING with current cached values."""
+        payload = struct.pack(
+            "<IBBB",
+            self._baudrate,
+            self._stop_val,
+            self._parity_val,
+            self._data_bits,
+        )
+        if self.logger:
+            self.logger.debug(
+                "cdc_acm SET_LINE_CODING baud=%d stop=%d parity=%d bits=%d payload=%s",
+                self._baudrate, self._stop_val, self._parity_val, self._data_bits,
+                payload.hex(),
+            )
+        self.dev.ctrl_transfer(
+            0x21, _SET_LINE_CODING, 0, self._ctrl_intf, payload, timeout=1000
+        )
+
+    def set_baudrate(self, baudrate: int):
+        self._baudrate = baudrate
+        self._send_line_coding()
+
+    def set_line_params(self, bytesize: int, parity: str, stopbits: float):
+        self._stop_val = _STOP_BITS.get(stopbits, 0)
+        self._parity_val = _PARITY.get(parity, 0)
+        self._data_bits = bytesize
+        self._send_line_coding()
+
+    def set_dtr(self, state: bool):
+        self._dtr = state
+        self._send_line_state()
+
+    def set_rts(self, state: bool):
+        self._rts = state
+        self._send_line_state()
+
+    def set_break(self, state: bool):
+        # SEND_BREAK: wValue = duration in ms, 0xFFFF = on until cleared, 0 = off
+        value = 0xFFFF if state else 0x0000
+        if self.logger:
+            self.logger.debug("cdc_acm SEND_BREAK val=0x%04x", value)
+        self.dev.ctrl_transfer(
+            0x21, _SEND_BREAK, value, self._ctrl_intf, timeout=1000
+        )
+
+    @classmethod
+    def matches(cls, dev: usb.core.Device) -> bool:
+        """Match any device with a CDC ACM interface."""
+        try:
+            cfg = dev.get_active_configuration()
+        except usb.core.USBError:
+            try:
+                dev.set_configuration()
+                cfg = dev.get_active_configuration()
+            except usb.core.USBError:
+                return False
+        for intf in cfg:
+            if (intf.bInterfaceClass == _CDC_CLASS and
+                    intf.bInterfaceSubClass == _CDC_ACM_SUBCLASS):
+                return True
+        return False

pyserial_pyusb-0.1.0/src/serial_pyusb/drivers/cp210x.py

@@ -0,0 +1,104 @@
+"""Silicon Labs CP210x USB-to-UART driver."""
+
+import struct
+
+import usb.core
+
+from serial_pyusb.drivers.base import USBSerialDriver
+
+# CP210x vendor-specific request codes
+_IFC_ENABLE = 0x00
+_SET_LINE_CTL = 0x03
+_SET_FLOW = 0x13
+_SET_MHS = 0x07
+_GET_MDMSTS = 0x08
+_SET_BAUDRATE = 0x1E
+
+# Line control encoding
+_DATA_BITS = {5: 0x0500, 6: 0x0600, 7: 0x0700, 8: 0x0800}
+_PARITY = {"N": 0x0000, "O": 0x0010, "E": 0x0020, "M": 0x0030, "S": 0x0040}
+_STOP_BITS = {1: 0x0000, 1.5: 0x0100, 2: 0x0200}
+
+# Modem handshake bits
+_DTR_ON = 0x0101
+_DTR_OFF = 0x0100
+_RTS_ON = 0x0202
+_RTS_OFF = 0x0200
+
+# Modem status bits
+_CTS = 0x10
+_DSR = 0x20
+_RI = 0x40
+_DCD = 0x80
+
+# Known CP210x VID/PIDs
+_VID = 0x10C4
+_PIDS = {0xEA60, 0xEA61, 0xEA70, 0xEA80}
+
+
+class CP210xDriver(USBSerialDriver):
+    """Driver for Silicon Labs CP210x USB-to-UART bridges."""
+
+    def __init__(self, dev: usb.core.Device):
+        self._intf = 0
+        super().__init__(dev)
+
+    def _ctrl(self, request, value=0, data=None):
+        """Send a vendor-specific control transfer to the CP210x."""
+        if self.logger:
+            self.logger.debug(
+                "cp210x ctrl_out req=0x%02x val=0x%04x data=%s",
+                request, value, data.hex() if data else None,
+            )
+        if data is not None:
+            self.dev.ctrl_transfer(0x41, request, value, self._intf, data, timeout=1000)
+        else:
+            self.dev.ctrl_transfer(0x41, request, value, self._intf, timeout=1000)
+
+    def _ctrl_in(self, request, length, value=0):
+        """Read a vendor-specific control transfer from the CP210x."""
+        result = self.dev.ctrl_transfer(0xC1, request, value, self._intf, length, timeout=1000)
+        if self.logger:
+            self.logger.debug(
+                "cp210x ctrl_in req=0x%02x val=0x%04x result=%s",
+                request, value, bytes(result).hex(),
+            )
+        return result
+
+    def open(self):
+        self._ctrl(_IFC_ENABLE, 0x0001)
+
+    def close(self):
+        self._ctrl(_IFC_ENABLE, 0x0000)
+
+    def set_baudrate(self, baudrate: int):
+        payload = struct.pack("<I", baudrate)
+        self._ctrl(_SET_BAUDRATE, data=payload)
+
+    def set_line_params(self, bytesize: int, parity: str, stopbits: float):
+        value = _DATA_BITS.get(bytesize, 0x0800) | _PARITY.get(parity, 0) | _STOP_BITS.get(stopbits, 0)
+        self._ctrl(_SET_LINE_CTL, value)
+
+    def set_dtr(self, state: bool):
+        self._ctrl(_SET_MHS, _DTR_ON if state else _DTR_OFF)
+
+    def set_rts(self, state: bool):
+        self._ctrl(_SET_MHS, _RTS_ON if state else _RTS_OFF)
+
+    def get_modem_status(self) -> dict:
+        data = self._ctrl_in(_GET_MDMSTS, 1)
+        status = data[0]
+        return {
+            "cts": bool(status & _CTS),
+            "dsr": bool(status & _DSR),
+            "ri": bool(status & _RI),
+            "cd": bool(status & _DCD),
+        }
+
+    def set_break(self, state: bool):
+        # CP210x SET_BREAK: request 0x05, wValue 1=on 0=off
+        self._ctrl(0x05, 0x0001 if state else 0x0000)
+
+    @classmethod
+    def matches(cls, dev: usb.core.Device) -> bool:
+        return dev.idVendor == _VID and dev.idProduct in _PIDS

pyserial_pyusb-0.1.0/src/serial_pyusb/serial.py

@@ -0,0 +1,480 @@
+"""Pyserial Serial class backed by pyusb.
+
+URL format:
+    pyusb://host[:port]/VID:PID[?serial=X&instance=N&logging=LEVEL]
+    pyusb:///direct/VID:PID[?serial=X&instance=N&logging=LEVEL]
+
+Remote examples (via USB/IP):
+    pyusb://192.168.1.20/10c4:ea60
+    pyusb://192.168.1.20:3240/10c4:ea60?serial=0001
+    pyusb://192.168.1.20/10c4:ea60?logging=debug
+
+Local examples (direct via libusb):
+    pyusb:///direct/10c4:ea60
+    pyusb:///direct/10c4:ea60?serial=0001&instance=1
+"""
+
+import errno
+import logging
+import time
+import urllib.parse
+
+import usb.core
+import usb.util
+
+from serial.serialutil import (
+    SerialBase,
+    SerialException,
+    PortNotOpenError,
+    to_bytes,
+)
+
+from serial_pyusb.drivers.cp210x import CP210xDriver
+from serial_pyusb.drivers.cdc_acm import CDCACMDriver
+
+LOGGER_NAME = "pySerial.pyusb"
+
+# Driver classes in priority order (most specific first)
+_DRIVERS = [CP210xDriver, CDCACMDriver]
+
+
+def _select_driver(dev):
+    """Auto-select a driver for the given USB device."""
+    for cls in _DRIVERS:
+        if cls.matches(dev):
+            return cls(dev)
+    raise SerialException(
+        f"No driver found for USB device "
+        f"{dev.idVendor:04x}:{dev.idProduct:04x}"
+    )
+
+
+class Serial(SerialBase):
+    """Pyserial port backed by a USB serial device via pyusb."""
+
+    BAUDRATES = (
+        50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800,
+        9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000,
+        576000, 921600, 1000000, 1152000, 1500000, 2000000, 2500000,
+        3000000, 3500000, 4000000,
+    )
+
+    # Minimum USB bulk read size — USB bulk transfers deliver whole
+    # packets, so requesting fewer bytes than the device sends causes
+    # EOVERFLOW.  64 bytes matches the full-speed bulk max packet size.
+    _USB_READ_SIZE = 64
+
+    def __init__(self, *args, **kwargs):
+        self._backend = None
+        self._usb_dev = None
+        self._driver = None
+        self._driver_cls = None
+        self.logger = None
+        self._last_baudrate = None
+        self._last_line_params = None
+        self._read_buf = bytearray()
+        super().__init__(*args, **kwargs)
+
+    def open(self):
+        if self.is_open:
+            raise SerialException("Port is already open.")
+        if self._port is None:
+            raise SerialException("Port must be configured before it can be used.")
+
+        params = self._parse_url(self.portstr)
+
+        if self._backend is not None:
+            # Reopen after close — use reconnect logic which reuses the
+            # existing connection instead of opening a new one
+            # (USB/IP servers are often single-connection).
+            self.is_open = True
+            self._reconnect_driver()
+            if not self._dsrdtr:
+                self._update_dtr_state()
+            if not self._rtscts:
+                self._update_rts_state()
+            return
+
+        if params["host"] is not None:
+            from usbip_backend import get_backend
+            self._backend = get_backend(params["host"], port=params["port"])
+        else:
+            self._backend = None  # use default pyusb backend (libusb)
+
+        find_kwargs = {
+            "idVendor": params["vid"],
+            "idProduct": params["pid"],
+        }
+        if self._backend is not None:
+            find_kwargs["backend"] = self._backend
+        if params["serial"] is not None:
+            find_kwargs["serial_number"] = params["serial"]
+
+        # Find matching device(s)
+        instance = params["instance"]
+        if instance > 0:
+            devs = list(usb.core.find(find_all=True, **find_kwargs))
+            if instance >= len(devs):
+                raise SerialException(
+                    f"USB device {params['vid']:04x}:{params['pid']:04x} "
+                    f"instance {instance} not found "
+                    f"({len(devs)} device(s) available)"
+                )
+            self._usb_dev = devs[instance]
+        else:
+            self._usb_dev = usb.core.find(**find_kwargs)
+
+        if self._usb_dev is None:
+            raise SerialException(
+                f"USB device {params['vid']:04x}:{params['pid']:04x} not found"
+            )
+
+        self._driver = _select_driver(self._usb_dev)
+        self._driver_cls = type(self._driver)
+        self._driver.logger = self.logger
+        if self.logger:
+            self.logger.info(
+                "opened %04x:%04x using %s",
+                self._usb_dev.idVendor, self._usb_dev.idProduct,
+                type(self._driver).__name__,
+            )
+        self._driver.open()
+        self.is_open = True
+        self._reconfigure_port()
+        if not self._dsrdtr:
+            self._update_dtr_state()
+        if not self._rtscts:
+            self._update_rts_state()
+
+    def close(self):
+        if self.is_open:
+            try:
+                self._driver.close()
+            except Exception:
+                pass
+            self._driver = None
+            # Keep self._backend and self._usb_dev alive for reuse on reopen
+            self.is_open = False
+        super().close()
+
+    def _reconfigure_port(self):
+        if not self.is_open:
+            return
+        if self._baudrate != self._last_baudrate:
+            self._driver.set_baudrate(self._baudrate)
+            self._last_baudrate = self._baudrate
+        line_params = (self._bytesize, self._parity, self._stopbits)
+        if line_params != self._last_line_params:
+            self._driver.set_line_params(*line_params)
+            self._last_line_params = line_params
+
+    def _parse_url(self, url):
+        """Parse a pyusb:// URL and return a dict of connection parameters.
+
+        Formats:
+            pyusb://host[:port]/VID:PID[?serial=X&instance=N&logging=LEVEL]
+            pyusb:///direct/VID:PID[?serial=X&instance=N&logging=LEVEL]
+        """
+        parts = urllib.parse.urlsplit(url)
+        if parts.scheme == "usbip":
+            raise SerialException(
+                'The usbip:// scheme has been replaced by pyusb://. '
+                'Use pyusb://host[:port]/VID:PID instead of usbip://host/busid'
+            )
+        if parts.scheme != "pyusb":
+            raise SerialException(
+                f'Expected URL starting with "pyusb://", got {parts.scheme!r}'
+            )
+
+        query = urllib.parse.parse_qs(parts.query)
+
+        # Logging setup
+        if "logging" in query:
+            level_name = query["logging"][0].upper()
+            level = getattr(logging, level_name, None)
+            if level is not None:
+                self.logger = logging.getLogger(LOGGER_NAME)
+                self.logger.setLevel(level)
+                logging.basicConfig()
+
+        host = parts.hostname or None
+        port = parts.port or 3240
+
+        path = parts.path.lstrip("/")
+
+        # Local/direct mode: pyusb:///direct/VID:PID
+        if path.startswith("direct/"):
+            if host is not None:
+                raise SerialException(
+                    f'"direct" mode cannot be used with a host: {url}'
+                )
+            host = None
+            vid_pid = path[len("direct/"):]
+        elif host is not None:
+            # Remote mode: pyusb://host/VID:PID
+            vid_pid = path
+        else:
+            raise SerialException(
+                f'Expected a host or "direct/" prefix. '
+                f'Format: pyusb://host/VID:PID or pyusb:///direct/VID:PID'
+            )
+
+        # Parse VID:PID
+        if ":" not in vid_pid:
+            raise SerialException(
+                f"Expected VID:PID in URL path, got {vid_pid!r}"
+            )
+        try:
+            vid_str, pid_str = vid_pid.split(":", 1)
+            vid = int(vid_str, 16)
+            pid = int(pid_str, 16)
+        except ValueError:
+            raise SerialException(
+                f"Invalid VID:PID {vid_pid!r} — expected hex values like 10c4:ea60"
+            )
+
+        serial = query.get("serial", [None])[0]
+        instance = int(query.get("instance", [0])[0])
+
+        return {
+            "host": host,
+            "port": port,
+            "vid": vid,
+            "pid": pid,
+            "serial": serial,
+            "instance": instance,
+        }
+
+    # -- Reconnect handling --
+
+    # Maximum time (seconds) to wait for a device to re-enumerate after
+    # a disconnect (e.g. ESP32 resetting into bootloader mode).
+    _RECONNECT_TIMEOUT = 5.0
+    _RECONNECT_INTERVAL = 0.1
+
+    def _is_connection_error(self, exc):
+        """Return True if the USBError indicates a broken connection."""
+        msg = str(exc).lower()
+        return any(k in msg for k in ("connection closed", "receive timeout",
+                                       "send failed", "receive failed"))
+
+    def _clear_backend_cache(self):
+        """Clear cached descriptors so the driver reads fresh ones."""
+        if self._backend is not None and hasattr(self._backend, "_cache"):
+            self._backend._cache.clear()
+
+    def _reconnect_driver(self):
+        """Rebuild the driver after a disconnect.
+
+        For USB/IP backends, the backend's _reopen() (triggered on the
+        next submit()) handles the TCP reconnect and re-import
+        automatically.  We just need to rebuild the driver so it picks
+        up fresh endpoint info, then reconfigure baud/line params.
+
+        Does NOT call driver.open() or touch modem control lines -- the
+        caller (esptool reset logic) is in charge of DTR/RTS sequencing.
+        """
+        driver_cls = self._driver_cls or type(self._driver)
+        self._clear_backend_cache()
+        deadline = time.monotonic() + self._RECONNECT_TIMEOUT
+        while True:
+            try:
+                self._driver = driver_cls(self._usb_dev)
+                self._driver.logger = self.logger
+                self._last_baudrate = None
+                self._last_line_params = None
+                self._read_buf.clear()
+                self._reconfigure_port()
+                if self.logger:
+                    self.logger.info("reconnected")
+                return
+            except (usb.core.USBError, SerialException) as e:
+                if time.monotonic() >= deadline:
+                    raise SerialException(
+                        f"Device did not recover within "
+                        f"{self._RECONNECT_TIMEOUT}s: {e}"
+                    )
+                if self.logger:
+                    self.logger.debug("reconnect attempt failed: %s, retrying...", e)
+                self._clear_backend_cache()
+                time.sleep(self._RECONNECT_INTERVAL)
+
+    # -- Read / Write --
+
+    def read(self, size=1):
+        if not self.is_open:
+            raise PortNotOpenError()
+        if size == 0:
+            return b""
+
+        # Convert pyserial timeout convention to USB timeout in ms.
+        # None = blocking (very long timeout), 0 = non-blocking, float = seconds
+        if self._timeout is None:
+            usb_timeout = 0  # pyusb 0 = unlimited
+        elif self._timeout == 0:
+            usb_timeout = 1  # minimal non-blocking
+        else:
+            usb_timeout = int(self._timeout * 1000)
+
+        data = bytearray()
+        # Return buffered data first
+        if self._read_buf:
+            n = min(size, len(self._read_buf))
+            data.extend(self._read_buf[:n])
+            del self._read_buf[:n]
+
+        while len(data) < size:
+            # Always read at least _USB_READ_SIZE to avoid EOVERFLOW
+            # on USB bulk endpoints.
+            read_size = max(size - len(data), self._USB_READ_SIZE)
+            try:
+                chunk = self._driver.read(read_size, timeout=usb_timeout)
+                needed = size - len(data)
+                data.extend(chunk[:needed])
+                if len(chunk) > needed:
+                    self._read_buf.extend(chunk[needed:])
+            except usb.core.USBTimeoutError:
+                break
+            except usb.core.USBError as e:
+                if "timeout" in str(e).lower():
+                    break
+                if self._is_connection_error(e):
+                    if self.logger:
+                        self.logger.info("read: connection lost, reconnecting...")
+                    self._reconnect_driver()
+                    continue
+                raise SerialException(f"USB read error: {e}")
+            # After first chunk, don't block waiting for more
+            if self._timeout is not None:
+                break
+        if self.logger:
+            self.logger.debug("read %d bytes: %s", len(data), data.hex())
+        return bytes(data)
+
+    def write(self, data):
+        if not self.is_open:
+            raise PortNotOpenError()
+        data = to_bytes(data)
+        if not data:
+            return 0
+
+        if self._write_timeout is None:
+            usb_timeout = 0
+        elif self._write_timeout == 0:
+            usb_timeout = 1
+        else:
+            usb_timeout = int(self._write_timeout * 1000)
+
+        if self.logger:
+            self.logger.debug("write %d bytes: %s", len(data), data.hex())
+        try:
+            return self._driver.write(data, timeout=usb_timeout)
+        except usb.core.USBError as e:
+            if self._is_connection_error(e):
+                if self.logger:
+                    self.logger.info("write: connection lost, reconnecting...")
+                self._reconnect_driver()
+                return self._driver.write(data, timeout=usb_timeout)
+            raise SerialException(f"USB write error: {e}")
+
+    @property
+    def in_waiting(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        # USB bulk endpoints don't have a queryable input buffer size
+        return 0
+
+    def reset_input_buffer(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        # USB bulk endpoints don't buffer data on our side, so there's
+        # nothing to drain.  Attempting a short-timeout USB read over
+        # USB/IP is expensive due to server-side timeout margins.
+
+    def reset_output_buffer(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+
+    def fileno(self):
+        raise OSError(errno.ENOTTY, "pyusb serial port has no file descriptor")
+
+    def setDTR(self, state):
+        self.dtr = state
+
+    def setRTS(self, state):
+        self.rts = state
+
+    def flush(self):
+        if not self.is_open:
+            return
+
+    # -- Modem control lines --
+
+    def _update_rts_state(self):
+        if self.is_open:
+            try:
+                self._driver.set_rts(self._rts_state)
+            except usb.core.USBError as e:
+                if self._is_connection_error(e):
+                    self._reconnect_driver()
+                    self._driver.set_rts(self._rts_state)
+                else:
+                    raise
+
+    def _update_dtr_state(self):
+        if self.is_open:
+            try:
+                self._driver.set_dtr(self._dtr_state)
+            except usb.core.USBError as e:
+                if self._is_connection_error(e):
+                    self._reconnect_driver()
+                    self._driver.set_dtr(self._dtr_state)
+                else:
+                    raise
+
+    def _update_break_state(self):
+        if self.is_open:
+            try:
+                self._driver.set_break(self._break_state)
+            except usb.core.USBError as e:
+                if self._is_connection_error(e):
+                    self._reconnect_driver()
+                    self._driver.set_break(self._break_state)
+                else:
+                    raise
+
+    @property
+    def pid(self):
+        if self._usb_dev is not None:
+            return self._usb_dev.idProduct
+        return None
+
+    @property
+    def vid(self):
+        if self._usb_dev is not None:
+            return self._usb_dev.idVendor
+        return None
+
+    @property
+    def cts(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._driver.get_modem_status()["cts"]
+
+    @property
+    def dsr(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._driver.get_modem_status()["dsr"]
+
+    @property
+    def ri(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._driver.get_modem_status()["ri"]
+
+    @property
+    def cd(self):
+        if not self.is_open:
+            raise PortNotOpenError()
+        return self._driver.get_modem_status()["cd"]

pyserial_pyusb-0.1.0/src/serial_pyusb/urlhandler/protocol_pyusb.py

@@ -0,0 +1,10 @@
+"""Pyserial URL handler for pyusb:// scheme.
+
+Register this handler by calling serial_pyusb.register() or by
+appending 'serial_pyusb.urlhandler' to serial.protocol_handler_packages
+before calling serial.serial_for_url().
+"""
+
+from serial_pyusb.serial import Serial
+
+__all__ = ["Serial"]

pyserial_pyusb-0.1.0/src/serial_pyusb/urlhandler/protocol_usbip.py

@@ -0,0 +1,10 @@
+"""Pyserial URL handler for usbip:// scheme.
+
+Register this handler by calling serial_pyusb.register() or by
+appending 'serial_pyusb.urlhandler' to serial.protocol_handler_packages
+before calling serial.serial_for_url().
+"""
+
+from serial_pyusb.serial import Serial
+
+__all__ = ["Serial"]