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

espbridge/__init__.py

@@ -0,0 +1,45 @@
+"""espbridge — control every ESP32 peripheral from Python over USB serial.
+
+Flash esp/esp.ino once, then:
+
+    from espbridge import Bridge
+
+    with Bridge() as esp:                # auto-detects the serial port
+        esp.gpio.mode(2, "output")
+        esp.gpio.write(2, 1)
+        print(esp.adc.read(34))
+        print(esp.i2c.scan())
+        esp.wifi.connect("ssid", "password")
+        sock = esp.net.tcp_connect("example.com", 80)  # TCP through the ESP32 radio
+"""
+from .bridge import Bridge, BridgeSet, Info, connect_all
+from .constants import Cap, ChipModel, Status
+from .errors import (
+    BridgeError,
+    BridgeTimeoutError,
+    NoDeviceError,
+    ProtocolError,
+    RemoteError,
+    UnsupportedError,
+)
+from .transport import find_ports
+
+__version__ = "0.0.2"
+
+__all__ = [
+    "Bridge",
+    "BridgeSet",
+    "connect_all",
+    "Info",
+    "Cap",
+    "ChipModel",
+    "Status",
+    "BridgeError",
+    "BridgeTimeoutError",
+    "NoDeviceError",
+    "ProtocolError",
+    "RemoteError",
+    "UnsupportedError",
+    "find_ports",
+    "__version__",
+]

espbridge/analog.py

