espbridge 1.0.0__py3-none-any.whl

espbridge/__init__.py

@@ -0,0 +1,96 @@
+"""
+espbridge - Framed USB bridge protocol for ESP32 <-> Termux/Linux, no root required.
+
+Typical usage:
+
+    import espbridge as eb
+
+    backend = eb.detect_backend()
+    if backend == "termux":
+        path = eb.auto_detect_device()
+        eb.request_permission(path)
+        # ... open_usb_device() re-execs your script with TERMUX_USB_FD set ...
+        device = eb.wrap_fd(int(os.environ["TERMUX_USB_FD"]))
+    else:
+        device = eb.wrap_direct()
+
+    ep_in, ep_out, iface = eb.get_cdc_endpoints(device)
+    eb.claim_device(device, iface, fd_wrapped=(backend == "termux"))
+    eb.reset_endpoint_toggles(device, ep_in, ep_out)
+
+    sender   = eb.Sender(device, ep_out)
+    receiver = eb.ReceiverThread(device, ep_in)
+    receiver.start()
+
+    proto = eb.Protocol(sender, receiver)
+    proto.start()
+
+    resp = proto.send_cmd("PING")
+    print(resp)   # -> {"ok": True, "msg": "pong"}  (if your firmware implements PING)
+
+See examples/echo_cmd.py for a complete runnable version of the above, and
+the companion BridgeProtocol PlatformIO library for the ESP32-side firmware
+that speaks the same frames.
+"""
+
+from .protocol import (
+    Protocol,
+    FrameParser,
+    build_frame,
+    build_cmd,
+    build_ack,
+    build_html_frame,
+    MAGIC,
+    TYPE_CMD,
+    TYPE_RESP,
+    TYPE_EVENT,
+    TYPE_PCAP,
+    TYPE_ACK,
+    TYPE_HTML,
+    HEADER_SIZE,
+    MAX_PAYLOAD,
+)
+from .sender import Sender
+from .receiver import ReceiverThread
+from .usb_device import (
+    detect_backend,
+    is_root,
+    has_termux_api,
+    list_usb_devices,
+    request_permission,
+    open_usb_device,
+    auto_detect_device,
+    launch_with_fd,
+    relaunch_with_fd,
+    wrap_fd,
+    wrap_direct,
+    find_usb_device_direct,
+    claim_device,
+    get_cdc_endpoints,
+    reset_endpoint_toggles,
+    describe_device,
+    init_uart_bridge,
+    set_uart_bridge_baud,
+    is_uart_bridge,
+    set_dtr_rts,
+    UART_BRIDGE_VIDPIDS,
+    ESP32_KNOWN,
+)
+
+__all__ = [
+    # protocol
+    "Protocol", "FrameParser", "build_frame", "build_cmd", "build_ack", "build_html_frame",
+    "MAGIC", "TYPE_CMD", "TYPE_RESP", "TYPE_EVENT", "TYPE_PCAP", "TYPE_ACK", "TYPE_HTML",
+    "HEADER_SIZE", "MAX_PAYLOAD",
+    # transport
+    "Sender", "ReceiverThread",
+    # device / backend
+    "detect_backend", "is_root", "has_termux_api",
+    "list_usb_devices", "request_permission", "open_usb_device", "auto_detect_device",
+    "launch_with_fd", "relaunch_with_fd", "wrap_fd", "wrap_direct", "find_usb_device_direct",
+    "claim_device", "get_cdc_endpoints", "reset_endpoint_toggles",
+    "describe_device", "init_uart_bridge", "set_uart_bridge_baud", "is_uart_bridge",
+    "set_dtr_rts", "UART_BRIDGE_VIDPIDS", "ESP32_KNOWN",
+]
+
+__version__ = "1.0.0"

espbridge/protocol.py

