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

espbridge/spi.py

@@ -0,0 +1,43 @@
+"""SPI master, full-duplex transfers."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+# Max data per TRANSFER frame: payload cap minus host(1) + cs(1) header bytes.
+_CHUNK = C.MAX_PAYLOAD - 2
+
+
+class Spi:
+    def __init__(self, bridge):
+        self._b = bridge
+
+    def init(self, *, sck: int = 18, miso: int = 19, mosi: int = 23,
+             freq: int = 1_000_000, mode: int = 0, msb_first: bool = True,
+             host: int = 0) -> None:
+        self._b.request(C.SPI_INIT, struct.pack(">BbbbIBB", host, sck, miso, mosi,
+                                                freq, mode, 1 if msb_first else 0))
+
+    def transfer(self, tx: bytes, *, cs: int | None = None, host: int = 0) -> bytes:
+        """Full-duplex transfer; returns the bytes clocked in (len == len(tx)).
+
+        With `cs` given, CS is held low for the whole transfer — limited to
+        one frame (≤ 2046 bytes). Without `cs`, any length (chunked).
+        """
+        tx = bytes(tx)
+        cs_b = 255 if cs is None else cs  # i8 -1 == 255 unsigned
+        if cs is not None and len(tx) > _CHUNK:
+            raise ValueError(
+                f"transfers with CS are limited to {_CHUNK} bytes per call "
+                "(CS would deassert between chunks); split the transfer or manage "
+                "CS manually via gpio"
+            )
+        rx = bytearray()
+        for off in range(0, len(tx), _CHUNK):
+            chunk = tx[off : off + _CHUNK]
+            rx += self._b.request(C.SPI_TRANSFER, bytes([host, cs_b]) + chunk, timeout=10.0)
+        return bytes(rx)
+
+    def deinit(self, host: int = 0) -> None:
+        self._b.request(C.SPI_DEINIT, bytes([host]))

espbridge/transport.py

@@ -0,0 +1,121 @@
+"""Serial transport with ESP32 auto-detection, plus an in-memory mock for tests."""
+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."""
+
+    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

espbridge/uart.py

@@ -0,0 +1,111 @@
+"""Secondary UARTs (1, 2): write from host, RX streamed back as events."""
+from __future__ import annotations
+
+import struct
+import threading
+
+from . import constants as C
+
+# Per-request write chunk: bounds single-request size (and how long the
+# firmware's synchronous UART write can stall on slow baud rates).
+_WRITE_CHUNK = 1024
+
+
+class UartPort:
+    """Bridged UART with a pyserial-like surface (read/write/in_waiting/...)."""
+
+    def __init__(self, bridge, port: int):
+        self._b = bridge
+        self.port = port
+        self.timeout: float | None = None  # default for read()/read_until()
+        self._buf = bytearray()
+        self._cond = threading.Condition()
+        self._callbacks: list = []
+
+    def _feed(self, data: bytes) -> None:
+        with self._cond:
+            self._buf += data
+            self._cond.notify_all()
+        for cb in list(self._callbacks):
+            cb(data)
+
+    def write(self, data: bytes) -> None:
+        data = bytes(data)
+        for off in range(0, len(data), _WRITE_CHUNK):
+            self._b.request(C.UART_WRITE, bytes([self.port]) + data[off : off + _WRITE_CHUNK])
+
+    def read(self, n: int | None = None, timeout: float | None = None) -> bytes:
+        """Read up to n buffered bytes (all if n is None); waits up to `timeout`
+        (default: self.timeout, pyserial-style; None blocks until data)."""
+        timeout = self.timeout if timeout is None else timeout
+        with self._cond:
+            if not self._buf and timeout != 0:
+                self._cond.wait(timeout)
+            n = len(self._buf) if n is None else min(n, len(self._buf))
+            data = bytes(self._buf[:n])
+            del self._buf[:n]
+            return data
+
+    @property
+    def in_waiting(self) -> int:
+        """Bytes already received and buffered (pyserial-compatible)."""
+        with self._cond:
+            return len(self._buf)
+
+    def reset_input_buffer(self) -> None:
+        with self._cond:
+            self._buf.clear()
+
+    def flush(self) -> None:
+        pass  # writes are synchronous requests; nothing left to flush
+
+    def readline(self, timeout: float | None = None) -> bytes:
+        t = timeout if timeout is not None else (self.timeout or 2.0)
+        return self.read_until(b"\n", t)
+
+    def read_until(self, sep: bytes = b"\n", timeout: float = 2.0) -> bytes:
+        import time
+        deadline = time.monotonic() + timeout
+        with self._cond:
+            while True:
+                i = self._buf.find(sep)
+                if i >= 0:
+                    data = bytes(self._buf[: i + len(sep)])
+                    del self._buf[: i + len(sep)]
+                    return data
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    data = bytes(self._buf)
+                    self._buf.clear()
+                    return data
+                self._cond.wait(remaining)
+
+    def on_rx(self, callback) -> None:
+        """callback(bytes) on every RX chunk (runs on the reader thread)."""
+        self._callbacks.append(callback)
+
+    def close(self) -> None:
+        self._b.request(C.UART_DEINIT, bytes([self.port]))
+
+
+class Uart:
+    def __init__(self, bridge):
+        self._b = bridge
+        self._ports: dict[int, UartPort] = {}
+        bridge.on_event(C.UART_RX_EVT, self._on_rx)
+
+    def _on_rx(self, payload: bytes) -> None:
+        if len(payload) < 2:
+            return
+        port = self._ports.get(payload[0])
+        if port is not None:
+            port._feed(payload[1:])
+
+    def init(self, *, port: int = 1, tx: int = 17, rx: int = 16,
+             baud: int = 115_200) -> UartPort:
+        self._b.request(C.UART_INIT, struct.pack(">BbbI", port, tx, rx, baud))
+        p = self._ports.get(port)
+        if p is None:
+            p = UartPort(self._b, port)
+            self._ports[port] = p
+        return p

