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

espbridge/compat/smbus.py

@@ -0,0 +1,63 @@
+"""smbus2-compatible SMBus, so classic Raspberry Pi I2C code runs unchanged.
+
+    from espbridge import Bridge
+    from espbridge.compat.smbus import SMBus
+
+    with Bridge() as esp:
+        bus = SMBus(esp)                       # instead of smbus2.SMBus(1)
+        temp = bus.read_byte_data(0x48, 0x00)  # the rest of the code is identical
+        bus.write_i2c_block_data(0x20, 0x06, [0xFF, 0x00])
+
+Word data is little-endian, matching the SMBus specification (and smbus2).
+"""
+from __future__ import annotations
+
+
+class SMBus:
+    def __init__(self, esp, *, sda: int = 21, scl: int = 22,
+                 freq: int = 100_000, bus: int = 0, init: bool = True):
+        self._i2c = esp.i2c
+        self._bus = bus
+        if init:
+            self._i2c.init(sda=sda, scl=scl, freq=freq, bus=bus)
+
+    # ---- plain byte ----------------------------------------------------------
+    def read_byte(self, addr: int) -> int:
+        return self._i2c.read(addr, 1, self._bus)[0]
+
+    def write_byte(self, addr: int, value: int) -> None:
+        self._i2c.write(addr, bytes([value & 0xFF]), self._bus)
+
+    def write_quick(self, addr: int) -> None:
+        self._i2c.write(addr, b"", self._bus)
+
+    # ---- register (command) based -----------------------------------------------
+    def read_byte_data(self, addr: int, register: int) -> int:
+        return self._i2c.write_read(addr, bytes([register]), 1, self._bus)[0]
+
+    def write_byte_data(self, addr: int, register: int, value: int) -> None:
+        self._i2c.write(addr, bytes([register, value & 0xFF]), self._bus)
+
+    def read_word_data(self, addr: int, register: int) -> int:
+        lo, hi = self._i2c.write_read(addr, bytes([register]), 2, self._bus)
+        return lo | (hi << 8)
+
+    def write_word_data(self, addr: int, register: int, value: int) -> None:
+        self._i2c.write(addr, bytes([register, value & 0xFF, (value >> 8) & 0xFF]),
+                        self._bus)
+
+    def read_i2c_block_data(self, addr: int, register: int, length: int = 32) -> list[int]:
+        return list(self._i2c.write_read(addr, bytes([register]), length, self._bus))
+
+    def write_i2c_block_data(self, addr: int, register: int, data) -> None:
+        self._i2c.write(addr, bytes([register]) + bytes(data), self._bus)
+
+    # ---- lifecycle -------------------------------------------------------------
+    def close(self) -> None:
+        pass  # the Bridge owns the link
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()

espbridge/constants.py