@@ -0,0 +1,292 @@
+"""
+protocol.py - Framed binary bridge protocol for ESP32 <-> host communication
+over USB CDC. Part of the `espbridge` library — use this to build your own
+ESP32-to-Termux (or ESP32-to-Linux) tools without root, without a serial
+line-protocol, and without writing USB framing code yourself.
+
+Pairs with the matching BridgeProtocol.h/.cpp PlatformIO library on the
+ESP32 side. Both speak the exact same frame layout, so any command/response/
+event you invent will round-trip correctly as long as the two are kept in
+sync.
+
+Frame layout:
+  [MAGIC 2B][TYPE 1B][ID 1B][LENGTH 4B LE][PAYLOAD NB]
+
+Types:
+  0x01  CMD        Host  -> ESP32   JSON command
+  0x02  RESP       ESP32 -> Host    JSON response (mirrors CMD id)
+  0x03  EVENT      ESP32 -> Host    JSON async event (id=0)
+  0x04  PCAP       ESP32 -> Host    binary chunk  (id = chunk index) — use
+                                     for any binary stream, not just pcap
+  0x05  ACK        Host  -> ESP32   JSON {"chunk": N}
+  0x06  HTML       Host  -> ESP32   chunked raw payload (e.g. web UI upload)
+"""
+
+import json
+import struct
+import threading
+import queue
+import time
+
+MAGIC        = b'\xAD\xDE'
+TYPE_CMD     = 0x01
+TYPE_RESP    = 0x02
+TYPE_EVENT   = 0x03
+TYPE_PCAP    = 0x04
+TYPE_ACK     = 0x05
+TYPE_HTML    = 0x06
+HEADER_SIZE  = 8          # 2 magic + 1 type + 1 id + 4 length (LE)
+MAX_PAYLOAD  = 65536      # sanity cap; real chunks are ≤512 B
+
+
+def build_html_frame(seq: int, chunk: bytes, is_last: bool) -> bytes:
+    # 2-byte seq (LE) + 1-byte is_last flag + raw chunk data
+    inner = struct.pack('<HB', seq, 1 if is_last else 0) + chunk
+    return build_frame(TYPE_HTML, 0, inner)
+
+#  Frame building 
+
+def build_frame(ptype: int, pid: int, payload: bytes) -> bytes:
+    header = MAGIC + struct.pack('<BBL', ptype, pid, len(payload))
+    return header + payload
+
+def build_cmd(cmd: str, args: dict = None, pid: int = 0) -> bytes:
+    payload = json.dumps({"cmd": cmd, "args": args or {}}).encode()
+    return build_frame(TYPE_CMD, pid, payload)
+
+def build_ack(chunk_index: int) -> bytes:
+    payload = json.dumps({"chunk": chunk_index}).encode()
+    return build_frame(TYPE_ACK, 0, payload)
+
+
+#  Frame parsing ─
+
+class FrameParser:
+    """
+    Stateful streaming parser.
+    Feed raw bytes in any chunk size, get complete frame dicts out.
+    Uses bytearray internally to avoid O(n²) bytes concatenation.
+    """
+
+    def __init__(self):
+        self._buf = bytearray()
+
+    def reset(self):
+        self._buf = bytearray()
+
+    def feed(self, data: bytes) -> list:
+        """Feed raw bytes. Returns list of parsed frame dicts (may be empty)."""
+        self._buf += data
+        frames = []
+        while True:
+            frame = self._try_parse()
+            if frame is None:
+                break
+            frames.append(frame)
+        return frames
+
+    def _try_parse(self):
+        buf = self._buf
+
+        if len(buf) < HEADER_SIZE:
+            return None
+
+        # Resync on bad magic
+        if buf[0] != 0xAD or buf[1] != 0xDE:
+            idx = buf.find(b'\xAD\xDE', 1)
+            if idx == -1:
+                self._buf = bytearray(buf[-1:]) if buf else bytearray()
+                return None
+            del self._buf[:idx]
+            buf = self._buf
+            if len(buf) < HEADER_SIZE:
+                return None
+
+        ptype, pid, length = struct.unpack_from('<BBL', buf, 2)
+
+        if length > MAX_PAYLOAD:
+            del self._buf[:2]
+            return None
+
+        total = HEADER_SIZE + length
+        if len(buf) < total:
+            return None
+
+        payload = bytes(buf[HEADER_SIZE:total])
+        del self._buf[:total]
+
+        return {
+            "type":    ptype,
+            "id":      pid,
+            "length":  length,
+            "payload": payload,
+            "json":    _safe_json(payload) if ptype != TYPE_PCAP else None,
+        }
+
+
+def _safe_json(data: bytes):
+    try:
+        return json.loads(data)
+    except Exception:
+        return None
+
+
+
+class Protocol:
+    """
+    Wraps a Sender + ReceiverThread with framed protocol logic.
+
+    Usage:
+        proto = Protocol(sender, receiver)
+        proto.start()
+
+        resp = proto.send_cmd("SCAN_WIFI", timeout=30)
+
+        proto.on_event = lambda ev: ...     # called in dispatch thread
+        proto.on_pcap  = lambda data, idx: ...
+    """
+
+    def __init__(self, sender, receiver_thread):
+        self._tx       = sender
+        self._rx       = receiver_thread
+        self._parser   = FrameParser()
+        self._pending  = {}              # pid -> {"event": Event, "result": any}
+        self._lock     = threading.Lock()
+        self._id_ctr   = 1
+        self._running  = False
+
+        self._dispatch_q  = queue.Queue(maxsize=2048)
+        self._html_resp_q  = queue.Queue(maxsize=16)
+
+        self.on_event  = None   # fn(frame_dict)
+        self.on_pcap   = None   # fn(data: bytes, chunk_idx: int)
+        self.log       = print
+
+    def start(self):
+        self._running = True
+        self._parser.reset()
+
+        t_rx = threading.Thread(target=self._read_loop,
+                                daemon=True, name="proto-rx")
+        t_rx.start()
+
+        t_cb = threading.Thread(target=self._callback_loop,
+                                daemon=True, name="proto-cb")
+        t_cb.start()
+
+    def stop(self):
+        self._running = False
+        with self._lock:
+            for entry in self._pending.values():
+                entry["event"].set()
+
+    def reset(self):
+        """Clear parser state and pending commands. Call between retries."""
+        self._parser.reset()
+        with self._lock:
+            for entry in self._pending.values():
+                entry["event"].set()
+            self._pending.clear()
+
+    def send_cmd(self, cmd: str, args: dict = None, timeout: float = 5.0):
+        """
+        Send a CMD frame, block until the matching RESP arrives.
+        Returns the response JSON dict, or None on timeout.
+        """
+        with self._lock:
+            # Pick an ID not currently in use
+            pid = self._id_ctr & 0xFF
+            while pid in self._pending or pid == 0:
+                self._id_ctr = (self._id_ctr % 254) + 1
+                pid = self._id_ctr & 0xFF
+            self._id_ctr = (self._id_ctr % 254) + 1
+
+            evt = threading.Event()
+            self._pending[pid] = {"event": evt, "result": None}
+
+        frame = build_cmd(cmd, args or {}, pid)
+        self._tx.send_bytes(frame)
+        self.log(f"[proto] >> CMD id={pid} cmd={cmd}")
+
+        evt.wait(timeout=timeout)
+
+        with self._lock:
+            entry = self._pending.pop(pid, None)
+
+        if entry and entry["result"] is not None:
+            return entry["result"]
+
+        self.log(f"[proto] CMD id={pid} '{cmd}' timed out after {timeout}s")
+        return None
+
+    def send_ack(self, chunk_index: int):
+        self._tx.send_bytes(build_ack(chunk_index))
+
+    def _read_loop(self):
+        while self._running:
+            raw = self._rx.readline_bytes(timeout=0.01)   # 10 ms poll
+            if not raw:
+                continue
+            for frame in self._parser.feed(raw):
+                self._dispatch(frame)
+
+    def _dispatch(self, frame: dict):
+        t = frame["type"]
+
+        if t == TYPE_RESP:
+            pid = frame["id"]
+            if pid == 0:
+                # Raw HTML chunk ACK — goes to its own queue, not the shared one
+                try:
+                    self._html_resp_q.put_nowait(frame["json"])
+                except queue.Full:
+                    pass
+            else:
+                with self._lock:
+                    entry = self._pending.get(pid)
+                if entry:
+                    entry["result"] = frame["json"]
+                    entry["event"].set()
+
+        elif t == TYPE_EVENT:
+            try:
+                self._dispatch_q.put_nowait(("event", frame["json"]))
+            except queue.Full:
+                pass
+
+        elif t == TYPE_PCAP:
+            idx = frame["id"]
+            self.send_ack(idx)
+            try:
+                self._dispatch_q.put_nowait(("pcap", frame["payload"], idx))
+            except queue.Full:
+                pass
+
+    def _wait_html_resp(self, expected_seq, timeout=3.0):
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            try:
+                resp = self._html_resp_q.get(timeout=remaining)
+            except queue.Empty:
+                return None
+            if resp and resp.get("seq") == expected_seq:
+                return resp
+
+    def _callback_loop(self):
+        while self._running:
+            try:
+                item = self._dispatch_q.get(timeout=0.05)
+            except queue.Empty:
+                continue
+
+            kind = item[0]
+            try:
+                if kind == "event" and self.on_event:
+                    self.on_event(item[1])
+                elif kind == "pcap" and self.on_pcap:
+                    self.on_pcap(item[1], item[2])
+            except Exception as e:
+                self.log(f"[proto] callback error: {e}")

