esplink 1.0.2__py3-none-any.whl

esplink/__init__.py

@@ -0,0 +1,88 @@
+"""esplink — control every ESP32 peripheral from Python over USB or Bluetooth.
+
+Flash the firmware once (Arduino library "esplink"), then:
+
+    from esplink import Bridge
+
+    with Bridge() as esp:                # USB first, then Bluetooth, then Wi-Fi
+        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
+
+        esp.nvs.set("runs", 1)           # on-board key/value storage
+        esp.fs.mount("littlefs")         # on-board files
+        esp.can.begin(tx=21, rx=22)      # CAN bus
+        esp.ota.flash("new.bin")         # update the firmware over the link
+
+    # device drivers in pure Python (RMT / 1-Wire / I2C primitives), all under
+    # esplink.drivers: dht, oled, neopixel, ds18b20, hcsr04, ir, stepper, ...
+    # ...or write/register your own — esp.<name>(...) — see esplink.drivers
+    #    and docs/DRIVERS.md ("bring your own driver").
+"""
+from .bridge import Bridge, BridgeSet, Info
+from .constants import Cap, ChipModel, Status
+from .drivers import driver_names, register_driver
+from .manager import BridgeManager, connect, disconnect_all
+from .errors import (
+    AuthError,
+    BridgeError,
+    BridgeTimeoutError,
+    NoDeviceError,
+    ProtocolError,
+    RemoteError,
+    UnsupportedError,
+)
+from .transports import find_ports, find_wifi_devices
+from .gpio import EdgeEvent
+from .watch import WatchEvent
+
+
+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)
+
+
+def __getattr__(name):
+    # Lazy: importing AsyncBridge pulls in asyncio, so defer it until first use
+    # rather than charging every sync/USB-only script for the import.
+    if name == "AsyncBridge":
+        from .aio import AsyncBridge
+
+        return AsyncBridge
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__version__ = "1.0.1"
+
+# Grouped by role, not alphabetised: this list is the shape of the public API.
+__all__ = [
+    "Bridge",
+    "AsyncBridge",
+    "BridgeSet",
+    "BridgeManager",
+    "connect",
+    "disconnect_all",
+    "register_driver",
+    "driver_names",
+    "find_ble_devices",
+    "find_wifi_devices",
+    "Info",
+    "Cap",
+    "ChipModel",
+    "Status",
+    "AuthError",
+    "BridgeError",
+    "BridgeTimeoutError",
+    "NoDeviceError",
+    "ProtocolError",
+    "RemoteError",
+    "UnsupportedError",
+    "find_ports",
+    "EdgeEvent",
+    "WatchEvent",
+    "__version__",
+]

esplink/_log.py

