esp32-stream 0.1.0__tar.gz

esp32_stream-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: esp32-stream
+Version: 0.1.0
+Summary: ESP32 serial stream protocol parser and frame source adapter
+Author: ESP32 Host Tooling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+Requires-Dist: numpy>=1.26
+Provides-Extra: opencv
+Requires-Dist: opencv-python>=4.10; extra == "opencv"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# esp32-stream
+
+Reusable Python package for ESP32 serial stream protocol parsing and camera frame assembly.
+
+This package is the source of truth for host-side stream handling used by calibration and other consumer projects.
+
+## Install
+
+```bash
+pip install esp32-stream
+```
+
+With OpenCV decode support:
+
+```bash
+pip install "esp32-stream[opencv]"
+```
+
+## Development Install
+
+From this folder:
+
+```bash
+pip install -e ".[dev,opencv]"
+pytest
+```
+
+## Public API
+
+- `esp32_stream.protocol`: packet constants, parser, command builders
+- `esp32_stream.board_profiles`: board defaults and aliases
+- `esp32_stream.esp32_frame_source`: `Esp32FrameSource`, `Esp32VideoCaptureAdapter`
+
+## Consumer Pinning (recommended)
+
+Pin exact versions in downstream projects:
+
+```txt
+esp32-stream==0.1.0
+```
+
+For local integration testing before release:
+
+```bash
+pip install -e /absolute/path/to/esp32/python/esp32_stream
+```
+
+Do not use editable installs for production or CI release branches.
+
+## Upgrade Workflow
+
+1. Update package in this repo on a feature branch.
+2. Run package tests (`pytest`).
+3. Run the consumer smoke test in each downstream project.
+4. Bump version and tag release.
+5. Update pinned version in each consumer project when ready.
+
+## Release
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Tag example:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```

esp32_stream-0.1.0/README.md

@@ -0,0 +1,71 @@
+# esp32-stream
+
+Reusable Python package for ESP32 serial stream protocol parsing and camera frame assembly.
+
+This package is the source of truth for host-side stream handling used by calibration and other consumer projects.
+
+## Install
+
+```bash
+pip install esp32-stream
+```
+
+With OpenCV decode support:
+
+```bash
+pip install "esp32-stream[opencv]"
+```
+
+## Development Install
+
+From this folder:
+
+```bash
+pip install -e ".[dev,opencv]"
+pytest
+```
+
+## Public API
+
+- `esp32_stream.protocol`: packet constants, parser, command builders
+- `esp32_stream.board_profiles`: board defaults and aliases
+- `esp32_stream.esp32_frame_source`: `Esp32FrameSource`, `Esp32VideoCaptureAdapter`
+
+## Consumer Pinning (recommended)
+
+Pin exact versions in downstream projects:
+
+```txt
+esp32-stream==0.1.0
+```
+
+For local integration testing before release:
+
+```bash
+pip install -e /absolute/path/to/esp32/python/esp32_stream
+```
+
+Do not use editable installs for production or CI release branches.
+
+## Upgrade Workflow
+
+1. Update package in this repo on a feature branch.
+2. Run package tests (`pytest`).
+3. Run the consumer smoke test in each downstream project.
+4. Bump version and tag release.
+5. Update pinned version in each consumer project when ready.
+
+## Release
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Tag example:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```