espbridge/receiver.py

@@ -0,0 +1,129 @@
+"""
+receiver.py - Background thread reading raw bytes from the ESP32's USB bulk
+IN endpoint. Part of the `espbridge` library.
+"""
+
+import threading
+import queue
+import time
+import usb.core
+
+# How many raw-byte chunks to buffer before dropping oldest.
+# 512 × 16 KB = 8 MB max memory - comfortable on any modern phone.
+_BYTE_QUEUE_DEPTH = 512
+_LINE_QUEUE_DEPTH = 256
+_READ_SIZE        = 16 * 1024   # 16 KB per bulk read
+_USB_TIMEOUT_MS   = 100         # tighter poll → lower latency
+
+
+class ReceiverThread(threading.Thread):
+    def __init__(self, device, ep_in_addr: int, log_func=None):
+        super().__init__(daemon=True, name="ESP32-Receiver")
+        self.device      = device
+        self.ep_in_addr  = ep_in_addr
+        self.log         = log_func or print
+        self._line_queue = queue.Queue(maxsize=_LINE_QUEUE_DEPTH)
+        self._byte_queue = queue.Queue(maxsize=_BYTE_QUEUE_DEPTH)
+        self._stop_event = threading.Event()
+        self._buf        = b""          # only used for line splitting
+        self._error_count = 0
+
+    def stop(self):
+        self._stop_event.set()
+
+    def readline(self, timeout: float = None) -> "str | None":
+        """Get next text line (for READY handshake / debug). Non-blocking with timeout."""
+        try:
+            return self._line_queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def readline_bytes(self, timeout: float = None) -> "bytes | None":
+        """Get next raw USB chunk for the framed protocol parser."""
+        try:
+            return self._byte_queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def drain_stale(self, duration: float = 0.5):
+        """
+        Discard any bytes sitting in our internal queues that were filled by
+        the receiver thread from a previous session.
+
+        IMPORTANT: Do NOT call device.read() here - the receiver thread owns
+        the USB endpoint exclusively. Calling read() from a second thread
+        causes libusb on Android to return corrupt data or lock up the
+        endpoint, which is what causes the 30-second hang on the second run.
+
+        Instead we just drain the software queues. The receiver thread is
+        already running and will have consumed any hardware FIFO leftovers
+        within a few hundred ms via its normal poll loop.
+        """
+        deadline = time.monotonic() + duration
+        drained = 0
+        while time.monotonic() < deadline:
+            drained_this_round = 0
+            try:
+                self._byte_queue.get_nowait()
+                drained += 1
+                drained_this_round += 1
+            except queue.Empty:
+                pass
+            try:
+                self._line_queue.get_nowait()
+                drained_this_round += 1
+            except queue.Empty:
+                pass
+            if drained_this_round == 0:
+                time.sleep(0.02)
+        self._buf = b""
+
+
+    def run(self):
+        while not self._stop_event.is_set():
+            try:
+                chunk = bytes(self.device.read(self.ep_in_addr, _READ_SIZE,
+                                               timeout=_USB_TIMEOUT_MS))
+                if not chunk:
+                    continue
+
+                self._error_count = 0
+                try:
+                    self._byte_queue.put_nowait(chunk)
+                except queue.Full:
+                    try:
+                        self._byte_queue.get_nowait()
+                    except queue.Empty:
+                        pass
+                    self._byte_queue.put_nowait(chunk)
+
+                self._buf += chunk
+                self._flush_lines()
+
+            except usb.core.USBTimeoutError:
+                continue
+
+            except usb.core.USBError as e:
+                code = getattr(e, 'errno', None)
+
+                if code in (None, 32, 75):
+                    self._error_count += 1
+                    if self._error_count <= 5:
+                        self.log(f"USB error (recoverable, #{self._error_count}): {e}")
+                    time.sleep(min(0.05 * self._error_count, 0.3))
+                    continue
+                else:
+                    self.log(f"fatal USB error: {e}")
+                    break
+
+
+    def _flush_lines(self):
+        """Split accumulated buffer into newline-delimited text lines."""
+        while b"\n" in self._buf:
+            line, self._buf = self._buf.split(b"\n", 1)
+            text = line.rstrip(b"\r").decode("utf-8", errors="replace").strip()
+            if text:
+                try:
+                    self._line_queue.put_nowait(text)
+                except queue.Full:
+                    pass   # don't block on debug lines

espbridge/sender.py

@@ -0,0 +1,47 @@
+"""
+sender.py - Thread-safe sender for the ESP32's USB bulk OUT endpoint.
+Part of the `espbridge` library.
+"""
+
+import threading
+import time
+import usb.core
+
+_DEFAULT_TIMEOUT_MS = 3000   # USB write timeout
+_MAX_RETRIES        = 2
+
+
+class Sender:
+    def __init__(self, device, ep_out_addr: int, log_func=None,
+                 timeout_ms: int = _DEFAULT_TIMEOUT_MS):
+        self.device       = device
+        self.ep_out_addr  = ep_out_addr
+        self.log          = log_func or print
+        self._timeout_ms  = timeout_ms
+        self._lock        = threading.Lock()
+
+
+    def send_bytes(self, data: bytes) -> bool:
+        """
+        Send raw bytes with retry on recoverable USB errors.
+        Thread-safe. Returns True on success.
+        """
+        with self._lock:
+            for attempt in range(_MAX_RETRIES):
+                try:
+                    self.device.write(self.ep_out_addr, data,
+                                      timeout=self._timeout_ms)
+                    return True
+                except usb.core.USBError as e:
+                    code = getattr(e, 'errno', None)
+                    if code in (32, 75) and attempt < _MAX_RETRIES - 1:
+                        time.sleep(0.02 * (attempt + 1))
+                        continue
+                    self.log(f"[sender] write error (attempt {attempt+1}): {e}")
+                    return False
+        return False
+
+    def send(self, message: str, newline: bool = True) -> bool:
+        """Send a UTF-8 string (legacy text mode, still used for debug)."""
+        data = (message + "\n" if newline else message).encode("utf-8")
+        return self.send_bytes(data)

