matebot 0.2.0__py3-none-any.whl

matebot/slog.py

@@ -0,0 +1,225 @@
+"""Decoder for GaggiMate binary shot logs (``.slog``) and the shot index (``index.bin``).
+
+Format reference: ``src/display/models/shot_log_format.h`` in the GaggiMate
+firmware (format v5, little-endian throughout). Older versions carry fewer
+sample fields; ``fieldsMask`` says which are present, always in the fixed
+order below.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import struct
+from dataclasses import dataclass, field
+
+SHOT_MAGIC = 0x544F4853  # "SHOT"
+INDEX_MAGIC = 0x58444953  # "SIDX"
+
+# (key, struct char, divisor) in fieldsMask bit order 0..12.
+SAMPLE_FIELDS = [
+    ("t", "H", None),  # sample tick; seconds = t * sampleInterval / 1000
+    ("tt", "H", 10),  # target temp °C
+    ("ct", "H", 10),  # current temp °C
+    ("tp", "H", 10),  # target pressure bar
+    ("cp", "H", 10),  # current pressure bar
+    ("fl", "h", 100),  # pump flow ml/s
+    ("tf", "h", 100),  # target flow ml/s
+    ("pf", "h", 100),  # puck flow ml/s
+    ("vf", "h", 100),  # bluetooth-scale flow ml/s
+    ("v", "H", 10),  # bluetooth weight g
+    ("ev", "H", 10),  # estimated weight g
+    ("pr", "H", 100),  # puck resistance
+    ("si", "H", None),  # system info bitfield
+]
+
+# ShotIndexEntry.flags
+FLAG_COMPLETED = 0x01
+FLAG_DELETED = 0x02
+FLAG_HAS_NOTES = 0x04
+
+
+class SlogError(ValueError):
+    """Raised when input bytes are not a valid shot log / index."""
+
+
+def _cstr(raw: bytes) -> str:
+    return raw.split(b"\0", 1)[0].decode("utf-8", errors="replace")
+
+
+@dataclass
+class PhaseTransition:
+    sample_index: int
+    phase_number: int
+    name: str
+
+
+@dataclass
+class Shot:
+    version: int
+    sample_interval_ms: int
+    fields_mask: int
+    sample_count: int
+    duration_ms: int
+    start_epoch: int
+    profile_id: str
+    profile_name: str
+    final_weight_g: float
+    phases: list[PhaseTransition] = field(default_factory=list)
+    # column-oriented: {"t": [...], "ct": [...], ...} only for fields present in fields_mask
+    series: dict[str, list[float]] = field(default_factory=dict)
+
+    @property
+    def times_s(self) -> list[float]:
+        step = self.sample_interval_ms / 1000.0
+        return [t * step for t in self.series.get("t", [])]
+
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "sample_interval_ms": self.sample_interval_ms,
+            "sample_count": self.sample_count,
+            "duration_ms": self.duration_ms,
+            "start_epoch": self.start_epoch,
+            "profile_id": self.profile_id,
+            "profile_name": self.profile_name,
+            "final_weight_g": self.final_weight_g,
+            "phases": [
+                {"sample_index": p.sample_index, "phase": p.phase_number, "name": p.name}
+                for p in self.phases
+            ],
+            "series": self.series,
+        }
+
+    def to_json(self, **kwargs) -> str:
+        return json.dumps(self.to_dict(), **kwargs)
+
+    def to_csv(self) -> str:
+        keys = [k for k, _, _ in SAMPLE_FIELDS if k in self.series]
+        out = io.StringIO()
+        w = csv.writer(out)
+        w.writerow(["time_s", *keys])
+        step = self.sample_interval_ms / 1000.0
+        for i in range(len(self.series.get("t", []))):
+            w.writerow([self.series["t"][i] * step, *(self.series[k][i] for k in keys)])
+        return out.getvalue()
+
+
+@dataclass
+class IndexEntry:
+    id: int
+    timestamp: int
+    duration_ms: int
+    volume_g: float
+    rating: int
+    flags: int
+    profile_id: str
+    profile_name: str
+
+    @property
+    def completed(self) -> bool:
+        return bool(self.flags & FLAG_COMPLETED)
+
+    @property
+    def deleted(self) -> bool:
+        return bool(self.flags & FLAG_DELETED)
+
+    @property
+    def has_notes(self) -> bool:
+        return bool(self.flags & FLAG_HAS_NOTES)
+
+    @property
+    def padded_id(self) -> str:
+        return f"{self.id:06d}"
+
+
+@dataclass
+class ShotIndex:
+    version: int
+    next_id: int
+    entries: list[IndexEntry]
+
+
+def parse_slog(data: bytes) -> Shot:
+    """Parse a .slog file. Raises SlogError on anything that isn't one.
+
+    Tolerates truncated sample sections (crash during recording): decodes as
+    many complete samples as are actually present.
+    """
+    if len(data) < 24 or struct.unpack_from("<I", data, 0)[0] != SHOT_MAGIC:
+        raise SlogError("not a shot log (missing SHOT magic)")
+
+    version, _sample_size, header_size, interval, _res1 = struct.unpack_from("<BBHHH", data, 4)
+    fields_mask, sample_count, duration_ms, start_epoch = struct.unpack_from("<IIII", data, 12)
+    if header_size < 108 or header_size > len(data):
+        raise SlogError(f"implausible headerSize {header_size}")
+    profile_id = _cstr(data[28:60])
+    profile_name = _cstr(data[60:108])
+    (final_weight,) = struct.unpack_from("<H", data, 108)
+
+    phases: list[PhaseTransition] = []
+    if version >= 5 and header_size >= 459:
+        count = data[458]
+        for i in range(min(count, 12)):
+            off = 110 + i * 29
+            idx, num = struct.unpack_from("<HB", data, off)
+            phases.append(PhaseTransition(idx, num, _cstr(data[off + 4 : off + 29])))
+
+    present = [(k, c, d) for bit, (k, c, d) in enumerate(SAMPLE_FIELDS) if fields_mask & (1 << bit)]
+    fmt = "<" + "".join(c for _, c, _ in present)
+    size = struct.calcsize(fmt)
+    body = data[header_size:]
+    n_available = len(body) // size if size else 0
+    n = min(sample_count, n_available) if sample_count else n_available
+
+    series: dict[str, list[float]] = {k: [] for k, _, _ in present}
+    for values in struct.iter_unpack(fmt, body[: n * size]):
+        for (k, _, div), v in zip(present, values, strict=True):
+            series[k].append(v / div if div else v)
+
+    return Shot(
+        version=version,
+        sample_interval_ms=interval or 250,
+        fields_mask=fields_mask,
+        sample_count=n,
+        duration_ms=duration_ms,
+        start_epoch=start_epoch,
+        profile_id=profile_id,
+        profile_name=profile_name,
+        final_weight_g=final_weight / 10.0,
+        phases=phases,
+        series=series,
+    )
+
+
+def parse_index(data: bytes) -> ShotIndex:
+    """Parse /h/index.bin."""
+    if len(data) < 32 or struct.unpack_from("<I", data, 0)[0] != INDEX_MAGIC:
+        raise SlogError("not a shot index (missing SIDX magic)")
+    version, entry_size, entry_count, next_id = struct.unpack_from("<HHII", data, 4)
+    if entry_size < 96:
+        raise SlogError(f"implausible entrySize {entry_size}")
+    entries = []
+    for i in range(entry_count):
+        off = 32 + i * entry_size
+        if off + entry_size > len(data):
+            break  # truncated index
+        sid, ts, dur, vol, rating, flags = struct.unpack_from("<IIIHBB", data, off)
+        entries.append(
+            IndexEntry(
+                id=sid,
+                timestamp=ts,
+                duration_ms=dur,
+                volume_g=vol / 10.0,
+                rating=rating,
+                flags=flags,
+                profile_id=_cstr(data[off + 16 : off + 48]),
+                profile_name=_cstr(data[off + 48 : off + 96]),
+            )
+        )
+    return ShotIndex(version=version, next_id=next_id, entries=entries)
+
+
+def is_slog(data: bytes) -> bool:
+    return len(data) >= 4 and struct.unpack_from("<I", data, 0)[0] == SHOT_MAGIC

matebot/state.py

@@ -0,0 +1,42 @@
+"""Tiny atomic JSON state file (questionnaire defaults + resume data)."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+class State:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self._data: dict[str, Any] = {}
+        if self.path.exists():
+            try:
+                self._data = json.loads(self.path.read_text())
+            except (json.JSONDecodeError, OSError):
+                self._data = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+        self._flush()
+
+    def update(self, **kwargs: Any) -> None:
+        self._data.update(kwargs)
+        self._flush()
+
+    def _flush(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self.path.parent, prefix=".state-")
+        try:
+            with os.fdopen(fd, "w") as fh:
+                json.dump(self._data, fh, indent=1)
+            os.replace(tmp, self.path)
+        except BaseException:
+            os.unlink(tmp)
+            raise

