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

espbridge/compat/blinka.py

@@ -0,0 +1,209 @@
+"""CircuitPython / Adafruit-Blinka compatible I2C, SPI and DigitalInOut.
+
+Implements the same duck-typed protocols as ``busio.I2C``, ``busio.SPI`` and
+``digitalio.DigitalInOut``, so the hundreds of ``adafruit-circuitpython-*``
+driver libraries run unchanged through the bridge:
+
+    pip install adafruit-circuitpython-bme280
+
+    from espbridge import Bridge
+    from espbridge.compat.blinka import I2C
+    from adafruit_bme280.basic import Adafruit_BME280_I2C
+
+    with Bridge() as esp:
+        bme = Adafruit_BME280_I2C(I2C(esp))
+        print(bme.temperature, bme.relative_humidity)
+
+SPI devices work the same way, with CS handled by ``DigitalInOut`` exactly as
+``adafruit_bus_device.spi_device.SPIDevice`` expects.
+No Adafruit package is imported here — only their wire protocols are spoken.
+"""
+from __future__ import annotations
+
+import threading
+
+
+class I2C:
+    """busio.I2C-compatible bus on the ESP32's I2C."""
+
+    def __init__(self, esp, *, sda: int = 21, scl: int = 22,
+                 frequency: int = 400_000, bus: int = 0, init: bool = True):
+        self._i2c = esp.i2c
+        self._bus = bus
+        self._lock = threading.Lock()
+        if init:
+            self._i2c.init(sda=sda, scl=scl, freq=frequency, bus=bus)
+
+    # -- locking protocol (drivers call these around every transaction) ------
+    def try_lock(self) -> bool:
+        return self._lock.acquire(blocking=False)
+
+    def unlock(self) -> None:
+        self._lock.release()
+
+    # -- transfers -------------------------------------------------------------
+    def scan(self) -> list[int]:
+        return self._i2c.scan(self._bus)
+
+    def writeto(self, address: int, buffer, *, start: int = 0, end=None) -> None:
+        end = len(buffer) if end is None else end
+        self._i2c.write(address, bytes(buffer[start:end]), self._bus)
+
+    def readfrom_into(self, address: int, buffer, *, start: int = 0, end=None) -> None:
+        end = len(buffer) if end is None else end
+        data = self._i2c.read(address, end - start, self._bus)
+        buffer[start:end] = data
+
+    def writeto_then_readfrom(self, address: int, out_buffer, in_buffer, *,
+                              out_start: int = 0, out_end=None,
+                              in_start: int = 0, in_end=None) -> None:
+        out_end = len(out_buffer) if out_end is None else out_end
+        in_end = len(in_buffer) if in_end is None else in_end
+        data = self._i2c.write_read(address, bytes(out_buffer[out_start:out_end]),
+                                    in_end - in_start, self._bus)
+        in_buffer[in_start:in_end] = data
+
+    def deinit(self) -> None:
+        self._i2c.deinit(self._bus)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.deinit()
+
+
+class SPI:
+    """busio.SPI-compatible bus on the ESP32's SPI.
+
+    Chip select is *not* handled here — pass a ``DigitalInOut`` to
+    ``adafruit_bus_device.spi_device.SPIDevice``, exactly like on a Pi.
+    """
+
+    def __init__(self, esp, *, sck: int = 18, mosi: int = 23, miso: int = 19,
+                 host: int = 0):
+        self._spi = esp.spi
+        self._host = host
+        self._pins = (sck, miso, mosi)
+        self._lock = threading.Lock()
+        self._frequency = 100_000
+        self.configure()  # CircuitPython default: 100 kHz, mode 0
+
+    def try_lock(self) -> bool:
+        return self._lock.acquire(blocking=False)
+
+    def unlock(self) -> None:
+        self._lock.release()
+
+    def configure(self, *, baudrate: int = 100_000, polarity: int = 0,
+                  phase: int = 0, bits: int = 8) -> None:
+        if bits != 8:
+            raise ValueError("only 8-bit SPI transfers are supported")
+        sck, miso, mosi = self._pins
+        self._frequency = baudrate
+        self._spi.init(sck=sck, miso=miso, mosi=mosi, freq=baudrate,
+                       mode=(polarity << 1) | phase, host=self._host)
+
+    @property
+    def frequency(self) -> int:
+        return self._frequency
+
+    def write(self, buffer, *, start: int = 0, end=None) -> None:
+        end = len(buffer) if end is None else end
+        self._spi.transfer(bytes(buffer[start:end]), host=self._host)
+
+    def readinto(self, buffer, *, start: int = 0, end=None, write_value: int = 0) -> None:
+        end = len(buffer) if end is None else end
+        rx = self._spi.transfer(bytes([write_value]) * (end - start), host=self._host)
+        buffer[start:end] = rx
+
+    def write_readinto(self, out_buffer, in_buffer, *,
+                       out_start: int = 0, out_end=None,
+                       in_start: int = 0, in_end=None) -> None:
+        out_end = len(out_buffer) if out_end is None else out_end
+        in_end = len(in_buffer) if in_end is None else in_end
+        if (out_end - out_start) != (in_end - in_start):
+            raise ValueError("buffer slices must be of equal length")
+        rx = self._spi.transfer(bytes(out_buffer[out_start:out_end]), host=self._host)
+        in_buffer[in_start:in_end] = rx
+
+    def deinit(self) -> None:
+        self._spi.deinit(self._host)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.deinit()
+
+
+class Direction:
+    INPUT = "input"
+    OUTPUT = "output"
+
+
+class Pull:
+    UP = "up"
+    DOWN = "down"
+
+
+class DigitalInOut:
+    """digitalio.DigitalInOut-compatible pin (used for CS lines and plain GPIO)."""
+
+    def __init__(self, esp, pin: int):
+        self._gpio = esp.gpio
+        self.pin = pin
+        self._direction = Direction.INPUT
+        self._pull = None
+        self._value = False
+        self._gpio.mode(pin, "input")
+
+    def switch_to_output(self, value: bool = False, drive_mode=None) -> None:
+        self._direction = Direction.OUTPUT
+        self._gpio.mode(self.pin, "output")
+        self.value = value
+
+    def switch_to_input(self, pull=None) -> None:
+        self._direction = Direction.INPUT
+        self._pull = pull
+        self._gpio.mode(self.pin, {Pull.UP: "input_pullup",
+                                   Pull.DOWN: "input_pulldown"}.get(pull, "input"))
+
+    @property
+    def direction(self):
+        return self._direction
+
+    @direction.setter
+    def direction(self, value) -> None:
+        if value == Direction.OUTPUT:
+            self.switch_to_output()
+        else:
+            self.switch_to_input()
+
+    @property
+    def value(self) -> bool:
+        if self._direction == Direction.OUTPUT:
+            return self._value
+        return bool(self._gpio.read(self.pin))
+
+    @value.setter
+    def value(self, val: bool) -> None:
+        self._value = bool(val)
+        self._gpio.write(self.pin, self._value)
+
+    @property
+    def pull(self):
+        return self._pull
+
+    @pull.setter
+    def pull(self, value) -> None:
+        self.switch_to_input(value)
+
+    def deinit(self) -> None:
+        self._gpio.mode(self.pin, "input")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.deinit()