@@ -0,0 +1,199 @@
+"""python-esp-bridge — shared protocol contract.
+
+MUST stay in sync with esp/src/espbridge/commands.h.
+"""
+from __future__ import annotations
+
+import enum
+
+PROTOCOL_VERSION = 1
+
+# Frame (logical, pre-COBS):
+#   flags u8 | seq u8 | cmd u16 BE | payload .. | crc16 BE
+# COBS-encoded on the wire, frames delimited by 0x00.
+FLAG_EVENT = 0x01
+FLAG_ERROR = 0x02
+FLAG_MORE = 0x04
+
+MAX_PAYLOAD = 2048
+NET_CHUNK = 512
+UART_CHUNK = 256
+
+
+class Status(enum.IntEnum):
+    OK = 0x00
+    UNKNOWN_CMD = 0x01
+    BAD_ARGS = 0x02
+    UNSUPPORTED = 0x03
+    BUSY = 0x04
+    TIMEOUT = 0x05
+    NO_MEM = 0x06
+    BAD_PIN = 0x07
+    NOT_INIT = 0x08
+    IO = 0x09
+    WIFI = 0x0A
+    SOCKET = 0x0B
+    CRC = 0x0C
+
+
+class Cap(enum.IntFlag):
+    WIFI = 1 << 0
+    BLE = 1 << 1
+    BT_CLASSIC = 1 << 2
+    DAC = 1 << 3
+    TOUCH = 1 << 4
+    HALL = 1 << 5
+    PSRAM = 1 << 6
+    NATIVE_USB = 1 << 7
+    BLE_FW = 1 << 8
+
+
+class ChipModel(enum.IntEnum):
+    UNKNOWN = 0
+    ESP32 = 1
+    ESP32S2 = 2
+    ESP32S3 = 3
+    ESP32C3 = 4
+    ESP32C6 = 5
+    ESP32H2 = 6
+
+
+def _cmd(mod: int, op: int) -> int:
+    return (mod << 8) | op
+
+
+MOD_SYS = 0x00
+MOD_GPIO = 0x10
+MOD_ADC = 0x20
+MOD_DAC = 0x21
+MOD_TOUCH = 0x22
+MOD_PWM = 0x30
+MOD_I2C = 0x40
+MOD_SPI = 0x41
+MOD_UART = 0x42
+MOD_WIFI = 0x50
+MOD_NET = 0x51
+MOD_BLE = 0x60
+
+# SYS
+SYS_PING = _cmd(MOD_SYS, 0x01)
+SYS_INFO = _cmd(MOD_SYS, 0x02)
+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_READY = _cmd(MOD_SYS, 0x80)
+SYS_LOG = _cmd(MOD_SYS, 0x81)
+
+BRIDGE_NAME_MAX = 32
+
+# GPIO
+GPIO_SET_MODE = _cmd(MOD_GPIO, 0x01)
+GPIO_WRITE = _cmd(MOD_GPIO, 0x02)
+GPIO_READ = _cmd(MOD_GPIO, 0x03)
+GPIO_WRITE_MASK = _cmd(MOD_GPIO, 0x04)
+GPIO_READ_ALL = _cmd(MOD_GPIO, 0x05)
+GPIO_WATCH = _cmd(MOD_GPIO, 0x06)
+GPIO_UNWATCH = _cmd(MOD_GPIO, 0x07)
+GPIO_EDGE_EVT = _cmd(MOD_GPIO, 0x80)
+
+# ADC / DAC / TOUCH
+ADC_CONFIG = _cmd(MOD_ADC, 0x01)
+ADC_READ = _cmd(MOD_ADC, 0x02)
+ADC_READ_MV = _cmd(MOD_ADC, 0x03)
+DAC_WRITE = _cmd(MOD_DAC, 0x01)
+DAC_COSINE = _cmd(MOD_DAC, 0x02)
+DAC_COS_STOP = _cmd(MOD_DAC, 0x03)
+DAC_DISABLE = _cmd(MOD_DAC, 0x04)
+TOUCH_READ = _cmd(MOD_TOUCH, 0x01)
+
+# PWM
+PWM_ATTACH = _cmd(MOD_PWM, 0x01)
+PWM_WRITE = _cmd(MOD_PWM, 0x02)
+PWM_DETACH = _cmd(MOD_PWM, 0x03)
+PWM_TONE = _cmd(MOD_PWM, 0x04)
+
+# I2C
+I2C_INIT = _cmd(MOD_I2C, 0x01)
+I2C_SCAN = _cmd(MOD_I2C, 0x02)
+I2C_WRITE = _cmd(MOD_I2C, 0x03)
+I2C_READ = _cmd(MOD_I2C, 0x04)
+I2C_WRITE_READ = _cmd(MOD_I2C, 0x05)
+I2C_DEINIT = _cmd(MOD_I2C, 0x06)
+
+# SPI
+SPI_INIT = _cmd(MOD_SPI, 0x01)
+SPI_TRANSFER = _cmd(MOD_SPI, 0x02)
+SPI_DEINIT = _cmd(MOD_SPI, 0x03)
+
+# UART
+UART_INIT = _cmd(MOD_UART, 0x01)
+UART_WRITE = _cmd(MOD_UART, 0x02)
+UART_DEINIT = _cmd(MOD_UART, 0x03)
+UART_RX_EVT = _cmd(MOD_UART, 0x80)
+
+# WIFI
+WIFI_SCAN = _cmd(MOD_WIFI, 0x01)
+WIFI_CONNECT = _cmd(MOD_WIFI, 0x02)
+WIFI_DISCONNECT = _cmd(MOD_WIFI, 0x03)
+WIFI_STATUS = _cmd(MOD_WIFI, 0x04)
+WIFI_AP_START = _cmd(MOD_WIFI, 0x05)
+WIFI_AP_STOP = _cmd(MOD_WIFI, 0x06)
+WIFI_HOSTNAME = _cmd(MOD_WIFI, 0x07)
+WIFI_STATE_EVT = _cmd(MOD_WIFI, 0x80)
+WIFI_SCAN_RES = _cmd(MOD_WIFI, 0x81)
+WIFI_SCAN_DONE = _cmd(MOD_WIFI, 0x82)
+
+# NET
+NET_TCP_CONNECT = _cmd(MOD_NET, 0x01)
+NET_TCP_LISTEN = _cmd(MOD_NET, 0x02)
+NET_UDP_OPEN = _cmd(MOD_NET, 0x03)
+NET_SEND = _cmd(MOD_NET, 0x04)
+NET_SEND_TO = _cmd(MOD_NET, 0x05)
+NET_CLOSE = _cmd(MOD_NET, 0x06)
+NET_WINDOW_ACK = _cmd(MOD_NET, 0x07)
+NET_DATA_EVT = _cmd(MOD_NET, 0x80)
+NET_ACCEPT_EVT = _cmd(MOD_NET, 0x81)
+NET_CLOSED_EVT = _cmd(MOD_NET, 0x82)
+NET_UDP_EVT = _cmd(MOD_NET, 0x83)
+
+# BLE
+BLE_SCAN_START = _cmd(MOD_BLE, 0x01)
+BLE_SCAN_STOP = _cmd(MOD_BLE, 0x02)
+BLE_ADV_START = _cmd(MOD_BLE, 0x03)
+BLE_ADV_STOP = _cmd(MOD_BLE, 0x04)
+BLE_GATTS_DEF = _cmd(MOD_BLE, 0x05)
+BLE_GATTS_SET = _cmd(MOD_BLE, 0x06)
+BLE_GATTS_NTFY = _cmd(MOD_BLE, 0x07)
+BLE_GATTC_CONN = _cmd(MOD_BLE, 0x08)
+BLE_GATTC_DISC = _cmd(MOD_BLE, 0x09)
+BLE_GATTC_READ = _cmd(MOD_BLE, 0x0A)
+BLE_GATTC_WRITE = _cmd(MOD_BLE, 0x0B)
+BLE_GATTC_SUB = _cmd(MOD_BLE, 0x0C)
+BLE_ADV_EVT = _cmd(MOD_BLE, 0x80)
+BLE_GATTS_WR_EVT = _cmd(MOD_BLE, 0x81)
+BLE_GATTS_CONN_EVT = _cmd(MOD_BLE, 0x82)
+BLE_GATTC_NTFY_EVT = _cmd(MOD_BLE, 0x83)
+BLE_GATTC_DISC_EVT = _cmd(MOD_BLE, 0x84)
+
+GATT_PROP_READ = 0x01
+GATT_PROP_WRITE = 0x02
+GATT_PROP_NOTIFY = 0x04
+GATT_PROP_WRITE_NR = 0x08
+
+# USB-UART bridge chips found on ESP32 dev boards: (vid, pid) -> chip
+KNOWN_USB_IDS = {
+    (0x10C4, 0xEA60): "cp210x",   # CP2102/CP2104 (most DevKitC)
+    (0x1A86, 0x7523): "ch340",    # CH340
+    (0x1A86, 0x55D4): "ch9102",   # CH9102 (CH340 successor)
+    (0x303A, None): "native",     # Espressif native USB (S2/S3/C3/...)
+}
+
+# Safe upgraded baud per bridge chip (conservative defaults; CH340 can do 2M).
+UPGRADE_BAUD = {
+    "cp210x": 921600,
+    "ch340": 921600,
+    "ch9102": 921600,
+    "native": None,  # USB CDC ignores baud
+    None: 921600,
+}

