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

espbridge/net.py

@@ -0,0 +1,279 @@
+"""TCP/UDP sockets proxied through the ESP32 radio.
+
+Socket-like objects backed by the NET module's credit-window flow control:
+the firmware never sends more than the window un-acked; we replenish credit
+as the application consumes data, so fast peers get normal TCP backpressure.
+"""
+from __future__ import annotations
+
+import queue
+import struct
+import threading
+import time
+
+from . import constants as C
+from .errors import BridgeError, BridgeTimeoutError
+from .protocol import ip_str, lp
+
+# Per-request send chunk: bounds single-request size (and how long the
+# firmware's synchronous socket write can run). Well under MAX_PAYLOAD.
+_SEND_CHUNK = 1024
+
+
+_UNSET = object()
+
+
+class TcpSocket:
+    def __init__(self, net: "Net", handle: int, peer: tuple[str, int] | None = None):
+        self._net = net
+        self._b = net._b
+        self.handle = handle
+        self.peer = peer
+        self._buf = bytearray()
+        self._cond = threading.Condition()
+        self._open = True
+        self._timeout: float | None = None
+
+    def settimeout(self, timeout: float | None) -> None:
+        """Default timeout for recv() — stdlib socket semantics."""
+        self._timeout = timeout
+
+    def gettimeout(self) -> float | None:
+        return self._timeout
+
+    # internal: called from the reader thread
+    def _feed(self, data: bytes) -> None:
+        with self._cond:
+            self._buf += data
+            self._cond.notify_all()
+
+    def _closed_remote(self) -> None:
+        with self._cond:
+            self._open = False
+            self._cond.notify_all()
+
+    @property
+    def connected(self) -> bool:
+        return self._open
+
+    def recv(self, maxbytes: int = 65536, timeout: float | None = _UNSET) -> bytes:
+        """Like socket.recv: b'' means the peer closed. Blocks up to `timeout`
+        (default: the settimeout() value; None blocks until data/close)."""
+        if timeout is _UNSET:
+            timeout = self._timeout
+        deadline = None if timeout is None else time.monotonic() + timeout
+        with self._cond:
+            while not self._buf:
+                if not self._open:
+                    return b""
+                wait = None if deadline is None else deadline - time.monotonic()
+                if wait is not None and wait <= 0:
+                    raise BridgeTimeoutError("recv timed out")
+                self._cond.wait(wait if wait is not None else 0.5)
+            n = min(maxbytes, len(self._buf))
+            data = bytes(self._buf[:n])
+            del self._buf[:n]
+        # Replenish the firmware's send window (fire-and-forget).
+        self._b.send(C.NET_WINDOW_ACK, struct.pack(">BH", self.handle, n))
+        return data
+
+    def recv_exactly(self, n: int, timeout: float | None = None) -> bytes:
+        out = bytearray()
+        while len(out) < n:
+            chunk = self.recv(n - len(out), timeout)
+            if not chunk:
+                raise BridgeError("connection closed mid-read")
+            out += chunk
+        return bytes(out)
+
+    def send(self, data: bytes) -> int:
+        """Send all of `data`; returns len(data)."""
+        data = bytes(data)
+        off = 0
+        while off < len(data):
+            chunk = data[off : off + _SEND_CHUNK]
+            r = self._b.request(C.NET_SEND, bytes([self.handle]) + chunk, timeout=10.0)
+            (sent,) = struct.unpack(">H", r)
+            if sent == 0:
+                raise BridgeError("send failed (socket closed?)")
+            off += sent
+        return len(data)
+
+    sendall = send
+
+    def close(self) -> None:
+        if self._open:
+            self._open = False
+            try:
+                self._b.request(C.NET_CLOSE, bytes([self.handle]))
+            except BridgeError:
+                pass
+        self._net._forget(self.handle)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class TcpServer:
+    def __init__(self, net: "Net", handle: int, port: int):
+        self._net = net
+        self.handle = handle
+        self.port = port
+        self._accepted: queue.Queue[TcpSocket] = queue.Queue()
+
+    def accept(self, timeout: float | None = None) -> TcpSocket:
+        try:
+            return self._accepted.get(timeout=timeout)
+        except queue.Empty:
+            raise BridgeTimeoutError("no incoming connection") from None
+
+    def close(self) -> None:
+        try:
+            self._net._b.request(C.NET_CLOSE, bytes([self.handle]))
+        except BridgeError:
+            pass
+        self._net._forget(self.handle)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class UdpSocket:
+    def __init__(self, net: "Net", handle: int, local_port: int):
+        self._net = net
+        self._b = net._b
+        self.handle = handle
+        self.local_port = local_port
+        self._timeout: float | None = None
+        self._packets: queue.Queue[tuple[bytes, tuple[str, int]]] = queue.Queue(maxsize=256)
+
+    def settimeout(self, timeout: float | None) -> None:
+        self._timeout = timeout
+
+    def gettimeout(self) -> float | None:
+        return self._timeout
+
+    def _feed(self, data: bytes, addr: tuple[str, int]) -> None:
+        try:
+            self._packets.put_nowait((data, addr))
+        except queue.Full:
+            pass  # UDP: drop on overflow
+
+    def sendto(self, data: bytes, addr: tuple[str, int]) -> None:
+        ip = bytes(int(x) for x in addr[0].split("."))
+        if len(data) > C.MAX_PAYLOAD - 7:
+            raise ValueError(f"datagram too large (> {C.MAX_PAYLOAD - 7})")
+        self._b.request(C.NET_SEND_TO,
+                        bytes([self.handle]) + ip + struct.pack(">H", addr[1]) + bytes(data))
+
+    def recvfrom(self, timeout: float | None = _UNSET) -> tuple[bytes, tuple[str, int]]:
+        if timeout is _UNSET:
+            timeout = self._timeout
+        try:
+            return self._packets.get(timeout=timeout)
+        except queue.Empty:
+            raise BridgeTimeoutError("no datagram received") from None
+
+    def close(self) -> None:
+        try:
+            self._b.request(C.NET_CLOSE, bytes([self.handle]))
+        except BridgeError:
+            pass
+        self._net._forget(self.handle)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class Net:
+    def __init__(self, bridge):
+        self._b = bridge
+        self._sockets: dict[int, object] = {}
+        bridge.on_event(C.NET_DATA_EVT, self._on_data)
+        bridge.on_event(C.NET_UDP_EVT, self._on_udp)
+        bridge.on_event(C.NET_ACCEPT_EVT, self._on_accept)
+        bridge.on_event(C.NET_CLOSED_EVT, self._on_closed)
+
+    # ---- events (reader thread) ------------------------------------------------
+
+    def _on_data(self, p: bytes) -> None:
+        s = self._sockets.get(p[0]) if p else None
+        if isinstance(s, TcpSocket):
+            s._feed(p[1:])
+
+    def _on_udp(self, p: bytes) -> None:
+        if len(p) < 7:
+            return
+        s = self._sockets.get(p[0])
+        if isinstance(s, UdpSocket):
+            (port,) = struct.unpack_from(">H", p, 5)
+            s._feed(p[7:], (ip_str(p[1:5]), port))
+
+    def _on_accept(self, p: bytes) -> None:
+        if len(p) < 8:
+            return
+        srv = self._sockets.get(p[0])
+        if isinstance(srv, TcpServer):
+            (port,) = struct.unpack_from(">H", p, 6)
+            sock = TcpSocket(self, p[1], (ip_str(p[2:6]), port))
+            self._sockets[p[1]] = sock
+            srv._accepted.put(sock)
+
+    def _on_closed(self, p: bytes) -> None:
+        s = self._sockets.get(p[0]) if p else None
+        if isinstance(s, TcpSocket):
+            s._closed_remote()
+
+    def _forget(self, handle: int) -> None:
+        self._sockets.pop(handle, None)
+
+    # ---- API -----------------------------------------------------------------------
+
+    def tcp_connect(self, host: str, port: int, timeout: float = 10.0) -> TcpSocket:
+        """Open a TCP connection *through the ESP32's Wi-Fi*."""
+        r = self._b.request(C.NET_TCP_CONNECT,
+                            struct.pack(">H", port) + lp(host),
+                            timeout=timeout)
+        sock = TcpSocket(self, r[0], (host, port))
+        self._sockets[r[0]] = sock
+        return sock
+
+    def tcp_listen(self, port: int) -> TcpServer:
+        r = self._b.request(C.NET_TCP_LISTEN, struct.pack(">H", port))
+        srv = TcpServer(self, r[0], port)
+        self._sockets[r[0]] = srv
+        return srv
+
+    def udp(self, local_port: int = 0) -> UdpSocket:
+        r = self._b.request(C.NET_UDP_OPEN, struct.pack(">H", local_port))
+        sock = UdpSocket(self, r[0], local_port)
+        self._sockets[r[0]] = sock
+        return sock
+
+    def http_get(self, url: str, timeout: float = 15.0) -> tuple[int, bytes]:
+        """Tiny HTTP/1.0 GET through the bridge (no TLS). Returns (status, body)."""
+        if not url.startswith("http://"):
+            raise ValueError("only http:// supported (no TLS on the proxy path)")
+        rest = url[7:]
+        host, _, path = rest.partition("/")
+        host, _, port_s = host.partition(":")
+        with self.tcp_connect(host, int(port_s) if port_s else 80, timeout) as s:
+            s.send(f"GET /{path} HTTP/1.0\r\nHost: {host}\r\nConnection: close\r\n\r\n".encode())
+            raw = bytearray()
+            while True:
+                chunk = s.recv(timeout=timeout)
+                if not chunk:
+                    break
+                raw += chunk
+        head, _, body = bytes(raw).partition(b"\r\n\r\n")
+        status = int(head.split(b" ", 2)[1]) if b" " in head else 0
+        return status, body

