Source code for rigconductor.motif

# ╔══════════════════════════════════════════════════════════════════╗
# ║  Rig Conductor — motif                                           ║
# ║  « drive the loopbio recorder »                                  ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║  Motif REST client, recording discovery, an in-memory fake.      ║
# ╚══════════════════════════════════════════════════════════════════╝
"""Motif (loopbio) recorder control over its REST API, plus an in-memory fake.

Only the handful of endpoints Conductor needs are wrapped; the wire format is
the same as the vendor's ``motifapi`` package (``X-Api-Key`` header, JSON body,
HTTPS with the recnode's self-signed certificate).
"""

from __future__ import annotations

import json
import os
import shutil
import ssl
import subprocess
import time
import urllib.error
import urllib.request
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import Protocol

import yaml

from rigconductor import ConductorError
from rigconductor.constants import HTTP_TIMEOUT_S, MOTIF_PORT, RECORDING_QUIET_S


[docs] class MotifError(ConductorError): pass
[docs] @dataclass class CameraStatus: serial: str status: str # e.g. "ready", "running", "pending", "ERROR", "unknown" filename: str | None # the recording being written, if any raw: dict @property def is_recording(self) -> bool: info = self.raw.get("camera_info") or {} return ( bool(self.filename) or self.status == "pending" or bool(info.get("record_is_recording")) ) @property def is_ok(self) -> bool: return self.status.upper() not in {"ERROR", "UNKNOWN", ""}
[docs] class Recorder(Protocol): """What the session needs from a recorder (real Motif or the fake).""" def version(self) -> dict: ... def camera(self) -> CameraStatus: ... def start_recording( self, filename: str, duration_s: float, codec: str | None, metadata: dict | None ) -> dict: ... def stop_recording(self) -> dict: ...
def resolve_api_key(api_key: str | None = None, api_key_cmd: str | None = "recnode-apikey") -> str: key = api_key or os.environ.get("MOTIF_API_KEY") if key: return key if api_key_cmd and shutil.which(api_key_cmd): try: key = subprocess.check_output([api_key_cmd], text=True, timeout=10).strip() except (subprocess.SubprocessError, OSError) as e: raise MotifError(f"could not read the Motif API key via {api_key_cmd}: {e}") from e if key: return key raise MotifError( "no Motif API key: set MOTIF_API_KEY or make sure `recnode-apikey` is on the PATH" ) class MotifClient: def __init__( self, host: str = "127.0.0.1", port: int = MOTIF_PORT, serial: str | None = None, api_key: str | None = None, api_key_cmd: str | None = "recnode-apikey", timeout_s: float = HTTP_TIMEOUT_S, ): self.host, self.port, self.timeout_s = host, int(port), timeout_s self._serial = serial self._key = resolve_api_key(api_key, api_key_cmd) self._ssl = ssl.create_default_context() self._ssl.check_hostname = False self._ssl.verify_mode = ssl.CERT_NONE # recnode uses a self-signed certificate # ── transport ────────────────────────────────────────────────────── def _call(self, method: str, endpoint: str, data: dict | None = None) -> dict: prefix = "" if endpoint == "version" else "api/1/" url = f"https://{self.host}:{self.port}/{prefix}{endpoint}" body = json.dumps(data).encode() if data is not None else None req = urllib.request.Request(url, data=body, method=method) req.add_header("X-Api-Key", self._key) req.add_header("Content-Type", "application/json") try: with urllib.request.urlopen(req, timeout=self.timeout_s, context=self._ssl) as r: raw = r.read() except urllib.error.HTTPError as e: try: err = json.loads(e.read().decode()) msg = err.get("error", str(e)) except Exception: msg = str(e) raise MotifError(f"Motif API {method} {endpoint}: {msg}") from e except (urllib.error.URLError, OSError) as e: raise MotifError( f"Motif is not reachable at {self.host}:{self.port} " f"(is the recnode running? `sudo supervisorctl status`): {e}" ) from e return json.loads(raw.decode()) if raw else {} # ── queries ──────────────────────────────────────────────────────── def version(self) -> dict: return self._call("GET", "version") def cameras(self) -> list[dict]: return self._call("GET", "cameras").get("cameras", []) @property def serial(self) -> str: if not self._serial: cams = self.cameras() if not cams: raise MotifError("Motif reports no camera") self._serial = str(cams[0]["serial"]) return self._serial def camera(self) -> CameraStatus: r = self._call("GET", f"camera/{self.serial}") info = r.get("camera_info") or {} return CameraStatus( serial=self.serial, status=str(info.get("status", "unknown")), filename=info.get("filename") or None, raw=r, ) def recordings(self) -> list[dict]: return self._call("GET", f"camera/{self.serial}/recordings").get("recordings", []) # ── control ──────────────────────────────────────────────────────── def start_recording( self, filename: str, duration_s: float, codec: str | None = None, metadata: dict | None = None, ) -> dict: data: dict = {"filename": filename, "duration": float(duration_s)} if codec: data["codec"] = codec if metadata: data["metadata"] = metadata return self._call("POST", f"camera/{self.serial}/recording/start", data) def stop_recording(self) -> dict: return self._call("POST", f"camera/{self.serial}/recording/stop", {}) def read(self, name: str): """One camera setting, e.g. ``read("PixelFormat")`` → ``"Mono8"``.""" r = self._call("GET", f"camera/{self.serial}/read/{name}") return r.get(str(self.serial)) if isinstance(r, dict) else r def configure(self, **settings) -> dict: """PATCH camera settings, e.g. ``AcquisitionFrameRate=50.0``.""" return self._call("PATCH", f"camera/{self.serial}/configure", settings) # ── helpers shared by real and fake ──────────────────────────────────────
[docs] def motif_dir_name(title: str, when: datetime) -> str: """Motif names the store ``<title lowercased>_<YYYYMMDD>_<HHMMSS>``.""" return f"{title.lower()}_{when.strftime('%Y%m%d_%H%M%S')}"
[docs] def find_new_recording( data_root: Path, started_after: float, title: str | None = None ) -> Path | None: """The newest recording folder created after ``started_after`` (epoch seconds) whose name starts with ``title`` (lower-cased), if given. Motif writes ``<data_root>/<camera serial>/<title>_<stamp>``, so one level of sub-directories is searched as well.""" root = Path(data_root) cands = [] for d in list(root.iterdir()) + [c for s in root.iterdir() if s.is_dir() for c in s.iterdir()]: if not d.is_dir() or not (d / "metadata.yaml").is_file(): continue if title and not d.name.startswith(title.lower()): continue if d.stat().st_mtime >= started_after - 5: cands.append(d) return max(cands, key=lambda d: d.stat().st_mtime) if cands else None
[docs] def recording_is_closed( rec_dir: Path, quiet_s: float = RECORDING_QUIET_S, now: float | None = None ) -> bool: """True when no file in the store changed for ``quiet_s`` seconds (``now`` = epoch s).""" files = [p for p in Path(rec_dir).iterdir() if p.is_file()] if not files: return False newest = max(p.stat().st_mtime for p in files) return (time.time() if now is None else now) - newest >= quiet_s
def wait_for_stop( rec: Recorder, timeout_s: float, poll_s: float = 2.0, log=None, clock=time.monotonic, sleep=time.sleep, ) -> None: t0 = clock() while rec.camera().is_recording: if clock() - t0 > timeout_s: raise MotifError(f"recording still running after {timeout_s:.0f} s") if log: log(f"recording… {clock() - t0:.0f} s") sleep(poll_s) # ── fake for tests and dry runs ──────────────────────────────────────────
[docs] class FakeMotif: """Behaves like Motif from the outside: a recording lasts ``duration`` seconds of *fake clock* time, writes ``metadata.yaml`` and one chunk file into ``data_root/<title>_<stamp>``. Advance time with :meth:`tick` or pass a real clock for timing tests.""" def __init__(self, data_root: Path, serial: str = "FAKE0001", camera_status: str = "ready"): self.data_root = Path(data_root) self.serial = serial self.camera_status = camera_status self.now = 0.0 self.calls: list[tuple] = [] self._rec: dict | None = None self.recordings_made: list[Path] = [] def tick(self, s: float): self.now += s self._finish_if_due() def _finish_if_due(self): if self._rec and self.now >= self._rec["end"]: self._rec = None def version(self) -> dict: return {"api": 1, "software": "fake-6.1.10"} def configure(self, **settings) -> dict: self.settings = {**getattr(self, "settings", {}), **settings} self.calls.append(("configure", settings)) return {} def read(self, name: str): return getattr(self, "settings", {}).get(name) def camera(self) -> CameraStatus: self._finish_if_due() return CameraStatus( serial=self.serial, status="running" if self._rec else self.camera_status, filename=self._rec["path"] if self._rec else None, raw={}, ) def start_recording(self, filename, duration_s, codec=None, metadata=None) -> dict: self.calls.append(("start", filename, duration_s, codec, metadata)) if self.camera_status.upper() == "ERROR": raise MotifError("Motif API POST recording/start: camera not ready") if self._rec: raise MotifError("already recording") when = datetime.fromtimestamp(time.time()) d = self.data_root / motif_dir_name(filename, when) d.mkdir(parents=True) meta = { "__store": {"class": "VideoImgStoreFFMPEG", "format": codec or "fake"}, "title": filename, "camera_serial": self.serial, "acquisitionframerate": 25.0, "motif_version": "fake", "created_utc": when.isoformat(), } if metadata: meta.update(metadata) (d / "metadata.yaml").write_text(yaml.safe_dump(meta), encoding="utf-8") (d / "000000.mp4").write_bytes(b"\x00" * 16) self._rec = {"path": str(d), "end": self.now + float(duration_s)} self.recordings_made.append(d) return {"filename": str(d)} def stop_recording(self) -> dict: self.calls.append(("stop",)) self._rec = None return {}