@@ -0,0 +1,64 @@
+"""ADC (oneshot reads), DAC (write + cosine generator), capacitive touch."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+# Attenuation -> roughly full-scale input voltage on classic ESP32:
+#   0 dB ≈ 1.1 V, 2.5 dB ≈ 1.5 V, 6 dB ≈ 2.2 V, 11 dB ≈ 3.3 V (default)
+ATTEN = {0: 0, 2.5: 1, 6: 2, 11: 3, "0db": 0, "2.5db": 1, "6db": 2, "11db": 3}
+
+
+class Adc:
+    def __init__(self, bridge):
+        self._b = bridge
+
+    def config(self, pin: int, atten=11) -> None:
+        self._b.request(C.ADC_CONFIG, bytes([pin, ATTEN.get(atten, int(atten))]))
+
+    def read(self, pin: int) -> int:
+        """Raw 12-bit reading (0..4095)."""
+        return struct.unpack(">H", self._b.request(C.ADC_READ, bytes([pin])))[0]
+
+    def read_mv(self, pin: int) -> int:
+        """Calibrated millivolts."""
+        return struct.unpack(">H", self._b.request(C.ADC_READ_MV, bytes([pin])))[0]
+
+
+class Dac:
+    """True 8-bit DAC — classic ESP32 (GPIO 25/26) and S2 (GPIO 17/18) only."""
+
+    def __init__(self, bridge):
+        bridge.require(C.Cap.DAC, "DAC")
+        self._b = bridge
+
+    def write(self, pin: int, value: int) -> None:
+        """Output value 0..255 (0..3.3 V)."""
+        self._b.request(C.DAC_WRITE, bytes([pin, value & 0xFF]))
+
+    def cosine(self, pin: int, freq_hz: int, *, scale: int = 0, offset: int = 0,
+               phase_180: bool = False) -> None:
+        """Start the hardware cosine-wave generator (~130 Hz .. ~100 kHz).
+
+        scale: 0..3 = full/half/quarter/eighth amplitude.
+        """
+        self._b.request(C.DAC_COSINE, struct.pack(">BIBbB", pin, freq_hz, scale & 3,
+                                                  offset, 1 if phase_180 else 0))
+
+    def cosine_stop(self, pin: int) -> None:
+        self._b.request(C.DAC_COS_STOP, bytes([pin]))
+
+    def disable(self, pin: int) -> None:
+        self._b.request(C.DAC_DISABLE, bytes([pin]))
+
+
+class Touch:
+    """Capacitive touch pads (classic ESP32: lower = touched; S2/S3: higher = touched)."""
+
+    def __init__(self, bridge):
+        bridge.require(C.Cap.TOUCH, "touch sensing")
+        self._b = bridge
+
+    def read(self, pin: int) -> int:
+        return struct.unpack(">I", self._b.request(C.TOUCH_READ, bytes([pin])))[0]

espbridge/ble.py

@@ -0,0 +1,223 @@
+"""BLE: scanning, advertising, GATT server and basic GATT client."""
+from __future__ import annotations
+
+import queue
+import struct
+import threading
+import time
+import uuid as _uuid
+from dataclasses import dataclass
+
+from . import constants as C
+from .errors import BridgeTimeoutError
+from .protocol import lp
+
+
+def to_uuid128(value: int | str | _uuid.UUID) -> bytes:
+    """16/32-bit ints expand into the Bluetooth base UUID; strs/UUIDs pass through."""
+    if isinstance(value, int):
+        return _uuid.UUID(f"{value:08x}-0000-1000-8000-00805f9b34fb").bytes
+    if isinstance(value, str):
+        return _uuid.UUID(value).bytes
+    return value.bytes
+
+
+@dataclass(frozen=True)
+class Advertisement:
+    addr: str
+    addr_type: int
+    rssi: int
+    data: bytes  # raw advertisement payload (AD structures)
+
+    @property
+    def name(self) -> str | None:
+        """Local name parsed from the AD structures, if present."""
+        i, d = 0, self.data
+        while i + 1 < len(d):
+            length = d[i]
+            if length == 0 or i + 1 + length > len(d) + 1:
+                break
+            ad_type = d[i + 1]
+            if ad_type in (0x08, 0x09):  # shortened / complete local name
+                return d[i + 2 : i + 1 + length].decode("utf-8", "replace")
+            i += 1 + length
+        return None
+
+
+class Characteristic:
+    """A characteristic of the local GATT server."""
+
+    def __init__(self, ble: "Ble", char_id: int, uuid_: bytes):
+        self._ble = ble
+        self.char_id = char_id
+        self.uuid = uuid_
+        self.on_write = None  # callback(bytes)
+
+    def set(self, data: bytes) -> None:
+        self._ble._b.request(C.BLE_GATTS_SET, bytes([self.char_id]) + bytes(data))
+
+    def notify(self, data: bytes) -> None:
+        self._ble._b.request(C.BLE_GATTS_NTFY, bytes([self.char_id]) + bytes(data))
+
+
+class GattClient:
+    """Connection to a remote BLE peripheral (one at a time)."""
+
+    def __init__(self, ble: "Ble"):
+        self._ble = ble
+        self.connected = True
+
+    def read(self, service, char) -> bytes:
+        return self._ble._b.request(
+            C.BLE_GATTC_READ, to_uuid128(service) + to_uuid128(char), timeout=10.0)
+
+    def write(self, service, char, data: bytes) -> None:
+        self._ble._b.request(
+            C.BLE_GATTC_WRITE, to_uuid128(service) + to_uuid128(char) + bytes(data),
+            timeout=10.0)
+
+    def subscribe(self, service, char, callback) -> None:
+        """callback(bytes) for notifications from this characteristic."""
+        self._ble._notify_callbacks[to_uuid128(char)] = callback
+        self._ble._b.request(
+            C.BLE_GATTC_SUB, to_uuid128(service) + to_uuid128(char) + b"\x01",
+            timeout=10.0)
+
+    def unsubscribe(self, service, char) -> None:
+        self._ble._notify_callbacks.pop(to_uuid128(char), None)
+        self._ble._b.request(
+            C.BLE_GATTC_SUB, to_uuid128(service) + to_uuid128(char) + b"\x00",
+            timeout=10.0)
+
+    def disconnect(self) -> None:
+        self.connected = False
+        self._ble._b.request(C.BLE_GATTC_DISC, timeout=10.0)
+
+
+class Ble:
+    # characteristic property flags
+    READ = C.GATT_PROP_READ
+    WRITE = C.GATT_PROP_WRITE
+    NOTIFY = C.GATT_PROP_NOTIFY
+    WRITE_NR = C.GATT_PROP_WRITE_NR
+
+    def __init__(self, bridge):
+        self._b = bridge
+        bridge.require(C.Cap.BLE_FW, "BLE (firmware built without it?)")
+        self._adv_queue: queue.Queue[Advertisement] = queue.Queue(maxsize=512)
+        self._adv_callbacks: list = []
+        self._chars: dict[int, Characteristic] = {}
+        self._notify_callbacks: dict[bytes, object] = {}
+        self._server_connected = threading.Event()
+        bridge.on_event(C.BLE_ADV_EVT, self._on_adv)
+        bridge.on_event(C.BLE_GATTS_WR_EVT, self._on_gatts_write)
+        bridge.on_event(C.BLE_GATTS_CONN_EVT, self._on_gatts_conn)
+        bridge.on_event(C.BLE_GATTC_NTFY_EVT, self._on_notify)
+
+    # ---- events (reader thread) ---------------------------------------------------
+
+    def _on_adv(self, p: bytes) -> None:
+        if len(p) < 8:
+            return
+        adv = Advertisement(
+            addr=":".join(f"{x:02x}" for x in p[0:6]),
+            addr_type=p[6],
+            rssi=int.from_bytes(p[7:8], "big", signed=True),
+            data=p[8:],
+        )
+        for cb in list(self._adv_callbacks):
+            cb(adv)
+        try:
+            self._adv_queue.put_nowait(adv)
+        except queue.Full:
+            pass
+
+    def _on_gatts_write(self, p: bytes) -> None:
+        if not p:
+            return
+        ch = self._chars.get(p[0])
+        if ch is not None and ch.on_write is not None:
+            ch.on_write(p[1:])
+
+    def _on_gatts_conn(self, p: bytes) -> None:
+        if p and p[0]:
+            self._server_connected.set()
+        else:
+            self._server_connected.clear()
+
+    def _on_notify(self, p: bytes) -> None:
+        if len(p) < 16:
+            return
+        cb = self._notify_callbacks.get(bytes(p[:16]))
+        if cb is not None:
+            cb(p[16:])
+
+    # ---- scanning --------------------------------------------------------------------
+
+    def scan(self, duration: float = 5.0, *, active: bool = True,
+             callback=None) -> list[Advertisement]:
+        """Collect advertisements for `duration` seconds.
+
+        With `callback`, advertisements also stream to it live. Returns devices
+        deduplicated by address (strongest RSSI kept).
+        """
+        if callback is not None:
+            self._adv_callbacks.append(callback)
+        while not self._adv_queue.empty():  # drop stale results
+            self._adv_queue.get_nowait()
+        self._b.request(C.BLE_SCAN_START, bytes([min(255, int(duration) + 1), 1 if active else 0]),
+                        timeout=10.0)
+        seen: dict[str, Advertisement] = {}
+        deadline = time.monotonic() + duration
+        while time.monotonic() < deadline:
+            try:
+                adv = self._adv_queue.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            cur = seen.get(adv.addr)
+            if cur is None or adv.rssi > cur.rssi or (adv.name and not cur.name):
+                seen[adv.addr] = adv
+        self._b.request(C.BLE_SCAN_STOP, timeout=10.0)
+        if callback is not None:
+            self._adv_callbacks.remove(callback)
+        return sorted(seen.values(), key=lambda a: -a.rssi)
+
+    # ---- advertising ----------------------------------------------------------------
+
+    def advertise(self, name: str = "", *, manufacturer_data: bytes = b"",
+                  service_uuid16: int = 0) -> None:
+        payload = lp(name) + lp(manufacturer_data) + struct.pack(">H", service_uuid16)
+        self._b.request(C.BLE_ADV_START, payload, timeout=10.0)
+
+    def advertise_stop(self) -> None:
+        self._b.request(C.BLE_ADV_STOP, timeout=10.0)
+
+    # ---- GATT server -----------------------------------------------------------------
+
+    def serve(self, service, chars: list[tuple[object, int]]) -> list[Characteristic]:
+        """Define a GATT service. `chars` is [(uuid, props), ...] with props a
+        bitmask of Ble.READ / Ble.WRITE / Ble.NOTIFY / Ble.WRITE_NR.
+        Call advertise() afterwards to become discoverable."""
+        payload = to_uuid128(service) + bytes([len(chars)])
+        for u, props in chars:
+            payload += to_uuid128(u) + bytes([props])
+        ids = self._b.request(C.BLE_GATTS_DEF, payload, timeout=10.0)
+        out = []
+        for (u, _), cid in zip(chars, ids):
+            ch = Characteristic(self, cid, to_uuid128(u))
+            self._chars[cid] = ch
+            out.append(ch)
+        return out
+
+    def wait_connect(self, timeout: float | None = None) -> bool:
+        return self._server_connected.wait(timeout)
+
+    # ---- GATT client ------------------------------------------------------------------
+
+    def connect(self, addr: str, addr_type: int = 0, timeout: float = 15.0) -> GattClient:
+        """Connect to a peripheral by address ("aa:bb:cc:dd:ee:ff")."""
+        mac = bytes(int(x, 16) for x in addr.split(":"))
+        if len(mac) != 6:
+            raise ValueError("address must be 6 bytes, e.g. 'aa:bb:cc:dd:ee:ff'")
+        self._b.request(C.BLE_GATTC_CONN, mac + bytes([addr_type]), timeout=timeout)
+        return GattClient(self)