espbridge/wifi.py

@@ -0,0 +1,128 @@
+"""Wi-Fi management: scan, STA connect, AP mode, status."""
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+
+from . import constants as C
+from .errors import BridgeTimeoutError
+from .protocol import ip_str as _ip
+from .protocol import lp
+
+WL_CONNECTED = 3  # wl_status_t
+
+AUTH_MODES = {0: "open", 1: "wep", 2: "wpa_psk", 3: "wpa2_psk", 4: "wpa_wpa2_psk",
+              5: "wpa2_enterprise", 6: "wpa3_psk", 7: "wpa2_wpa3_psk", 8: "wapi_psk"}
+
+
+@dataclass(frozen=True)
+class Network:
+    ssid: str
+    rssi: int
+    bssid: str
+    channel: int
+    auth: str
+
+
+@dataclass(frozen=True)
+class WifiStatus:
+    status: int
+    ip: str
+    gateway: str
+    netmask: str
+    rssi: int
+    channel: int
+    mac: str
+
+    @property
+    def connected(self) -> bool:
+        return self.status == WL_CONNECTED
+
+
+class Wifi:
+    def __init__(self, bridge):
+        self._b = bridge
+        self._scan_results: list[Network] = []
+        self._scan_done = threading.Event()
+        self._state_callbacks: list = []
+        bridge.on_event(C.WIFI_SCAN_RES, self._on_scan_res)
+        bridge.on_event(C.WIFI_SCAN_DONE, self._on_scan_done)
+        bridge.on_event(C.WIFI_STATE_EVT, self._on_state)
+
+    # ---- events ---------------------------------------------------------------
+
+    def _on_scan_res(self, p: bytes) -> None:
+        if len(p) < 12:
+            return
+        ssid = p[12 : 12 + p[11]].decode("utf-8", "replace")
+        rssi = int.from_bytes(p[2:3], "big", signed=True)
+        bssid = ":".join(f"{x:02x}" for x in p[5:11])
+        self._scan_results.append(
+            Network(ssid, rssi, bssid, p[4], AUTH_MODES.get(p[3], str(p[3])))
+        )
+
+    def _on_scan_done(self, p: bytes) -> None:
+        self._scan_done.set()
+
+    def _on_state(self, p: bytes) -> None:
+        if not p:
+            return
+        event = {1: "connected", 2: "got_ip", 3: "disconnected"}.get(p[0], str(p[0]))
+        ip = _ip(p[1:5]) if len(p) >= 5 else "0.0.0.0"
+        for cb in list(self._state_callbacks):
+            cb(event, ip)
+
+    def on_state(self, callback) -> None:
+        """callback(event: str, ip: str) on connect/got_ip/disconnect."""
+        self._state_callbacks.append(callback)
+
+    # ---- commands ----------------------------------------------------------------
+
+    def scan(self, timeout: float = 15.0) -> list[Network]:
+        self._scan_results = []
+        self._scan_done.clear()
+        self._b.request(C.WIFI_SCAN)
+        if not self._scan_done.wait(timeout):
+            raise BridgeTimeoutError("Wi-Fi scan did not finish")
+        return sorted(self._scan_results, key=lambda n: -n.rssi)
+
+    def connect(self, ssid: str, password: str = "", *, wait: bool = True,
+                timeout: float = 20.0) -> WifiStatus:
+        self._b.request(C.WIFI_CONNECT, lp(ssid) + lp(password))
+        if not wait:
+            return self.status()
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            st = self.status()
+            if st.connected and st.ip != "0.0.0.0":
+                return st
+            time.sleep(0.25)
+        raise BridgeTimeoutError(f"could not join {ssid!r} within {timeout}s")
+
+    def disconnect(self) -> None:
+        self._b.request(C.WIFI_DISCONNECT)
+
+    def status(self) -> WifiStatus:
+        p = self._b.request(C.WIFI_STATUS)
+        return WifiStatus(
+            status=p[0],
+            ip=_ip(p[1:5]),
+            gateway=_ip(p[5:9]),
+            netmask=_ip(p[9:13]),
+            rssi=int.from_bytes(p[13:14], "big", signed=True),
+            channel=p[14],
+            mac=":".join(f"{x:02x}" for x in p[15:21]),
+        )
+
+    def ap_start(self, ssid: str, password: str = "", *, channel: int = 1,
+                 max_conn: int = 4) -> str:
+        """Start an access point; returns its IP (clients usually get 192.168.4.x)."""
+        payload = lp(ssid) + lp(password) + bytes([channel, max_conn])
+        return _ip(self._b.request(C.WIFI_AP_START, payload, timeout=5.0))
+
+    def ap_stop(self) -> None:
+        self._b.request(C.WIFI_AP_STOP)
+
+    def hostname(self, name: str) -> None:
+        self._b.request(C.WIFI_HOSTNAME, lp(name))

