python-esp-bridge 0.1.1__tar.gz → 0.3.0__tar.gz

{python_esp_bridge-0.1.1 → python_esp_bridge-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-esp-bridge
-Version: 0.1.1
-Summary: Control every ESP32 peripheral from Python over USB serial or Bluetooth — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE
+Version: 0.3.0
+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/python-esp-bridge
 Author: HamzaYslmn
-Keywords: ble,bridge,esp32,firmata,gpio,i2c,raspberry-pi,serial,spi
+Keywords: ble,bridge,esp32,espnow,firmata,gpio,i2c,raspberry-pi,serial,spi
 Requires-Python: >=3.10
 Requires-Dist: pyserial>=3.5
 Provides-Extra: ble

{python_esp_bridge-0.1.1 → python_esp_bridge-0.3.0}/espbridge/__init__.py

@@ -1,4 +1,4 @@
-"""espbridge — control every ESP32 peripheral from Python over USB serial.
+"""espbridge — control every ESP32 peripheral from Python over USB or Bluetooth.
 
 Flash firmware/firmware.ino once, then:
 
@@ -11,6 +11,14 @@ Flash firmware/firmware.ino once, then:
         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 primitives):
+    #   espbridge.neopixel, .dht, .ds18b20, .hcsr04, .ir, .stepper
 """
 from .bridge import Bridge, BridgeSet, Info, connect_all
 from .constants import Cap, ChipModel, Status
@@ -32,7 +40,7 @@ def find_ble_devices(timeout: float = 5.0):
 
     return _scan(timeout)
 
-__version__ = "0.1.1"
+__version__ = "0.3.0"
 
 __all__ = [
     "Bridge",

python_esp_bridge-0.3.0/espbridge/_log.py

@@ -0,0 +1,68 @@
+"""Library logger: "[espbridge]" 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/VS Code have VT processing on already; flip it on
+        # for the classic console. Failure means no ANSI support.
+        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__("[espbridge] %(levelprefix)s %(message)s")
+        self.use_colors = use_colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        pad = " " * max(0, 8 - len(record.levelname))  # align like uvicorn
+        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("espbridge")
+if not log.handlers:
+    if 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

{python_esp_bridge-0.1.1 → python_esp_bridge-0.3.0}/espbridge/bridge.py

@@ -2,13 +2,13 @@
 from __future__ import annotations
 
 import dataclasses
-import functools
 import struct
 import threading
 import time
 from dataclasses import dataclass
 
 from . import constants as C
+from ._log import log
 from .errors import (
     AuthError,
     BridgeError,
@@ -124,12 +124,9 @@ class Bridge:
                     "no ESP32 serial port found (CP210x/CH340/CH9102/native USB); "
                     "pass port='COM5' / '/dev/ttyUSB0' explicitly — or ble=True"
                 )
-            if name is None and mac is None and len(ports) > 1:
-                names = ", ".join(p.device for p in ports)
-                raise NoDeviceError(
-                    f"multiple ESP32-like ports found ({names}); pass port=, "
-                    f"name= or mac= — or use espbridge.connect_all()"
-                )
+            # Several ESP32-like ports: probe each in turn and keep the first
+            # that answers the bridge handshake (and matches name=/mac= if
+            # given) — non-bridge boards just time out and are skipped.
             candidates = [(lambda p=p: SerialTransport(p.device, baud, usb_chip=p.usb_chip),
                            p.device, p.usb_chip) for p in ports]
 
@@ -137,9 +134,12 @@ class Bridge:
         errors: list[str] = []
         for factory, label, chip in candidates:
             self._reset_state()
+            if probing:
+                log.debug(f"probing {label} ...")
             try:
                 self._t = factory()
             except Exception as e:
+                log.debug(f"{label}: open failed: {e}")
                 errors.append(f"{label}: {e}")
                 continue
             self._reader = threading.Thread(target=self._read_loop, daemon=True,
@@ -156,6 +156,16 @@ class Bridge:
                     if upgrade_baud and getattr(self._t, "has_baud", True):
                         self._upgrade_baud(baud, target_baud)
                     self.reset_on_exit = reset_on_exit
+                    if probing and name is None and mac is None:
+                        others = ", ".join(l for _, l, _ in candidates
+                                           if l != label) or "none"
+                        log.info(
+                            f"auto-selected {label}: "
+                            f"name={self.info.name or '(unnamed)'} "
+                            f"mac={self.info.mac} "
+                            f"chip={self.info.chip.name} "
+                            f"(other candidates: {others}; pin one with "
+                            f"port=, name=, mac= or ble='name-or-mac')")
                     return
                 errors.append(f"{label}: name={self.info.name!r} "
                               f"mac={self.info.mac} (no match)")
@@ -164,6 +174,7 @@ class Bridge:
                 self.close()
                 if not probing:
                     raise
+                log.debug(f"{label}: {e}")
                 errors.append(f"{label}: {e}")
             except BaseException:
                 self.close()
@@ -195,11 +206,8 @@ class Bridge:
                 f"no bridge{what} found over Bluetooth — is the board powered, "
                 f"in range, and flashed with BRIDGE_BLE_LINK enabled?"
             )
-        if target is None and name is None and mac is None and len(devs) > 1:
-            names = ", ".join(d.name or d.address for d in devs)
-            raise NoDeviceError(
-                f"multiple bridges advertising ({names}); pass ble='name-or-mac'"
-            )
+        # Several bridges advertising: probe in adv order, first auth +
+        # handshake wins (the caller prints which one was auto-selected).
         return [(lambda d=d: BleTransport(d.address),
                  f"BLE {d.name or d.address}", None) for d in devs]
 
@@ -228,6 +236,7 @@ class Bridge:
         self._closing = False
         self.info = None
         self.on_event(C.SYS_READY, self._on_ready)
+        self.on_event(C.SYS_LOG, self._on_sys_log)
 
     def _matches(self, name: str | None, mac: str | None) -> bool:
         assert self.info is not None
@@ -291,10 +300,12 @@ class Bridge:
         for _ in range(3):
             try:
                 self.ping(b"baud")
+                log.debug(f"baud upgraded {current} -> {target}")
                 return
             except BridgeTimeoutError:
                 continue
         # Could not talk at the new baud: fall back.
+        log.warning(f"baud upgrade to {target} failed; falling back to {current}")
         self._t.set_baudrate(current)
         try:
             self.ping(b"fallback")
@@ -310,6 +321,7 @@ class Bridge:
         chip = getattr(self._t, "usb_chip", None)
         if port is None:
             raise BridgeTimeoutError("link lost and transport cannot be reopened")
+        log.warning(f"link lost; reopening {port} at {baud} baud")
         self._t.close()
         self._reader.join(timeout=1.0)
         time.sleep(0.3)  # let the device reboot from the close-time reset
@@ -345,15 +357,18 @@ class Bridge:
         while not self._closing:
             try:
                 data = self._t.read()
-            except Exception:
+            except Exception as e:
+                if not self._closing:
+                    log.warning(f"transport read failed ({e}); link is down")
                 break  # port closed / unplugged
             if not data:
                 continue
             for chunk in self._splitter.feed(data):
                 try:
                     frame = decode_frame(chunk)
-                except ProtocolError:
-                    continue  # corrupted frame: drop; requester times out & retries
+                except ProtocolError as e:
+                    log.debug(f"dropping corrupted frame: {e}")
+                    continue  # requester times out & retries
                 self._handle_frame(frame)
         # Wake up anyone still waiting.
         with self._pending_lock:
@@ -370,6 +385,13 @@ class Bridge:
             p.frame = frame
             p.event.set()
 
+    def _on_sys_log(self, payload: bytes) -> None:
+        # Firmware log line (incl. redirected ESP-IDF Wi-Fi/BT logs):
+        # level u8 | message. Surface via the espbridge logger.
+        if payload:
+            msg = payload[1:].decode("utf-8", "replace")
+            (log.warning if payload[0] >= 2 else log.info)(f"[fw] {msg}")
+
     def _dispatch_event(self, frame: Frame) -> None:
         with self._handlers_lock:
             specific = list(self._handlers.get(frame.cmd, ()))