matebot/sync.py

@@ -0,0 +1,163 @@
+"""Keep a git-backed shot journal in sync with the machine.
+
+Layout of the data repo (created on first sync if missing):
+    shots/NNNNNN.slog + NNNNNN.json   raw shot logs + notes
+    profiles/<label>.json             brew profiles
+    settings.json                     machine settings (credentials redacted)
+    docs/                             generated shot-explorer site (GitHub Pages)
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import logging
+import re
+import subprocess
+from pathlib import Path
+
+import aiohttp
+
+from .machine import GaggiMateClient, MachineError
+from .sitegen import generate
+
+log = logging.getLogger(__name__)
+
+
+class SyncConflict(RuntimeError):
+    """Manual edits conflict with the incoming sync; resolve by hand."""
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args], capture_output=True, text=True, check=False
+    )
+
+
+def _safe_name(label: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._ -]", "_", label).strip() or "unnamed"
+
+
+async def sync(
+    client: GaggiMateClient, repo: str | Path, *, site_title: str = "Shot Journal"
+) -> bool:
+    """Pull, mirror machine state into the repo, regenerate site, commit, push.
+
+    Returns True if a commit was pushed. Raises SyncConflict on rebase conflict.
+    Needs a live client session; profile export additionally needs the WS
+    connection (skipped gracefully when the socket is down).
+    """
+    repo = Path(repo)
+    shots_dir = repo / "shots"
+    shots_dir.mkdir(parents=True, exist_ok=True)
+
+    with open(repo / ".matebot.lock", "w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            log.info("another sync is running; skipping")
+            return False
+
+        if (repo / ".git").exists() and _git(repo, "remote").stdout.strip():
+            pull = _git(repo, "pull", "--rebase", "--autostash")
+            if pull.returncode != 0:
+                _git(repo, "rebase", "--abort")
+                raise SyncConflict(pull.stderr.strip()[-500:])
+
+        # quarantine legacy corrupted notes first (SPA-fallback downloads, see machine.py)
+        for p in shots_dir.glob("*.json"):
+            if not p.read_bytes().lstrip().startswith(b"{"):
+                log.warning("quarantining corrupt notes file %s", p.name)
+                p.rename(p.with_suffix(".json.corrupt"))
+
+        # --- shots ---
+        index = await client.fetch_index()
+        for entry in index.entries:
+            if entry.deleted or not entry.completed:
+                continue
+            slog_path = shots_dir / f"{entry.padded_id}.slog"
+            if not slog_path.exists():
+                try:
+                    slog_path.write_bytes(await client.fetch_slog(entry.id))
+                    log.info("downloaded shot %s", entry.padded_id)
+                except MachineError as exc:
+                    log.warning("%s", exc)
+                    continue
+            notes_path = shots_dir / f"{entry.padded_id}.json"
+            if entry.has_notes or not notes_path.exists():
+                notes = await client.fetch_notes(entry.id)
+                if notes is not None:
+                    new = json.dumps(notes, indent=1).encode()
+                    if not notes_path.exists() or notes_path.read_bytes() != new:
+                        notes_path.write_bytes(new)
+
+        # --- profiles + settings (best effort) ---
+        try:
+            profiles = await client.profiles_list()
+            pdir = repo / "profiles"
+            pdir.mkdir(exist_ok=True)
+            for prof in profiles:
+                (pdir / f"{_safe_name(prof.get('label', 'unnamed'))}.json").write_text(
+                    json.dumps(prof, indent=2, sort_keys=True)
+                )
+        except MachineError as exc:
+            log.info("profiles skipped (%s)", exc)
+        try:
+            settings = await client.fetch_settings(redact=True)
+            (repo / "settings.json").write_text(json.dumps(settings, indent=2, sort_keys=True))
+        except Exception as exc:  # noqa: BLE001
+            log.info("settings skipped (%s)", exc)
+
+        # --- site ---
+        generate(shots_dir, repo / "docs", title=site_title)
+
+        # --- commit + push ---
+        if not (repo / ".git").exists():
+            _git(repo, "init", "-b", "main")
+        _git(repo, "add", "-A")
+        if not _git(repo, "status", "--porcelain").stdout.strip():
+            log.info("nothing to commit")
+            return False
+        latest = max((e.id for e in index.entries), default=0)
+        commit = _git(repo, "commit", "-m", f"sync: through shot {latest:06d}")
+        if commit.returncode != 0:
+            log.error("commit failed: %s", commit.stderr.strip())
+            return False
+        if _git(repo, "remote").stdout.strip():
+            push = _git(repo, "push")
+            if push.returncode != 0:
+                log.error("push failed: %s", push.stderr.strip()[-300:])
+        return True
+
+
+async def sync_soon(
+    client: GaggiMateClient, repo: str | Path, notify, *,
+    site_title: str = "Shot Journal", state=None, quiet: bool = False,
+) -> None:
+    """Post-shot sync wrapper: run, report problems, never raise.
+
+    A failed sync is remembered in *state* (``sync_pending``) so the caller
+    can retry when the machine comes back online.
+    """
+    try:
+        await sync(client, repo, site_title=site_title)
+    except SyncConflict as exc:
+        await notify(f"⚠️ Shot journal sync hit a git conflict — fix it manually:\n{exc}")
+    except (TimeoutError, aiohttp.ClientError, OSError) as exc:
+        log.warning("sync failed, machine unreachable: %r", exc)
+        if state is not None:
+            state.set("sync_pending", True)
+        if not quiet:
+            await notify(
+                "📡 The machine went offline before the journal could sync — "
+                "I'll catch up as soon as it's back on."
+            )
+    except Exception as exc:  # noqa: BLE001
+        log.exception("sync failed")
+        if state is not None:
+            state.set("sync_pending", True)
+        if not quiet:
+            await notify(f"⚠️ Shot journal sync failed: {exc!r}")
+    else:
+        if state is not None:
+            state.set("sync_pending", False)

matebot/watcher.py

@@ -0,0 +1,137 @@
+"""Shot-end detection over the GaggiMate status stream.
+
+A shot "ends" when ``process.a`` transitions 1 -> 0 while the machine was in
+brew mode. The finished shot's id is then resolved by polling ``index.bin``
+(the header/index are finalized only after extended recording ends, which can
+take up to ~1 minute after the pump stops while a bluetooth scale settles).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from .machine import GaggiMateClient
+from .slog import IndexEntry
+
+log = logging.getLogger(__name__)
+
+MODE_BREW = 1
+BREW_PROCESSES = {"brew", "infusion"}
+
+
+@dataclass
+class FinishedShot:
+    entry: IndexEntry
+    profile_label: str
+    duration_ms: int
+
+
+class ShotWatcher:
+    def __init__(
+        self,
+        client: GaggiMateClient,
+        *,
+        min_duration_s: float = 10.0,
+        ignore_profiles: str = r"(?i)backflush|descale|flush|clean",
+        last_known_id: int = -1,
+        on_utility=None,
+    ) -> None:
+        self.client = client
+        self.min_duration_ms = min_duration_s * 1000
+        self.ignore_re = re.compile(ignore_profiles) if ignore_profiles else None
+        self.last_known_id = last_known_id
+        self.on_utility = on_utility  # async callback(profile) for ignored utility runs
+
+    def _frame_is_shot_end(self, prev: dict | None, frame: dict) -> bool:
+        if prev is None:
+            return False
+        p_prev = prev.get("process") or {}
+        p_now = frame.get("process") or {}
+        return (
+            p_prev.get("a") == 1
+            and p_now.get("a") == 0
+            and prev.get("m") == MODE_BREW
+            and p_prev.get("s", "brew") in BREW_PROCESSES
+        )
+
+    def _accept(self, profile: str, duration_ms: float) -> bool:
+        if duration_ms < self.min_duration_ms:
+            log.info("ignoring short shot (%.1fs)", duration_ms / 1000)
+            return False
+        if self.ignore_re and self.ignore_re.search(profile or ""):
+            log.info("ignoring utility profile %r", profile)
+            return False
+        return True
+
+    async def _resolve_new_entry(self, *, budget_s: float = 120.0, poll_s: float = 3.0):
+        """Poll index.bin until a new completed entry appears."""
+        waited = 0.0
+        while waited <= budget_s:
+            try:
+                index = await self.client.fetch_index()
+            except Exception as exc:  # noqa: BLE001 - transient HTTP errors are fine
+                log.debug("index poll failed: %s", exc)
+            else:
+                fresh = [
+                    e
+                    for e in index.entries
+                    if e.id > self.last_known_id and e.completed and not e.deleted
+                ]
+                if fresh:
+                    return max(fresh, key=lambda e: e.id)
+            await asyncio.sleep(poll_s)
+            waited += poll_s
+        return None
+
+    async def shots(self, frames: AsyncIterator[dict]) -> AsyncIterator[FinishedShot]:
+        """Consume status frames, yield finished (accepted) shots."""
+        prev: dict | None = None
+        # Initialize last_known_id from the machine so pre-existing shots
+        # never fire the questionnaire.
+        if self.last_known_id < 0:
+            try:
+                index = await self.client.fetch_index()
+                self.last_known_id = max((e.id for e in index.entries), default=0)
+                log.info("starting after shot id %d", self.last_known_id)
+            except Exception:  # noqa: BLE001
+                self.last_known_id = 0
+
+        async for frame in frames:
+            if frame.get("tp") != "evt:status":
+                continue
+            if self._frame_is_shot_end(prev, frame):
+                profile = prev.get("p", "")
+                duration = (prev.get("process") or {}).get("e", 0)
+                log.info("shot ended: profile=%r duration=%.1fs", profile, duration / 1000)
+                is_utility = (
+                    duration >= self.min_duration_ms
+                    and self.ignore_re
+                    and self.ignore_re.search(profile or "")
+                )
+                if is_utility and self.on_utility:
+                    await self.on_utility(profile)
+                if self._accept(profile, duration):
+                    entry = await self._resolve_new_entry()
+                    if entry is None:
+                        log.warning("shot ended but no new index entry appeared")
+                    else:
+                        self.last_known_id = entry.id
+                        yield FinishedShot(entry, profile, entry.duration_ms or duration)
+            prev = frame
+
+
+async def replay_frames(path: str | Path, *, delay_s: float = 0.0) -> AsyncIterator[dict]:
+    """Replay a JSONL capture of WS frames (for tests and --replay dry-runs)."""
+    for line in Path(path).read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if delay_s:
+            await asyncio.sleep(delay_s)
+        yield json.loads(line)