python_esp_bridge-0.0.2.dist-info/METADATA

@@ -0,0 +1,36 @@
+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
+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: oled
+Requires-Dist: pillow>=10; extra == 'oled'
+Description-Content-Type: text/markdown
+
+# python-esp-bridge
+
+Control every ESP32 peripheral from Python over USB serial — GPIO, PWM, ADC,
+DAC, touch, I2C, SPI, UART, Wi-Fi (with TCP/UDP sockets through the ESP32
+radio) and BLE. Flash the bridge firmware once, then it's all Python.
+
+```python
+from espbridge import Bridge
+
+with Bridge() as esp:                      # auto-detects the USB port
+    esp.gpio.mode(2, "output")
+    esp.gpio.write(2, 1)
+    print(esp.adc.read_mv(34), "mV")
+    esp.i2c.init(sda=21, scl=22)
+    print(esp.i2c.scan())
+    esp.wifi.connect("ssid", "password")
+    status, body = esp.net.http_get("http://example.com/")
+```
+
+- Firmware (flash once with Arduino IDE) and full docs:
+  **<https://github.com/HamzaYslmn/python-esp-bridge>**
+- Works on Raspberry Pi OS, Linux, Windows, macOS (Python ≥ 3.10, pyserial).
+- `espbridge` CLI: connection info; `espbridge ports`: list candidate ports.

python_esp_bridge-0.0.2.dist-info/RECORD

@@ -0,0 +1,27 @@
+espbridge/__init__.py,sha256=J6wt84grWASJUf09iWopqoXdbONxV17rRlYBswsDIkU,1063
+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/gpio.py,sha256=daaE7GgjYxGBnGpFbkKMTsqLmyao8e5Hs_1dM3uFWFc,2384
+espbridge/i2c.py,sha256=S7uISLcMOMFTGIfOeL8li4TIG9slI6E3G380u7Q9ACM,2772
+espbridge/net.py,sha256=PHVg2OQYh5Ap-Zdi1C9vW-qEohExzwgBT-03ImCElYI,9634
+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/uart.py,sha256=-PgCjr5iMkhp9b_PYr_qPNYBwPfjYv4Ancjq0bxgWtc,3870
+espbridge/wifi.py,sha256=q7FH-9DoClSyR7ibGCb2KHkNTP4NqrqNo6gtn9SAzpw,4198
+espbridge/compat/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+espbridge/compat/blinka.py,sha256=Pke1QWnXx6yoXR8T62XQBofSYUciyEHBTpw5fLIRo9c,6924
+espbridge/compat/gpiozero.py,sha256=PMD7_yUPH0CF9mycf4XZeollH-G54MeSy3X72vXNZJY,7841
+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,,

python_esp_bridge-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

python_esp_bridge-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+espbridge = espbridge.cli:main