@@ -377,13 +399,13 @@ class Bridge:
         for cb in specific:
             try:
                 cb(frame.payload)
-            except Exception:
-                pass  # user callbacks must not kill the reader
+            except Exception:  # user callbacks must not kill the reader
+                log.exception(f"event callback {cb!r} raised")
         for cb in wildcard:
             try:
                 cb(frame)
             except Exception:
-                pass
+                log.exception(f"event callback {cb!r} raised")
 
     # ---- events API ----------------------------------------------------------------
 
@@ -459,6 +481,42 @@ class Bridge:
         return {"free": free, "min_free": min_free, "largest_block": largest,
                 "dropped_events": dropped}
 
+    def deep_sleep(self, seconds: float = 0, *, wake_pin: int | None = None,
+                   wake_level: int = 1) -> None:
+        """Put the ESP32 into deep sleep; it reboots on wake-up.
+
+        The link drops while asleep. Wake on a timer (`seconds`), a GPIO
+        level (`wake_pin`/`wake_level`), or both. After a timer wake the
+        board boots fresh — reconnect with a new Bridge() or `reset()` flow.
+
+        Not available on classic ESP32 when the BLE link is compiled in
+        (IRAM limit) — build with BRIDGE_ENABLE_BLE 0 to enable it there.
+        """
+        self.require(C.Cap.SLEEP, "sleep")
+        self.request(C.SYS_SLEEP, self._sleep_args(0, seconds, wake_pin, wake_level))
+
+    def light_sleep(self, seconds: float = 0, *, wake_pin: int | None = None,
+                    wake_level: int = 1) -> int:
+        """Pause the ESP32 in light sleep; returns the wake cause (RAM and
+        the link survive; the reply arrives after wake-up)."""
+        self.require(C.Cap.SLEEP, "sleep")
+        r = self.request(C.SYS_SLEEP, self._sleep_args(1, seconds, wake_pin, wake_level),
+                         timeout=seconds + self.timeout)
+        return r[0]
+
+    def wake_cause(self) -> int:
+        """esp_sleep_wakeup_cause_t of the last boot (0 = normal reset,
+        2 ext0, 3 ext1, 4 timer, 7 gpio)."""
+        return self.request(C.SYS_WAKE_CAUSE)[0]
+
+    @staticmethod
+    def _sleep_args(mode: int, seconds: float, wake_pin: int | None,
+                    wake_level: int) -> bytes:
+        if seconds <= 0 and wake_pin is None:
+            raise ValueError("give a timer (seconds) and/or a wake_pin")
+        return struct.pack(">BQbB", mode, round(seconds * 1_000_000),
+                           -1 if wake_pin is None else wake_pin, wake_level)
+
     def reset(self) -> None:
         """Soft-reset the ESP32 and wait for it to come back."""
         self._ready.clear()
@@ -477,60 +535,44 @@ class Bridge:
 
     # ---- sub-APIs (lazy, created on first access) ----------------------------------------------
 