espbridge/oled.py

@@ -0,0 +1,182 @@
+"""Direct OLED support: SSD1306 / SH1106 / clones over the bridge's I2C.
+
+    pip install "python-esp-bridge[oled]"   (just adds Pillow for drawing)
+
+    from espbridge import Bridge
+    from espbridge.oled import OLED
+
+    with Bridge() as esp:
+        oled = OLED(esp)                       # bus init + auto-detect + power up
+        with oled.draw() as d:                 # d is a PIL ImageDraw
+            d.text((0, 10), "Hello!", fill="white")
+            d.rectangle((0, 56, 127, 62), fill="white")
+
+Drawing is plain PIL: text with any TTF font, shapes, bitmaps — build your own
+Image and call ``oled.show(image)`` if you prefer.
+
+Compatibility (learned the hard way): cheap "SSD1306" modules are very often
+SH1106-family clones. SH1106 lacks the SSD1306's horizontal addressing mode
+(bulk framebuffer dumps come out interleaved/wrapped), and clones disagree on
+where the visible window sits in controller RAM (column offset 0 vs 2).
+This driver therefore:
+
+- writes in *page mode*, which every chip in the family implements,
+- powers up with both families' commands (each chip ignores the other's),
+- defaults to column offset 0 (true SSD1306s and most 0.96" clones).
+
+Only genuine 1.3" SH1106 modules (window centered in 132-column RAM) need
+``OLED(esp, colstart=2)`` — symptom: image shifted sideways with a stripe of
+stale pixels at one edge; try colstart 0..4.
+
+Every common panel adjustment has a named method — no datasheet bytes needed:
+``contrast(0..255)``, ``invert()``, ``power(False)``, ``vertical_offset(rows)``,
+``start_line(row)``, ``flip(horizontal=..., vertical=...)`` and the
+``colstart`` attribute.
+"""
+from __future__ import annotations
+
+import contextlib
+
+from .errors import NoDeviceError
+
+_CMD = 0x00   # control byte: command stream follows
+_DATA = 0x40  # control byte: display data follows
+
+_INSTALL_HINT = (
+    'OLED drawing needs Pillow — install it with:\n'
+    '    pip install "python-esp-bridge[oled]"  (or: pip install pillow)'
+)
+
+# PIL packs mode-"1" rows MSB-first; panel pages want the top pixel in bit 0.
+_BITREV = bytes(int(f"{i:08b}"[::-1], 2) for i in range(256))
+
+
+class OLED:
+    """A 128x64/128x32 I2C OLED driven directly over the bridge."""
+
+    def __init__(self, esp, *, addr: int | None = None, sda: int = 21,
+                 scl: int = 22, freq: int = 400_000, bus: int = 0,
+                 width: int = 128, height: int = 64, colstart: int = 0,
+                 contrast: int = 0xCF, init_bus: bool = True):
+        try:
+            from PIL import Image, ImageDraw
+        except ImportError as e:
+            raise ImportError(_INSTALL_HINT) from e
+        self._Image, self._ImageDraw = Image, ImageDraw
+
+        self._i2c = esp.i2c
+        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(esp.i2c, "max_write", 2046) - 1
+        self.width, self.height = width, height
+        self.colstart = colstart
+
+        if init_bus:
+            self._i2c.init(sda=sda, scl=scl, freq=freq, bus=bus)
+        if addr is None:
+            found = self._i2c.scan(bus)
+            addr = next((a for a in (0x3C, 0x3D) if a in found), None)
+            if addr is None:
+                raise NoDeviceError(
+                    f"no OLED at 0x3C/0x3D (i2c scan found: {[hex(a) for a in found]})"
+                )
+        self.addr = addr
+
+        self.command(
+            0xAE,               # display off
+            0xD5, 0x80,         # clock divide
+            0xA8, height - 1,   # multiplex
+            0xD3, 0x00,         # display offset
+            0x40,               # start line 0
+            0xAD, 0x8B,         # SH1106: DC-DC on        (NOP on SSD1306)
+            0x8D, 0x14,         # SSD1306: charge pump on (NOP on SH1106)
+            0xA1, 0xC8,         # flip horizontally + vertically (rotation 0)
+            0xDA, 0x12 if height == 64 else 0x02,  # COM pins
+            0x81, contrast,
+            0xD9, 0xF1,         # precharge
+            0xDB, 0x40,         # VCOM detect
+            0xA4, 0xA6,         # from RAM, not inverted
+        )
+        self.clear()            # wipe power-on RAM noise before lighting up
+        self.command(0xAF)      # display on
+
+    # ---- low level ------------------------------------------------------------
+
+    def command(self, *cmds: int, wait: bool = True) -> None:
+        self._i2c.write(self.addr, bytes([_CMD, *cmds]), self._bus, wait=wait)
+
+    def _write_data(self, data: bytes, *, wait: bool = True) -> None:
+        chunk = self._chunk
+        for off in range(0, len(data), chunk):
+            self._i2c.write(self.addr, bytes([_DATA]) + data[off : off + chunk],
+                            self._bus,
+                            wait=wait and off + chunk >= len(data))
+
+    # ---- drawing ---------------------------------------------------------------
+
+    def show(self, image=None) -> None:
+        """Push a PIL image (mode '1' or anything convertible) to the panel."""
+        if image is None:
+            image = self._Image.new("1", (self.width, self.height))
+        if image.mode != "1":  # any nonzero pixel lights up (no dithering)
+            image = image.convert("L").point(lambda v: 255 if v else 0, mode="1")
+        # Transposing makes each image row a display column, so tobytes()
+        # yields the 8-pixel vertical slices pages are made of (MSB-first;
+        # the panel wants the top pixel in bit 0, hence the bit reversal).
+        raw = image.transpose(self._Image.Transpose.TRANSPOSE).tobytes()
+        bpr = self.height // 8  # transposed row = bpr bytes, one per page
+        low = 0x00 | (self.colstart & 0x0F)
+        high = 0x10 | (self.colstart >> 4)
+        pages = self.height // 8
+        for page in range(pages):
+            # Pipelined: everything fire-and-forget except the final data
+            # write, which acts as the frame sync (firmware runs in order).
+            self.command(0xB0 + page, low, high, wait=False)
+            self._write_data(raw[page::bpr].translate(_BITREV),
+                             wait=page == pages - 1)
+
+    @contextlib.contextmanager
+    def draw(self):
+        """Context manager: yields a PIL ImageDraw; pushes the frame on exit."""
+        image = self._Image.new("1", (self.width, self.height))
+        yield self._ImageDraw.Draw(image)
+        self.show(image)
+
+    def clear(self) -> None:
+        self.show(None)
+
+    # ---- panel controls -----------------------------------------------------------
+    # Named knobs for every common panel adjustment — no datasheet bytes needed.
+    # (`colstart` is a plain attribute: `oled.colstart = 2` applies on next show().)
+
+    def contrast(self, value: int) -> None:
+        """Brightness, 0..255."""
+        self.command(0x81, value & 0xFF)
+
+    def invert(self, enabled: bool = True) -> None:
+        """White-on-black <-> black-on-white, instantly (no redraw needed)."""
+        self.command(0xA7 if enabled else 0xA6)
+
+    def power(self, on: bool = True) -> None:
+        """Panel on/off (RAM contents are kept while off)."""
+        self.command(0xAF if on else 0xAE)
+
+    def vertical_offset(self, rows: int = 0) -> None:
+        """Shift the image down by 0..63 rows — fixes panels whose glass is
+        wired with a vertical offset (image starts a couple rows low/high)."""
+        self.command(0xD3, rows & 0x3F)
+
+    def start_line(self, line: int = 0) -> None:
+        """Hardware vertical scroll: which RAM row appears at the top."""
+        self.command(0x40 | (line & 0x3F))
+
+    def flip(self, *, horizontal: bool = False, vertical: bool = False) -> None:
+        """Mirror the panel in hardware (for displays mounted rotated).
+
+        flip(horizontal=True, vertical=True) is a 180° rotation. The vertical
+        mirror applies instantly; the horizontal one applies from the next
+        show() (it remaps how RAM is written).
+        """
+        self.command(0xA0 if horizontal else 0xA1,
+                     0xC0 if vertical else 0xC8)