@@ -0,0 +1,73 @@
+"""Library logger: "[esplink]" prefix + uvicorn-style colored level prefix.
+
+Mirrors uvicorn.logging.DefaultFormatter (same colors, same ``LEVEL:``
+padding) without depending on uvicorn: colors auto-enable only when stderr
+is a terminal that supports ANSI, and NO_COLOR is honored.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+# uvicorn's palette: DEBUG cyan, INFO green, WARNING yellow, ERROR red,
+# CRITICAL bright red.
+_LEVEL_COLORS = {
+    logging.DEBUG: 36,
+    logging.INFO: 32,
+    logging.WARNING: 33,
+    logging.ERROR: 31,
+    logging.CRITICAL: 91,
+}
+
+
+def _supports_color(stream) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if not getattr(stream, "isatty", lambda: False)():
+        return False
+    if sys.platform == "win32":
+        # Windows Terminal and VS Code already have VT processing enabled.
+        # For the classic Windows console, try to enable it here.
+        # If the call fails, ANSI escape sequences are not supported.
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(-12)  # STD_ERROR_HANDLE
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+        return bool(kernel32.SetConsoleMode(
+            handle, mode.value | ENABLE_VIRTUAL_TERMINAL_PROCESSING))
+    return True
+
+
+class _Formatter(logging.Formatter):
+    def __init__(self, use_colors: bool):
+        super().__init__("[esplink] %(levelprefix)s %(message)s")
+        self.use_colors = use_colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        pad = " " * max(0, 8 - len(record.levelname))  # right-pad level name to 8 chars, matching uvicorn's alignment
+        if self.use_colors:
+            color = _LEVEL_COLORS.get(record.levelno, 0)
+            record.levelprefix = (
+                f"\x1b[{color}m{record.levelname}\x1b[0m:{pad}")
+        else:
+            record.levelprefix = f"{record.levelname}:{pad}"
+        return super().format(record)
+
+
+log = logging.getLogger("esplink")
+if not log.handlers:
+    if os.environ.get("ESPLINK_DEBUG"):
+        # Enable frame-level tracing (every request and response with command
+        # names) without modifying the script: ESPLINK_DEBUG=1 python app.py
+        log.setLevel(logging.DEBUG)
+    elif log.level == logging.NOTSET:  # respect a level the app set first
+        log.setLevel(logging.INFO)
+    _handler = logging.StreamHandler(sys.stderr)
+    _handler.setFormatter(_Formatter(_supports_color(sys.stderr)))
+    log.addHandler(_handler)
+    log.propagate = False

esplink/aio.py

@@ -0,0 +1,225 @@
+"""asyncio facade: ``await`` every bridge call and fan out concurrent I/O.
+
+The ESP32 firmware is *already* concurrent — requests carry a sequence number,
+many can be in flight at once, and a slow call on one task never stalls the
+fast lane (see ``examples/basics/rtos_concurrency.py``). ``AsyncBridge`` simply
+exposes that concurrency to ``asyncio`` so you can ``await`` bridge calls and
+run them together with ``asyncio.gather``, instead of juggling threads yourself:
+
+    import asyncio
+    from esplink import AsyncBridge
+
+    async def main():
+        async with AsyncBridge(ble=False) as esp:
+            await esp.gpio.mode(2, "output")
+            await esp.gpio.write(2, 1)
+            # both reads are issued together and overlap on the wire:
+            t, h = await asyncio.gather(esp.adc.read(34), esp.adc.read(35))
+            print(t, h)
+
+    asyncio.run(main())
+
+Edge interrupts (``gpio.watch``) become an async stream — no callback thread:
+
+    async with AsyncBridge() as esp:
+        await esp.gpio.mode(4, "input_pullup")
+        await esp.gpio.watch(4, edge="falling", debounce_ms=30)
+        async for ev in esp.gpio_events():
+            print("pressed", ev.pin, ev.millis)
+
+How it works (and what to expect): the firmware speaks a synchronous
+request/response protocol and the underlying ``Bridge`` is fully thread-safe,
+so each awaited call runs the matching ``Bridge`` method in a worker thread
+(``asyncio.to_thread``). Calls awaited together genuinely overlap on the link
+because ``Bridge`` pipelines concurrent requests and correlates replies by
+sequence number — ``await`` here is about *the host not blocking*, not about
+moving work onto the ESP32 (the firmware's task split already does that).
+
+For tight inner loops or fire-and-forget streaming (e.g. pushing OLED frames),
+the plain synchronous ``Bridge`` is still the right tool — there is nothing to
+gain from awaiting each byte, and a thread per call would only add overhead.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+
+from . import constants as C
+from .bridge import Bridge
+from .gpio import EdgeEvent
+from .watch import WatchEvent
+
+
+def _to_coro(fn):
+    """Wrap a blocking bridge callable so it runs in a thread and can be awaited."""
+    @functools.wraps(fn)
+    async def _call(*args, **kwargs):
+        return await asyncio.to_thread(fn, *args, **kwargs)
+    return _call
+
+
+def _async_attr(attr):
+    """Adapt a bound bridge attribute for async use: callables become coroutines
+    that run in a worker thread; plain values (info, caps, max_write, ...) pass
+    through. One uniform rule — nothing has to enumerate which calls touch the
+    wire, so a new Bridge method is awaitable automatically."""
+    return _to_coro(attr) if callable(attr) else attr
+
+
+class _AsyncSubApi:
+    """Proxies a sync sub-API (``esp.gpio``, ``esp.adc``, ...): every method
+    becomes awaitable; plain attributes (e.g. ``i2c.max_write``) pass through."""
+
+    def __init__(self, target):
+        self._target = target
+
+    def __getattr__(self, name):
+        if name.startswith("_"):  # don't expose the sub-API's internals
+            raise AttributeError(name)
+        return _async_attr(getattr(self._target, name))
+
+    def __dir__(self):
+        return dir(self._target)
+
+
+class _EventStream:
+    """Async iterator over a firmware event, fed from the reader thread.
+
+    Registered with ``Bridge.on_event``; each event payload is handed to the
+    asyncio loop via ``call_soon_threadsafe`` and surfaces through ``async for``.
+    """
+
+    def __init__(self, bridge: Bridge, cmd: int, loop, parse=None, maxsize: int = 0):
+        self._bridge = bridge
+        self._cmd = cmd
+        self._loop = loop
+        self._parse = parse
+        self._queue: asyncio.Queue = asyncio.Queue(maxsize)
+        bridge.on_event(cmd, self._on_event)
+
+    def _on_event(self, payload: bytes) -> None:
+        item = self._parse(payload) if self._parse else payload
+        if item is None:  # parser rejected a malformed/short payload
+            return
+        # Hop from the reader thread onto the asyncio loop; drop if the queue is
+        # full (a bounded maxsize gives back-pressure without blocking the reader).
+        self._loop.call_soon_threadsafe(self._offer, item)
+
+    def _offer(self, item) -> None:
+        try:
+            self._queue.put_nowait(item)
+        except asyncio.QueueFull:
+            pass
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        return await self._queue.get()
+
+    async def aclose(self) -> None:
+        """Stop the stream and unregister it from the bridge (call when done, or
+        just break out of the ``async for`` and let it be garbage-collected)."""
+        self._bridge.off_event(self._cmd, self._on_event)
+
+
+class AsyncBridge:
+    """``asyncio`` wrapper around :class:`Bridge`.
+
+    Accepts the same arguments as ``Bridge``. Connection happens off the event
+    loop, so use it as an async context manager (or ``await .connect()``):
+
+    >>> async with AsyncBridge(ble=False) as esp:
+    ...     await esp.gpio.write(2, 1)
+
+    The wrapped synchronous bridge is available as ``.bridge`` for anything not
+    surfaced here (events, ``on_event``, device drivers).
+    """
+
+    def __init__(self, *args, **kwargs):
+        # Bridge() connects (and blocks) in its constructor, so defer it. Args
+        # are passed straight through, so AsyncBridge("relays") selects a board
+        # exactly the way Bridge("relays") does.
+        self._args, self._kwargs = args, kwargs
+        self._bridge = None
+        self._owned = True  # we opened it, so we close it
+
+    @classmethod
+    def wrap(cls, bridge: Bridge) -> AsyncBridge:
+        """Wrap an already-connected Bridge for ``await`` use, sharing its link.
+
+        Lets an async app reuse the one shared connection instead of opening a
+        second:  ``esp = AsyncBridge.wrap(esplink.connect(ble=False))``.
+        ``close()`` is then a no-op for the wrapper — whoever owns the Bridge
+        (e.g. the BridgeManager behind connect()) closes it.
+        """
+        self = cls.__new__(cls)
+        self._args, self._kwargs = (), {}
+        self._bridge = bridge
+        self._owned = False
+        return self
+
+    @property
+    def bridge(self) -> Bridge:
+        """The underlying synchronous :class:`Bridge` (for events, ``on_event``,
+        device drivers, or any method not surfaced here). Raises if not yet
+        connected."""
+        if self._bridge is None:
+            raise RuntimeError(
+                "AsyncBridge is not connected — use `async with AsyncBridge(...)` "
+                "or `await bridge.connect()`"
+            )
+        return self._bridge
+
+    async def connect(self) -> AsyncBridge:
+        """Open the link off the event loop (Bridge() blocks while connecting).
+        Usually you don't call this directly — use ``async with AsyncBridge():``."""
+        if self._bridge is None:
+            self._bridge = await asyncio.to_thread(Bridge, *self._args,
+                                                   **self._kwargs)
+        return self
+
+    async def close(self) -> None:
+        """Close the link off the event loop. No-op for a wrapper created with
+        :meth:`wrap` (whoever owns the underlying Bridge closes it)."""
+        if self._bridge is not None and self._owned:
+            await asyncio.to_thread(self._bridge.close)
+        self._bridge = None
+
+    async def __aenter__(self) -> AsyncBridge:
+        return await self.connect()
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    def events(self, cmd: int, *, parse=None, maxsize: int = 0) -> _EventStream:
+        """``async for`` over a raw firmware event ``cmd`` (payloads are bytes
+        unless ``parse`` is given). See ``gpio_events()`` for the GPIO edge case."""
+        return _EventStream(self.bridge, cmd, asyncio.get_running_loop(),
+                            parse=parse, maxsize=maxsize)
+
+    def gpio_events(self, *, maxsize: int = 0) -> _EventStream:
+        """``async for ev in esp.gpio_events()`` yields :class:`EdgeEvent`s from
+        every pin armed with ``await esp.gpio.watch(pin, ...)``."""
+        return self.events(C.GPIO_EDGE_EVT, parse=EdgeEvent.parse, maxsize=maxsize)
+
+    def watch_events(self, *, maxsize: int = 0) -> _EventStream:
+        """``async for ev in esp.watch_events()`` yields :class:`WatchEvent`s
+        from every rule defined with ``await esp.watch.add(...)`` — the polled,
+        non-interrupt, threshold-based events."""
+        return self.events(C.WATCH_EVT, parse=WatchEvent.parse, maxsize=maxsize)
+
+    def __getattr__(self, name):
+        if name.startswith("_"):  # never proxy private/dunder lookups
+            raise AttributeError(name)
+        attr = getattr(self.bridge, name)
+        if name in Bridge._SUBAPIS:
+            proxy = _AsyncSubApi(attr)
+            setattr(self, name, proxy)  # cache: this name skips __getattr__ next time
+            return proxy
+        return _async_attr(attr)
+
+    def __dir__(self):
+        extra = (*Bridge._SUBAPIS, "bridge", "connect", "close",
+                 "events", "gpio_events", "watch_events")
+        return [*super().__dir__(), *extra]

esplink/analog.py

@@ -0,0 +1,82 @@
+"""ADC (oneshot reads), DAC (write + cosine generator), capacitive touch."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+# Attenuation level -> approximate full-scale input range 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:
+    """Oneshot ADC reads.
+
+        esp.adc.config(34, atten=11)   # full ~3.3 V range
+        raw = esp.adc.read(34)         # 0..4095
+        mv = esp.adc.read_mv(34)       # calibrated millivolts
+    """
+
+    def __init__(self, bridge):
+        self._b = bridge
+
+    def config(self, pin: int, atten: float = 11) -> None:
+        """Set the input attenuation for a pin (0/2.5/6/11 dB; default 11 ≈ 3.3 V)."""
+        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.
+
+        esp.dac.write(25, 128)            # ~1.65 V
+        esp.dac.cosine(25, 1000)          # 1 kHz cosine wave
+        esp.dac.disable(25)               # stops the wave and releases the pin
+    """
+
+    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 = full amplitude, 1 = half, 2 = quarter, 3 = eighth.
+        """
+        self._b.request(C.DAC_COSINE, struct.pack(">BIBbB", pin, freq_hz, scale & 3,
+                                                  offset, 1 if phase_180 else 0))
+
+    def disable(self, pin: int) -> None:
+        """Stop any cosine generator on the pin, turn the DAC off and release it.
+
+        A plain :meth:`write` also stops the generator, so there is nothing else
+        to call to take the pin back."""
+        self._b.request(C.DAC_DISABLE, bytes([pin]))
+
+
+class Touch:
+    """Capacitive touch pads (classic ESP32: lower = touched; S2/S3: higher = touched).
+
+        val = esp.touch.read(4)           # raw pad reading
+    """
+
+    def __init__(self, bridge):
+        bridge.require(C.Cap.TOUCH, "touch sensing")
+        self._b = bridge
+
+    def read(self, pin: int) -> int:
+        """Raw capacitive reading for a touch pad."""
+        return struct.unpack(">I", self._b.request(C.TOUCH_READ, bytes([pin])))[0]