esplink 1.0.2__tar.gz

esplink-1.0.2/.gitignore

@@ -0,0 +1,227 @@
+# Written by python/examples/devices/i2s_record.py when you run it.
+python/examples/devices/recording.wav
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# Prebuilt firmware image bundled into the wheel — regenerated by
+# tools/build_firmware.py (locally / in CI) before the package is built.
+python/esplink/firmware/*.bin
+# Isolated arduino-cli build scratch for tools/build_firmware.py (ELF/map/bins).
+tools/.fw-build/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

esplink-1.0.2/.python-version

@@ -0,0 +1 @@
+3.14

esplink-1.0.2/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: esplink
+Version: 1.0.2
+Summary: Control every ESP32 peripheral from Python over USB serial or Bluetooth — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE, ESP-NOW, RMT, 1-Wire, CAN, I2S, files, NVS, OTA
+Project-URL: Homepage, https://github.com/HamzaYslmn/esplink
+Author: HamzaYslmn
+Keywords: ble,bridge,esp32,espnow,firmata,gpio,i2c,raspberry-pi,serial,spi
+Requires-Python: >=3.11
+Requires-Dist: bleak>=3.0.2
+Requires-Dist: pyserial>=3.5
+Provides-Extra: all
+Requires-Dist: bleak>=0.22; extra == 'all'
+Requires-Dist: esptool>=5; extra == 'all'
+Requires-Dist: fastmcp>=2.3; extra == 'all'
+Requires-Dist: pillow>=10; extra == 'all'
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == 'ble'
+Provides-Extra: flash
+Requires-Dist: esptool>=5; extra == 'flash'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.3; extra == 'mcp'
+Provides-Extra: oled
+Requires-Dist: pillow>=10; extra == 'oled'
+Description-Content-Type: text/markdown
+
+# esplink
+
+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 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_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/")
+```
+
+- On-device rules react without the host in the loop
+  (`esp.watch.add("adc", pin=34, above=3200, do=("pwm", 13, 0))`), and
+  `esp.radio_off()` silences Wi-Fi + Bluetooth entirely for jitter-sensitive
+  realtime work (frees ~110 KB heap, unlocks the ADC2 pins).
+- Firmware (flash once with Arduino IDE) and full docs:
+  **<https://github.com/HamzaYslmn/esplink>**
+- Works on Raspberry Pi OS, Linux, Windows, macOS (Python ≥ 3.11, pyserial).
+- `esplink` CLI: connection info; `esplink ports`: list candidate ports.

esplink-1.0.2/README.md

@@ -0,0 +1,27 @@
+# esplink
+
+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 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_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/")
+```
+
+- On-device rules react without the host in the loop
+  (`esp.watch.add("adc", pin=34, above=3200, do=("pwm", 13, 0))`), and
+  `esp.radio_off()` silences Wi-Fi + Bluetooth entirely for jitter-sensitive
+  realtime work (frees ~110 KB heap, unlocks the ADC2 pins).
+- Firmware (flash once with Arduino IDE) and full docs:
+  **<https://github.com/HamzaYslmn/esplink>**
+- Works on Raspberry Pi OS, Linux, Windows, macOS (Python ≥ 3.11, pyserial).
+- `esplink` CLI: connection info; `esplink ports`: list candidate ports.

esplink-1.0.2/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-1.0.2/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-1.0.2/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]