espbridge/errors.py

@@ -0,0 +1,38 @@
+"""Exception hierarchy for espbridge."""
+from __future__ import annotations
+
+from .constants import Status
+
+
+class BridgeError(Exception):
+    """Base class for all espbridge errors."""
+
+
+class BridgeTimeoutError(BridgeError, TimeoutError):
+    """The firmware did not answer in time."""
+
+
+class ProtocolError(BridgeError):
+    """Malformed frame, CRC mismatch, or protocol version mismatch."""
+
+
+class NoDeviceError(BridgeError):
+    """No (or ambiguous) ESP32 bridge serial port found."""
+
+
+class UnsupportedError(BridgeError):
+    """The connected chip lacks this capability (e.g. DAC on ESP32-S3)."""
+
+
+class RemoteError(BridgeError):
+    """The firmware returned an error status for a request."""
+
+    def __init__(self, status: int, cmd: int):
+        try:
+            self.status = Status(status)
+            name = self.status.name
+        except ValueError:
+            self.status = status  # unknown code
+            name = f"0x{status:02X}"
+        self.cmd = cmd
+        super().__init__(f"firmware error {name} for command 0x{cmd:04X}")

espbridge/gpio.py

@@ -0,0 +1,72 @@
+"""GPIO: modes, read/write, batch ops, edge interrupts."""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from . import constants as C
+
+MODES = {
+    "input": 0,
+    "output": 1,
+    "input_pullup": 2,
+    "input_pulldown": 3,
+    "output_open_drain": 4,
+}
+EDGES = {"rising": 1, "falling": 2, "change": 3}
+
+
+@dataclass(frozen=True)
+class EdgeEvent:
+    pin: int
+    level: int
+    millis: int  # firmware uptime ms
+
+
+class Gpio:
+    def __init__(self, bridge):
+        self._b = bridge
+        self._watchers: dict[int, list] = {}
+        bridge.on_event(C.GPIO_EDGE_EVT, self._on_edge)
+
+    def _on_edge(self, payload: bytes) -> None:
+        if len(payload) < 6:
+            return
+        ev = EdgeEvent(payload[0], payload[1], struct.unpack_from(">I", payload, 2)[0])
+        for cb in self._watchers.get(ev.pin, ()):
+            cb(ev)
+
+    def mode(self, pin: int, mode: str | int) -> None:
+        m = MODES[mode] if isinstance(mode, str) else int(mode)
+        self._b.request(C.GPIO_SET_MODE, bytes([pin, m]))
+
+    def write(self, pin: int, value: int | bool) -> None:
+        self._b.request(C.GPIO_WRITE, bytes([pin, 1 if value else 0]))
+
+    def read(self, pin: int) -> int:
+        return self._b.request(C.GPIO_READ, bytes([pin]))[0]
+
+    def write_many(self, values: dict[int, int | bool]) -> None:
+        """Set multiple output pins in one round-trip."""
+        mask = vals = 0
+        for pin, v in values.items():
+            mask |= 1 << pin
+            if v:
+                vals |= 1 << pin
+        self._b.request(C.GPIO_WRITE_MASK, struct.pack(">QQ", mask, vals))
+
+    def read_all(self) -> int:
+        """Levels of all pins as a bitmask (bit N = GPIO N)."""
+        (levels,) = struct.unpack(">Q", self._b.request(C.GPIO_READ_ALL))
+        return levels
+
+    def watch(self, pin: int, edge: str = "change", debounce_ms: int = 0, callback=None) -> None:
+        """Get `callback(EdgeEvent)` on pin edges (callback runs on the reader thread)."""
+        e = EDGES[edge] if isinstance(edge, str) else int(edge)
+        if callback is not None:
+            self._watchers.setdefault(pin, []).append(callback)
+        self._b.request(C.GPIO_WATCH, struct.pack(">BBH", pin, e, debounce_ms))
+
+    def unwatch(self, pin: int) -> None:
+        self._b.request(C.GPIO_UNWATCH, bytes([pin]))
+        self._watchers.pop(pin, None)

