python-esp-bridge 0.0.2__py3-none-any.whl → 0.1.0__py3-none-any.whl

espbridge/__init__.py

@@ -1,6 +1,6 @@
 """espbridge — control every ESP32 peripheral from Python over USB serial.
 
-Flash esp/esp.ino once, then:
+Flash firmware/firmware.ino once, then:
 
     from espbridge import Bridge
 
@@ -15,6 +15,7 @@ Flash esp/esp.ino once, then:
 from .bridge import Bridge, BridgeSet, Info, connect_all
 from .constants import Cap, ChipModel, Status
 from .errors import (
+    AuthError,
     BridgeError,
     BridgeTimeoutError,
     NoDeviceError,
@@ -22,18 +23,27 @@ from .errors import (
     RemoteError,
     UnsupportedError,
 )
-from .transport import find_ports
+from .transports import find_ports
 
-__version__ = "0.0.2"
+
+def find_ble_devices(timeout: float = 5.0):
+    """Scan for bridges advertising over Bluetooth (needs the [ble] extra)."""
+    from .transports.ble import find_ble_devices as _scan
+
+    return _scan(timeout)
+
+__version__ = "0.1.0"
 
 __all__ = [
     "Bridge",
     "BridgeSet",
     "connect_all",
+    "find_ble_devices",
     "Info",
     "Cap",
     "ChipModel",
     "Status",
+    "AuthError",
     "BridgeError",
     "BridgeTimeoutError",
     "NoDeviceError",

espbridge/bridge.py

@@ -10,6 +10,7 @@ from dataclasses import dataclass
 
 from . import constants as C
 from .errors import (
+    AuthError,
     BridgeError,
     BridgeTimeoutError,
     NoDeviceError,
@@ -18,7 +19,7 @@ from .errors import (
     UnsupportedError,
 )
 from .protocol import Frame, FrameSplitter, decode_frame, encode_frame
-from .transport import SerialTransport, find_ports
+from .transports import SerialTransport, find_ports
 
 
 @dataclass(frozen=True)
@@ -78,6 +79,12 @@ class Bridge:
 
     >>> esp = Bridge(name="relays")
     >>> esp = Bridge(mac="24:a1:60:12:34:56")
+
+    Over Bluetooth instead of USB (firmware default password "espbridge",
+    change it at the top of firmware/firmware.ino):
+
+    >>> esp = Bridge(ble=True)                      # the only advertising bridge
+    >>> esp = Bridge(ble="relays", password="espbridge")
     """
 
     def __init__(
@@ -86,6 +93,8 @@ class Bridge:
         *,
         name: str | None = None,
         mac: str | None = None,
+        ble: bool | str = False,
+        password: str | None = None,
         baud: int = 115200,
         upgrade_baud: bool = True,
         target_baud: int | None = None,
@@ -98,18 +107,22 @@ class Bridge:
         self.reset_on_exit = False  # set for real only once connected (see below)
         self.info: Info | None = None
 
-        # Candidate ports: explicit transport/port, or every ESP32-like port.
+        # Candidates: (transport factory, label, usb_chip).
         if transport is not None:
-            candidates = [(transport, None, getattr(transport, "usb_chip", None))]
+            candidates = [(lambda t=transport: t, "transport",
+                           getattr(transport, "usb_chip", None))]
+        elif ble:
+            candidates = self._ble_candidates(ble, name, mac)
         elif port is not None:
             chip = next((p.usb_chip for p in find_ports() if p.device == port), None)
-            candidates = [(None, port, chip)]
+            candidates = [(lambda p=port, c=chip: SerialTransport(p, baud, usb_chip=c),
+                           port, chip)]
         else:
             ports = find_ports()
             if not ports:
                 raise NoDeviceError(
                     "no ESP32 serial port found (CP210x/CH340/CH9102/native USB); "
-                    "pass port='COM5' / '/dev/ttyUSB0' explicitly"
+                    "pass port='COM5' / '/dev/ttyUSB0' explicitly — or ble=True"
                 )
             if name is None and mac is None and len(ports) > 1:
                 names = ", ".join(p.device for p in ports)
@@ -117,41 +130,92 @@ class Bridge:
                     f"multiple ESP32-like ports found ({names}); pass port=, "
                     f"name= or mac= — or use espbridge.connect_all()"
                 )
-            candidates = [(None, p.device, p.usb_chip) for p in ports]
+            candidates = [(lambda p=p: SerialTransport(p.device, baud, usb_chip=p.usb_chip),
+                           p.device, p.usb_chip) for p in ports]
 
         probing = len(candidates) > 1
         errors: list[str] = []
-        for t, prt, chip in candidates:
+        for factory, label, chip in candidates:
             self._reset_state()
             try:
-                self._t = t if t is not None else SerialTransport(prt, baud, usb_chip=chip)
+                self._t = factory()
             except Exception as e:
