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

codex_usage_epd/cli.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""codex-usage-epd: fetch OpenAI Codex usage and push it to an e-paper display.
+
+Primary data source: OAuth `wham/usage` endpoint (see CodexBar).
+Display protocol is compatible with the EPD-nRF5 web client (RLE + bitplanes).
+
+Commands:
+  --selftest     render sample data + verify RLE round-trip (no network/BLE)
+  --dry-run      fetch + render preview.png, print summary (no BLE)
+  --once         fetch + render + push to display once
+  --loop         push every N minutes forever
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import time
+from pathlib import Path
+
+from .api import (
+    UsageFetchError,
+    build_usage_url,
+    fetch_usage,
+    parse_usage,
+    read_auth,
+    sample_balance,
+)
+from .ble import BlePushError, probe, push_display, test_screen
+from .config import expand_user, load_config
+from .render import image_to_planes, planes_to_rgb, render_dashboard, resolve_font_path
+from .token_usage import read_token_usage
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Codex usage -> e-paper display")
+    p.add_argument("--config", default=None, help="path to YAML config (default: repo config/ or bundled)")
+    p.add_argument("--debug", action="store_true", help="dump raw wham/usage JSON to tmp/usage_dump.json")
+    p.add_argument("--font", default=None, help="override render.font")
+    p.add_argument("--show-history", action=argparse.BooleanOptionalAction, default=None,
+                   help="show the Last 7 days token chart (overrides render.show_history)")
+    p.add_argument("--sample", action="store_true", help="use synthetic sample data (no network)")
+    p.add_argument("--force", action="store_true", help="with --init: overwrite an existing config")
+    g = p.add_mutually_exclusive_group()
+    g.add_argument("--init", action="store_true", help="generate a config from the template (no network/device)")
+    g.add_argument("--selftest", action="store_true", help="render sample data, no network/device")
+    g.add_argument("--dry-run", action="store_true", help="fetch + render preview.png, no BLE")
+    g.add_argument("--probe", action="store_true", help="connect + INIT, print device config/mtu, no image")
+    g.add_argument("--test-screen", action="store_true", help="INIT + CLEAR full refresh, check firmware path")
+    g.add_argument("--once", action="store_true", help="fetch + render + push once")
+    g.add_argument("--loop", action="store_true", help="push every N minutes forever")
+    return p.parse_args(argv)
+
+
+def load_balance(args: argparse.Namespace, cfg: dict) -> tuple:
+    """Return (balance, raw_dict_or_None)."""
+    codex = cfg["codex"]
+    auth_file = expand_user(codex["auth_file"])
+    access_token, account_id = read_auth(Path(auth_file))
+    url = build_usage_url(Path(auth_file).parent)
+    raw = fetch_usage(access_token, account_id, url, timeout=codex.get("timeout", 15.0))
+    if args.debug:
+        dump_dir = Path(__file__).resolve().parent.parent / "tmp"
+        dump_dir.mkdir(exist_ok=True)
+        dump_path = dump_dir / "usage_dump.json"
+        dump_path.write_text(json.dumps(raw, indent=2))
+        print(f"[debug] raw wham/usage JSON -> {dump_path}")
+    balance = parse_usage(raw)
+    balance.models, balance.daily_usage = read_token_usage(
+        Path(auth_file).parent, now=balance.fetched_at, limit=None,
+        history_days=7 if cfg["render"].get("show_history", False) else 0,
+    )
+    return balance, raw
+
+
+def render(balance, cfg: dict, font_path: str) -> tuple[bytes, bytes]:
+    render_cfg = cfg["render"]
+    img = render_dashboard(
+        balance,
+        font_path=font_path,
+        warn_threshold=render_cfg.get("warn_threshold", 20.0),
+        show_history=render_cfg.get("show_history", False),
+        width=cfg["display"]["width"],
+        height=cfg["display"]["height"],
+    )
+    preview = render_cfg.get("preview", "preview.png")
+    img.save(preview)
+    print(f"[render] saved {preview} ({img.size[0]}x{img.size[1]})")
+    return image_to_planes(img)
+
+
+def run_selftest(cfg: dict, font_path: str) -> int:
+    balance = sample_balance()
+    render_cfg = cfg["render"]
+    img = render_dashboard(
+        balance,
+        font_path=font_path,
+        warn_threshold=render_cfg.get("warn_threshold", 20.0),
+        show_history=render_cfg.get("show_history", False),
+        width=cfg["display"]["width"],
+        height=cfg["display"]["height"],
+    )
+    preview = render_cfg.get("preview", "preview.png")
+    img.save(preview)
+    bw, red = image_to_planes(img)
+    print(f"[selftest] rendered {img.size[0]}x{img.size[1]} -> {preview}")
+    print(f"[selftest] planes: bw={len(bw)}B red={len(red)}B")
+
+    # RLE round-trip: compress -> decompress == original, chunks self-contained
+    from .rle import _rle_decompressed, rle_chunks
+
+    chunk_size = 242  # MTU 247 - 5
+    for name, plane in (("bw", bw), ("red", red)):
+        chunks = rle_chunks(plane, chunk_size)
+        for i, ch in enumerate(chunks):
+            if len(ch) > chunk_size:
+                print(f"[selftest] FAIL chunk {name}[{i}] {len(ch)} > {chunk_size}")
+                return 1
+        joined = b"".join(chunks)
+        decoded = _rle_decompressed(joined, len(plane))
+        if decoded != plane:
+            print(f"[selftest] FAIL {name} RLE round-trip ({len(decoded)} != {len(plane)})")
+            return 1
+        print(f"[selftest] ok {name}: {len(plane)}B -> {len(joined)}B RLE in {len(chunks)} chunks")
+
+    # plane round-trip: every pure black/white/red pixel must decode back
+    back = planes_to_rgb(bw, red, img.size[0], img.size[1])
+    pa, pb = img.load(), back.load()
+    assert pa is not None and pb is not None
+    bad = 0
+    checked = 0
+    for yy in range(img.size[1]):
+        for xx in range(img.size[0]):
+            a = pa[xx, yy]
+            if a in ((0, 0, 0), (255, 255, 255), (255, 0, 0)):
+                checked += 1
+                if pb[xx, yy] != a:
+                    bad += 1
+    print(f"[selftest] pure-colour round-trip: {checked} px checked, {bad} wrong")
+    if bad == 0:
+        print("[selftest] PASS")
+        return 0
+    print("[selftest] FAIL: bitplane encode/decode mismatch")
+    return 1
+
+
+async def run_push(planes, cfg: dict) -> None:
+    ble = cfg["ble"]
+    display = cfg["display"]
+    await push_display(
+        planes,
+        model_id=int(display["model_id"]),
+        device=ble["device"],
+        mtu=int(ble.get("mtu", 247)),
+        scan_timeout=float(ble.get("scan_timeout", 10.0)),
+        scan_retries=int(ble.get("scan_retries", 3)),
+        interleave=int(ble.get("interleave", 50)),
+        sleep_after_push=bool(display.get("sleep_after_push", False)),
+        patch_wakeup_pin=bool(ble.get("patch_wakeup_pin", True)),
+        pacing_ms=float(ble.get("pacing_ms", 0.0)),
+        hold_after_refresh=float(ble.get("hold_after_refresh", 15.0)),
+        slot=ble.get("slot", 0),
+    )
+
+
+async def run_probe(cfg: dict) -> None:
+    ble = cfg["ble"]
+    display = cfg["display"]
+    await probe(
+        device=ble["device"],
+        model_id=int(display["model_id"]),
+        mtu=int(ble.get("mtu", 247)),
+        scan_timeout=float(ble.get("scan_timeout", 10.0)),
+        scan_retries=int(ble.get("scan_retries", 3)),
+    )
+
+
+async def run_test_screen(cfg: dict) -> None:
+    ble = cfg["ble"]
+    display = cfg["display"]
+    await test_screen(
+        device=ble["device"],
+        model_id=int(display["model_id"]),
+        mtu=int(ble.get("mtu", 247)),
+        scan_timeout=float(ble.get("scan_timeout", 10.0)),
+        scan_retries=int(ble.get("scan_retries", 3)),
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+
+    if args.init:
+        try:
+            from .config import init_config
+
+            dest = init_config(args.config, force=args.force)
+        except FileExistsError as e:
+            print(f"[error] {e}", file=sys.stderr)
+            return 1
+        print(f"[init] wrote {dest}")
+        return 0
+
+    cfg = load_config(args.config)
+    if args.show_history is not None:
+        cfg["render"]["show_history"] = args.show_history
+    print(f"[cfg] using {cfg['_path']}")
+
+    if args.selftest:
+        font_path = resolve_font_path(args.font or cfg["render"].get("font", ""))
+        return run_selftest(cfg, font_path)
+
+    if args.probe:
+        try:
+            asyncio.run(run_probe(cfg))
+            return 0
+        except BlePushError as e:
+            print(f"[error] {e}", file=sys.stderr)
+            return 1
+
+    if args.test_screen:
+        try:
+            asyncio.run(run_test_screen(cfg))
+            return 0
+        except BlePushError as e:
+            print(f"[error] {e}", file=sys.stderr)
+            return 1
+
+    def do_once() -> int:
+        if args.sample:
+            balance = sample_balance()
+            print("[fetch] using synthetic sample snapshot")
+        else:
+            balance, _raw = load_balance(args, cfg)
+            print("[fetch] usage snapshot:")
+        print(balance.summary())
+        font_path = resolve_font_path(args.font or cfg["render"].get("font", ""))
+        planes = render(balance, cfg, font_path)
+        if args.dry_run:
+            print("[dry-run] skipping BLE push")
+            return 0
+        asyncio.run(run_push(planes, cfg))
+        return 0
+
+    if args.dry_run or args.once:
+        try:
+            return do_once()
+        except (UsageFetchError, BlePushError) as e:
+            print(f"[error] {e}", file=sys.stderr)
+            return 1
+
+    if args.loop:
+        interval = int(cfg["schedule"].get("interval_minutes", 5)) * 60
+        print(f"[loop] pushing every {interval // 60} min (Ctrl-C to stop)")
+        while True:
+            try:
+                do_once()
+            except (UsageFetchError, BlePushError) as e:
+                print(f"[error] {e}", file=sys.stderr)
+            time.sleep(interval)
+        return 0
+
+    print("no action given (use --selftest / --probe / --dry-run / --once / --loop)", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex_usage_epd/codex_usage_epd.yaml.example

@@ -0,0 +1,30 @@
+display:
+  width: 400
+  height: 300
+  model_id: 0x02        # SSD1683/SSD1619 400x300 B/W/R
+  sleep_after_push: false   # web client never sends SLEEP; early sleep aborts refresh
+
+ble:
+  device: "auto"         # "auto" (scan NRF_EPD) | MAC address | name substring
+  mtu: 247
+  scan_timeout: 10       # seconds per scan attempt
+  scan_retries: 3        # retry the scan before giving up (missed adv packets)
+  interleave: 50         # match web client: 50 writes w/o response, then 1 with
+  patch_wakeup_pin: true
+  pacing_ms: 0.0         # no pacing (web client sends back-to-back)
+  hold_after_refresh: 20.0  # stay connected until panel busy refresh completes
+  slot: 0                # epdiy.cn slot firmware: image slot to write (0..N-1);
+                         # "auto" = first free slot; -1 / "none" = no SET_SLOT cmd
+
+codex:
+  auth_file: "~/.codex/auth.json"
+  timeout: 15
+
+render:
+  font: ""               # empty = auto-detect; or path to a .ttf
+  warn_threshold: 20     # remaining % below this renders the bar red
+  preview: "preview.png"
+  show_history: false    # opt in to the Last 7 days chart beside today's usage
+
+schedule:
+  interval_minutes: 60    # used by --loop; launchd uses its plist StartInterval

codex_usage_epd/config.py

@@ -0,0 +1,127 @@
+"""Config + CLI helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+DEFAULT_CONFIG_NAME = "codex_usage_epd.yaml"
+TEMPLATE_NAME = "codex_usage_epd.yaml.example"
+
+USER_CONFIG_DIR = "~/.config/codex-usage-epd"
+
+_DEFAULTS = {
+    "display": {
+        "width": 400,
+        "height": 300,
+        "model_id": 0x02,
+        "sleep_after_push": False,
+    },
+    "ble": {
+        "device": "auto",
+        "mtu": 247,
+        "scan_timeout": 10.0,
+        "scan_retries": 3,
+        "interleave": 50,
+        "patch_wakeup_pin": True,
+        "pacing_ms": 0.0,
+        "hold_after_refresh": 20.0,
+        "slot": 0,
+    },
+    "codex": {
+        "auth_file": "~/.codex/auth.json",
+        "timeout": 15.0,
+    },
+    "render": {
+        "font": "",
+        "warn_threshold": 20.0,
+        "preview": "preview.png",
+        "show_history": False,
+    },
+    "schedule": {
+        "interval_minutes": 5,
+    },
+}
+
+
+def _bundled_template_text() -> str:
+    repo = Path(__file__).resolve().parent.parent / "config" / TEMPLATE_NAME
+    if repo.exists():
+        return repo.read_text(encoding="utf-8")
+    import importlib.resources
+
+    res = importlib.resources.files("codex_usage_epd").joinpath(TEMPLATE_NAME)
+    return res.read_text(encoding="utf-8")
+
+
+def init_config(path: str | None = None, force: bool = False) -> str:
+    """Generate a real config file from the bundled template.
+
+    Defaults to <repo root>/config/codex_usage_epd.yaml when the repo checkout
+    is present, otherwise to ~/.config/codex-usage-epd/codex_usage_epd.yaml.
+    Refuses to overwrite an existing file unless force=True.
+    Returns the path written.
+    """
+    dest = _default_config_path(path)
+    if dest.exists() and not force:
+        raise FileExistsError(f"config already exists: {dest} (use --force to overwrite)")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(_bundled_template_text())
+    return str(dest)
+
+
+def _default_config_path(path: str | None) -> Path:
+    if path:
+        return Path(path)
+    repo = Path(__file__).resolve().parent.parent / "config" / DEFAULT_CONFIG_NAME
+    if repo.parent.exists():
+        return repo
+    return Path(USER_CONFIG_DIR).expanduser() / DEFAULT_CONFIG_NAME
+
+
+def load_config(path: str | None) -> dict:
+    import yaml
+
+    if path:
+        cfg_path = Path(path)
+        if not cfg_path.exists():
+            raise FileNotFoundError(f"config not found: {cfg_path}")
+    else:
+        # 1) repo checkout layout: <repo root>/config/codex_usage_epd.yaml
+        repo_cfg = Path(__file__).resolve().parent.parent / "config" / DEFAULT_CONFIG_NAME
+        # 2) installed package: ~/.config/codex-usage-epd/codex_usage_epd.yaml
+        user_cfg = Path(USER_CONFIG_DIR).expanduser() / DEFAULT_CONFIG_NAME
+        if repo_cfg.exists():
+            cfg_path = repo_cfg
+        elif user_cfg.exists():
+            cfg_path = user_cfg
+        else:
+            # 3) bundled template as the fallback default
+            return _merge(yaml.safe_load(_bundled_template_text()) or {}, f"<bundled>:{TEMPLATE_NAME}")
+    with cfg_path.open() as f:
+        user_cfg = yaml.safe_load(f) or {}
+    return _merge(user_cfg, str(cfg_path))
+
+
+def _merge(user_cfg: dict, src: str) -> dict:
+    merged = {}
+    for section, defaults in _DEFAULTS.items():
+        merged[section] = dict(defaults)
+        if isinstance(user_cfg.get(section), dict):
+            merged[section].update(user_cfg[section])
+
+    # top-level flat keys are accepted too
+    for key, value in user_cfg.items():
+        if key not in _DEFAULTS:
+            merged[key] = value
+
+    merged["_path"] = src
+    return merged
+
+
+def expand_user(text: str) -> str:
+    return str(Path(text).expanduser())
+
+
+def resolve_codex_home() -> Path:
+    override = __import__("os").environ.get("CODEX_HOME")
+    return Path(override) if override else Path.home() / ".codex"

codex_usage_epd/model.py

@@ -0,0 +1,73 @@
+"""Data model for Codex usage quota snapshots.
+
+Quota field names mirror the `wham/usage` payload decoded by CodexBar's
+CodexOAuthUsageFetcher. Per-model token totals come from today's local Codex
+session logs, like CodexBar's local token-history view.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+
+
+@dataclass
+class Window:
+    name: str  # window identity e.g. "five_hour", "weekly"
+    label: str  # short display label e.g. "5H", "WK"
+    used_percent: float  # 0..100 used
+    resets_at: int | None  # unix epoch seconds
+    limit_seconds: int | None
+    reset_after_seconds: int | None = None
+
+    @property
+    def remaining_percent(self) -> float:
+        return max(0.0, min(100.0, 100.0 - self.used_percent))
+
+
+@dataclass
+class ModelTokenUsage:
+    id: str  # e.g. "gpt-5.6-sol"
+    tokens: int
+
+
+@dataclass
+class DailyTokenUsage:
+    day: date
+    tokens: int
+
+
+@dataclass
+class Balance:
+    plan_type: str | None
+    windows: list[Window] = field(default_factory=list)  # global windows
+    models: list[ModelTokenUsage] = field(default_factory=list)  # all today's models, ranked
+    credits_balance: float | None = None
+    credits_unlimited: bool = False
+    has_credits: bool = False
+    fetched_at: datetime = field(default_factory=datetime.now)
+    source: str = "oauth"  # "oauth" | "sample"
+    daily_usage: list[DailyTokenUsage] = field(default_factory=list)
+
+    @property
+    def total_tokens_today(self) -> int:
+        return sum(model.tokens for model in self.models)
+
+    def window(self, name: str) -> Window | None:
+        for w in self.windows:
+            if w.name == name:
+                return w
+        return None
+
+    def summary(self) -> str:
+        lines = [f"plan: {self.plan_type}"]
+        for w in self.windows:
+            lines.append(f"  {w.name}: used {w.used_percent:.1f}% remaining {w.remaining_percent:.1f}%")
+        lines.append(f"  today Total: {self.total_tokens_today} tokens")
+        for m in self.models:
+            lines.append(f"  today {m.id}: {m.tokens} tokens")
+        for day in self.daily_usage:
+            lines.append(f"  {day.day.isoformat()}: {day.tokens} tokens")
+        if self.has_credits:
+            lines.append(f"  credits: balance={self.credits_balance} unlimited={self.credits_unlimited}")
+        return "\n".join(lines)