espbridge/compat/gpiozero.py

@@ -0,0 +1,233 @@
+"""gpiozero pin factory — LED, Button, PWMLED & friends on ESP32 pins.
+
+    pip install gpiozero
+
+    from gpiozero import LED, Button
+    from espbridge import Bridge
+    from espbridge.compat.gpiozero import EspBridgeFactory
+
+    esp = Bridge()
+    factory = EspBridgeFactory(esp)
+
+    led = LED(2, pin_factory=factory)          # ESP32 GPIO numbers
+    btn = Button(4, pin_factory=factory)
+    btn.when_pressed = led.toggle
+
+    # or make it the default for every gpiozero device:
+    from gpiozero import Device
+    Device.pin_factory = factory
+
+Supported: input/output, pull-up/down, edge detection with debounce
+(``when_pressed``/``when_changed``), and PWM (``PWMLED``, ``value=0.5``).
+"""
+from __future__ import annotations
+
+import time
+
+from gpiozero.exc import PinInvalidFunction, PinInvalidPin, PinInvalidPull, PinSetInput
+from gpiozero.pins import BoardInfo, Factory, HeaderInfo, Pin, PinInfo
+
+_PWM_RES_BITS = 12
+_PWM_MAX = (1 << _PWM_RES_BITS) - 1
+_EDGE_MAP = {"both": "change", "rising": "rising", "falling": "falling"}
+_PULL_MODES = {"floating": "input", "up": "input_pullup", "down": "input_pulldown"}
+
+
+def _board_info(gpio_count: int, chip: str) -> BoardInfo:
+    pins = {
+        n: PinInfo(number=n, name=f"GPIO{n}",
+                   names=frozenset({n, str(n), f"GPIO{n}"}),
+                   pull="", row=n + 1, col=1, interfaces=frozenset({"gpio"}))
+        for n in range(gpio_count)
+    }
+    header = HeaderInfo(name="GPIO", rows=gpio_count, columns=1, pins=pins)
+    return BoardInfo(
+        revision="espbridge", model=chip, pcb_revision="1.0", released="2026",
+        soc=chip, manufacturer="Espressif", memory=0, storage="flash",
+        usb=1, usb3=0, ethernet=0, eth_speed=0, wifi=True, bluetooth=True,
+        csi=0, dsi=0, headers={"GPIO": header}, board="",
+    )
+
+
+class EspBridgePin(Pin):
+    def __init__(self, factory: "EspBridgeFactory", info: PinInfo):
+        super().__init__()
+        self._factory = factory
+        self._info = info
+        self._gpio = factory._esp.gpio
+        self._pwm = factory._esp.pwm
+        self._n = info.number
+
+        self._function = "input"
+        self._pull = "floating"
+        self._frequency: float | None = None
+        self._duty = 0.0
+        self._bounce: float | None = None
+        self._edges = "both"
+        self._when_changed = None
+        self._watching = False
+        self._gpio.mode(self._n, "input")
+
+    def __repr__(self):
+        return f"<EspBridgePin GPIO{self._n}>"
+
+    # ---- identity -------------------------------------------------------------
+    def _get_info(self):
+        return self._info
+
+    # ---- function -------------------------------------------------------------
+    def _get_function(self):
+        return self._function
+
+    def _set_function(self, value):
+        if value not in ("input", "output"):
+            raise PinInvalidFunction(f"invalid function {value!r} for {self!r}")
+        self._function = value
+        if value == "input":
+            self._gpio.mode(self._n, _PULL_MODES[self._pull])
+        else:
+            self._gpio.mode(self._n, "output")
+
+    def output_with_state(self, state):
+        self._function = "output"
+        self._gpio.mode(self._n, "output")
+        self._set_state(state)
+
+    def input_with_pull(self, pull):
+        self._pull = pull
+        self._set_function("input")
+
+    # ---- state ------------------------------------------------------------------
+    def _get_state(self):
+        if self._frequency is not None:
+            return self._duty
+        return self._gpio.read(self._n)
+
+    def _set_state(self, value):
+        if self._frequency is not None:
+            self._duty = max(0.0, min(1.0, float(value)))
+            self._pwm.write(self._n, round(self._duty * _PWM_MAX))
+        elif self._function == "input":
+            raise PinSetInput(f"cannot set state of input {self!r}")
+        else:
+            self._gpio.write(self._n, bool(value))
+
+    # ---- pull ---------------------------------------------------------------------
+    def _get_pull(self):
+        return self._pull
+
+    def _set_pull(self, value):
+        if value not in _PULL_MODES:
+            raise PinInvalidPull(f"invalid pull {value!r} for {self!r}")
+        self._pull = value
+        if self._function == "input":
+            self._gpio.mode(self._n, _PULL_MODES[value])
+
+    # ---- PWM -----------------------------------------------------------------------
+    def _get_frequency(self):
+        return self._frequency
+
+    def _set_frequency(self, value):
+        if value is None:
+            if self._frequency is not None:
+                self._pwm.detach(self._n)
+                self._frequency = None
+                if self._function == "output":
+                    self._gpio.mode(self._n, "output")
+                    self._gpio.write(self._n, False)
+        else:
+            self._pwm.attach(self._n, int(value), _PWM_RES_BITS)
+            self._frequency = float(value)
+            self._pwm.write(self._n, round(self._duty * _PWM_MAX))
+
+    # ---- edge detection ----------------------------------------------------------------
+    def _get_bounce(self):
+        return self._bounce
+
+    def _set_bounce(self, value):
+        self._bounce = value
+        self._rearm()
+
+    def _get_edges(self):
+        return self._edges
+
+    def _set_edges(self, value):
+        if value not in ("both", "rising", "falling", "none"):
+            raise PinInvalidFunction(f"invalid edges {value!r}")
+        self._edges = value
+        self._rearm()
+
+    def _get_when_changed(self):
+        return self._when_changed
+
+    def _set_when_changed(self, value):
+        self._when_changed = value
+        self._rearm()
+
+    def _rearm(self):
+        if self._watching:
+            self._gpio.unwatch(self._n)
+            self._watching = False
+        if self._when_changed is not None and self._edges != "none":
+            debounce_ms = int((self._bounce or 0) * 1000)
+            self._gpio.watch(self._n, _EDGE_MAP[self._edges],
+                             debounce_ms=debounce_ms, callback=self._on_edge)
+            self._watching = True
+
+    def _on_edge(self, event):
+        cb = self._when_changed
+        if cb is not None:
+            cb(self._factory.ticks(), event.level)
+
+    def close(self):
+        try:
+            if self._watching:
+                self._gpio.unwatch(self._n)
+                self._watching = False
+            if self._frequency is not None:
+                self._pwm.detach(self._n)
+                self._frequency = None
+            self._gpio.mode(self._n, "input")
+        except Exception:
+            pass  # bridge may already be closed (e.g. at interpreter exit)
+        self._function = "input"
+
+
+class EspBridgeFactory(Factory):
+    """gpiozero pin factory backed by an espbridge Bridge."""
+
+    def __init__(self, esp):
+        super().__init__()
+        self._esp = esp
+        self.pins: dict = {}
+        gpio_count = esp.info.gpio_count if esp.info is not None else 40
+        chip = esp.info.chip.name if esp.info is not None else "ESP32"
+        self._board_info = _board_info(gpio_count, chip)
+
+    def _get_board_info(self):
+        return self._board_info
+
+    @property
+    def board_info(self):
+        return self._board_info
+
+    def pin(self, name):
+        for _header, info in self.board_info.find_pin(name):
+            pin = self.pins.get(info)
+            if pin is None:
+                pin = EspBridgePin(self, info)
+                self.pins[info] = pin
+            return pin
+        raise PinInvalidPin(f"{name} is not a valid pin name")
+
+    def ticks(self):
+        return time.monotonic()
+
+    @staticmethod
+    def ticks_diff(later, earlier):
+        return later - earlier
+
+    def close(self):
+        for pin in list(self.pins.values()):
+            pin.close()
+        self.pins.clear()