espbridge/protocol.py

@@ -0,0 +1,159 @@
+"""Frame codec: COBS framing + CRC-16/CCITT-FALSE.
+
+Wire format (see docs/PROTOCOL.md):
+    logical frame = flags u8 | seq u8 | cmd u16 BE | payload | crc16 BE
+    on the wire   = COBS(logical) + b"\\x00"
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from .constants import FLAG_ERROR, FLAG_EVENT, MAX_PAYLOAD
+from .errors import ProtocolError
+
+_HDR = struct.Struct(">BBH")
+
+# ---- CRC-16/CCITT-FALSE (table-driven) ---------------------------------------
+
+
+def _make_table() -> list[int]:
+    table = []
+    for byte in range(256):
+        crc = byte << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+        table.append(crc)
+    return table
+
+
+_CRC_TABLE = _make_table()
+
+
+def crc16_ccitt(data: bytes) -> int:
+    crc = 0xFFFF
+    for b in data:
+        crc = ((crc << 8) & 0xFFFF) ^ _CRC_TABLE[((crc >> 8) ^ b) & 0xFF]
+    return crc
+
+
+# ---- COBS ----------------------------------------------------------------------
+
+
+def cobs_encode(data: bytes) -> bytes:
+    out = bytearray([0])  # placeholder for first code byte
+    code_idx = 0
+    code = 1
+    for b in data:
+        if b == 0:
+            out[code_idx] = code
+            code_idx = len(out)
+            out.append(0)
+            code = 1
+        else:
+            out.append(b)
+            code += 1
+            if code == 0xFF:
+                out[code_idx] = code
+                code_idx = len(out)
+                out.append(0)
+                code = 1
+    out[code_idx] = code
+    return bytes(out)
+
+
+def cobs_decode(data: bytes) -> bytes:
+    out = bytearray()
+    i = 0
+    n = len(data)
+    while i < n:
+        code = data[i]
+        if code == 0:
+            raise ProtocolError("zero byte inside COBS frame")
+        i += 1
+        end = i + code - 1
+        if end > n:
+            raise ProtocolError("truncated COBS block")
+        out += data[i:end]
+        i = end
+        if code != 0xFF and i < n:
+            out.append(0)
+    return bytes(out)
+
+
+# ---- frames ---------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Frame:
+    flags: int
+    seq: int
+    cmd: int
+    payload: bytes
+
+    @property
+    def is_event(self) -> bool:
+        return bool(self.flags & FLAG_EVENT)
+
+    @property
+    def is_error(self) -> bool:
+        return bool(self.flags & FLAG_ERROR)
+
+
+def encode_frame(flags: int, seq: int, cmd: int, payload: bytes = b"") -> bytes:
+    """Logical frame -> wire bytes (COBS + 0x00 delimiter)."""
+    if len(payload) > MAX_PAYLOAD:
+        raise ProtocolError(f"payload too large: {len(payload)} > {MAX_PAYLOAD}")
+    logical = _HDR.pack(flags, seq, cmd) + payload
+    logical += struct.pack(">H", crc16_ccitt(logical))
+    return cobs_encode(logical) + b"\x00"
+
+
+def decode_frame(encoded: bytes) -> Frame:
+    """Wire bytes between delimiters -> logical Frame. Raises ProtocolError."""
+    logical = cobs_decode(encoded)
+    if len(logical) < 6:
+        raise ProtocolError(f"frame too short: {len(logical)} bytes")
+    (crc,) = struct.unpack_from(">H", logical, len(logical) - 2)
+    if crc16_ccitt(logical[:-2]) != crc:
+        raise ProtocolError("CRC mismatch")
+    flags, seq, cmd = _HDR.unpack_from(logical)
+    return Frame(flags, seq, cmd, logical[4:-2])
+
+
+# ---- wire-format helpers shared by the sub-API modules ---------------------------
+
+
+def lp(s: str | bytes) -> bytes:
+    """Length-prefixed string (len u8 | bytes) — the protocol's string format."""
+    b = s.encode() if isinstance(s, str) else bytes(s)
+    if len(b) > 255:
+        raise ProtocolError(f"string too long for length prefix: {len(b)} bytes")
+    return bytes([len(b)]) + b
+
+
+def ip_str(b: bytes) -> str:
+    """4 raw bytes -> dotted-quad string."""
+    return ".".join(str(x) for x in b)
+
+
+class FrameSplitter:
+    """Accumulates raw serial bytes and yields COBS chunks between 0x00 delimiters."""
+
+    def __init__(self) -> None:
+        self._buf = bytearray()
+
+    def feed(self, data: bytes) -> list[bytes]:
+        chunks: list[bytes] = []
+        self._buf += data
+        while True:
+            i = self._buf.find(0)
+            if i < 0:
+                break
+            if i > 0:
+                chunks.append(bytes(self._buf[:i]))
+            del self._buf[: i + 1]
+        return chunks
+
+    def reset(self) -> None:
+        self._buf.clear()

