codex-usage-epd 2026.10.1__py3-none-any.whl

codex_usage_epd/__init__.py

@@ -0,0 +1,3 @@
+"""codex-usage-epd: push OpenAI Codex usage quota to a 4.2" e-paper display."""
+
+__version__ = "2026.10.1"

codex_usage_epd/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_usage_epd/api.py

@@ -0,0 +1,258 @@
+"""Fetch and parse OpenAI Codex usage from the OAuth `wham/usage` endpoint.
+
+Replicates CodexBar's CodexOAuthUsageFetcher behaviour:
+  - credentials come from ~/.codex/auth.json (tokens.access_token/account_id)
+  - base URL honours the `chatgpt_base_url` key in ~/.codex/config.toml
+  - endpoint: GET <base>/wham/usage   (or /api/codex/usage on custom bases)
+  - headers: Authorization: Bearer, User-Agent, Accept, ChatGPT-Account-Id
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:  # pragma: no cover
+    requests = None  # type: ignore[assignment]
+
+from .model import Balance, DailyTokenUsage, ModelTokenUsage, Window
+
+DEFAULT_CHATGPT_BASE = "https://chatgpt.com/backend-api/"
+USAGE_PATH = "/wham/usage"
+CODEX_USAGE_PATH = "/api/codex/usage"
+
+
+class UsageFetchError(Exception):
+    pass
+
+
+def codex_home() -> Path:
+    override = os_environ_get("CODEX_HOME")
+    if override:
+        return Path(override)
+    return Path.home() / ".codex"
+
+
+def os_environ_get(key: str, default: str = "") -> str:
+    import os
+
+    return os.environ.get(key, default)
+
+
+def read_auth(auth_file: Path) -> tuple[str, str | None]:
+    """Return (access_token, account_id) from ~/.codex/auth.json."""
+    if not auth_file.exists():
+        raise UsageFetchError(f"auth file not found: {auth_file}. Run `codex` to log in.")
+    try:
+        data = json.loads(auth_file.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        raise UsageFetchError(f"failed to decode {auth_file}: {e}") from e
+
+    tokens = data.get("tokens") or {}
+    access_token = tokens.get("access_token") or tokens.get("accessToken") or ""
+    if not access_token:
+        api_key = (data.get("OPENAI_API_KEY") or "").strip()
+        if api_key:
+            raise UsageFetchError(
+                "auth.json holds an API key, not an OAuth login. "
+                "`wham/usage` requires ChatGPT subscription auth (`codex login`)."
+            )
+        raise UsageFetchError(f"no access_token in {auth_file}")
+    account_id = tokens.get("account_id") or tokens.get("accountId") or None
+    return access_token, account_id
+
+
+def resolve_base_url(home: Path) -> str:
+    """Read chatgpt_base_url from config.toml (like CodexBar)."""
+    cfg = home / "config.toml"
+    if cfg.exists():
+        try:
+            for raw_line in cfg.read_text().splitlines():
+                line = raw_line.split("#", 1)[0].strip()
+                if not line:
+                    continue
+                if "=" in line:
+                    key, _, value = line.partition("=")
+                    if key.strip() == "chatgpt_base_url":
+                        value = value.strip().strip('"').strip("'").rstrip("/")
+                        if value:
+                            return value
+        except OSError:
+            pass
+    return DEFAULT_CHATGPT_BASE.rstrip("/")
+
+
+def build_usage_url(home: Path) -> str:
+    base = resolve_base_url(home)
+    path = USAGE_PATH if base.endswith("/backend-api") else CODEX_USAGE_PATH
+    return base + path
+
+
+def fetch_usage(access_token: str, account_id: str | None, url: str, timeout: float = 15.0,
+                attempts: int = 3) -> dict:
+    if requests is None:
+        raise UsageFetchError("requests is required. Install with: pip install requests")
+
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "User-Agent": "codex-usage-epd/0.1",
+        "Accept": "application/json",
+        "Origin": "https://chatgpt.com",
+        "Referer": "https://chatgpt.com/",
+    }
+    if account_id:
+        headers["ChatGPT-Account-Id"] = account_id
+
+    last_err: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            resp = requests.get(url, headers=headers, timeout=timeout)  # type: ignore[name-defined]
+        except Exception as e:  # network / TLS errors -> retry with backoff
+            last_err = e
+            if attempt < attempts:
+                import time
+
+                time.sleep(1.5 * attempt)
+                continue
+            raise UsageFetchError(f"network error: {e}") from e
+
+        if resp.status_code in (401, 403):
+            raise UsageFetchError(
+                f"HTTP {resp.status_code}: token expired/invalid. Run `codex` to re-authenticate."
+            )
+        if resp.status_code != 200:
+            raise UsageFetchError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            return resp.json()
+        except ValueError as e:
+            raise UsageFetchError(f"invalid JSON response: {e}") from e
+    raise UsageFetchError(f"network error: {last_err}")  # pragma: no cover
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+def _to_float(value) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _to_int(value) -> int | None:
+    f = _to_float(value)
+    return int(f) if f is not None else None
+
+
+def _window(raw, name: str, label: str) -> Window | None:
+    if not isinstance(raw, dict):
+        return None
+    used = _to_float(raw.get("used_percent"))
+    if used is None:
+        used = 0.0
+    return Window(
+        name=name,
+        label=label,
+        used_percent=used,
+        resets_at=_to_int(raw.get("reset_at")) or _to_int(raw.get("resets_at")),
+        limit_seconds=_to_int(raw.get("limit_window_seconds")),
+        reset_after_seconds=_to_int(raw.get("reset_after_seconds")),
+    )
+
+
+def _name_for_window(reset_at: int | None, limit_seconds: int | None) -> str:
+    # wham/usage windows have no "name" field; infer from duration.
+    if limit_seconds:
+        if limit_seconds == 5 * 3600:
+            return "five_hour"
+        if limit_seconds == 7 * 24 * 3600:
+            return "weekly"
+        if limit_seconds == 30 * 24 * 3600:
+            return "thirty_day"
+        return f"win_{limit_seconds // 60}m"
+    return "window"
+
+
+def _windows_from_rate_limit(rate: dict) -> list[Window]:
+    out: list[Window] = []
+    pw = _window(rate.get("primary_window"), "five_hour", "5H")
+    sw = _window(rate.get("secondary_window"), "weekly", "WK")
+    if pw:
+        pw.name = _name_for_window(pw.resets_at, pw.limit_seconds)
+        pw.label = _label_for(pw.name)
+        out.append(pw)
+    if sw:
+        sw.name = _name_for_window(sw.resets_at, sw.limit_seconds)
+        sw.label = _label_for(sw.name)
+        out.append(sw)
+    return out
+
+
+def _label_for(name: str) -> str:
+    return {
+        "five_hour": "5H",
+        "weekly": "WK",
+        "thirty_day": "30D",
+    }.get(name, name.upper()[:3])
+
+
+def parse_usage(raw: dict) -> Balance:
+    plan_type = raw.get("plan_type") or None
+
+    credits_raw = raw.get("credits")
+    has_credits = False
+    credits_unlimited = False
+    credits_balance = None
+    if isinstance(credits_raw, dict):
+        has_credits = bool(credits_raw.get("has_credits", False))
+        credits_unlimited = bool(credits_raw.get("unlimited", False))
+        credits_balance = _to_float(credits_raw.get("balance"))
+
+    rate = raw.get("rate_limit") or {}
+    windows = _windows_from_rate_limit(rate) if isinstance(rate, dict) else []
+
+    return Balance(
+        plan_type=plan_type,
+        windows=windows,
+        credits_balance=credits_balance,
+        credits_unlimited=credits_unlimited,
+        has_credits=has_credits,
+        source="oauth",
+    )
+
+
+def sample_balance() -> Balance:
+    """Synthetic snapshot used by --selftest (no network / no device)."""
+    local_now = datetime.now().astimezone()
+    now = int(local_now.timestamp())
+    return Balance(
+        plan_type="plus",
+        windows=[
+            Window("five_hour", "5H", used_percent=17.0, resets_at=now + 3600, limit_seconds=5 * 3600, reset_after_seconds=3600),
+            Window("weekly", "WK", used_percent=36.0, resets_at=now + 3 * 86400, limit_seconds=7 * 86400, reset_after_seconds=3 * 86400),
+        ],
+        models=[
+            ModelTokenUsage("gpt-5.6-sol", 12_840_000),
+            ModelTokenUsage("gpt-6-astra", 6_275_000),
+            ModelTokenUsage("gpt-5.6-luna", 925_000),
+        ],
+        has_credits=False,
+        source="sample",
+        daily_usage=[
+            DailyTokenUsage(local_now.date() - timedelta(days=7 - i), tokens)
+            for i, tokens in enumerate([8_200_000, 12_500_000, 0, 9_700_000, 18_300_000, 14_100_000, 22_600_000])
+        ],
+        fetched_at=local_now,
+    )

codex_usage_epd/ble.py

@@ -0,0 +1,345 @@
+"""BLE push of the two bitplanes to an EPD-nRF5 device.
+
+Protocol (EPD-nRF5/EPD/EPD_service.c + html/js/main.js):
+  - service 62750001-d828-918d-fb46-b6c11c675aec, char 62750002
+  - after connecting, subscribe to notifications (CCCD write w/ response),
+    then INIT 0x01 [model_id] w/ response; the device replies with the epd
+    config, then "mtu=244 rle=1" and "t=..."
+  - WRITE_IMG 0x30 [flags] [payload]   flags: bit0=1 red plane, bit1=1 first
+    chunk (begin), bit2=1 RLE-encoded payload
+  - REFRESH 0x05, SLEEP 0x06 (w/ response)
+  - chunk size = (max_data_len - 2); the device reports max_data_len = MTU - 3.
+
+Slot firmware (epdiy.cn web client) adds:
+  - SET_SLOT 0x31 [action, slot]  action=0 select write slot, action=1 display
+  - device announces "slots=<count> <usedMask> [selected]" (usedMask decimal)
+    after connecting; sending SET_SLOT [0, slot] before INIT routes WRITE_IMG
+    into that slot.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+
+from .rle import raw_chunks, rle_chunks
+
+BLE_EPD_SVC = "62750001-d828-918d-fb46-b6c11c675aec"
+BLE_EPD_CHAR = "62750002-d828-918d-fb46-b6c11c675aec"
+
+CMD_INIT = 0x01
+CMD_CLEAR = 0x02
+CMD_REFRESH = 0x05
+CMD_SLEEP = 0x06
+CMD_WRITE_IMG = 0x30
+CMD_SET_SLOT = 0x31
+CMD_SET_CONFIG = 0x90
+
+DEFAULT_DEVICE_NAME = "NRF_EPD"
+_MTU_RE = re.compile(rb"mtu=(\d+)")
+_SLOTS_RE = re.compile(rb"slots=(\d+)\s+(\d+|0x[0-9A-Fa-f]+)(?:\s+(-?\d+))?")
+
+
+class BlePushError(Exception):
+    pass
+
+
+async def _resolve_device(device: str, scan_timeout: float, scan_retries: int = 3) -> str:
+    if device.lower() != "auto":
+        return device  # caller passes a concrete address or name substring
+    from bleak import BleakScanner
+
+    print(f"[ble] scanning for '{DEFAULT_DEVICE_NAME}' ...")
+    seen: dict[str, str] = {}
+    for attempt in range(1, max(1, scan_retries) + 1):
+        if attempt > 1:
+            print(f"[ble] scan attempt {attempt}/{scan_retries} ...")
+        target: asyncio.Future[tuple[str, str]] = asyncio.get_running_loop().create_future()
+
+        def _cb(device_, _adv, target=target):
+            if device_.name:
+                seen[device_.address] = device_.name
+            if device_.name and DEFAULT_DEVICE_NAME in device_.name and not target.done():
+                target.set_result((device_.name, device_.address))
+
+        try:
+            async with BleakScanner(detection_callback=_cb):
+                name, address = await asyncio.wait_for(target, timeout=scan_timeout)
+        except asyncio.TimeoutError:
+            continue
+        print(f"[ble] found {name} @ {address}")
+        return address
+
+    names = [f"{n} {a}" for a, n in seen.items()]
+    raise BlePushError(
+        f"no '{DEFAULT_DEVICE_NAME}' device found after {max(1, scan_retries)} scans. seen: {names}"
+    )
+
+
+async def _request_mtu(client, mtu: int) -> None:
+    # bleak 3.x dropped request_mtu on some backends (macOS/CB negotiates MTU
+    # automatically); call it only when the backend exposes it.
+    request_mtu = getattr(client, "request_mtu", None)
+    if request_mtu is None:
+        return
+    try:
+        await request_mtu(mtu)
+    except Exception as exc:  # noqa: BLE001 — backend may not support MTU exchange
+        print(f"[ble] request_mtu skipped: {exc}")
+
+
+class _Notifier:
+    """Synchronous notify callback (bleak 3.x callbacks are sync)."""
+
+    def __init__(self) -> None:
+        self.config: bytes | None = None
+        self.mtu: int | None = None
+        self.messages: list[str] = []
+        self.slots_count: int = 0
+        self.slots_used_mask: int = 0
+        self.slots_selected: int | None = None
+
+    def __call__(self, _characteristic: object, data: bytearray) -> None:
+        blob = bytes(data)
+        if self.config is None and len(blob) >= 11 and not blob.startswith((b"mtu=", b"t=", b"slots=")):
+            self.config = blob
+        m = _MTU_RE.search(blob)
+        if m:
+            self.mtu = int(m.group(1))
+        sm = _SLOTS_RE.search(blob)
+        if sm:
+            self.slots_count = int(sm.group(1))
+            mask = sm.group(2).decode(errors="replace")
+            self.slots_used_mask = int(mask, 16) if mask.lower().startswith("0x") else int(mask, 10)
+            self.slots_selected = int(sm.group(3)) if sm.group(3) else None
+        if blob.startswith((b"mtu=", b"t=", b"slots=")):
+            self.messages.append(blob.decode(errors="replace"))
+
+
+def _config_bytes_to_str(cfg: bytes) -> str:
+    if len(cfg) < 11:
+        return cfg.hex()
+    names = ["mosi", "sclk", "cs", "dc", "rst", "busy", "bs", "model", "wakeup", "led", "en"]
+    return ", ".join(f"{names[i]}={cfg[i]:#04x}" for i in range(11))
+
+
+def _resolve_slot(slot_cfg, notifier: _Notifier) -> int | None:
+    """Map the configured ``slot`` to a concrete slot index to write into.
+
+    - ``None`` / ``"none"`` / ``-1`` -> no SET_SLOT command (raw behaviour)
+    - ``int >= 0``                   -> that exact slot
+    - ``"auto"``                     -> first free slot per the device's
+                                        usedMask; falls back to the currently
+                                        selected slot, then slot 0
+    Returns ``None`` (no slot command) when the device does not advertise
+    slot support and the caller asked for ``"auto"``.
+    """
+    if slot_cfg is None:
+        return None
+    if isinstance(slot_cfg, str):
+        s = slot_cfg.strip().lower()
+        if s in ("none", "off", "disabled"):
+            return None
+        if s == "auto":
+            count = notifier.slots_count or 0
+            if count <= 0:
+                return None
+            mask = notifier.slots_used_mask or 0
+            for i in range(count):
+                if not (mask >> i) & 1:
+                    return i
+            cur = notifier.slots_selected
+            return cur if cur is not None and 0 <= cur < count else 0
+        try:
+            slot_cfg = int(s)
+        except ValueError:
+            raise BlePushError(f"invalid ble.slot value: {slot_cfg!r}")
+    slot_idx = int(slot_cfg)
+    if slot_idx < 0:
+        return None
+    if notifier.slots_count and slot_idx >= notifier.slots_count:
+        print(f"[ble] warning: slot {slot_idx} >= device slot count {notifier.slots_count}")
+    return slot_idx
+
+
+async def probe(
+    device: str,
+    model_id: int,
+    mtu: int,
+    scan_timeout: float,
+    scan_retries: int = 3,
+) -> None:
+    """Connect, subscribe, INIT, and report what the device says."""
+    from bleak import BleakClient
+
+    address = await _resolve_device(device, scan_timeout, scan_retries)
+    notifier = _Notifier()
+    async with BleakClient(address, timeout=30) as client:
+        await _request_mtu(client, mtu)
+        await client.start_notify(BLE_EPD_CHAR, notifier)
+        print(f"[probe] connected to {address}")
+        print(f"[probe] negotiated mtu: {getattr(client, 'mtu_size', '?')}")
+        try:
+            version_char = client.services.get_characteristic("62750003-d828-918d-fb46-b6c11c675aec")
+            if version_char:
+                ver = await client.read_gatt_char(version_char)
+                print(f"[probe] firmware version: 0x{ver[0]:02x}")
+        except Exception:  # noqa: BLE001, S110 — version characteristic is optional
+            pass
+        await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_INIT, model_id & 0xFF]), response=True)
+        deadline = time.monotonic() + 2.0
+        while time.monotonic() < deadline and notifier.mtu is None:
+            await asyncio.sleep(0.05)
+        if notifier.config is not None:
+            print(f"[probe] epd config: {_config_bytes_to_str(notifier.config)}")
+        print(f"[probe] mtu reported by device: {notifier.mtu}")
+        for msg in notifier.messages:
+            print(f"[probe] device: {msg}")
+
+
+async def test_screen(
+    device: str,
+    model_id: int,
+    mtu: int,
+    scan_timeout: float,
+    scan_retries: int = 3,
+) -> None:
+    """Minimal firmware path check: INIT + CLEAR(with refresh). The screen
+    should flash to white and the REFRESH inside CLEAR should block a few
+    seconds (busy wait), proving the EPD driver is bound and commands work."""
+    from bleak import BleakClient
+
+    address = await _resolve_device(device, scan_timeout, scan_retries)
+    notifier = _Notifier()
+    async with BleakClient(address, timeout=30) as client:
+        await _request_mtu(client, mtu)
+        await client.start_notify(BLE_EPD_CHAR, notifier)
+        t0 = time.monotonic()
+        await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_INIT, model_id & 0xFF]), response=True)
+        print(f"[test] INIT done in {time.monotonic() - t0:.2f}s")
+        t1 = time.monotonic()
+        await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_CLEAR]), response=True)
+        print(f"[test] CLEAR (full refresh) done in {time.monotonic() - t1:.2f}s")
+        print(f"[test] mtu reported: {notifier.mtu}")
+
+
+async def push_display(
+    planes: tuple[bytes, bytes],
+    model_id: int,
+    device: str,
+    mtu: int = 247,
+    scan_timeout: float = 10.0,
+    scan_retries: int = 3,
+    interleave: int = 50,
+    sleep_after_push: bool = False,
+    patch_wakeup_pin: bool = True,
+    pacing_ms: float = 0.0,
+    hold_after_refresh: float = 15.0,
+    slot: int | str | None = None,
+) -> None:
+    """Mirror the proven-good web client sequence (html/js/main.js sendimg).
+
+    Order matters: INIT [0x01] (no model byte; firmware falls back to the
+    stored config.model_id) -> WRITE_IMG chunks (RLE, interleave write/response)
+    -> REFRESH -> stay connected while the panel finishes its busy refresh.
+    The web client never sends SLEEP and does not disconnect during refresh;
+    sending SLEEP or dropping the link mid-refresh aborts the image.
+
+    On slot firmware (epdiy.cn) a ``SET_SLOT [0, slot]`` is sent before INIT,
+    exactly like the web client, so WRITE_IMG lands in the chosen slot instead
+    of overwriting whatever slot the device currently has selected.
+    """
+    from bleak import BleakClient
+
+    address = await _resolve_device(device, scan_timeout, scan_retries)
+    notifier = _Notifier()
+
+    async with BleakClient(address, timeout=30) as client:
+        await _request_mtu(client, mtu)
+        await client.start_notify(BLE_EPD_CHAR, notifier)
+
+        # "auto" needs the device's slot announcement before picking a free slot
+        if isinstance(slot, str) and slot.strip().lower() == "auto":
+            deadline = time.monotonic() + 2.0
+            while time.monotonic() < deadline and notifier.slots_count == 0:
+                await asyncio.sleep(0.05)
+        use_slot = _resolve_slot(slot, notifier)
+        if use_slot is not None:
+            occupied = bool(notifier.slots_count and (notifier.slots_used_mask >> use_slot) & 1)
+            print(
+                f"[ble] SET_SLOT write slot {use_slot}"
+                + (" (occupied, will overwrite)" if occupied else "")
+            )
+            await client.write_gatt_char(
+                BLE_EPD_CHAR, bytes([CMD_SET_SLOT, 0x00, use_slot & 0xFF]), response=True
+            )
+
+        # INIT without a model byte, exactly like the web client. The device
+        # replies with the epd config + "mtu=<n> rle=1" + "t=<unix>".
+        t0 = time.monotonic()
+        await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_INIT]), response=True)
+        deadline = time.monotonic() + 2.0
+        while time.monotonic() < deadline and notifier.mtu is None:
+            await asyncio.sleep(0.05)
+        print(f"[ble] INIT + mtu wait: {time.monotonic() - t0:.2f}s")
+        if notifier.config is not None:
+            print(f"[ble] epd config: {_config_bytes_to_str(notifier.config)}")
+        if notifier.slots_count:
+            print(
+                f"[ble] device slots: count={notifier.slots_count} "
+                f"used=0x{notifier.slots_used_mask:x} selected={notifier.slots_selected}"
+            )
+        for msg in notifier.messages:
+            print(f"[ble] device: {msg}")
+
+        negotiated = getattr(client, "mtu_size", 0) or 23
+        max_data_len = notifier.mtu or (negotiated - 3)
+        chunk_size = max_data_len - 2
+        if chunk_size < 8:
+            raise BlePushError(f"max data len too small for transfers: {max_data_len}")
+        print(f"[ble] negotiated mtu={negotiated} device max_data_len={max_data_len} chunk={chunk_size}B")
+
+        # if configured, force wakeup_pin=0xFF so the device keeps re-advertising
+        if patch_wakeup_pin and notifier.config and len(notifier.config) >= 11 and notifier.config[8] != 0xFF:
+                patched = bytearray(notifier.config[:11])
+                patched[8] = 0xFF
+                print("[ble] patching config wakeup_pin -> 0xFF")
+                await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_SET_CONFIG]) + bytes(patched), response=True)
+                await asyncio.sleep(0.1)
+
+        for red_plane, plane_bytes in enumerate(planes):
+            compressed = rle_chunks(plane_bytes, chunk_size)
+            use_rle = sum(len(c) for c in compressed) < len(plane_bytes)
+            chunks = compressed if use_rle else raw_chunks(plane_bytes, chunk_size)
+            print(
+                f"[ble] {'red ' if red_plane else 'black'} plane "
+                f"{len(plane_bytes)}B -> {len(chunks)} chunks "
+                f"({'RLE' if use_rle else 'raw'})"
+            )
+            for i, chunk in enumerate(chunks):
+                flags = 0x00
+                if red_plane:
+                    flags |= 0x01
+                if i == 0:
+                    flags |= 0x02  # begin
+                if use_rle:
+                    flags |= 0x04
+                msg = bytes([CMD_WRITE_IMG, flags]) + chunk
+                response = (i % (interleave + 1)) == 0
+                await client.write_gatt_char(BLE_EPD_CHAR, msg, response=response)
+                if pacing_ms:
+                    await asyncio.sleep(pacing_ms / 1000.0)
+
+        # REFRESH without response: the firmware blocks in SSD16xx_WaitBusy
+        # while the panel refreshes, so a write-with-response would just sit
+        # waiting for an ATT ack the device only sends after the busy-wait
+        # finishes. Fire-and-forget, then hold the connection open long enough
+        # for the panel to finish; the firmware sleeps the panel on disconnect
+        # and would abort a mid-flight refresh.
+        await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_REFRESH]), response=False)
+        print(f"[ble] REFRESH sent (no-response), holding {hold_after_refresh}s for panel refresh...")
+        await asyncio.sleep(hold_after_refresh)
+        if sleep_after_push:
+            await client.write_gatt_char(BLE_EPD_CHAR, bytes([CMD_SLEEP]), response=True)
+            print("[ble] display sleeping")