espbridge/compat/luma.py

@@ -0,0 +1,90 @@
+"""Adapter that lets the luma.oled / luma.lcd display libraries drive their
+displays through the bridge's I2C — so you get the battle-tested drivers
+(SSD1306, SH1106, SSD1309, ...) and PIL drawing, while the ESP32 just relays
+I2C traffic.
+
+    pip install luma.oled
+
+    from luma.oled.device import ssd1306        # or sh1106, ...
+    from espbridge.compat.luma import LumaI2C
+
+    esp.i2c.init(sda=21, scl=22, freq=400_000)
+    device = ssd1306(LumaI2C(esp.i2c, addr=0x3C))
+
+This module deliberately does not import luma — it only implements the
+``command``/``data``/``cleanup`` serial-interface protocol luma expects.
+"""
+from __future__ import annotations
+
+_CMD_MODE = 0x00   # control byte: command stream follows
+_DATA_MODE = 0x40  # control byte: display data follows
+
+
+class LumaI2C:
+    """luma serial interface backed by an espbridge I2c bus."""
+
+    def __init__(self, i2c, addr: int = 0x3C, bus: int = 0):
+        self._i2c = i2c
+        self._addr = addr
+        self._bus = bus
+        # largest data write minus the control byte (128 on old firmware,
+        # whose Wire TX buffer silently truncates longer transmissions)
+        self._chunk = getattr(i2c, "max_write", 2046) - 1
+
+    def command(self, *cmd: int) -> None:
+        self._i2c.write(self._addr, bytes([_CMD_MODE, *cmd]), self._bus)
+
+    def data(self, data) -> None:
+        data = bytes(bytearray(data))  # luma may pass a list of ints
+        for off in range(0, len(data), self._chunk):
+            self._i2c.write(self._addr,
+                            bytes([_DATA_MODE]) + data[off : off + self._chunk],
+                            self._bus)
+
+    def cleanup(self) -> None:
+        pass  # nothing to release; the Bridge owns the link
+
+
+class LumaSPI:
+    """luma serial interface for SPI displays (SSD1306-SPI, ST77xx, ILI9341, ...).
+
+        from luma.lcd.device import st7735
+        device = st7735(LumaSPI(esp, dc=4, rst=16, cs=5), width=160, height=128)
+    """
+
+    def __init__(self, esp, *, dc: int, rst: int | None = None, cs: int | None = None,
+                 sck: int = 18, mosi: int = 23, miso: int = 19,
+                 freq: int = 8_000_000, host: int = 0, init_bus: bool = True):
+        self._spi = esp.spi
+        self._gpio = esp.gpio
+        self._dc = dc
+        self._cs = cs
+        self._host = host
+        if init_bus:
+            self._spi.init(sck=sck, miso=miso, mosi=mosi, freq=freq, host=host)
+        self._gpio.mode(dc, "output")
+        if rst is not None:  # power-on reset pulse, as luma's own spi interface does
+            import time
+            self._gpio.mode(rst, "output")
+            self._gpio.write(rst, 0)
+            time.sleep(0.01)
+            self._gpio.write(rst, 1)
+            time.sleep(0.01)
+
+    def _send(self, data: bytes) -> None:
+        # CS is asserted per chunk; display controllers latch per byte, so
+        # chunk boundaries are harmless.
+        max_chunk = 2046  # MAX_PAYLOAD minus the transfer header
+        for off in range(0, len(data), max_chunk):
+            self._spi.transfer(data[off : off + max_chunk], cs=self._cs, host=self._host)
+
+    def command(self, *cmd: int) -> None:
+        self._gpio.write(self._dc, 0)
+        self._send(bytes(cmd))
+
+    def data(self, data) -> None:
+        self._gpio.write(self._dc, 1)
+        self._send(bytes(bytearray(data)))
+
+    def cleanup(self) -> None:
+        pass