-                errors.append(f"{prt}: {e}")
+                errors.append(f"{label}: {e}")
                 continue
             self._reader = threading.Thread(target=self._read_loop, daemon=True,
                                             name="espbridge-reader")
             self._reader.start()
             try:
-                self._handshake(reset_on_open)
+                if getattr(self._t, "needs_auth", False):
+                    self._auth(password)
+                    self._handshake(reset_on_open=False)
+                else:
+                    self._handshake(reset_on_open)
                 assert self.info is not None
                 if self._matches(name, mac):
-                    if upgrade_baud:
+                    if upgrade_baud and getattr(self._t, "has_baud", True):
                         self._upgrade_baud(baud, target_baud)
                     self.reset_on_exit = reset_on_exit
                     return
-                errors.append(f"{prt or 'transport'}: name={self.info.name!r} "
+                errors.append(f"{label}: name={self.info.name!r} "
                               f"mac={self.info.mac} (no match)")
                 self.close()
             except (BridgeTimeoutError, ProtocolError) as e:
                 self.close()
                 if not probing:
                     raise
-                errors.append(f"{prt or 'transport'}: {e}")
+                errors.append(f"{label}: {e}")
             except BaseException:
                 self.close()
                 raise
         raise NoDeviceError("no matching bridge found — " + "; ".join(errors))
 
+    @staticmethod
+    def _ble_candidates(ble: bool | str, name: str | None, mac: str | None):
+        from .transports.ble import BleTransport, find_ble_devices
+
+        target = ble if isinstance(ble, str) else None
+        devs = find_ble_devices()
+        if target is not None:
+            tmac = _norm_mac(target)
+            devs = [d for d in devs
+                    if d.name == target or d.device_name == target
+                    or _norm_mac(d.address) == tmac or _norm_mac(d.mac) == tmac]
+        # The advertised name carries the bridge MAC and custom name: narrow
+        # the candidates before connecting when the caller passed name=/mac=.
+        # On no match keep the full list (adv data can be stale/truncated) —
+        # the post-connect _matches() check stays authoritative either way.
+        if mac is not None:
+            devs = [d for d in devs if _norm_mac(d.mac) == _norm_mac(mac)] or devs
+        if name is not None:
+            devs = [d for d in devs if d.device_name == name] or devs
+        if not devs:
+            what = f" named/at {target!r}" if target else ""
+            raise NoDeviceError(
+                f"no bridge{what} found over Bluetooth — is the board powered, "
+                f"in range, and flashed with BRIDGE_BLE_LINK enabled?"
+            )
+        if target is None and name is None and mac is None and len(devs) > 1:
+            names = ", ".join(d.name or d.address for d in devs)
+            raise NoDeviceError(
+                f"multiple bridges advertising ({names}); pass ble='name-or-mac'"
+            )
+        return [(lambda d=d: BleTransport(d.address),
+                 f"BLE {d.name or d.address}", None) for d in devs]
+
+    def _auth(self, password: str | None) -> None:
+        """Authenticate a wireless link (SYS_AUTH) before the handshake."""
+        pw = (C.DEFAULT_PASSWORD if password is None else password).encode()
+        try:
+            self.request(C.SYS_AUTH, pw, timeout=5.0)
+        except RemoteError as e:
+            if e.status == C.Status.DENIED:
+                raise AuthError(
+                    "bridge rejected the password — check BRIDGE_PASSWORD at "
+                    "the top of firmware/firmware.ino"
+                ) from None
+            raise
+
     def _reset_state(self) -> None:
         self._splitter = FrameSplitter()
         self._pending: dict[int, _Pending] = {}
@@ -203,13 +267,13 @@ class Bridge:
                     continue
         if not self._ready.is_set():
             raise BridgeTimeoutError(
-                "no response from bridge firmware — is it flashed? (esp/README.md)"
+                "no response from bridge firmware — is it flashed? (firmware/README.md)"
             )
         assert self.info is not None
         if self.info.protocol != C.PROTOCOL_VERSION:
             raise ProtocolError(
                 f"protocol mismatch: firmware speaks v{self.info.protocol}, "
-                f"this library v{C.PROTOCOL_VERSION} — reflash esp/esp.ino or "
+                f"this library v{C.PROTOCOL_VERSION} — reflash firmware.ino or "
                 f"update python-esp-bridge"
             )
 
@@ -232,7 +296,29 @@ class Bridge:
                 continue
         # Could not talk at the new baud: fall back.
         self._t.set_baudrate(current)
-        self.ping(b"fallback")
+        try:
+            self.ping(b"fallback")
+        except BridgeTimeoutError:
+            # The firmware already switched to `target` and can't hear us.
+            # Reopen the port: the open-time DTR/RTS toggle resets the board
+            # (reliable even where a manual reset pulse is not).
+            self._reconnect(current)
+
+    def _reconnect(self, baud: int) -> None:
+        """Reopen the serial port and redo the handshake (recovers a dead link)."""
+        port = getattr(getattr(self._t, "ser", None), "port", None)
+        chip = getattr(self._t, "usb_chip", None)
+        if port is None:
+            raise BridgeTimeoutError("link lost and transport cannot be reopened")
+        self._t.close()
+        self._reader.join(timeout=1.0)
+        time.sleep(0.3)  # let the device reboot from the close-time reset
+        self._reset_state()
+        self._t = SerialTransport(port, baud, usb_chip=chip)
+        self._reader = threading.Thread(target=self._read_loop, daemon=True,
+                                        name="espbridge-reader")
+        self._reader.start()
+        self._handshake(reset_on_open=True)
 
     def close(self) -> None:
         if self._closing:

espbridge/cli.py

@@ -7,7 +7,7 @@ import sys
 from . import __version__
 from .bridge import Bridge, connect_all
 from .errors import BridgeError
-from .transport import find_ports
+from .transports import find_ports
 
 
 def _print_info(esp: Bridge) -> None:
@@ -32,10 +32,18 @@ def main(argv: list[str] | None = None) -> int:
     ap.add_argument("--version", action="version", version=f"espbridge {__version__}")
     ap.add_argument("-p", "--port", help="serial port (default: auto-detect)")
     ap.add_argument("-n", "--name", help="select device by stored name")
+    ap.add_argument("-b", "--ble", nargs="?", const=True, metavar="NAME_OR_MAC",
+                    help="connect over Bluetooth instead of USB")
+    ap.add_argument("--password", help="Bluetooth link password "
+                                       "(default: 'espbridge')")
     ap.add_argument("--no-baud-upgrade", action="store_true",
                     help="stay at 115200 instead of upgrading the link speed")
     sub = ap.add_subparsers(dest="cmd")
     sub.add_parser("ports", help="list ESP32-like serial ports")
+    p_scan = sub.add_parser("scan", help="connect to every attached device and "
+                                         "list port/name/chip/mac")
+    p_scan.add_argument("--ble", action="store_true", dest="scan_ble",
+                        help="scan for bridges advertising over Bluetooth")
     sub.add_parser("info", help="connect and print firmware/chip info (default; "
                                 "shows every device when several are attached)")
     p_name = sub.add_parser("set-name", help="store a device name on the ESP32 (NVS)")
@@ -43,8 +51,25 @@ def main(argv: list[str] | None = None) -> int:
     args = ap.parse_args(argv)
 
     kwargs = dict(upgrade_baud=not args.no_baud_upgrade)
+    if args.ble:
+        kwargs["ble"] = args.ble
+    if args.password is not None:
+        kwargs["password"] = args.password
 
     try:
+        if args.cmd == "scan" and args.scan_ble:
+            from .transports.ble import find_ble_devices
+
+            devs = find_ble_devices()
+            if not devs:
+                print("no bridges advertising over Bluetooth")
+                return 1
+            print(f"{'NAME':<16s} {'MAC':<18s} {'ADVERTISED':<32s} RSSI")
+            for d in devs:
+                print(f"{d.device_name or '-':<16s} {d.mac or '-':<18s} "
+                      f"{d.name:<32s} {d.rssi} dBm")
+            return 0
+
         if args.cmd == "ports":
             ports = find_ports()
             if not ports:
@@ -54,14 +79,36 @@ def main(argv: list[str] | None = None) -> int:
                 print(f"{p.device}\t{p.usb_chip}\t{p.description}")
             return 0
 
+        if args.cmd == "scan":
+            ports = find_ports()
+            if not ports:
+                print("no ESP32-like serial ports found")
+                return 1
+            print(f"{'PORT':<12s} {'NAME':<16s} {'CHIP':<10s} {'MAC':<17s} FW")
+            rc = 0
+            for p in ports:
+                try:
+                    # info only — skip the baud upgrade for a quicker probe
+                    with Bridge(p.device, upgrade_baud=False) as esp:
+                        info = esp.info
+                        fw = ".".join(map(str, info.fw_version))
+                        print(f"{p.device:<12s} {info.name or '-':<16s} "
+                              f"{info.chip.name:<10s} {info.mac:<17s} v{fw}")
+                except BridgeError as e:
+                    print(f"{p.device:<12s} error: {e}")
+                    rc = 1
+            return rc
+
         if args.cmd == "set-name":
             with Bridge(args.port, name=args.name, **kwargs) as esp:
                 esp.set_name(args.new_name)
                 print(f"{esp.info.mac} is now named {args.new_name!r}")
+                print("(the Bluetooth advertised name updates on next reset)")
             return 0
 
         # default: info
-        if args.port is None and args.name is None and len(find_ports()) > 1:
+        if args.port is None and args.name is None and not args.ble \
+                and len(find_ports()) > 1:
             with connect_all(**kwargs) as boards:
                 for i, esp in enumerate(boards):
                     if i:

espbridge/constants.py

@@ -1,6 +1,6 @@
 """python-esp-bridge — shared protocol contract.
 
-MUST stay in sync with esp/src/espbridge/commands.h.
+MUST stay in sync with firmware/src/espbridge/commands.h.
 """
 from __future__ import annotations
 
@@ -34,6 +34,7 @@ class Status(enum.IntEnum):
     WIFI = 0x0A
     SOCKET = 0x0B
     CRC = 0x0C
+    DENIED = 0x0D  # wireless link not authenticated (see SYS_AUTH)
 
 
 class Cap(enum.IntFlag):
@@ -46,6 +47,7 @@ class Cap(enum.IntFlag):
     PSRAM = 1 << 6
     NATIVE_USB = 1 << 7
     BLE_FW = 1 << 8
+    BLE_LINK = 1 << 9  # bridge reachable over the BLE transport
 
 
 class ChipModel(enum.IntEnum):
@@ -82,6 +84,7 @@ SYS_SET_BAUD = _cmd(MOD_SYS, 0x03)
 SYS_RESET = _cmd(MOD_SYS, 0x04)
 SYS_FREE_HEAP = _cmd(MOD_SYS, 0x05)
 SYS_SET_NAME = _cmd(MOD_SYS, 0x06)
+SYS_AUTH = _cmd(MOD_SYS, 0x07)
 SYS_READY = _cmd(MOD_SYS, 0x80)
 SYS_LOG = _cmd(MOD_SYS, 0x81)
 
@@ -189,6 +192,13 @@ KNOWN_USB_IDS = {
     (0x303A, None): "native",     # Espressif native USB (S2/S3/C3/...)
 }
 
+# BLE link: Nordic-UART-style GATT service the firmware exposes as a transport.
+# MUST stay in sync with firmware link_ble.cpp.
+BLE_LINK_SERVICE_UUID = "6e400001-b5a3-f393-e0a9-e50e24dcca9e"
+BLE_LINK_RX_UUID = "6e400002-b5a3-f393-e0a9-e50e24dcca9e"  # host -> board (write)
+BLE_LINK_TX_UUID = "6e400003-b5a3-f393-e0a9-e50e24dcca9e"  # board -> host (notify)
+DEFAULT_PASSWORD = "espbridge"  # firmware default; change in firmware.ino
+
 # Safe upgraded baud per bridge chip (conservative defaults; CH340 can do 2M).
 UPGRADE_BAUD = {
     "cp210x": 921600,

espbridge/errors.py

@@ -24,6 +24,11 @@ class UnsupportedError(BridgeError):
     """The connected chip lacks this capability (e.g. DAC on ESP32-S3)."""
 
 
+class AuthError(BridgeError):
+    """The bridge rejected the wireless-link password (see BRIDGE_PASSWORD
+    at the top of firmware/firmware.ino)."""
+
+
 class RemoteError(BridgeError):
     """The firmware returned an error status for a request."""
 

espbridge/transport.py

@@ -1,121 +1,5 @@
-"""Serial transport with ESP32 auto-detection, plus an in-memory mock for tests."""
-from __future__ import annotations
+"""Back-compat shim — transports now live in espbridge.transports.*"""
+from .transports.serial import PortInfo, SerialTransport, autodetect_port, find_ports
+from .transports.mock import MockTransport
 
-import time
-from dataclasses import dataclass
-
-from .constants import KNOWN_USB_IDS
-from .errors import NoDeviceError
-
-
-@dataclass(frozen=True)
-class PortInfo:
-    device: str          # e.g. "COM5" or "/dev/ttyUSB0"
-    usb_chip: str | None  # "cp210x" | "ch340" | "ch9102" | "native" | None
-    description: str = ""
-
-
-def find_ports() -> list[PortInfo]:
-    """List serial ports that look like an ESP32 (by USB VID/PID)."""
-    from serial.tools import list_ports
-
-    found: list[PortInfo] = []
-    for p in list_ports.comports():
-        if p.vid is None:
-            continue
-        for (vid, pid), chip in KNOWN_USB_IDS.items():
-            if p.vid == vid and (pid is None or p.pid == pid):
-                found.append(PortInfo(p.device, chip, p.description or ""))
-                break
-    return found
-
-
-def autodetect_port() -> PortInfo:
-    ports = find_ports()
-    if not ports:
-        raise NoDeviceError(
-            "no ESP32 serial port found (CP210x/CH340/CH9102/native USB); "
-            "pass port='COM5' / '/dev/ttyUSB0' explicitly"
-        )
-    if len(ports) > 1:
-        names = ", ".join(p.device for p in ports)
-        raise NoDeviceError(f"multiple ESP32-like ports found ({names}); pass port= explicitly")
-    return ports[0]
-
-
-class SerialTransport:
-    """Thin pyserial wrapper. read() returns whatever bytes are available."""
-
-    def __init__(self, port: str, baud: int = 115200, usb_chip: str | None = None):
-        import serial
-
-        self.usb_chip = usb_chip
-        self.ser = serial.Serial(port, baudrate=baud, timeout=0.05, write_timeout=2.0)
-
-    def read(self) -> bytes:
-        data = self.ser.read(1)  # blocks up to `timeout`
-        waiting = self.ser.in_waiting
-        if data and waiting:
-            data += self.ser.read(waiting)
-        return data
-
-    def write(self, data: bytes) -> None:
-        self.ser.write(data)
-
-    def set_baudrate(self, baud: int) -> None:
-        self.ser.baudrate = baud
-        self.ser.reset_input_buffer()
-
-    def pulse_reset(self) -> None:
-        """Toggle RTS/DTR the way esptool does to hard-reset the ESP32."""
-        self.ser.dtr = False
-        self.ser.rts = True
-        time.sleep(0.1)
-        self.ser.rts = False
-
-    def close(self) -> None:
-        try:
-            self.ser.close()
-        except Exception:
-            pass
-
-
-class MockTransport:
-    """In-memory transport for hardware-free tests.
-
-    `responder(data: bytes)` is called with everything the host writes; it can
-    push firmware->host bytes back via `inject()`.
-    """
-
-    def __init__(self, responder=None):
-        import queue
-
-        self.usb_chip = None
-        self._rx: queue.Queue[bytes] = queue.Queue()
-        self.responder = responder
-        self.closed = False
-        self.baud = 115200
-
-    def inject(self, data: bytes) -> None:
-        self._rx.put(data)
-
-    def read(self) -> bytes:
-        import queue
-
-        try:
-            return self._rx.get(timeout=0.05)
-        except queue.Empty:
-            return b""
-
-    def write(self, data: bytes) -> None:
-        if self.responder is not None:
-            self.responder(data)
-
-    def set_baudrate(self, baud: int) -> None:
-        self.baud = baud
-
-    def pulse_reset(self) -> None:
-        pass
-
-    def close(self) -> None:
-        self.closed = True
+__all__ = ["PortInfo", "SerialTransport", "MockTransport", "autodetect_port", "find_ports"]

espbridge/transports/__init__.py

@@ -0,0 +1,22 @@
+"""Transports: byte links the Bridge protocol runs over (serial, BLE, mock).
+
+A transport provides:
+    read() -> bytes        # whatever is available (may block briefly, b"" ok)
+    write(data: bytes)     # send raw bytes
+    close()
+    set_baudrate(baud)     # serial links only; no-op elsewhere
+    pulse_reset()          # serial links only; no-op elsewhere
+    usb_chip: str | None   # adapter hint for baud upgrade ("cp210x", ...)
+    has_baud: bool         # False to skip baud negotiation entirely
+    needs_auth: bool       # True = Bridge sends SYS_AUTH before the handshake
+"""
+from .serial import PortInfo, SerialTransport, autodetect_port, find_ports
+from .mock import MockTransport
+
+__all__ = [
+    "PortInfo",
+    "SerialTransport",
+    "MockTransport",
+    "autodetect_port",
+    "find_ports",
+]

espbridge/transports/ble.py

@@ -0,0 +1,162 @@
+"""Bluetooth (BLE) transport — talk to the bridge with no USB cable.
+
+The firmware advertises a Nordic-UART-style GATT service (see firmware
+link_ble.cpp); this transport carries the exact same COBS frame stream over
+it. Requires the `bleak` package: ``pip install python-esp-bridge[ble]``.
+
+bleak is asyncio-based; a private event loop runs in a daemon thread so the
+transport exposes the same blocking read()/write() interface as the serial
+one. Notifications land in a queue that read() drains.
+"""
+from __future__ import annotations
+
+import queue
+import threading
+from dataclasses import dataclass
+
+from ..constants import BLE_LINK_RX_UUID, BLE_LINK_SERVICE_UUID, BLE_LINK_TX_UUID
+from ..errors import BridgeError, NoDeviceError
+
+
+ADV_NAME_PREFIX = "espbridge_"  # firmware advertises espbridge_<mac>[_<name>]
+
+
+@dataclass(frozen=True)
+class BleDeviceInfo:
+    name: str     # advertised name: "espbridge_c049efd03fe0" or "espbridge_c049efd03fe0_relays"
+    address: str  # MAC on Windows/Linux, CoreBluetooth UUID on macOS
+    rssi: int
+
+    def _parts(self) -> tuple[str, str]:
+        rest = self.name.removeprefix(ADV_NAME_PREFIX)
+        hexpart, _, custom = rest.partition("_")
+        if len(hexpart) == 12 and all(c in "0123456789abcdef" for c in hexpart):
+            return hexpart, custom
+        return "", ""
+
+    @property
+    def mac(self) -> str:
+        """Bridge MAC (matches Info.mac) parsed from the advertised name."""
+        hexpart, _ = self._parts()
+        return ":".join(hexpart[i : i + 2] for i in range(0, 12, 2)) if hexpart else ""
+
+    @property
+    def device_name(self) -> str:
+        """User-assigned name (espbridge set-name), "" when unset."""
+        return self._parts()[1]
+
+
+def _require_bleak():
+    try:
+        import bleak  # noqa: F401
+    except ImportError:
+        raise BridgeError(
+            "the Bluetooth transport needs the 'bleak' package — "
+            "install with: pip install python-esp-bridge[ble]"
+        ) from None
+
+
+def find_ble_devices(timeout: float = 5.0) -> list[BleDeviceInfo]:
+    """Scan for bridges advertising the BLE link service."""
+    _require_bleak()
+    import asyncio
+
+    from bleak import BleakScanner
+
+    async def _scan():
+        found = await BleakScanner.discover(
+            timeout=timeout, return_adv=True,
+            service_uuids=[BLE_LINK_SERVICE_UUID],
+        )
+        return [
+            BleDeviceInfo(dev.name or "", dev.address, adv.rssi)
+            for dev, adv in found.values()
+        ]
+
+    return asyncio.run(_scan())
+
+
+class BleTransport:
+    """BLE GATT transport with the same blocking interface as SerialTransport."""
+
+    has_baud = False    # wireless: no baud negotiation
+    needs_auth = True   # firmware requires SYS_AUTH before other commands
+    usb_chip = None
+
+    def __init__(self, address: str, *, connect_timeout: float = 10.0):
+        _require_bleak()
+        import asyncio
+
+        self.address = address
+        self._rx: queue.Queue[bytes] = queue.Queue()
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever,
+                                        daemon=True, name="espbridge-ble")
+        self._thread.start()
+        self._client = None
+        try:
+            self._run(self._connect(address, connect_timeout), connect_timeout + 5)
+        except BaseException:
+            self._stop_loop()
+            raise
+
+    def _run(self, coro, timeout: float):
+        import asyncio
+
+        fut = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return fut.result(timeout)
+
+    async def _connect(self, address: str, timeout: float) -> None:
+        from bleak import BleakClient
+        from bleak.exc import BleakError
+
+        client = BleakClient(address, timeout=timeout)
+        try:
+            await client.connect()
+            await client.start_notify(BLE_LINK_TX_UUID, self._on_notify)
+        except BleakError as e:
+            raise NoDeviceError(f"BLE connect to {address} failed: {e}") from None
+        self._client = client
+        # write-without-response payload limit for this connection
+        self._chunk = max(20, client.mtu_size - 3)
+
+    def _on_notify(self, _char, data: bytearray) -> None:
+        self._rx.put(bytes(data))
+
+    async def _write(self, data: bytes) -> None:
+        for i in range(0, len(data), self._chunk):
+            await self._client.write_gatt_char(
+                BLE_LINK_RX_UUID, data[i : i + self._chunk], response=False)
+
+    async def _disconnect(self) -> None:
+        if self._client is not None:
+            try:
+                await self._client.disconnect()
+            except Exception:
+                pass
+
+    def read(self) -> bytes:
+        try:
+            return self._rx.get(timeout=0.05)
+        except queue.Empty:
+            return b""
+
+    def write(self, data: bytes) -> None:
+        self._run(self._write(data), timeout=10.0)
+
+    def set_baudrate(self, baud: int) -> None:
+        pass  # wireless
+
+    def pulse_reset(self) -> None:
+        pass  # no DTR/RTS lines over the air
+
+    def _stop_loop(self) -> None:
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=2.0)
+
+    def close(self) -> None:
+        try:
+            self._run(self._disconnect(), timeout=5.0)
+        except Exception:
+            pass
+        self._stop_loop()