-    @functools.cached_property
-    def gpio(self):
-        from .gpio import Gpio
-        return Gpio(self)
-
-    @functools.cached_property
-    def adc(self):
-        from .analog import Adc
-        return Adc(self)
-
-    @functools.cached_property
-    def dac(self):
-        from .analog import Dac
-        return Dac(self)
-
-    @functools.cached_property
-    def touch(self):
-        from .analog import Touch
-        return Touch(self)
-
-    @functools.cached_property
-    def pwm(self):
-        from .pwm import Pwm
-        return Pwm(self)
-
-    @functools.cached_property
-    def i2c(self):
-        from .i2c import I2c
-        return I2c(self)
-
-    @functools.cached_property
-    def spi(self):
-        from .spi import Spi
-        return Spi(self)
-
-    @functools.cached_property
-    def uart(self):
-        from .uart import Uart
-        return Uart(self)
-
-    @functools.cached_property
-    def wifi(self):
-        from .wifi import Wifi
-        return Wifi(self)
-
-    @functools.cached_property
-    def net(self):
-        from .net import Net
-        return Net(self)
-
-    @functools.cached_property
-    def ble(self):
-        from .ble import Ble
-        return Ble(self)
+    _SUBAPIS = {
+        "gpio": ("gpio", "Gpio"),
+        "adc": ("analog", "Adc"),
+        "dac": ("analog", "Dac"),
+        "touch": ("analog", "Touch"),
+        "pwm": ("pwm", "Pwm"),
+        "i2c": ("i2c", "I2c"),
+        "spi": ("spi", "Spi"),
+        "uart": ("uart", "Uart"),
+        "wifi": ("wifi", "Wifi"),
+        "net": ("net", "Net"),
+        "ble": ("ble", "Ble"),
+        "espnow": ("espnow", "EspNow"),
+        "rmt": ("rmt", "Rmt"),
+        "onewire": ("onewire", "OneWire"),
+        "fs": ("fs", "Fs"),
+        "nvs": ("nvs", "Nvs"),
+        "ota": ("ota", "Ota"),
+        "can": ("can", "Can"),
+        "i2s": ("i2s", "I2s"),
+        "eth": ("eth", "Eth"),
+        "camera": ("camera", "Camera"),
+        "mcpwm": ("mcpwm", "Mcpwm"),
+    }
+
+    def __getattr__(self, name):
+        try:
+            mod_name, cls_name = self._SUBAPIS[name]
+        except KeyError:
+            raise AttributeError(name) from None
+        import importlib
+
+        obj = getattr(importlib.import_module(f".{mod_name}", __package__), cls_name)(self)
+        setattr(self, name, obj)  # cache: next access skips __getattr__
+        return obj
+
+    def __dir__(self):
+        return [*super().__dir__(), *self._SUBAPIS]
 
 
 class BridgeSet(list):
@@ -574,6 +616,7 @@ def connect_all(**kwargs) -> BridgeSet:
         try:
             out.append(Bridge(p.device, **kwargs))
         except BridgeError as e:
+            log.warning(f"connect_all: skipping {p.device}: {e}")
             errors.append(f"{p.device}: {e}")
     if not out:
         raise NoDeviceError("no bridges connected"

python_esp_bridge-0.3.0/espbridge/camera.py

@@ -0,0 +1,81 @@
+"""Camera — JPEG snapshots from OV-series sensors (firmware opt-in).
+
+Build the firmware with ``#define BRIDGE_ENABLE_CAM 1`` (esp32/s2/s3 with
+PSRAM), then:
+
+    esp.camera.begin("ai-thinker")            # ESP32-CAM board
+    jpeg = esp.camera.capture()               # bytes, ready to save
+    open("shot.jpg", "wb").write(jpeg)
+    esp.camera.set("framesize", FRAMESIZE_VGA)
+
+Frames cross the link at ~92 KB/s over USB — snapshots, not video.
+"""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+# framesize_t values (esp32-camera)
+FRAMESIZE_QQVGA, FRAMESIZE_QCIF, FRAMESIZE_HQVGA, FRAMESIZE_240X240, \
+    FRAMESIZE_QVGA, FRAMESIZE_CIF, FRAMESIZE_HVGA, FRAMESIZE_VGA, \
+    FRAMESIZE_SVGA, FRAMESIZE_XGA, FRAMESIZE_HD, FRAMESIZE_SXGA, \
+    FRAMESIZE_UXGA = range(13)
+
+# CAM_SET property ids (mirrors firmware mod_cam.cpp)
+_PROPS = {"framesize": 0, "quality": 1, "brightness": 2, "contrast": 3,
+          "saturation": 4, "vflip": 5, "hmirror": 6, "special_effect": 7,
+          "whitebal": 8, "exposure_ctrl": 9, "aec_value": 10,
+          "gain_ctrl": 11, "agc_gain": 12}
+
+# pin maps: pwdn, reset, xclk, siod, sioc, d7..d0, vsync, href, pclk
+PRESETS: dict[str, list[int]] = {
+    "ai-thinker":    [32, -1, 0, 26, 27, 35, 34, 39, 36, 21, 19, 18, 5, 25, 23, 22],
+    "esp-eye":       [-1, -1, 4, 18, 23, 36, 37, 38, 39, 35, 14, 13, 34, 5, 27, 25],
+    "m5stack-wide":  [-1, 15, 27, 22, 23, 19, 36, 18, 39, 5, 34, 35, 32, 25, 26, 21],
+    "xiao-s3-sense": [-1, -1, 10, 40, 39, 48, 11, 12, 14, 16, 18, 17, 15, 38, 47, 13],
+    "freenove-s3":   [-1, -1, 15, 4, 5, 16, 17, 18, 12, 10, 8, 9, 11, 6, 7, 13],
+}
+
+_CHUNK = C.MAX_PAYLOAD - 8
+
+
+class Camera:
+    def __init__(self, bridge):
+        self._b = bridge
+        bridge.require(C.Cap.CAM, "camera (BRIDGE_ENABLE_CAM=1 firmware + PSRAM)")
+
+    def begin(self, preset: str | list[int] = "ai-thinker", *,
+              framesize: int = FRAMESIZE_VGA, quality: int = 12,
+              xclk_mhz: int = 20, fb_count: int = 1) -> None:
+        """Init the sensor. preset = board name or a 16-entry pin list.
+        quality: JPEG 0 (best) .. 63; fb_count 2 double-buffers in PSRAM."""
+        pins = PRESETS[preset] if isinstance(preset, str) else list(preset)
+        if len(pins) != 16:
+            raise ValueError("pin map must have 16 entries")
+        payload = struct.pack(">16b", *pins) + bytes([xclk_mhz, framesize,
+                                                      quality, fb_count])
+        self._b.request(C.CAM_INIT, payload, timeout=15.0)
+
+    def capture(self) -> bytes:
+        """Grab one frame and pull it across the link (JPEG bytes)."""
+        r = self._b.request(C.CAM_CAPTURE, timeout=10.0)
+        total = struct.unpack(">I", r[:4])[0]
+        out = bytearray()
+        while len(out) < total:
+            chunk = self._b.request(
+                C.CAM_READ, struct.pack(">IH", len(out),
+                                        min(_CHUNK, total - len(out))))
+            if not chunk:
+                break
+            out += chunk
+        self._b.request(C.CAM_RELEASE)
+        return bytes(out)
+
+    def set(self, prop: str, value: int) -> None:
+        """Tune the sensor: framesize, quality, brightness (-2..2),
+        contrast, saturation, vflip, hmirror, ... (see _PROPS)."""
+        self._b.request(C.CAM_SET, struct.pack(">Bi", _PROPS[prop], value))
+
+    def end(self) -> None:
+        self._b.request(C.CAM_DEINIT)

python_esp_bridge-0.3.0/espbridge/can.py

@@ -0,0 +1,105 @@
+"""CAN bus (the ESP32's TWAI controller, python-can-flavored API).
+
+Wire a CAN transceiver (SN65HVD230, TJA1050, ...) between the chosen pins
+and the bus — the ESP32 pins speak TTL, not CAN levels.
+
+    esp.can.begin(tx=21, rx=22, bitrate=500_000)
+    esp.can.send(0x123, b"\\x01\\x02")
+    msg = esp.can.recv(timeout=1.0)        # polled
+    esp.can.on_message(lambda m: print(m)) # or callbacks
+"""
+from __future__ import annotations
+
+import queue
+import struct
+from dataclasses import dataclass, field
+
+from . import constants as C
+
+_BITRATES = {25_000: 0, 50_000: 1, 100_000: 2, 125_000: 3,
+             250_000: 4, 500_000: 5, 800_000: 6, 1_000_000: 7}
+_MODES = {"normal": 0, "listen": 1, "no_ack": 2}
+
+
+@dataclass
+class Message:
+    id: int
+    data: bytes = b""
+    extended: bool = False
+    rtr: bool = field(default=False, repr=False)
+
+    def __str__(self) -> str:
+        return f"CAN {self.id:0{8 if self.extended else 3}X} [{len(self.data)}] {self.data.hex(' ')}"
+
+
+class Can:
+    def __init__(self, bridge):
+        self._b = bridge
+        bridge.require(C.Cap.TWAI, "CAN/TWAI")
+        self._rx: queue.Queue[Message] = queue.Queue(maxsize=1024)
+        self._callbacks: list = []
+        bridge.on_event(C.TWAI_RX_EVT, self._on_rx)
+
+    def _on_rx(self, payload: bytes) -> None:
+        msg = Message(id=struct.unpack_from(">I", payload, 1)[0],
+                      data=payload[5:],
+                      extended=bool(payload[0] & 1),
+                      rtr=bool(payload[0] & 2))
+        if self._callbacks:
+            for cb in self._callbacks:
+                cb(msg)
+        else:
+            try:
+                self._rx.put_nowait(msg)
+            except queue.Full:
+                pass  # oldest-first backpressure: drop newest
+
+    def begin(self, tx: int, rx: int, bitrate: int = 500_000, *,
+              mode: str = "normal",
+              accept: tuple[int, int] | None = None) -> None:
+        """Start the controller. mode: normal | listen | no_ack.
+
+        accept=(code, mask) programs the single acceptance filter
+        (hardware-level; see the ESP32 TRM for the bit layout).
+        """
+        payload = bytes([tx, rx, _MODES[mode], _BITRATES[bitrate]])
+        if accept is not None:
+            payload += struct.pack(">IIB", accept[0], accept[1], 1)
+        self._b.request(C.TWAI_INIT, payload)
+
+    def send(self, msg_or_id: Message | int, data: bytes = b"", *,
+             extended: bool = False, rtr: bool = False) -> None:
+        """Queue one frame (blocks briefly if the TX queue is full)."""
+        m = msg_or_id if isinstance(msg_or_id, Message) else Message(
+            msg_or_id, data, extended, rtr)
+        if len(m.data) > 8:
+            raise ValueError("classic CAN frames carry at most 8 bytes")
+        flags = (1 if m.extended else 0) | (2 if m.rtr else 0)
+        self._b.request(C.TWAI_SEND,
+                        struct.pack(">BI", flags, m.id) + m.data)
+
+    def recv(self, timeout: float | None = None) -> Message | None:
+        """Next received frame (None on timeout). Unused when callbacks are set."""
+        try:
+            return self._rx.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def on_message(self, callback) -> None:
+        """callback(Message) for every received frame (reader thread —
+        don't call blocking bridge requests from inside it)."""
+        self._callbacks.append(callback)
+
+    def status(self) -> dict:
+        r = self._b.request(C.TWAI_STATUS)
+        state, tx_err, rx_err = r[0], r[1], r[2]
+        return {"state": ("stopped", "running", "recovering", "bus_off")[state],
+                "tx_errors": tx_err, "rx_errors": rx_err,
+                "rx_missed": struct.unpack_from(">I", r, 3)[0]}
+
+    def recover(self) -> None:
+        """Start bus-off recovery."""
+        self._b.request(C.TWAI_RECOVER)
+
+    def end(self) -> None:
+        self._b.request(C.TWAI_DEINIT)

{python_esp_bridge-0.1.1 → python_esp_bridge-0.3.0}/espbridge/cli.py

@@ -2,9 +2,9 @@
 from __future__ import annotations
 
 import argparse
-import sys
 
 from . import __version__
+from ._log import log
 from .bridge import Bridge, connect_all
 from .errors import BridgeError
 from .transports import find_ports
@@ -119,7 +119,7 @@ def main(argv: list[str] | None = None) -> int:
             _print_info(esp)
         return 0
     except BridgeError as e:
-        print(f"error: {e}", file=sys.stderr)
+        log.error(str(e))
         return 1