espbridge/compat/rpi_gpio.py

@@ -0,0 +1,121 @@
+"""Drop-in-ish RPi.GPIO shim backed by the ESP32 bridge.
+
+    from espbridge.compat import rpi_gpio as GPIO
+
+    GPIO.setmode(GPIO.BCM)        # pin numbers are ESP32 GPIO numbers
+    GPIO.setup(2, GPIO.OUT)
+    GPIO.output(2, GPIO.HIGH)
+    GPIO.add_event_detect(4, GPIO.FALLING, callback=lambda ch: print(ch))
+
+Uses a process-wide Bridge (auto-detected port) unless you call attach(bridge).
+"""
+from __future__ import annotations
+
+from ..bridge import Bridge
+
+BCM = "BCM"
+BOARD = "BOARD"  # accepted but identical: numbering is always ESP32 GPIO
+OUT = "out"
+IN = "in"
+HIGH = 1
+LOW = 0
+PUD_UP = "up"
+PUD_DOWN = "down"
+PUD_OFF = "off"
+RISING = "rising"
+FALLING = "falling"
+BOTH = "change"
+
+_bridge: Bridge | None = None
+_owned = False
+
+
+def attach(bridge: Bridge) -> None:
+    """Use an existing Bridge instead of auto-connecting."""
+    global _bridge, _owned
+    _bridge = bridge
+    _owned = False
+
+
+def _b() -> Bridge:
+    global _bridge, _owned
+    if _bridge is None:
+        _bridge = Bridge()
+        _owned = True
+    return _bridge
+
+
+def setmode(mode) -> None:  # numbering is always ESP32 GPIO numbers
+    pass
+
+
+def setwarnings(flag: bool) -> None:
+    pass
+
+
+def setup(channel, direction, pull_up_down=PUD_OFF, initial=None) -> None:
+    channels = channel if isinstance(channel, (list, tuple)) else [channel]
+    for ch in channels:
+        if direction == OUT:
+            _b().gpio.mode(ch, "output")
+            if initial is not None:
+                _b().gpio.write(ch, initial)
+        else:
+            mode = {PUD_UP: "input_pullup", PUD_DOWN: "input_pulldown"}.get(
+                pull_up_down, "input")
+            _b().gpio.mode(ch, mode)
+
+
+def output(channel, value) -> None:
+    channels = channel if isinstance(channel, (list, tuple)) else [channel]
+    values = value if isinstance(value, (list, tuple)) else [value] * len(channels)
+    if len(channels) > 1:
+        _b().gpio.write_many(dict(zip(channels, values)))
+    else:
+        _b().gpio.write(channels[0], values[0])
+
+
+def input(channel) -> int:  # noqa: A001 — mirrors RPi.GPIO's name
+    return _b().gpio.read(channel)
+
+
+def add_event_detect(channel, edge, callback=None, bouncetime=0) -> None:
+    cb = (lambda ev, _cb=callback: _cb(ev.pin)) if callback else None
+    _b().gpio.watch(channel, edge, debounce_ms=bouncetime, callback=cb)
+
+
+def remove_event_detect(channel) -> None:
+    _b().gpio.unwatch(channel)
+
+
+class PWM:
+    """RPi.GPIO-style PWM object."""
+
+    def __init__(self, channel: int, frequency: float):
+        self.channel = channel
+        self.frequency = int(frequency)
+        self._duty = 0.0
+
+    def start(self, duty_cycle: float) -> None:
+        _b().pwm.attach(self.channel, self.frequency, 12)
+        self.ChangeDutyCycle(duty_cycle)
+
+    def ChangeDutyCycle(self, duty_cycle: float) -> None:
+        self._duty = duty_cycle
+        _b().pwm.duty_pct(self.channel, duty_cycle)
+
+    def ChangeFrequency(self, frequency: float) -> None:
+        self.frequency = int(frequency)
+        _b().pwm.attach(self.channel, self.frequency, 12)
+        _b().pwm.duty_pct(self.channel, self._duty)
+
+    def stop(self) -> None:
+        _b().pwm.detach(self.channel)
+
+
+def cleanup(channel=None) -> None:
+    global _bridge, _owned
+    if _bridge is not None and _owned:
+        _bridge.close()
+        _bridge = None
+        _owned = False