espbridge/usb_device.py

@@ -0,0 +1,636 @@
+"""
+usb_device.py - Auto-detect an ESP32 over USB and wrap it for libusb, with or
+without root. Part of the `espbridge` library.
+
+Supports two backends selected automatically at runtime:
+
+  termux   - No-root Termux: all USB access goes through the Android USB host
+             stack via termux-api Usb + TERMUX_USB_FD.  The two-process
+             bootstrap dance (parent requests permission -> child inherits fd)
+             is required.  Works on stock Android with Termux + Termux:API.
+
+  root     - Running as uid 0 (Termux:Root, Nethunter terminal, plain Linux,
+             etc.): libusb opens /dev/bus/usb directly - no termux-api
+             binary, no Android permission dialog, no child process needed.
+
+Call detect_backend() early in main() to pick the right path.
+All other public helpers work the same regardless of backend.
+"""
+
+import os
+import json
+import ctypes
+import usb.core
+import usb.backend.libusb1 as libusb1
+
+_TERMUX_API = "/data/data/com.termux/files/usr/libexec/termux-api"
+
+# Known ESP32 native USB VID:PIDs
+ESP32_KNOWN = {
+    (0x303A, 0x1001): "ESP32 native USB CDC",
+    (0x303A, 0x0002): "ESP32 native USB CDC",
+    (0x10C4, 0xEA60): "CP2102 (ESP32 devboard)",
+    (0x1A86, 0x7523): "CH340 (ESP32 devboard)",
+    (0x1A86, 0x55D4): "CH9102 (ESP32 devboard)",
+    (0x0403, 0x6001): "FTDI FT232 (ESP32 devboard)",
+}
+
+
+# Runtime environment detection
+
+def is_root() -> bool:
+    """Returns True if the current process is running as uid 0."""
+    return os.getuid() == 0
+
+
+def has_termux_api() -> bool:
+    """Returns True if the termux-api binary is present (Termux environment)."""
+    return os.path.isfile(_TERMUX_API)
+
+
+def detect_backend() -> str:
+    """
+    Determine which USB access backend to use and return its name.
+
+    Decision order:
+      1. uid == 0              -> 'root'   (Nethunter, Termux:Root, sudo)
+      2. termux-api present    -> 'termux' (stock Termux, no-root)
+      3. neither               -> RuntimeError with install hint
+
+    Returns: 'root' | 'termux'
+    """
+    if is_root():
+        return "root"
+    if has_termux_api():
+        return "termux"
+    raise RuntimeError(
+        "No USB backend available.\n"
+        "  • Run as root (Nethunter / Termux:Root / sudo), OR\n"
+        "  • Install Termux:API add-on and: pkg install termux-api"
+    )
+
+
+# Low-level: call termux-api Usb without subprocess 
+
+def _run_termux_api(*args, timeout: int = 15) -> str:
+    """
+    Fork + exec termux-api with the given args, collect stdout, return it.
+
+    Equivalent to:
+        /data/.../termux-api Usb -a <action> [params…]
+    but using only os.fork / os.execve / os.pipe - no subprocess module.
+
+    Args are everything *after* the binary path, e.g.:
+        _run_termux_api("Usb", "-a", "list")
+    """
+    r_fd, w_fd = os.pipe()
+
+    pid = os.fork()
+    if pid == 0:
+        try:
+            os.close(r_fd)
+            os.dup2(w_fd, 1)
+            os.close(w_fd)
+            devnull = os.open("/dev/null", os.O_WRONLY)
+            os.dup2(devnull, 2)
+            os.close(devnull)
+            argv = [_TERMUX_API] + list(args)
+            os.execve(_TERMUX_API, argv, os.environ.copy())
+        except Exception:
+            os._exit(1)
+        os._exit(0)  # unreachable, but safe
+    else:
+        os.close(w_fd)
+        chunks = []
+        while True:
+            chunk = os.read(r_fd, 4096)
+            if not chunk:
+                break
+            chunks.append(chunk)
+        os.close(r_fd)
+        _, status = os.waitpid(pid, 0)
+        exit_code = os.waitstatus_to_exitcode(status)
+        output = b"".join(chunks).decode("utf-8", errors="replace").strip()
+        if exit_code != 0 and not output:
+            raise RuntimeError(
+                f"termux-api exited {exit_code} with no output (args={args})"
+            )
+        return output
+
+
+# Termux backend: public API
+
+def list_usb_devices() -> list[str]:
+    """
+    Return a list of available USB device paths.
+    Replaces: subprocess.check_output(["termux-usb", "-l"])
+    Termux backend only.
+    """
+    out = _run_termux_api("Usb", "-a", "list")
+    try:
+        devices = json.loads(out)
+        return devices if isinstance(devices, list) else []
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"termux-api Usb list returned bad JSON: {e!r}\n{out!r}")
+
+
+def request_permission(device_path: str) -> bool:
+    """
+    Show the Android USB-permission dialog for device_path.
+    Returns True if the user granted permission.
+    Termux backend only.
+    """
+    try:
+        out = _run_termux_api(
+            "Usb", "-a", "permission",
+            "--ez", "request", "true",
+            "--es", "device", device_path,
+        )
+        return "yes" in out.lower() or "granted" in out.lower()
+    except Exception:
+        return False
+
+
+def open_usb_device(device_path: str, callback_cmd: str,
+                    export_as_env: bool = True) -> None:
+    """
+    Ask termux-api to open device_path and call callback_cmd with the fd.
+    Termux backend only.
+    """
+    params = [
+        "Usb", "-a", "open",
+        "--ez", "request", "true",
+        "--es", "device", device_path,
+    ]
+    out = _run_termux_api(*params)
+    _check_api_output(out)
+
+    fd_str = out.strip()
+    env = os.environ.copy()
+    if export_as_env:
+        env["TERMUX_USB_FD"] = fd_str
+        env["TERMUX_USB_DEVICE"] = device_path
+        argv = callback_cmd.split()
+        os.execvpe(argv[0], argv, env)
+    else:
+        argv = callback_cmd.split() + [fd_str]
+        os.execvpe(argv[0], argv, env)
+
+
+def _check_api_output(out: str):
+    """Raise RuntimeError on known termux-api error strings."""
+    lower = out.lower()
+    if "no such device" in lower:
+        raise RuntimeError("No such device.")
+    if "no permission" in lower or "permission denied" in lower:
+        raise RuntimeError("Permission denied.")
+    if "permission request timeout" in lower:
+        raise RuntimeError("Permission request timeout.")
+    if "failed to open" in lower or "open device failed" in lower:
+        raise RuntimeError("Open device failed.")
+
+
+def auto_detect_device() -> str:
+    """
+    Return the first available USB device path (termux backend).
+    Raises RuntimeError if none found.
+    """
+    devices = list_usb_devices()
+    if not devices:
+        raise RuntimeError("No USB devices found. Is the ESP32 plugged in via OTG?")
+    return devices[0]
+
+
+def launch_with_fd(cmd: str, device_path: str, log_file: str,
+                   tail_fn=None) -> tuple:
+    """
+    Fork-exec termux-api Usb open, log stdout+stderr to log_file (append),
+    and tail the log in a daemon thread.  Termux backend only.
+
+    Returns (child_pid, child_done_event, tail_thread).
+
+    The CALLER owns os.waitpid(child_pid, 0) and must call
+    child_done.set() afterward so the tail thread can drain final output
+    without racing on waitpid itself (which caused ChildProcessError).
+    """
+    import threading
+    import time
+
+    env = os.environ.copy()
+    env["TERMUX_CALLBACK"] = cmd
+    env["TERMUX_EXPORT_FD"] = "true"
+    argv = [_TERMUX_API, "Usb", "-a", "open",
+            "--ez", "request", "true", "--es", "device", device_path]
+
+    pid = os.fork()
+    if pid == 0:
+        try:
+            fd = os.open(log_file, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+            os.dup2(fd, 1)
+            os.dup2(fd, 2)
+            os.close(fd)
+            os.execve(_TERMUX_API, argv, env)
+        except Exception:
+            os._exit(1)
+
+    # The tail thread checks this Event instead of calling waitpid itself,
+    # avoiding ChildProcessError when the parent reaps the child first.
+    child_done = threading.Event()
+
+    def _tail():
+        fd = os.open(log_file, os.O_RDONLY | os.O_NONBLOCK)
+        buf = b""
+        try:
+            while True:
+                done = child_done.is_set()
+                try:
+                    chunk = os.read(fd, 4096)
+                    buf += chunk
+                except BlockingIOError:
+                    pass
+
+                # Flush on EITHER \n or \r as a line boundary. Anything the
+                # wrapped process prints with \r (e.g. a progress indicator)
+                # has no \n until it finishes, so splitting only on \n means
+                # such output sits buffered here indefinitely and then dumps
+                # all at once when a real \n finally shows up - looking like
+                # the process hung when it was actually working the whole
+                # time. Treating \r as a boundary too streams it live.
+                while True:
+                    nl = buf.find(b"\n")
+                    cr = buf.find(b"\r")
+                    if nl == -1 and cr == -1:
+                        break
+                    if nl == -1:
+                        idx, sep = cr, b"\r"
+                    elif cr == -1:
+                        idx, sep = nl, b"\n"
+                    else:
+                        idx, sep = (cr, b"\r") if cr < nl else (nl, b"\n")
+                    line, buf = buf[:idx], buf[idx + 1:]
+                    if tail_fn:
+                        tail_fn(line.decode("utf-8", errors="replace") + sep.decode())
+
+                if done:
+                    try:
+                        buf += os.read(fd, 65536)
+                    except BlockingIOError:
+                        pass
+                    while True:
+                        nl = buf.find(b"\n")
+                        cr = buf.find(b"\r")
+                        if nl == -1 and cr == -1:
+                            break
+                        if nl == -1:
+                            idx, sep = cr, b"\r"
+                        elif cr == -1:
+                            idx, sep = nl, b"\n"
+                        else:
+                            idx, sep = (cr, b"\r") if cr < nl else (nl, b"\n")
+                        line, buf = buf[:idx], buf[idx + 1:]
+                        if tail_fn:
+                            tail_fn(line.decode("utf-8", errors="replace") + sep.decode())
+                    if buf and tail_fn:
+                        tail_fn(buf.decode("utf-8", errors="replace") + "\n")
+                    break
+
+                time.sleep(0.05)
+        finally:
+            os.close(fd)
+
+    tail_thread = threading.Thread(target=_tail, daemon=True)
+    tail_thread.start()
+
+    return pid, child_done, tail_thread
+
+
+def relaunch_with_fd(device_path: str, script_path: str):
+    """
+    Re-invoke this script so TERMUX_USB_FD gets set by termux-api Usb open.
+    This replaces the current process - it does not return.
+    Termux backend only.
+    """
+    argv = [
+        _TERMUX_API, "Usb",
+        "-a", "open",
+        "--ez", "request", "true",
+        "--es", "device", device_path,
+    ]
+    env = os.environ.copy()
+    env["TERMUX_CALLBACK"] = f"python {script_path}"
+    env["TERMUX_EXPORT_FD"] = "true"
+    os.execve(_TERMUX_API, argv, env)
+
+
+
+def find_usb_device_direct(vid_pid_filter: list[tuple] | None = None):
+    """
+    Root path: scan the USB bus via libusb and return the first matching device.
+
+    vid_pid_filter: list of (vid, pid) tuples to try in order.
+                    Defaults to all entries in ESP32_KNOWN if None.
+
+    Falls back to the first non-hub device found if no known VID:PID matches.
+    Raises RuntimeError if nothing is found at all.
+    """
+    candidates = list(vid_pid_filter or ESP32_KNOWN.keys())
+
+    for vid, pid in candidates:
+        dev = usb.core.find(idVendor=vid, idProduct=pid)
+        if dev is not None:
+            return dev
+
+    all_devs = list(usb.core.find(find_all=True))
+    non_hubs = [d for d in all_devs if d.bDeviceClass != 9]
+    if non_hubs:
+        return non_hubs[0]
+
+    raise RuntimeError(
+        "No USB device found on the bus. Is the ESP32 plugged in via OTG?"
+    )
+
+def init_uart_bridge(device):
+    """
+    Sends raw vendor control requests to wake up and configure
+    external hardware serial bridges to 115200 baud, 8N1.
+    Includes an explicit hardware reset sequence to pull the ESP32
+    out of bootloader loops/reset traps caused by Android connection probes.
+    """
+    import time
+    vid, pid = device.idVendor, device.idProduct
+
+    # ── CASE 1: Silicon Labs CP2102 ───────────────────────────────────────────
+    if (vid, pid) == (0x10C4, 0xEA60):
+        print("[*] Initializing CP2102 line control registers...", flush=True)
+        try:
+            device.ctrl_transfer(0x41, 0x00, 0x0001, 0, None)       # Enable UART port
+            device.ctrl_transfer(0x40, 0x1E, 0xC200, 0x0001, None)  # Set baud rate to 115200
+            device.ctrl_transfer(0x40, 0x03, 0x0800, 0, None)       # 8N1 line control
+
+            # Hardware reset toggle for CP2102 auto-reset circuit
+            device.ctrl_transfer(0x41, 0x01, 0x0300, 0, None)       # De-assert DTR+RTS
+            time.sleep(0.05)
+            device.ctrl_transfer(0x41, 0x01, 0x0303, 0, None)       # Assert DTR+RTS (normal boot)
+            time.sleep(0.1)
+
+            print("[+] CP2102 successfully configured and reset!", flush=True)
+        except Exception as e:
+            print(f"[-] Warning: CP2102 initialization encountered an error: {e}", flush=True)
+
+    # ── CASE 2: WCH CH340 / CH341 ────────────────────────────────────────────
+    elif (vid, pid) in [(0x1A86, 0x7523), (0x1A86, 0x55D4)]:
+        print("[*] Initializing CH340 register state machine...", flush=True)
+        try:
+            # CH340 line initialization handshake
+            device.ctrl_transfer(0x40, 0xA1, 0, 0, None)
+
+            # Set baud rate to 115200 using the real CH340/CH341 divisor
+            # algorithm (from the Linux kernel's ch341.c driver - this is
+            # what actually runs whenever esptool.py works over a real
+            # /dev/ttyUSB* on Linux, so it's a known-correct reference).
+            #
+            # An earlier version of this code sent
+            #   ctrl_transfer(0x40, 0x9A, 0xC380, 0xEB00, None)
+            # which has wValue and wIndex reversed relative to the real
+            # protocol (wValue must be the constant 0x1312, wIndex the
+            # computed divisor) - it was writing garbage to the baud rate
+            # generator. Combined with a bogus 8N1 byte (0x0050 instead of
+            # the real LCR encoding 0xC3), the bridge was very likely never
+            # actually running at 115200 8N1 - explaining flaky syncs/
+            # frame drops that had nothing to do with the reset-pin timing.
+            baud_rate = 115200
+            factor = 1532620800 // baud_rate  # CH341_BAUDBASE_FACTOR
+            divisor = 3                        # CH341_BAUDBASE_DIVMAX
+            while factor > 0xFFF0 and divisor:
+                factor >>= 3
+                divisor -= 1
+            factor = 0x10000 - factor
+            a = ((factor & 0xFF00) | divisor) | 0x80  # BIT(7): CH341A
+            # packet-buffering flag - harmless on plain CH340/CH340G, and
+            # is what the modern kernel driver sets unconditionally.
+            lcr_8n1 = 0x80 | 0x40 | 0x03  # ENABLE_RX | ENABLE_TX | CS8
+            device.ctrl_transfer(0x40, 0x9A, 0x1312, a, None)
+            device.ctrl_transfer(0x40, 0x9A, 0x2518, lcr_8n1, None)
+
+            # ── HARDWARE RESET TOGGLE FOR ESP32 AUTO-RESET CIRCUIT ────────────
+            # 0xA4 modem control bits are ACTIVE-LOW. Bit weights per the
+            # Linux kernel ch341.c driver: bit5 (0x20) = DTR, bit6 (0x40) =
+            # RTS. (Earlier revision of this code used bit4 (0x10) for RTS,
+            # which isn't wired to anything - RTS never actually toggled,
+            # so this reset pulse silently did nothing on real hardware.)
+            #   0xFF = DTR+RTS de-asserted (idle / lines released)
+            #   0x9F = DTR+RTS asserted   (bits 5+6 pulled low → EN+BOOT driven)
+            #
+            # To get a clean normal-sketch boot (not bootloader):
+            #   1. Assert both  → ESP32 goes into reset
+            #   2. Release both → EN rises, BOOT pin=1 → runs sketch
+            device.ctrl_transfer(0x40, 0xA4, 0x9F, 0, None)  # Assert DTR+RTS → reset
+            time.sleep(0.1)                                    # Hold reset
+            device.ctrl_transfer(0x40, 0xA4, 0xFF, 0, None)  # Release → normal boot
+            time.sleep(0.5)               
+            
+            # Assert DTR so CH340 forwards RX data to host
+            device.ctrl_transfer(0x40, 0xA4, 0xDF, 0, None)  # DTR asserted, RTS released
+            time.sleep(0.05)
+
+            print("[+] CH340 successfully configured and released from reset!", flush=True)
+        except Exception as e:
+            print(f"[-] Warning: CH340 initialization encountered an error: {e}", flush=True)
+
+    # ── CASE 3: FTDI FT232 ───────────────────────────────────────────────────
+    elif (vid, pid) == (0x0403, 0x6001):
+        print("[*] Initializing FTDI FT232 line settings...", flush=True)
+        try:
+            device.ctrl_transfer(0x40, 0x00, 0x0000, 0, None)       # Reset device
+            time.sleep(0.05)
+            device.ctrl_transfer(0x40, 0x03, 0x001A, 0, None)       # Set baud rate to 115200
+            device.ctrl_transfer(0x40, 0x04, 0x0008, 0, None)       # 8N1 line control
+            device.ctrl_transfer(0x40, 0x01, 0x0202, 0, None)       # Assert DTR+RTS
+            time.sleep(0.1)
+
+            print("[+] FTDI FT232 successfully configured!", flush=True)
+        except Exception as e:
+            print(f"[-] Warning: FTDI initialization encountered an error: {e}", flush=True)
+
+    # ── CASE 4: Native USB ESP32-S3 / C3 — no bridge init needed ─────────────
+    else:
+        pass
+
+
+# Backward-compatibility alias — callers using the old name keep working
+init_cp2102_bridge = init_uart_bridge
+
+
+def wrap_direct(vid_pid_filter: list[tuple] | None = None):
+    """
+    Root backend equivalent of wrap_fd().
+
+    Opens the ESP32 directly via libusb without termux-api or an Android
+    file descriptor.  Returns a usb.core.Device ready for claim_device()
+    and get_cdc_endpoints() - same contract as wrap_fd().
+
+    Requires root (uid 0) so libusb can open /dev/bus/usb directly.
+    On Nethunter, ensure libusb-1.0 is installed:
+        apt install libusb-1.0-0
+    """
+    device = find_usb_device_direct(vid_pid_filter)
+    return device
+
+
+
+def wrap_fd(fd: int):
+    """
+    Wrap Android's USB file descriptor into a PyUSB Device object.
+    Must call LIBUSB_OPTION_NO_DEVICE_DISCOVERY before libusb_init.
+    Returns a usb.core.Device ready for use.
+    Termux backend only.
+    """
+    backend = libusb1.get_backend()
+    lib     = backend.lib
+    ctx     = backend.ctx
+
+    lib.libusb_set_option.argtypes = [libusb1.c_void_p, ctypes.c_int]
+    lib.libusb_set_option.restype  = ctypes.c_int
+    lib.libusb_set_option(None, 5)   # LIBUSB_OPTION_NO_DEVICE_DISCOVERY
+
+    lib.libusb_wrap_sys_device.argtypes = [
+        libusb1.c_void_p,
+        ctypes.c_int,
+        ctypes.POINTER(libusb1._libusb_device_handle),
+    ]
+    lib.libusb_get_device.argtypes = [libusb1._libusb_device_handle]
+    lib.libusb_get_device.restype  = ctypes.c_void_p
+
+    handle = libusb1._libusb_device_handle()
+    ret = lib.libusb_wrap_sys_device(ctx, int(fd), ctypes.byref(handle))
+    if ret != 0:
+        raise RuntimeError(f"libusb_wrap_sys_device failed: {ret}")
+
+    devid = lib.libusb_get_device(handle)
+
+    class _Dummy:
+        def __init__(self, devid, handle):
+            self.devid  = devid
+            self.handle = handle
+
+    dummy  = _Dummy(devid, handle)
+    device = usb.core.Device(dummy, backend)
+    device._ctx.handle = dummy
+    return device
+
+
+
+def describe_device(device) -> str:
+    vid, pid = device.idVendor, device.idProduct
+    label = ESP32_KNOWN.get((vid, pid), "Unknown device")
+    return f"{vid:04X}:{pid:04X} {label}"
+
+
+def get_cdc_endpoints(device):
+    """
+    Find bulk IN and OUT endpoints. 
+    Completely compatible drop-in replacement that works for BOTH:
+      1. Native USB CDC devices (ESP32-S3, ESP32-C3)
+      2. Serial Bridge chips (CP2102, CH340, CH9102, FTDI)
+    
+    Returns (ep_in_addr, ep_out_addr, interface_number).
+    """
+    import usb.util
+    vid, pid = device.idVendor, device.idProduct
+    cfg = device.get_active_configuration()
+
+    if (vid, pid) in [(0x303A, 0x1001), (0x303A, 0x0002)]:
+        # Native ESP32 S3/C3 USB CDC always maps bulk data to Interface 1
+        try:
+            intf = cfg[(1, 0)]
+            eps = list(intf)
+            ep_in = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            ep_out = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            if ep_in and ep_out:
+                return ep_in, ep_out, 1
+        except Exception:
+            pass
+
+    elif (vid, pid) in [(0x10C4, 0xEA60), (0x1A86, 0x7523), (0x1A86, 0x55D4), (0x0403, 0x6001)]:
+        # Hardware UART Bridges — enumerate from descriptor instead of hardcoding.
+        # Hardcoded 0x81/0x01 fails on fd-wrapped devices because set_configuration()
+        # is skipped (Termux no-root) so _ep_info is never populated.
+        try:
+            intf = cfg[(0, 0)]
+            eps = list(intf)
+            ep_in = next((e.bEndpointAddress for e in eps
+                          if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN
+                          and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            ep_out = next((e.bEndpointAddress for e in eps
+                           if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT
+                           and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            if ep_in and ep_out:
+                return ep_in, ep_out, 0
+        except Exception:
+            pass
+        # Absolute fallback if descriptor walk failed
+        return 0x81, 0x01, 0
+
+    # If a new or unknown device is plugged in, look for CDC Data class (0x0A) first
+    for intf in cfg:
+        if intf.bInterfaceClass == 0x0A:
+            eps = list(intf)
+            ep_in = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            ep_out = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+            if ep_in and ep_out:
+                return ep_in, ep_out, intf.bInterfaceNumber
+
+    # Final Fallback: Grab the first valid bulk pair found anywhere on the device
+    for intf in cfg:
+        eps = list(intf)
+        ep_in = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+        ep_out = next((e.bEndpointAddress for e in eps if usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT and usb.util.endpoint_type(e.bmAttributes) == usb.util.ENDPOINT_TYPE_BULK), None)
+        if ep_in and ep_out:
+            return ep_in, ep_out, intf.bInterfaceNumber
+
+    raise RuntimeError("No bulk endpoint pair found on device")
+
+def claim_device(device, interface_num: int, fd_wrapped: bool = False):
+    """
+    Detach kernel driver if needed and claim the interface.
+
+    fd_wrapped: set True when the device came from wrap_fd() (Termux no-root).
+    In that case we must NOT call set_configuration() — Android has already
+    configured the device and libusb's internal refcount doesn't survive a
+    second configuration attempt on a fd-wrapped handle.  Calling it on the
+    ESP32-S3 (which uses TinyUSB with two CDC interfaces) triggers:
+        assertion "refcnt >= 2" failed
+    and crashes the process.  The root (wrap_direct) path is fine.
+    """
+    import usb.util
+    try:
+        if device.is_kernel_driver_active(interface_num):
+            device.detach_kernel_driver(interface_num)
+    except Exception:
+        pass
+    if not fd_wrapped:
+        try:
+            device.set_configuration()
+        except Exception:
+            pass
+    try:
+        usb.util.claim_interface(device, interface_num)
+    except Exception:
+        pass
+
+
+def reset_endpoint_toggles(device, ep_in_addr: int, ep_out_addr: int):
+    """
+    Clear the DATA0/DATA1 toggle on both bulk endpoints.
+
+    Each invocation is a fresh OS process wrapping the *same* physical USB
+    device via TERMUX_USB_FD (termux) or a direct libusb open (root).
+    The toggle bit lives in the peripheral's endpoint state, not in process
+    memory, so a clean exit does NOT reset it.  Call this once right after
+    claim_device(), before any read/write.
+    """
+    for ep in (ep_in_addr, ep_out_addr):
+        try:
+            device.clear_halt(ep)
+        except usb.core.USBError:
+            pass

espbridge-1.0.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: espbridge
+Version: 1.0.0
+Summary: Framed binary USB bridge protocol for talking to an ESP32 from Termux (or any Linux host) — no root required.
+Author: 7wp81x
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/7wp81x/ESP-Bridge
+Project-URL: Repository, https://github.com/7wp81x/ESP-Bridge
+Project-URL: Issues, https://github.com/7wp81x/ESP-Bridge/issues
+Keywords: esp32,termux,usb,no-root,android,serial,bridge,protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Android
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyusb>=1.2.1
+Dynamic: license-file
+
+# ESP-Bridge
+
+Framed binary USB bridge protocol for talking to an ESP32 from Termux — or
+any Linux host — **no root required**.
+
+This is the transport layer extracted from [NRSuite](https://github.com/7wp81x/NRSuite).
+It doesn't know anything about Wi-Fi, packet capture, or any specific
+use case — it just gets JSON commands and binary chunks reliably between
+an ESP32 and a host process over USB CDC, with automatic root/no-root
+backend detection. Use it to build your own ESP32-to-Termux tools.
+
+Pairs with the [`BridgeProtocol`](https://github.com/7wp81x/BridgeProtocol) PlatformIO library on
+the firmware side — install both and the two speak the same frames out of
+the box.
+
+## Install
+
+```bash
+pip install espbridge          # once published
+# or, for local development:
+git clone https://github.com/7wp81x/ESP-Bridge
+cd ESP-Bridge
+pip install -e .
+```
+
+On stock Termux you'll also need:
+```bash
+pkg install python termux-api libusb
+```
+plus the **Termux:API** app from F-Droid (not the Play Store version).
+
+## Quick start
+
+See [`examples/echo_cmd.py`](examples/echo_cmd.py) for a full runnable
+example. The short version:
+
+```python
+import os, espbridge as eb
+
+backend = eb.detect_backend()          # "termux" or "root"
+device  = eb.wrap_fd(int(os.environ["TERMUX_USB_FD"])) if backend == "termux" \
+          else eb.wrap_direct()
+
+ep_in, ep_out, iface = eb.get_cdc_endpoints(device)
+eb.claim_device(device, iface, fd_wrapped=(backend == "termux"))
+eb.reset_endpoint_toggles(device, ep_in, ep_out)
+
+sender   = eb.Sender(device, ep_out)
+receiver = eb.ReceiverThread(device, ep_in); receiver.start()
+proto    = eb.Protocol(sender, receiver);    proto.start()
+
+resp = proto.send_cmd("PING")          # blocks until RESP or timeout
+print(resp)
+```
+
+## Frame format
+
+```
+[MAGIC 2B: 0xAD 0xDE][TYPE 1B][ID 1B][LENGTH 4B LE][PAYLOAD NB]
+```
+
+| Type  | Hex  | Direction     | Payload                              |
+|-------|------|---------------|---------------------------------------|
+| CMD   | 0x01 | Host → ESP32  | JSON `{"cmd": "...", "args": {...}}` |
+| RESP  | 0x02 | ESP32 → Host  | JSON response, matched by frame ID    |
+| EVENT | 0x03 | ESP32 → Host  | Async JSON, id=0                      |
+| PCAP  | 0x04 | ESP32 → Host  | Raw binary chunk (id = chunk index) — despite the name, use this for any binary stream |
+| ACK   | 0x05 | Host → ESP32  | JSON `{"chunk": N}` — flow control    |
+| HTML  | 0x06 | Host → ESP32  | Chunked raw payload upload            |
+
+Commands (`CMD`) are entirely up to you — define whatever `cmd` strings and
+`args` your firmware understands. This library only handles framing,
+transport, and request/response matching.
+
+## What's included
+
+- `protocol.py` — frame builder/parser, `Protocol` class (send_cmd/on_event/on_pcap)
+- `sender.py` — thread-safe bulk OUT writer with retry
+- `receiver.py` — background bulk IN reader thread
+- `usb_device.py` — root vs. no-root backend detection, permission flow, endpoint discovery
+
+## License
+
+MIT

espbridge-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+espbridge/__init__.py,sha256=3Tq3yTUwYjxWD1Iv3__BkegIhEMc-qxb1kCinvLFLjs,2710
+espbridge/protocol.py,sha256=gjS3KxCuQRbmvI3P4yVC75skHjFj7JfeuWvXqT-ApPw,9153
+espbridge/receiver.py,sha256=gSk29tujpXmNEqYBmmH0nigar2mX7VGMzV8riuT0kds,4697
+espbridge/sender.py,sha256=nTbjwNQl7mz4amHrQRr7X-9bTeGUdeST1R_U5nbIxts,1652
+espbridge/usb_device.py,sha256=g87CggCEJxRdUH_apmACFxA98Mcn4NOUYj1yMixpXWM,25516
+espbridge-1.0.0.dist-info/licenses/LICENSE,sha256=o7Urwh9i4GpPNG1gjUG8ekKcv988l8c8688uK92mPfc,1061
+espbridge-1.0.0.dist-info/METADATA,sha256=q25uFU_T0zk18AGDlyHn2gvjbzbv9-qX5eMfq3dSZJs,4044
+espbridge-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+espbridge-1.0.0.dist-info/top_level.txt,sha256=AvhZ9_x5BcXLdg5tqhhd0IGDP6hatdORRePsYaUfCJY,10
+espbridge-1.0.0.dist-info/RECORD,,

espbridge-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

espbridge-1.0.0.dist-info/licenses/LICENSE

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

espbridge-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+espbridge