espbridge/i2c.py

@@ -0,0 +1,65 @@
+"""I2C master (buses 0 and 1)."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+
+class I2c:
+    def __init__(self, bridge):
+        self._b = bridge
+
+    @property
+    def max_write(self) -> int:
+        """Largest data block write() accepts, firmware-dependent: older
+        firmware leaves Wire's TX buffer at its 128-byte default and
+        silently truncates anything longer."""
+        info = self._b.info
+        if info is not None and info.fw_version < (0, 0, 2):
+            return 128
+        return C.MAX_PAYLOAD - 2  # frame carries bus + addr first
+
+    def init(self, *, sda: int = 21, scl: int = 22, freq: int = 400_000, bus: int = 0) -> None:
+        self._b.request(C.I2C_INIT, struct.pack(">BBBI", bus, sda, scl, freq))
+
+    def scan(self, bus: int = 0) -> list[int]:
+        """Addresses (7-bit) that ACK on the bus."""
+        r = self._b.request(C.I2C_SCAN, bytes([bus]), timeout=5.0)
+        return list(r[1 : 1 + r[0]])
+
+    def write(self, addr: int, data: bytes, bus: int = 0, *, wait: bool = True) -> None:
+        """Write bytes to a device. ``wait=False`` sends fire-and-forget —
+        no ACK round-trip, errors are not reported; pair a burst of unwaited
+        writes with a final waited one to sync (the firmware executes
+        requests in arrival order)."""
+        if len(data) > self.max_write:
+            raise ValueError(f"max {self.max_write} bytes per I2C write "
+                             "(update the firmware for 2046)")
+        payload = bytes([bus, addr]) + bytes(data)
+        if wait:
+            self._b.request(C.I2C_WRITE, payload)
+        else:
+            self._b.send(C.I2C_WRITE, payload)
+
+    def read(self, addr: int, n: int, bus: int = 0) -> bytes:
+        if not 1 <= n <= 255:
+            raise ValueError("read length must be 1..255")
+        return self._b.request(C.I2C_READ, bytes([bus, addr, n]))
+
+    def write_read(self, addr: int, wdata: bytes, rlen: int, bus: int = 0) -> bytes:
+        """Write then read with a repeated start (typical register read)."""
+        if len(wdata) > 255 or not 1 <= rlen <= 255:
+            raise ValueError("wdata max 255 bytes, rlen 1..255")
+        payload = bytes([bus, addr, len(wdata)]) + bytes(wdata) + bytes([rlen])
+        return self._b.request(C.I2C_WRITE_READ, payload)
+
+    def read_reg(self, addr: int, reg: int, n: int = 1, bus: int = 0) -> bytes:
+        return self.write_read(addr, bytes([reg]), n, bus)
+
+    def write_reg(self, addr: int, reg: int, data: bytes | int, bus: int = 0) -> None:
+        data = bytes([data]) if isinstance(data, int) else bytes(data)
+        self.write(addr, bytes([reg]) + data, bus)
+
+    def deinit(self, bus: int = 0) -> None:
+        self._b.request(C.I2C_DEINIT, bytes([bus]))