espbridge/transports/mock.py

@@ -0,0 +1,46 @@
+"""In-memory transport for hardware-free tests."""
+from __future__ import annotations
+
+
+class MockTransport:
+    """In-memory transport for hardware-free tests.
+
+    `responder(data: bytes)` is called with everything the host writes; it can
+    push firmware->host bytes back via `inject()`.
+    """
+
+    has_baud = True    # exercises the baud-upgrade code path in tests
+    needs_auth = False  # tests flip this to emulate the wireless link
+
+    def __init__(self, responder=None):
+        import queue
+
+        self.usb_chip = None
+        self._rx: queue.Queue[bytes] = queue.Queue()
+        self.responder = responder
+        self.closed = False
+        self.baud = 115200
+
+    def inject(self, data: bytes) -> None:
+        self._rx.put(data)
+
+    def read(self) -> bytes:
+        import queue
+
+        try:
+            return self._rx.get(timeout=0.05)
+        except queue.Empty:
+            return b""
+
+    def write(self, data: bytes) -> None:
+        if self.responder is not None:
+            self.responder(data)
+
+    def set_baudrate(self, baud: int) -> None:
+        self.baud = baud
+
+    def pulse_reset(self) -> None:
+        pass
+
+    def close(self) -> None:
+        self.closed = True