esp32_stream-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esp32-stream"
+version = "0.1.0"
+description = "ESP32 serial stream protocol parser and frame source adapter"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "ESP32 Host Tooling" }
+]
+dependencies = [
+  "pyserial>=3.5",
+  "numpy>=1.26"
+]
+
+[project.optional-dependencies]
+opencv = [
+  "opencv-python>=4.10"
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

esp32_stream-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esp32_stream-0.1.0/src/esp32_stream/__init__.py

@@ -0,0 +1,21 @@
+from .board_profiles import (
+    BOARD_ALIASES,
+    BOARD_PROFILES,
+    CAMERA_MODE_DIMENSIONS,
+    BoardProfile,
+    get_board_profile,
+)
+from .esp32_frame_source import Esp32FrameSource, Esp32VideoCaptureAdapter, FrameMetadata
+
+__all__ = [
+    "BOARD_ALIASES",
+    "BOARD_PROFILES",
+    "CAMERA_MODE_DIMENSIONS",
+    "BoardProfile",
+    "get_board_profile",
+    "Esp32FrameSource",
+    "Esp32VideoCaptureAdapter",
+    "FrameMetadata",
+]
+
+__version__ = "0.1.0"

esp32_stream-0.1.0/src/esp32_stream/board_profiles.py

@@ -0,0 +1,54 @@
+"""Board profiles for ESP32 host tooling.
+
+Keeps serial defaults and mode metadata centralized so tooling can run
+unchanged across supported boards.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BoardProfile:
+    name: str
+    default_port: str
+    default_baud: int
+    camera_mode_dimensions: dict[str, tuple[int, int]]
+
+
+CAMERA_MODE_DIMENSIONS: dict[str, tuple[int, int]] = {
+    "dev_qvga": (320, 240),
+    "proc_lowres": (640, 400),
+}
+
+
+BOARD_PROFILES: dict[str, BoardProfile] = {
+    "esp32s3": BoardProfile(
+        name="esp32s3",
+        default_port="/dev/cu.usbmodem1101",
+        default_baud=115200,
+        camera_mode_dimensions=dict(CAMERA_MODE_DIMENSIONS),
+    ),
+    "esp32p4": BoardProfile(
+        name="esp32p4",
+        default_port="/dev/cu.usbmodem1101",
+        default_baud=6000000,
+        camera_mode_dimensions=dict(CAMERA_MODE_DIMENSIONS),
+    ),
+}
+
+
+BOARD_ALIASES = {
+    "s3": "esp32s3",
+    "p4": "esp32p4",
+}
+
+
+def get_board_profile(name: str) -> BoardProfile:
+    key = name.strip().lower()
+    key = BOARD_ALIASES.get(key, key)
+    if key not in BOARD_PROFILES:
+        supported = ", ".join(sorted(BOARD_PROFILES.keys()))
+        raise ValueError(f"Unsupported board '{name}'. Supported: {supported}")
+    return BOARD_PROFILES[key]

esp32_stream-0.1.0/src/esp32_stream/esp32_frame_source.py

@@ -0,0 +1,380 @@
+"""ESP32 camera frame source for direct integration into OpenCV pipelines.
+
+This module reads the USB serial stream protocol and returns decoded
+camera frames plus timing metadata suitable for calibration workflows.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .board_profiles import get_board_profile
+from .protocol import (
+	CAMERA_MODE_ID_TO_NAME,
+	CAMERA_MODE_NAME_TO_ID,
+	PACKET_TYPE_CONTROL_ACK,
+	PACKET_TYPE_FRAME_CHUNK,
+	PACKET_TYPE_FRAME_END,
+	PACKET_TYPE_FRAME_START,
+	PACKET_TYPE_STREAM_STATS,
+	STREAM_MODE_NAME_TO_ID,
+	StreamParser,
+	build_set_camera_mode_command,
+	build_set_stream_mode_command,
+)
+
+
+@dataclass
+class FrameMetadata:
+	frame_id: int
+	width: int
+	height: int
+	camera_mode: str
+	capture_start_us: int
+	capture_ready_us: int
+	packet_timestamp_us: int
+	host_recv_us: int
+	chunk_count: int
+	frame_len_expected: int
+	frame_len_received: int
+
+
+@dataclass
+class _FrameAssembly:
+	frame_id: int
+	capture_start_us: int
+	capture_ready_us: int
+	frame_len_bytes: int
+	width: int
+	height: int
+	camera_mode: int
+	received_bytes: int = 0
+	chunk_count: int = 0
+	next_offset: int = 0
+	broken: bool = False
+	frame_bytes: bytearray = field(default_factory=bytearray)
+
+
+class Esp32FrameSource:
+	"""Read ESP32 stream frames using a VideoCapture-like read() call.
+
+	read() returns (ok, frame_bgr, metadata).
+	If no frame arrives before timeout, returns (False, None, None).
+	"""
+
+	def __init__(
+		self,
+		port: str | None = None,
+		baud: int | None = None,
+		board: str = "esp32s3",
+		read_chunk_size: int = 4096,
+		read_timeout_s: float = 0.1,
+		set_camera_mode: str = "",
+		set_stream_mode: str = "",
+		serial_port: Any | None = None,
+	) -> None:
+		profile = get_board_profile(board)
+		self.port = port if port is not None else profile.default_port
+		self.baud = int(baud) if baud is not None else int(profile.default_baud)
+		self.board = profile.name
+		self.read_chunk_size = max(int(read_chunk_size), 256)
+		self.read_timeout_s = max(float(read_timeout_s), 0.001)
+		self.set_camera_mode = set_camera_mode
+		self.set_stream_mode = set_stream_mode
+
+		self._parser = StreamParser()
+		self._ser = serial_port
+		self._owns_serial = serial_port is None
+		self._active_frame: _FrameAssembly | None = None
+
+	def open(self) -> None:
+		if self._ser is None:
+			try:
+				import serial  # type: ignore
+			except ModuleNotFoundError as exc:
+				raise RuntimeError("Missing dependency: pyserial") from exc
+			self._ser = serial.Serial(self.port, self.baud, timeout=self.read_timeout_s)
+
+		# Clear stale bytes from prior sessions before issuing mode commands.
+		try:
+			self._ser.reset_input_buffer()
+		except Exception:
+			pass
+
+		if self.set_stream_mode:
+			stream_mode_name = self.set_stream_mode
+			# Compatibility aliases used by host CLI wrappers.
+			if stream_mode_name == "camera":
+				stream_mode_name = "imu_camera"
+			elif stream_mode_name == "imu":
+				stream_mode_name = "imu_only"
+
+			mode_id = STREAM_MODE_NAME_TO_ID[stream_mode_name]
+			cmd = build_set_stream_mode_command(mode_id, int(time.time() * 1_000_000))
+			self._ser.write(cmd)
+			self._ser.flush()
+
+		if self.set_camera_mode:
+			mode_id = CAMERA_MODE_NAME_TO_ID[self.set_camera_mode]
+			cmd = build_set_camera_mode_command(mode_id, int(time.time() * 1_000_000))
+			self._ser.write(cmd)
+			self._ser.flush()
+
+		# Start reads at a fresh packet boundary after control writes.
+		self._active_frame = None
+		self._parser = StreamParser()
+		try:
+			self._ser.reset_input_buffer()
+		except Exception:
+			pass
+
+	def close(self) -> None:
+		if self._ser is not None and self._owns_serial:
+			self._ser.close()
+		self._ser = None
+
+	def __enter__(self) -> "Esp32FrameSource":
+		self.open()
+		return self
+
+	def __exit__(self, exc_type, exc, tb) -> None:
+		del exc_type, exc, tb
+		self.close()
+
+	def _decode_jpeg(self, jpg_bytes: bytes):
+		try:
+			import cv2  # type: ignore
+			import numpy as np
+		except ModuleNotFoundError as exc:
+			raise RuntimeError("Missing dependencies: opencv-python and numpy") from exc
+
+		jpg = np.frombuffer(jpg_bytes, dtype=np.uint8)
+		return cv2.imdecode(jpg, cv2.IMREAD_COLOR)
+
+	def _decode_raw_fallback(self, frame_bytes: bytes, width: int, height: int):
+		try:
+			import cv2  # type: ignore
+			import numpy as np
+		except ModuleNotFoundError as exc:
+			raise RuntimeError("Missing dependencies: opencv-python and numpy") from exc
+
+		if width <= 0 or height <= 0:
+			return None
+
+		px = width * height
+		if len(frame_bytes) == px:
+			gray = np.frombuffer(frame_bytes, dtype=np.uint8).reshape((height, width))
+			return cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
+
+		if len(frame_bytes) == (px * 2):
+			rgb565 = np.frombuffer(frame_bytes, dtype=np.uint16).reshape((height, width))
+			r = ((rgb565 >> 11) & 0x1F).astype(np.uint8)
+			g = ((rgb565 >> 5) & 0x3F).astype(np.uint8)
+			b = (rgb565 & 0x1F).astype(np.uint8)
+			r8 = ((r * 255) // 31).astype(np.uint8)
+			g8 = ((g * 255) // 63).astype(np.uint8)
+			b8 = ((b * 255) // 31).astype(np.uint8)
+			return np.dstack((b8, g8, r8))
+
+		return None
+
+	def _handle_packet(self, pkt, host_recv_us: int):
+		if pkt.packet_type == PACKET_TYPE_CONTROL_ACK:
+			return None
+
+		if pkt.packet_type == PACKET_TYPE_STREAM_STATS:
+			return None
+
+		if pkt.packet_type == PACKET_TYPE_FRAME_START:
+			if len(pkt.payload) < 29:
+				self._active_frame = None
+				return None
+
+			frame_id = int.from_bytes(pkt.payload[0:4], "little")
+			capture_start_us = int.from_bytes(pkt.payload[4:12], "little")
+			capture_ready_us = int.from_bytes(pkt.payload[12:20], "little")
+			frame_len = int.from_bytes(pkt.payload[20:24], "little")
+			width = int.from_bytes(pkt.payload[24:26], "little")
+			height = int.from_bytes(pkt.payload[26:28], "little")
+			camera_mode = pkt.payload[28]
+
+			self._active_frame = _FrameAssembly(
+				frame_id=frame_id,
+				capture_start_us=capture_start_us,
+				capture_ready_us=capture_ready_us,
+				frame_len_bytes=frame_len,
+				width=width,
+				height=height,
+				camera_mode=camera_mode,
+			)
+			return None
+
+		if pkt.packet_type == PACKET_TYPE_FRAME_CHUNK:
+			if len(pkt.payload) < 8 or self._active_frame is None:
+				return None
+
+			frame_id = int.from_bytes(pkt.payload[0:4], "little")
+			offset = int.from_bytes(pkt.payload[4:8], "little")
+			chunk_data = pkt.payload[8:]
+
+			if frame_id != self._active_frame.frame_id:
+				self._active_frame.broken = True
+				return None
+			if offset != self._active_frame.next_offset:
+				self._active_frame.broken = True
+				return None
+			if (self._active_frame.received_bytes + len(chunk_data)) > self._active_frame.frame_len_bytes:
+				self._active_frame.broken = True
+				return None
+
+			self._active_frame.frame_bytes.extend(chunk_data)
+			self._active_frame.received_bytes += len(chunk_data)
+			self._active_frame.chunk_count += 1
+			self._active_frame.next_offset = offset + len(chunk_data)
+			return None
+
+		if pkt.packet_type == PACKET_TYPE_FRAME_END:
+			if len(pkt.payload) < 10 or self._active_frame is None:
+				return None
+
+			frame_id = int.from_bytes(pkt.payload[0:4], "little")
+			fw_frame_len = int.from_bytes(pkt.payload[4:8], "little")
+			fw_chunk_count = int.from_bytes(pkt.payload[8:10], "little")
+
+			if frame_id != self._active_frame.frame_id:
+				self._active_frame = None
+				return None
+
+			done = self._active_frame
+			self._active_frame = None
+
+			assembly_ok = (
+				(not done.broken)
+				and (done.received_bytes == done.frame_len_bytes)
+				and (fw_frame_len == done.frame_len_bytes)
+				and (fw_chunk_count == done.chunk_count)
+			)
+			if not assembly_ok:
+				return None
+
+			frame_bytes = bytes(done.frame_bytes)
+			frame = self._decode_jpeg(frame_bytes)
+			if frame is None:
+				frame = self._decode_raw_fallback(frame_bytes, done.width, done.height)
+			if frame is None:
+				return None
+
+			meta = FrameMetadata(
+				frame_id=done.frame_id,
+				width=done.width,
+				height=done.height,
+				camera_mode=CAMERA_MODE_ID_TO_NAME.get(done.camera_mode, f"unknown({done.camera_mode})"),
+				capture_start_us=done.capture_start_us,
+				capture_ready_us=done.capture_ready_us,
+				packet_timestamp_us=int(pkt.timestamp_us),
+				host_recv_us=host_recv_us,
+				chunk_count=done.chunk_count,
+				frame_len_expected=done.frame_len_bytes,
+				frame_len_received=done.received_bytes,
+			)
+			return frame, meta
+
+		return None
+
+	def read(self, timeout_s: float = 1.0):
+		"""Return (ok, frame_bgr, metadata) similar to cv2.VideoCapture.read()."""
+		if self._ser is None:
+			self.open()
+
+		deadline = time.monotonic() + max(timeout_s, 0.001)
+		while time.monotonic() < deadline:
+			chunk = self._ser.read(self.read_chunk_size)
+			if not chunk:
+				continue
+
+			host_recv_us = int(time.time_ns() // 1000)
+			for pkt in self._parser.feed(chunk):
+				out = self._handle_packet(pkt, host_recv_us)
+				if out is not None:
+					frame, meta = out
+					return True, frame, meta
+
+		return False, None, None
+
+
+class Esp32VideoCaptureAdapter:
+	"""cv2.VideoCapture-like wrapper around Esp32FrameSource.
+
+	read() follows OpenCV convention and returns (ok, frame).
+	Timestamp and transport metadata for the last successful read is available
+	via last_metadata.
+	"""
+
+	# Common OpenCV property IDs used by calling code.
+	_CAP_PROP_FRAME_WIDTH = 3
+	_CAP_PROP_FRAME_HEIGHT = 4
+
+	def __init__(
+		self,
+		port: str | None = None,
+		baud: int | None = None,
+		board: str = "esp32s3",
+		read_chunk_size: int = 4096,
+		read_timeout_s: float = 0.1,
+		set_camera_mode: str = "",
+		set_stream_mode: str = "",
+		serial_port: Any | None = None,
+		auto_open: bool = True,
+	) -> None:
+		self._source = Esp32FrameSource(
+			port=port,
+			baud=baud,
+			board=board,
+			read_chunk_size=read_chunk_size,
+			read_timeout_s=read_timeout_s,
+			set_camera_mode=set_camera_mode,
+			set_stream_mode=set_stream_mode,
+			serial_port=serial_port,
+		)
+		self.last_metadata: FrameMetadata | None = None
+		self._opened = False
+		if auto_open:
+			self.open()
+
+	def open(self) -> bool:
+		if self._opened:
+			return True
+		self._source.open()
+		self._opened = True
+		return True
+
+	def isOpened(self) -> bool:
+		return self._opened
+
+	def read(self, timeout_s: float = 1.0):
+		ok, frame, meta = self._source.read(timeout_s=timeout_s)
+		if ok:
+			self.last_metadata = meta
+			return True, frame
+		return False, None
+
+	def read_with_metadata(self, timeout_s: float = 1.0):
+		"""Convenience method if the caller wants frame and metadata together."""
+		ok, frame = self.read(timeout_s=timeout_s)
+		return ok, frame, self.last_metadata
+
+	def get(self, prop_id: int) -> float:
+		if self.last_metadata is None:
+			return 0.0
+		if prop_id == self._CAP_PROP_FRAME_WIDTH:
+			return float(self.last_metadata.width)
+		if prop_id == self._CAP_PROP_FRAME_HEIGHT:
+			return float(self.last_metadata.height)
+		return 0.0
+
+	def release(self) -> None:
+		if self._opened:
+			self._source.close()
+			self._opened = False

esp32_stream-0.1.0/src/esp32_stream/protocol.py

@@ -0,0 +1,169 @@
+"""Protocol parser and framing utilities for the ESP32 stream.
+
+This module should stay in sync with firmware/protocol.md.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+SYNC_BYTE = 0xAA
+PACKET_TYPE_IMU_SAMPLE = 0x01
+PACKET_TYPE_FRAME_START = 0x02
+PACKET_TYPE_FRAME_CHUNK = 0x03
+PACKET_TYPE_FRAME_END = 0x04
+PACKET_TYPE_CONTROL_CMD = 0x10
+PACKET_TYPE_CONTROL_ACK = 0x11
+PACKET_TYPE_STREAM_STATS = 0x12
+
+CONTROL_CMD_SET_CAMERA_MODE = 0x01
+CONTROL_CMD_SET_STREAM_MODE = 0x02
+CONTROL_CMD_GET_STREAM_STATS = 0x03
+
+CAMERA_MODE_DEV_QVGA = 0
+CAMERA_MODE_PROC_LOWRES = 1
+
+CAMERA_MODE_NAME_TO_ID = {
+    "dev_qvga": CAMERA_MODE_DEV_QVGA,
+    "proc_lowres": CAMERA_MODE_PROC_LOWRES,
+}
+
+CAMERA_MODE_ID_TO_NAME = {
+    CAMERA_MODE_DEV_QVGA: "dev_qvga",
+    CAMERA_MODE_PROC_LOWRES: "proc_lowres",
+}
+
+STREAM_MODE_IMU_CAMERA = 0
+STREAM_MODE_IMU_ONLY = 1
+
+STREAM_MODE_NAME_TO_ID = {
+    "imu_camera": STREAM_MODE_IMU_CAMERA,
+    "imu_only": STREAM_MODE_IMU_ONLY,
+}
+
+STREAM_MODE_ID_TO_NAME = {
+    STREAM_MODE_IMU_CAMERA: "imu_camera",
+    STREAM_MODE_IMU_ONLY: "imu_only",
+}
+
+VALID_PACKET_TYPES = {
+    PACKET_TYPE_IMU_SAMPLE,
+    PACKET_TYPE_FRAME_START,
+    PACKET_TYPE_FRAME_CHUNK,
+    PACKET_TYPE_FRAME_END,
+    PACKET_TYPE_CONTROL_CMD,
+    PACKET_TYPE_CONTROL_ACK,
+    PACKET_TYPE_STREAM_STATS,
+}
+
+HEADER_LEN = 1 + 1 + 2 + 8
+CRC_LEN = 2
+MIN_PACKET_LEN = HEADER_LEN + CRC_LEN
+MAX_PAYLOAD_LEN = 4096
+
+
+@dataclass(frozen=True)
+class Packet:
+    packet_type: int
+    timestamp_us: int
+    payload: bytes
+
+
+def _crc16_ccitt_false(data: bytes) -> int:
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            if crc & 0x8000:
+                crc = ((crc << 1) ^ 0x1021) & 0xFFFF
+            else:
+                crc = (crc << 1) & 0xFFFF
+    return crc
+
+
+class StreamParser:
+    """Incremental parser with sync recovery and CRC validation."""
+
+    def __init__(self) -> None:
+        self._buffer = bytearray()
+
+    def feed(self, data: bytes) -> list[Packet]:
+        self._buffer.extend(data)
+        packets: list[Packet] = []
+
+        while True:
+            if len(self._buffer) < MIN_PACKET_LEN:
+                break
+
+            if self._buffer[0] != SYNC_BYTE:
+                sync_idx = self._buffer.find(SYNC_BYTE)
+                if sync_idx == -1:
+                    self._buffer.clear()
+                    break
+                del self._buffer[:sync_idx]
+                if len(self._buffer) < MIN_PACKET_LEN:
+                    break
+
+            packet_type = self._buffer[1]
+            if packet_type not in VALID_PACKET_TYPES:
+                del self._buffer[0]
+                continue
+
+            payload_len = int.from_bytes(self._buffer[2:4], "little")
+            if payload_len > MAX_PAYLOAD_LEN:
+                del self._buffer[0]
+                continue
+
+            packet_len = HEADER_LEN + payload_len + CRC_LEN
+            if len(self._buffer) < packet_len:
+                break
+
+            packet_bytes = bytes(self._buffer[:packet_len])
+            crc_expected = int.from_bytes(packet_bytes[-2:], "little")
+            crc_data = packet_bytes[1:-2]
+            crc_actual = _crc16_ccitt_false(crc_data)
+
+            if crc_actual != crc_expected:
+                del self._buffer[0]
+                continue
+
+            packets.append(
+                Packet(
+                    packet_type=packet_bytes[1],
+                    timestamp_us=int.from_bytes(packet_bytes[4:12], "little"),
+                    payload=packet_bytes[12:-2],
+                )
+            )
+            del self._buffer[:packet_len]
+
+        return packets
+
+
+def parse_stream(data: bytes) -> list[Packet]:
+    """Parse a raw byte stream into protocol packets in one shot."""
+    return StreamParser().feed(data)
+
+
+def build_packet(packet_type: int, timestamp_us: int, payload: bytes) -> bytes:
+    payload_len = len(payload)
+    header = bytes([SYNC_BYTE, packet_type])
+    header += payload_len.to_bytes(2, "little")
+    header += int(timestamp_us).to_bytes(8, "little", signed=False)
+    crc = _crc16_ccitt_false(header[1:] + payload)
+    return header + payload + crc.to_bytes(2, "little")
+
+
+def build_set_camera_mode_command(mode_id: int, timestamp_us: int) -> bytes:
+    payload = bytes([CONTROL_CMD_SET_CAMERA_MODE, mode_id & 0xFF])
+    return build_packet(PACKET_TYPE_CONTROL_CMD, timestamp_us, payload)
+
+
+def build_set_stream_mode_command(mode_id: int, timestamp_us: int) -> bytes:
+    payload = bytes([CONTROL_CMD_SET_STREAM_MODE, mode_id & 0xFF])
+    return build_packet(PACKET_TYPE_CONTROL_CMD, timestamp_us, payload)
+
+
+def build_get_stream_stats_command(timestamp_us: int) -> bytes:
+    payload = bytes([CONTROL_CMD_GET_STREAM_STATS])
+    return build_packet(PACKET_TYPE_CONTROL_CMD, timestamp_us, payload)

esp32_stream-0.1.0/src/esp32_stream.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: esp32-stream
+Version: 0.1.0
+Summary: ESP32 serial stream protocol parser and frame source adapter
+Author: ESP32 Host Tooling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+Requires-Dist: numpy>=1.26
+Provides-Extra: opencv
+Requires-Dist: opencv-python>=4.10; extra == "opencv"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# esp32-stream
+
+Reusable Python package for ESP32 serial stream protocol parsing and camera frame assembly.
+
+This package is the source of truth for host-side stream handling used by calibration and other consumer projects.
+
+## Install
+
+```bash
+pip install esp32-stream
+```
+
+With OpenCV decode support:
+
+```bash
+pip install "esp32-stream[opencv]"
+```
+
+## Development Install
+
+From this folder:
+
+```bash
+pip install -e ".[dev,opencv]"
+pytest
+```
+
+## Public API
+
+- `esp32_stream.protocol`: packet constants, parser, command builders
+- `esp32_stream.board_profiles`: board defaults and aliases
+- `esp32_stream.esp32_frame_source`: `Esp32FrameSource`, `Esp32VideoCaptureAdapter`
+
+## Consumer Pinning (recommended)
+
+Pin exact versions in downstream projects:
+
+```txt
+esp32-stream==0.1.0
+```
+
+For local integration testing before release:
+
+```bash
+pip install -e /absolute/path/to/esp32/python/esp32_stream
+```
+
+Do not use editable installs for production or CI release branches.
+
+## Upgrade Workflow
+
+1. Update package in this repo on a feature branch.
+2. Run package tests (`pytest`).
+3. Run the consumer smoke test in each downstream project.
+4. Bump version and tag release.
+5. Update pinned version in each consumer project when ready.
+
+## Release
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Tag example:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```

esp32_stream-0.1.0/src/esp32_stream.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/esp32_stream/__init__.py
+src/esp32_stream/board_profiles.py
+src/esp32_stream/esp32_frame_source.py
+src/esp32_stream/protocol.py
+src/esp32_stream.egg-info/PKG-INFO
+src/esp32_stream.egg-info/SOURCES.txt
+src/esp32_stream.egg-info/dependency_links.txt
+src/esp32_stream.egg-info/requires.txt
+src/esp32_stream.egg-info/top_level.txt
+tests/test_board_profiles.py
+tests/test_frame_source.py
+tests/test_protocol.py

esp32_stream-0.1.0/src/esp32_stream.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

esp32_stream-0.1.0/src/esp32_stream.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pyserial>=3.5
+numpy>=1.26
+
+[dev]
+pytest>=8.0
+pytest-cov>=5.0
+
+[opencv]
+opencv-python>=4.10

esp32_stream-0.1.0/src/esp32_stream.egg-info/top_level.txt

@@ -0,0 +1 @@
+esp32_stream

esp32_stream-0.1.0/tests/test_board_profiles.py

@@ -0,0 +1,36 @@
+import pytest
+
+from esp32_stream.board_profiles import CAMERA_MODE_DIMENSIONS, get_board_profile
+from esp32_stream.esp32_frame_source import Esp32FrameSource
+
+
+def test_alias_resolution():
+    assert get_board_profile("s3").name == "esp32s3"
+    assert get_board_profile("p4").name == "esp32p4"
+
+
+def test_camera_mode_dimensions():
+    assert CAMERA_MODE_DIMENSIONS["dev_qvga"] == (320, 240)
+    assert CAMERA_MODE_DIMENSIONS["proc_lowres"] == (640, 400)
+
+
+def test_frame_source_uses_board_defaults():
+    src_s3 = Esp32FrameSource(board="esp32s3", serial_port=object())
+    assert src_s3.port == "/dev/cu.usbmodem1101"
+    assert src_s3.baud == 115200
+
+    src_p4 = Esp32FrameSource(board="esp32p4", serial_port=object())
+    assert src_p4.port == "/dev/cu.usbmodem1101"
+    assert src_p4.baud == 6000000
+
+
+def test_explicit_values_override_board_defaults():
+    src = Esp32FrameSource(port="/dev/tty.custom", baud=2000000, board="p4", serial_port=object())
+    assert src.port == "/dev/tty.custom"
+    assert src.baud == 2000000
+    assert src.board == "esp32p4"
+
+
+def test_unknown_board_raises():
+    with pytest.raises(ValueError):
+        get_board_profile("esp32-unknown")

esp32_stream-0.1.0/tests/test_frame_source.py

@@ -0,0 +1,110 @@
+from esp32_stream.board_profiles import CAMERA_MODE_DIMENSIONS
+from esp32_stream.esp32_frame_source import Esp32FrameSource, Esp32VideoCaptureAdapter
+from esp32_stream.protocol import (
+    CAMERA_MODE_DEV_QVGA,
+    PACKET_TYPE_FRAME_CHUNK,
+    PACKET_TYPE_FRAME_END,
+    PACKET_TYPE_FRAME_START,
+    build_packet,
+)
+
+
+class _FakeSerial:
+    def __init__(self, chunks):
+        self._chunks = list(chunks)
+        self.writes = []
+
+    def read(self, n):
+        del n
+        if not self._chunks:
+            return b""
+        return self._chunks.pop(0)
+
+    def write(self, data):
+        self.writes.append(bytes(data))
+        return len(data)
+
+    def flush(self):
+        return None
+
+    def close(self):
+        return None
+
+    def reset_input_buffer(self):
+        return None
+
+
+def _build_frame_packets(frame_id: int, payload: bytes):
+    capture_start_us = 1_000_000
+    capture_ready_us = 1_005_000
+    width, height = CAMERA_MODE_DIMENSIONS["dev_qvga"]
+
+    start_payload = bytearray()
+    start_payload.extend(frame_id.to_bytes(4, "little"))
+    start_payload.extend(capture_start_us.to_bytes(8, "little"))
+    start_payload.extend(capture_ready_us.to_bytes(8, "little"))
+    start_payload.extend(len(payload).to_bytes(4, "little"))
+    start_payload.extend(width.to_bytes(2, "little"))
+    start_payload.extend(height.to_bytes(2, "little"))
+    start_payload.append(CAMERA_MODE_DEV_QVGA)
+
+    chunk_payload = bytearray()
+    chunk_payload.extend(frame_id.to_bytes(4, "little"))
+    chunk_payload.extend((0).to_bytes(4, "little"))
+    chunk_payload.extend(payload)
+
+    end_payload = bytearray()
+    end_payload.extend(frame_id.to_bytes(4, "little"))
+    end_payload.extend(len(payload).to_bytes(4, "little"))
+    end_payload.extend((1).to_bytes(2, "little"))
+
+    return (
+        build_packet(PACKET_TYPE_FRAME_START, capture_ready_us, bytes(start_payload)),
+        build_packet(PACKET_TYPE_FRAME_CHUNK, capture_ready_us, bytes(chunk_payload)),
+        build_packet(PACKET_TYPE_FRAME_END, capture_ready_us, bytes(end_payload)),
+    )
+
+
+def test_read_returns_frame_and_timestamps():
+    jpeg_like_payload = b"\xff\xd8\xff\xd9"
+    p_start, p_chunk, p_end = _build_frame_packets(7, jpeg_like_payload)
+    fake = _FakeSerial([p_start + p_chunk + p_end])
+
+    src = Esp32FrameSource(serial_port=fake)
+
+    src._decode_jpeg = lambda b: {"decoded": b}  # type: ignore
+
+    ok, frame, meta = src.read(timeout_s=0.02)
+    assert ok
+    assert frame == {"decoded": jpeg_like_payload}
+    assert meta.frame_id == 7
+    assert meta.capture_start_us == 1_000_000
+    assert meta.capture_ready_us == 1_005_000
+    assert meta.packet_timestamp_us == 1_005_000
+    assert meta.frame_len_expected == len(jpeg_like_payload)
+    assert meta.frame_len_received == len(jpeg_like_payload)
+    assert meta.chunk_count == 1
+
+
+def test_cv2_adapter_read_and_metadata():
+    jpeg_like_payload = b"\xff\xd8\xff\xd9"
+    p_start, p_chunk, p_end = _build_frame_packets(13, jpeg_like_payload)
+    fake = _FakeSerial([p_start + p_chunk + p_end])
+
+    cap = Esp32VideoCaptureAdapter(serial_port=fake, auto_open=False)
+    assert not cap.isOpened()
+    assert cap.open()
+    assert cap.isOpened()
+
+    cap._source._decode_jpeg = lambda b: {"decoded": b}  # type: ignore
+
+    ok, frame = cap.read(timeout_s=0.02)
+    assert ok
+    assert frame == {"decoded": jpeg_like_payload}
+    assert cap.last_metadata is not None
+    assert cap.last_metadata.frame_id == 13
+    assert cap.get(3) == 320.0
+    assert cap.get(4) == 240.0
+
+    cap.release()
+    assert not cap.isOpened()

esp32_stream-0.1.0/tests/test_protocol.py

@@ -0,0 +1,90 @@
+from esp32_stream.protocol import (
+    MAX_PAYLOAD_LEN,
+    PACKET_TYPE_CONTROL_CMD,
+    PACKET_TYPE_IMU_SAMPLE,
+    PACKET_TYPE_STREAM_STATS,
+    StreamParser,
+    build_get_stream_stats_command,
+    build_packet,
+    build_set_camera_mode_command,
+    build_set_stream_mode_command,
+    parse_stream,
+)
+
+
+def test_parse_valid_packet():
+    payload = bytes([1, 2, 3, 4])
+    ts = 123456789
+    raw = build_packet(PACKET_TYPE_IMU_SAMPLE, ts, payload)
+
+    packets = parse_stream(raw)
+    assert len(packets) == 1
+    assert packets[0].packet_type == PACKET_TYPE_IMU_SAMPLE
+    assert packets[0].timestamp_us == ts
+    assert packets[0].payload == payload
+
+
+def test_crc_error_drops_packet():
+    raw = bytearray(build_packet(PACKET_TYPE_IMU_SAMPLE, 42, b"abc"))
+    raw[-1] ^= 0xFF
+    packets = parse_stream(bytes(raw))
+    assert packets == []
+
+
+def test_truncated_packet_waits_for_more():
+    payload = b"hello"
+    raw = build_packet(PACKET_TYPE_IMU_SAMPLE, 1, payload)
+
+    parser = StreamParser()
+    partial = raw[:-2]
+    assert parser.feed(partial) == []
+
+    packets = parser.feed(raw[-2:])
+    assert len(packets) == 1
+    assert packets[0].payload == payload
+
+
+def test_resync_after_noise():
+    pkt1 = build_packet(PACKET_TYPE_IMU_SAMPLE, 10, b"imu")
+    pkt2 = build_packet(PACKET_TYPE_CONTROL_CMD, 11, bytes([1, 0]))
+    raw = b"\x00\xFF\x13\x37" + pkt1 + b"\x99\x98" + pkt2
+
+    packets = parse_stream(raw)
+    assert len(packets) == 2
+    assert packets[0].payload == b"imu"
+    assert packets[1].packet_type == PACKET_TYPE_CONTROL_CMD
+
+
+def test_oversized_payload_len_is_rejected():
+    parser = StreamParser()
+    header = bytearray()
+    header.append(0xAA)
+    header.append(PACKET_TYPE_IMU_SAMPLE)
+    header.extend((MAX_PAYLOAD_LEN + 1).to_bytes(2, "little"))
+    header.extend((0).to_bytes(8, "little"))
+
+    raw = bytes(header) + b"\x00\x00" + build_packet(PACKET_TYPE_IMU_SAMPLE, 5, b"a")
+    packets = parser.feed(raw)
+    assert len(packets) == 1
+    assert packets[0].timestamp_us == 5
+
+
+def test_stream_stats_type_is_accepted():
+    raw = build_packet(PACKET_TYPE_STREAM_STATS, 77, b"abc")
+    packets = parse_stream(raw)
+    assert len(packets) == 1
+    assert packets[0].packet_type == PACKET_TYPE_STREAM_STATS
+
+
+def test_control_command_builders_emit_control_packets():
+    a = build_set_camera_mode_command(0, 111)
+    b = build_set_stream_mode_command(0, 222)
+    c = build_get_stream_stats_command(333)
+
+    pa = parse_stream(a)[0]
+    pb = parse_stream(b)[0]
+    pc = parse_stream(c)[0]
+
+    assert pa.packet_type == PACKET_TYPE_CONTROL_CMD
+    assert pb.packet_type == PACKET_TYPE_CONTROL_CMD
+    assert pc.packet_type == PACKET_TYPE_CONTROL_CMD