Files
cardputerzero-camera/cam-helper/czcamera_cam/protocol.py

322 lines
10 KiB
Python

"""Wire Protocol v1: CZFR binary frame pipe writer and newline-JSON control server."""
from __future__ import annotations
import json
import os
import select
import struct
import threading
from typing import Any, Callable, Optional, TextIO
PROTOCOL_VERSION = 1
CZFR_MAGIC = b"CZFR"
CZFR_HEADER_STRUCT = struct.Struct("<4sHHBBHI")
PIXFMT_YUV420 = 1
PIXFMT_RGB24 = 2
FLAG_ASPECT_16_9 = 0x01
def pack_czfr_header(
width: int,
height: int,
pixfmt: int,
flags: int,
payload_bytes: int,
) -> bytes:
"""Pack the 16-byte little-endian CZFR frame header."""
if not (0 <= width <= 0xFFFF and 0 <= height <= 0xFFFF):
raise ValueError(f"Frame dimensions out of uint16 range: {width}x{height}")
if pixfmt not in (PIXFMT_YUV420, PIXFMT_RGB24):
raise ValueError(f"Unsupported pixfmt: {pixfmt}")
if not (0 <= flags <= 0xFF):
raise ValueError(f"Flags out of uint8 range: {flags}")
if not (0 <= payload_bytes <= 0xFFFFFFFF):
raise ValueError(f"Payload length out of uint32 range: {payload_bytes}")
return CZFR_HEADER_STRUCT.pack(
CZFR_MAGIC,
width,
height,
pixfmt,
flags,
0,
payload_bytes,
)
class FramePipeWriter:
"""Single-slot latest-frame writer for the dedicated CZFR frame pipe.
push_frame() never blocks on pipe backpressure: if a previous unconsumed frame
is still queued, it is discarded and replaced by the newest frame.
"""
def __init__(self, frame_fd: int, owns_fd: bool = False) -> None:
if frame_fd < 0:
raise ValueError(f"Invalid frame_fd: {frame_fd}")
self._fd = frame_fd
self._owns_fd = owns_fd
self._cond = threading.Condition()
self._pending: Optional[tuple[int, int, int, int, bytes]] = None
self._stop = False
self._started = False
self._thread: Optional[threading.Thread] = None
self._frames_pushed = 0
self._frames_dropped = 0
self._frames_written = 0
try:
os.set_blocking(self._fd, False)
except OSError:
pass
@property
def frames_pushed(self) -> int:
with self._cond:
return self._frames_pushed
@property
def frames_dropped(self) -> int:
with self._cond:
return self._frames_dropped
@property
def frames_written(self) -> int:
with self._cond:
return self._frames_written
def start(self) -> None:
with self._cond:
if self._started:
return
self._stop = False
self._started = True
self._thread = threading.Thread(
target=self._writer_loop,
name="czfr-pipe-writer",
daemon=True,
)
self._thread.start()
def push_frame(
self,
width: int,
height: int,
pixfmt: int,
flags: int,
payload: bytes | bytearray | memoryview,
) -> None:
"""Queue the latest frame without blocking; drop any stale queued frame."""
data = bytes(payload)
with self._cond:
if self._stop:
return
if self._pending is not None:
self._frames_dropped += 1
self._pending = (width, height, pixfmt, flags, data)
self._frames_pushed += 1
self._cond.notify()
def stop(self, timeout: float = 1.0) -> None:
with self._cond:
self._stop = True
self._pending = None
self._cond.notify_all()
thread = self._thread
if thread is not None and thread.is_alive():
thread.join(timeout=timeout)
with self._cond:
self._thread = None
self._started = False
if self._owns_fd and self._fd >= 0:
try:
os.close(self._fd)
except OSError:
pass
self._fd = -1
def _write_packet(self, packet: bytes) -> bool:
mv = memoryview(packet)
offset = 0
total = len(packet)
try:
while offset < total:
with self._cond:
if self._stop:
return False
try:
written = os.write(self._fd, mv[offset:])
except BlockingIOError:
select.select([], [self._fd], [], 0.05)
continue
except (BrokenPipeError, OSError):
return False
if written <= 0:
return False
offset += written
return True
finally:
mv.release()
def _writer_loop(self) -> None:
while True:
with self._cond:
while self._pending is None and not self._stop:
self._cond.wait()
if self._stop:
return
frame = self._pending
self._pending = None
assert frame is not None
width, height, pixfmt, flags, payload = frame
header = pack_czfr_header(width, height, pixfmt, flags, len(payload))
if not self._write_packet(header + payload):
with self._cond:
self._stop = True
return
with self._cond:
self._frames_written += 1
class JsonProtocolServer:
"""Newline-delimited JSON control channel on stdin/stdout."""
def __init__(
self,
worker_factory: Callable[[Callable[[dict[str, Any]], None]], Any],
stdin: TextIO,
stdout: TextIO,
) -> None:
self._stdin = stdin
self._stdout = stdout
self._write_lock = threading.Lock()
self._shutdown_requested = False
self._worker = worker_factory(self.emit_event)
def emit_event(self, payload: dict[str, Any]) -> None:
self._write_json(payload)
def request_shutdown(self) -> None:
self._shutdown_requested = True
def _write_json(self, payload: dict[str, Any]) -> None:
line = json.dumps(payload, separators=(",", ":")) + "\n"
with self._write_lock:
try:
self._stdout.write(line)
self._stdout.flush()
except (BrokenPipeError, OSError, ValueError):
self._shutdown_requested = True
def _reply_ok(self, cmd_id: Any, extra: Optional[dict[str, Any]] = None) -> None:
reply: dict[str, Any] = {"id": cmd_id, "ok": True}
if extra:
reply.update(extra)
self._write_json(reply)
def _reply_err(self, cmd_id: Any, error: str) -> None:
self._write_json({"id": cmd_id, "ok": False, "error": error})
def _handle_command(self, msg: dict[str, Any]) -> None:
cmd_id = msg.get("id")
cmd = msg.get("cmd")
if not isinstance(cmd, str):
self._reply_err(cmd_id, "missing_cmd")
return
try:
if cmd == "configure":
res = self._worker.configure(
mode=str(msg.get("mode", "photo")),
main_w=int(msg["main_w"]),
main_h=int(msg["main_h"]),
preview_w=int(msg.get("preview_w", 226)),
preview_h=int(msg.get("preview_h", 170)),
fps=int(msg.get("fps", 30)),
zoom=float(msg.get("zoom", 1.0)),
ev=float(msg.get("ev", 0.0)),
transform=str(msg.get("transform", "auto")),
)
self._reply_ok(cmd_id, res)
elif cmd == "set_controls":
res = self._worker.set_controls(
zoom=float(msg["zoom"]) if "zoom" in msg else None,
ev=float(msg["ev"]) if "ev" in msg else None,
)
self._reply_ok(cmd_id, res)
elif cmd == "capture_still":
res = self._worker.capture_still(
tmp_path=str(msg["tmp_path"]),
width=int(msg["width"]),
height=int(msg["height"]),
)
self._reply_ok(cmd_id, res)
elif cmd == "start_video":
res = self._worker.start_video(
tmp_path=str(msg["tmp_path"]),
width=int(msg["width"]),
height=int(msg["height"]),
fps=int(msg.get("fps", 30)),
bitrate=int(msg.get("bitrate", 4000000)),
audio=bool(msg.get("audio", True)),
)
self._reply_ok(cmd_id, res)
elif cmd == "stop_video":
res = self._worker.stop_video()
self._reply_ok(cmd_id, res)
elif cmd == "pause":
res = self._worker.pause()
self._reply_ok(cmd_id, res)
elif cmd == "resume":
res = self._worker.resume()
self._reply_ok(cmd_id, res)
elif cmd == "shutdown":
self._worker.shutdown()
self._reply_ok(cmd_id)
self._shutdown_requested = True
else:
self._reply_err(cmd_id, f"unknown_cmd:{cmd}")
except Exception as exc: # noqa: BLE001
self._reply_err(cmd_id, str(exc))
def run(self) -> int:
self._worker.start()
try:
while not self._shutdown_requested:
try:
raw_line = self._stdin.readline()
except (OSError, ValueError):
break
if not raw_line:
break
line = raw_line.strip()
if not line:
continue
try:
msg = json.loads(line)
except json.JSONDecodeError as exc:
self.emit_event(
{
"event": "warn",
"code": "bad_command",
"message": f"Invalid JSON command: {exc}",
}
)
continue
if not isinstance(msg, dict):
self.emit_event(
{
"event": "warn",
"code": "bad_command",
"message": "Command must be a JSON object",
}
)
continue
self._handle_command(msg)
finally:
self._worker.shutdown()
return 0