espbridge/pwm.py

@@ -0,0 +1,41 @@
+"""PWM via the ESP32 LEDC peripheral, plus servo/tone conveniences."""
+from __future__ import annotations
+
+import struct
+
+from . import constants as C
+
+
+class Pwm:
+    def __init__(self, bridge):
+        self._b = bridge
+        self._attached: dict[int, tuple[int, int]] = {}  # pin -> (freq, res_bits)
+
+    def attach(self, pin: int, freq: int = 1000, resolution_bits: int = 10) -> None:
+        self._b.request(C.PWM_ATTACH, struct.pack(">BIB", pin, freq, resolution_bits))
+        self._attached[pin] = (freq, resolution_bits)
+
+    def write(self, pin: int, duty: int) -> None:
+        """Raw duty (0 .. 2**resolution_bits - 1)."""
+        self._b.request(C.PWM_WRITE, struct.pack(">BI", pin, duty))
+
+    def duty_pct(self, pin: int, percent: float) -> None:
+        if pin not in self._attached:
+            self.attach(pin)
+        _, res = self._attached[pin]
+        self.write(pin, round((2**res - 1) * max(0.0, min(100.0, percent)) / 100.0))
+
+    def detach(self, pin: int) -> None:
+        self._b.request(C.PWM_DETACH, bytes([pin]))
+        self._attached.pop(pin, None)
+
+    def tone(self, pin: int, freq: int) -> None:
+        """Square wave at `freq` Hz (0 = off) — buzzer-friendly."""
+        self._b.request(C.PWM_TONE, struct.pack(">BI", pin, freq))
+
+    def servo(self, pin: int, angle: float, *, min_us: int = 500, max_us: int = 2500) -> None:
+        """Drive a hobby servo: 50 Hz, angle 0..180 mapped to min_us..max_us."""
+        if self._attached.get(pin) != (50, 14):
+            self.attach(pin, 50, 14)
+        us = min_us + (max_us - min_us) * max(0.0, min(180.0, angle)) / 180.0
+        self.write(pin, round(us / 20000.0 * (2**14 - 1)))