espbridge 1.0.0__tar.gz

espbridge-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "espbridge"
+version = "1.0.0"
+description = "Framed binary USB bridge protocol for talking to an ESP32 from Termux (or any Linux host) — no root required."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "7wp81x" }
+]
+keywords = ["esp32", "termux", "usb", "no-root", "android", "serial", "bridge", "protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Android",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: System :: Hardware",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "pyusb>=1.2.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/7wp81x/ESP-Bridge"
+Repository = "https://github.com/7wp81x/ESP-Bridge"
+Issues = "https://github.com/7wp81x/ESP-Bridge/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

espbridge-1.0.0/setup.cfg

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

espbridge-1.0.0/src/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-1.0.0/src/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}")