espbridge/transports/serial.py

@@ -0,0 +1,83 @@
+"""Serial (USB) transport with ESP32 auto-detection."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from ..constants import KNOWN_USB_IDS
+from ..errors import NoDeviceError
+
+
+@dataclass(frozen=True)
+class PortInfo:
+    device: str          # e.g. "COM5" or "/dev/ttyUSB0"
+    usb_chip: str | None  # "cp210x" | "ch340" | "ch9102" | "native" | None
+    description: str = ""
+
+
+def find_ports() -> list[PortInfo]:
+    """List serial ports that look like an ESP32 (by USB VID/PID)."""
+    from serial.tools import list_ports
+
+    found: list[PortInfo] = []
+    for p in list_ports.comports():
+        if p.vid is None:
+            continue
+        for (vid, pid), chip in KNOWN_USB_IDS.items():
+            if p.vid == vid and (pid is None or p.pid == pid):
+                found.append(PortInfo(p.device, chip, p.description or ""))
+                break
+    return found
+
+
+def autodetect_port() -> PortInfo:
+    ports = find_ports()
+    if not ports:
+        raise NoDeviceError(
+            "no ESP32 serial port found (CP210x/CH340/CH9102/native USB); "
+            "pass port='COM5' / '/dev/ttyUSB0' explicitly"
+        )
+    if len(ports) > 1:
+        names = ", ".join(p.device for p in ports)
+        raise NoDeviceError(f"multiple ESP32-like ports found ({names}); pass port= explicitly")
+    return ports[0]
+
+
+class SerialTransport:
+    """Thin pyserial wrapper. read() returns whatever bytes are available."""
+
+    has_baud = True
+    needs_auth = False  # USB implies physical access
+
+    def __init__(self, port: str, baud: int = 115200, usb_chip: str | None = None):
+        import serial
+
+        self.usb_chip = usb_chip
+        self.ser = serial.Serial(port, baudrate=baud, timeout=0.05, write_timeout=2.0)
+
+    def read(self) -> bytes:
+        data = self.ser.read(1)  # blocks up to `timeout`
+        waiting = self.ser.in_waiting
+        if data and waiting:
+            data += self.ser.read(waiting)
+        return data
+
+    def write(self, data: bytes) -> None:
+        self.ser.write(data)
+
+    def set_baudrate(self, baud: int) -> None:
+        self.ser.baudrate = baud
+        self.ser.reset_input_buffer()
+
+    def pulse_reset(self) -> None:
+        """Toggle RTS/DTR the way esptool does to hard-reset the ESP32."""
+        self.ser.dtr = False
+        self.ser.rts = True
+        time.sleep(0.1)
+        self.ser.rts = False
+
+    def close(self) -> None:
+        try:
+            self.ser.close()
+        except Exception:
+            pass

{python_esp_bridge-0.0.2.dist-info → python_esp_bridge-0.1.0.dist-info}/METADATA

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: python-esp-bridge
-Version: 0.0.2
-Summary: Control every ESP32 peripheral from Python over USB serial — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE
+Version: 0.1.0
+Summary: Control every ESP32 peripheral from Python over USB serial or Bluetooth — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE
 Project-URL: Homepage, https://github.com/HamzaYslmn/python-esp-bridge
 Author: HamzaYslmn
 Keywords: ble,bridge,esp32,firmata,gpio,i2c,raspberry-pi,serial,spi
 Requires-Python: >=3.10
 Requires-Dist: pyserial>=3.5
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == 'ble'
 Provides-Extra: oled
 Requires-Dist: pillow>=10; extra == 'oled'
 Description-Content-Type: text/markdown

{python_esp_bridge-0.0.2.dist-info → python_esp_bridge-0.1.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-espbridge/__init__.py,sha256=J6wt84grWASJUf09iWopqoXdbONxV17rRlYBswsDIkU,1063
+espbridge/__init__.py,sha256=6VVe2-7SouV2rk7hgoSKceNaqzWEcw4bt8mCh_P3biA,1340
 espbridge/analog.py,sha256=zv1EFVZC2CSNBr-J0wvQw2QZIdKQzhSrknfYmaOkSig,2247
 espbridge/ble.py,sha256=fuTWlVoqCiDlu0e0-6r4Trq1VR_7skZwSFtpIgzZNyc,8321
-espbridge/bridge.py,sha256=E6kHPq6NYIkROn-e4pFqcZtp3l8DCXGlO5FDOIPYhT8,17358
-espbridge/cli.py,sha256=6gVeDrb7AbR-vGDnJlbBhhQ0J9HBxBZmbAzjcLh8rZM,3101
-espbridge/constants.py,sha256=btS0wKrp6MfsT28kqcqYL7I9dNHVWlYdXPw1P3Dgxzc,4816
-espbridge/errors.py,sha256=gYKhAohajGVGXiuzkC-i2KzvygvbgMZoqnJ8x-F7HyI,1051
+espbridge/bridge.py,sha256=qZ7eMboWXrqtdyh2vFr2gMXV5PeGgKUMGpiqp9FNZ68,21529
+espbridge/cli.py,sha256=AU77HpRtBtD0iKNs7e9JVetW7IGhJAj_HY_wCVyDvk8,5299
+espbridge/constants.py,sha256=oNLij2gfgTbj75M16ByaOZ4U0fn7X1X0AWNUuFNOdE0,5419
+espbridge/errors.py,sha256=111gvpi0J3-ioZ71X-yORDlSZvWWp3eSsy4BTZKUYbI,1203
 espbridge/gpio.py,sha256=daaE7GgjYxGBnGpFbkKMTsqLmyao8e5Hs_1dM3uFWFc,2384
 espbridge/i2c.py,sha256=S7uISLcMOMFTGIfOeL8li4TIG9slI6E3G380u7Q9ACM,2772
 espbridge/net.py,sha256=PHVg2OQYh5Ap-Zdi1C9vW-qEohExzwgBT-03ImCElYI,9634
@@ -12,7 +12,7 @@ espbridge/oled.py,sha256=UYEDZmfl8UwCw4B36Awk_uGdROR2W5jRpUeOfD1sCJ0,8072
 espbridge/protocol.py,sha256=kIns3gXxZ7wZABY5En5YeK1MgtT86-GVr4_JBMqIhTI,4405
 espbridge/pwm.py,sha256=S2VzG6lh0GRM-WUaXp6uHbKZ8dvlRVs4T7WW_nCxj0o,1669
 espbridge/spi.py,sha256=eNdrhPlpdgPPIzI4OHIC0vJ3dQnSX2W1m6lw6_n5DXk,1688
-espbridge/transport.py,sha256=rJmUyalr3-2ilVUGnhseV9alewmnD3v7QT_75ho31i4,3432
+espbridge/transport.py,sha256=03fJ2xZJgCu-_QEY7Bn08jVIbew2tlSKSRvt-AZGJ5E,295
 espbridge/uart.py,sha256=-PgCjr5iMkhp9b_PYr_qPNYBwPfjYv4Ancjq0bxgWtc,3870
 espbridge/wifi.py,sha256=q7FH-9DoClSyR7ibGCb2KHkNTP4NqrqNo6gtn9SAzpw,4198
 espbridge/compat/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -21,7 +21,11 @@ espbridge/compat/gpiozero.py,sha256=PMD7_yUPH0CF9mycf4XZeollH-G54MeSy3X72vXNZJY,
 espbridge/compat/luma.py,sha256=iErusKC4dccFzN5qK1HfZ_q0rt50j8L9SK0ZBtc9nlY,3382
 espbridge/compat/rpi_gpio.py,sha256=YwOXbXdNLVVHv1CbODV_tCNg59iXWEuhpBCkAaSZnF8,3346
 espbridge/compat/smbus.py,sha256=k8h1VQe6SzqRKvtfsuVzw8YFDjceedDdod5JtG0QX0s,2519
-python_esp_bridge-0.0.2.dist-info/METADATA,sha256=Cl44L_9aK_dV7oVYofm3KsPKACM4P5hJQ_lbdY0FoTQ,1393
-python_esp_bridge-0.0.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_esp_bridge-0.0.2.dist-info/entry_points.txt,sha256=xXm9lM8iMGXRhFiDBZrncBlA_RuWOSCxUO2_v7jGuGE,49
-python_esp_bridge-0.0.2.dist-info/RECORD,,
+espbridge/transports/__init__.py,sha256=0EFGmisSGAuhZx7UQ_RXDoNz8Pd2AqdqWCNOeLrYlzw,813
+espbridge/transports/ble.py,sha256=IQYVdwSB2txYBjm3o9RtYSTP5wGBGHJKzakVsdn6qgc,5383
+espbridge/transports/mock.py,sha256=WtIMB8FxinYnM7ns0bRL8lHB_Czn33T5PobGDnvWRhY,1205
+espbridge/transports/serial.py,sha256=PZcDRg8QG7-Y4MrBKfnm6DCC_2iO_ZOtztZsKxviVjo,2505
+python_esp_bridge-0.1.0.dist-info/METADATA,sha256=7WQYnWCLrjWW1ntL8QVVST1CsX1vuaWRQXq7azlI3G4,1469
+python_esp_bridge-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_esp_bridge-0.1.0.dist-info/entry_points.txt,sha256=xXm9lM8iMGXRhFiDBZrncBlA_RuWOSCxUO2_v7jGuGE,49
+python_esp_bridge-0.1.0.dist-info/RECORD,,