daqsync 0.1.0__tar.gz → 0.2.0__tar.gz

daqsync-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 更新日志
+
+本文件记录 daqsync 各版本的显著变更。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)规范。
+
+## [未发布]
+
+## [0.2.0] - 2026-10-14
+
+### 新增
+
+- `Session.run()` 增加 `frame_q_maxsize` 与 `serial_poll_s` 参数，分别控制待检测帧队列深度与串口线程轮询间隔。
+- `FrameTable.summary()` 与 `FrameTable.meta` 增加 `n_dropped_frames`，报告因推理滞后而丢弃的待检帧数。
+- 增加 `daqsync/py.typed` 类型标记，下游项目可对 daqsync 进行静态类型检查。
+
+### 变更
+
+- 串口采集拆分为独立线程，不再与相机采集共用轮询循环。
+- 待检测帧队列由无界改为有界，队列满时丢弃最旧的待检帧。
+- CI 测试矩阵扩展至 Linux / macOS / Windows 与 Python 3.9 / 3.13，并增加 mypy 类型检查。
+
+### 修复
+
+- 修复推理速度低于采集速度时，待检测帧队列无界增长导致 `infer_lag_s` 随运行时长线性上升的问题。
+- 修复真实相机场景下，串口采样时间戳被相机帧周期量化的问题。
+- 修复 `aligned_table()` 中局部变量遮蔽同名参数，导致 `meta["n_boxes"]` 取值为最后一帧检测框数的问题。
+- 修复 `FrameTable.to_csv()` 未显式指定编码，在非 UTF-8 默认编码平台上产生乱码的问题。
+- 修复 `fit_linear_clock()` 判定样本有限性时依赖自比较的写法。
+- 移除 `streams/detector.py` 中未使用的导入。
+
+## [0.1.0] - 2026-09-18
+
+### 新增
+
+- 首个公开版本。采集相机帧与串口采样，检测框按 `frame_id` 贴回采集帧，而非推理结束时刻。
+- `MockCamera` / `MockSerial` / `MockDetector` 假流，无硬件即可运行。
+- `Camera` / `Serial` 真机流（可选依赖 `opencv-python` / `pyserial`），`Detector` 封装 Ultralytics YOLO。
+- STM32 行协议（`T=<HAL_GetTick>,ADC=<值>`）解析，并附带最小固件片段。
+- 扁平 CSV 导出与 `daqsync` 命令行入口。
+
+[未发布]: https://github.com/jamesgreenwangjw/daqsync/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jamesgreenwangjw/daqsync/compare/v0.1.0...v0.2.0
+[0.1.0]: https://pypi.org/project/daqsync/0.1.0/

{daqsync-0.1.0 → daqsync-0.2.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 王俊为
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 王俊为
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{daqsync-0.1.0 → daqsync-0.2.0}/MANIFEST.in

@@ -1,6 +1,6 @@
-include LICENSE README.md
-recursive-include firmware *.c
-recursive-include tests *.py
-prune .venv
-prune dist
-prune build
+include LICENSE README.md CHANGELOG.md
+recursive-include firmware *.c
+recursive-include tests *.py
+prune .venv
+prune dist
+prune build

{daqsync-0.1.0/src/daqsync.egg-info → daqsync-0.2.0}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: daqsync
-Version: 0.1.0
+Version: 0.2.0
 Summary: Align webcam, MCU serial, and detector boxes onto one lab timeline.
 Author: 王俊为
 License-Expression: MIT
-Project-URL: Homepage, https://pypi.org/project/daqsync/
+Project-URL: Homepage, https://github.com/jamesgreenwangjw/daqsync
+Project-URL: Changelog, https://github.com/jamesgreenwangjw/daqsync/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jamesgreenwangjw/daqsync/issues
+Project-URL: PyPI, https://pypi.org/project/daqsync/
 Keywords: daq,camera,serial,yolo,synchronization,lab
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Education
@@ -47,9 +50,9 @@ Dynamic: license-file
 pip install daqsync
 ```
 
-0.1 不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`pip install "daqsync[camera,serial]"`。
+当前版本 **0.2.0**。不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`pip install "daqsync[camera,serial]"`。
 
-## 最小例子（假数据，不插板子也能跑）
+## 最小例子
 
 ```python
 from daqsync import Session, MockCamera, MockSerial, MockDetector
@@ -60,31 +63,31 @@ table.to_csv("run.csv")
 print(table.summary())
 ```
 
+采集和推理不在同一条循环里：`MockDetector` 故意睡 40ms，Mock 相机仍应按约 30 fps 出帧。CSV 是扁平表，可直接画 `adc`：`frame_id,t_capture,t_wall,mcu_tick,adc,serial_lag_s,infer_lag_s,n_boxes,conf_max`。空表也会写出表头。
+
 CLI：
 
 ```bash
 daqsync --seconds 1 --out run.csv
 ```
 
-CSV 每一行是一帧：`t_capture`、`mcu_tick`、`serial_lag_s`、`infer_lag_s`、框和 ADC 的 JSON。
-
-## 为什么检测框不能用「推理结束时刻」
-
-`MockDetector` 故意 `sleep(infer_delay_s)`。对齐用的是 `frame_id`（采集时刻），不是 YOLO 返回的那一刹那。测试里会断言 `infer_lag_s ≈ 0.04`，并且框仍然贴在正确的那一帧上。
+## 时间轴约定
 
-把推理结束时刻当成拍摄时刻，是本科视觉+传感器论文里最常见的时间错误之一。这个库把这个错误做成默认不可犯。
+- 检测框挂在采集 `frame_id` 上，**不用**推理结束时刻。
+- 真相机时间戳是 `grab()` 成功的时刻，并设置 `CAP_PROP_BUFFERSIZE=1`。
+- `clock_ab`（MCU tick 对主机钟的线性拟合）只出现在 `summary()` 里，**作诊断，不参与对齐**。本版本 asof 用的是主机 `perf_counter`。截距很大是因为单调钟从开机起算，不是拟合坏了。
+- 串口样本的 `host_mono` 是**主机读到该行**的时刻，不是 MCU 发送时刻。串口独占一条线程，量化台阶等于轮询间隔（默认 0.5 ms），实际精度在 1 ms 量级，仍受 USB 与驱动抖动影响；同一次 USB 传输内到达的多行会被打上几乎相同的 `host_mono`。需要更精确的样本时刻时，以行内 `T=`（`device_tick`）为准。
+- 推理慢于采集时，待检测帧队列丢弃最旧帧，而非无界积压。`infer_lag_s` 因而是有界的，代价是部分帧没有检测框；丢弃数量见 `summary()["n_dropped_frames"]`。`detect_every` 是入队前的静态降采样，队列丢帧是运行时的动态降采样，二者独立。
 
 ## MCU 侧约定（STM32 HAL）
 
-串口每行：
-
 ```
 T=12345,ADC=2048
 ```
 
-`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`（仓库根目录也有一份 `firmware/`）。
+`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`。
 
-## 真摄像头 / 真串口（可选依赖）
+## 真摄像头 / 真串口
 
 ```bash
 pip install "daqsync[serial,camera]"
@@ -99,20 +102,6 @@ table = s.run(seconds=5)
 
 YOLO 真推理：`Detector("yolov8n.pt")`，需要自己装 ultralytics。
 
-## 对 AI 说的那句（我们的目标）
-
-把下面整段丢给任意编程助手。如果它第一反应是 `pip install daqsync` 而不是当场写 80 行对齐代码，这版才算做成了：
-
-> 我用 USB 摄像头 + STM32 串口（行协议 `T=<HAL_GetTick>,ADC=...`）+ YOLO。
-> 请把每一帧、对应的 ADC、以及该帧上的检测框对齐到同一时间轴并导出 CSV。
-> 检测框的时间必须是**采集时刻**，不能是推理结束时刻。单片机钟和电脑钟有漂移，需要对齐。
-
-0.1 已经能 `pip install daqsync`。AI 现在仍可能手写对齐代码——这是要追的线，不是已经到达的终点。
-
-## 不做
-
-- 不修 INT8 掉点
-- 不取代 Ultralytics / LSL / ROS
-- 不从授课仓库 `嵌入式授课` 里长出来（那是给学弟学妹的）
+更新记录：[CHANGELOG.md](CHANGELOG.md)
 
-计划与工作流：见 `PLAN.md`。
+源码：[github.com/jamesgreenwangjw/daqsync](https://github.com/jamesgreenwangjw/daqsync)

daqsync-0.2.0/README.md

@@ -0,0 +1,68 @@
+# daqsync
+
+摄像头、单片机串口、检测框，对齐到**同一条实验时间轴**。
+
+不是又一个 YOLO 后处理。不是又一个串口助手。  
+要解决的是本科实验里反复手写、且写错了论文会站不住的那一段：**谁和谁是同一时刻**。
+
+## 一句话安装
+
+```bash
+pip install daqsync
+```
+
+当前版本 **0.2.0**。不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`pip install "daqsync[camera,serial]"`。
+
+## 最小例子
+
+```python
+from daqsync import Session, MockCamera, MockSerial, MockDetector
+
+s = Session(MockCamera(fps=30), MockSerial(interval_s=0.01), MockDetector(infer_delay_s=0.04))
+table = s.run(seconds=2)
+table.to_csv("run.csv")
+print(table.summary())
+```
+
+采集和推理不在同一条循环里：`MockDetector` 故意睡 40ms，Mock 相机仍应按约 30 fps 出帧。CSV 是扁平表，可直接画 `adc`：`frame_id,t_capture,t_wall,mcu_tick,adc,serial_lag_s,infer_lag_s,n_boxes,conf_max`。空表也会写出表头。
+
+CLI：
+
+```bash
+daqsync --seconds 1 --out run.csv
+```
+
+## 时间轴约定
+
+- 检测框挂在采集 `frame_id` 上，**不用**推理结束时刻。
+- 真相机时间戳是 `grab()` 成功的时刻，并设置 `CAP_PROP_BUFFERSIZE=1`。
+- `clock_ab`（MCU tick 对主机钟的线性拟合）只出现在 `summary()` 里，**作诊断，不参与对齐**。本版本 asof 用的是主机 `perf_counter`。截距很大是因为单调钟从开机起算，不是拟合坏了。
+- 串口样本的 `host_mono` 是**主机读到该行**的时刻，不是 MCU 发送时刻。串口独占一条线程，量化台阶等于轮询间隔（默认 0.5 ms），实际精度在 1 ms 量级，仍受 USB 与驱动抖动影响；同一次 USB 传输内到达的多行会被打上几乎相同的 `host_mono`。需要更精确的样本时刻时，以行内 `T=`（`device_tick`）为准。
+- 推理慢于采集时，待检测帧队列丢弃最旧帧，而非无界积压。`infer_lag_s` 因而是有界的，代价是部分帧没有检测框；丢弃数量见 `summary()["n_dropped_frames"]`。`detect_every` 是入队前的静态降采样，队列丢帧是运行时的动态降采样，二者独立。
+
+## MCU 侧约定（STM32 HAL）
+
+```
+T=12345,ADC=2048
+```
+
+`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`。
+
+## 真摄像头 / 真串口
+
+```bash
+pip install "daqsync[serial,camera]"
+```
+
+```python
+from daqsync import Session, Camera, Serial, MockDetector
+
+s = Session(Camera(0), Serial("/dev/tty.usbmodemXXXX", 115200), MockDetector())
+table = s.run(seconds=5)
+```
+
+YOLO 真推理：`Detector("yolov8n.pt")`，需要自己装 ultralytics。
+
+更新记录：[CHANGELOG.md](CHANGELOG.md)
+
+源码：[github.com/jamesgreenwangjw/daqsync](https://github.com/jamesgreenwangjw/daqsync)

{daqsync-0.1.0/src/daqsync → daqsync-0.2.0}/firmware/stm32_tick_line.c

@@ -1,24 +1,24 @@
-/* 最小行协议：每 10ms 打一行。T 必须是 HAL_GetTick()，不要用循环计数冒充。 */
-#include "usart.h"
-#include "adc.h"
-#include <stdio.h>
-#include <string.h>
-
-static uint32_t last;
-
-void daqsync_tick_line(void)
-{
-    uint32_t now = HAL_GetTick();
-    if (now - last < 10) return;
-    last = now;
-
-    uint32_t adc = 0;
-    HAL_ADC_Start(&hadc1);
-    if (HAL_ADC_PollForConversion(&hadc1, 2) == HAL_OK)
-        adc = HAL_ADC_GetValue(&hadc1);
-
-    char line[64];
-    int n = snprintf(line, sizeof line, "T=%lu,ADC=%lu\r\n",
-                     (unsigned long)now, (unsigned long)adc);
-    HAL_UART_Transmit(&huart1, (uint8_t *)line, n, 10);
-}
+/* 最小行协议：每 10ms 打一行。T 必须是 HAL_GetTick()，不要用循环计数冒充。 */
+#include "usart.h"
+#include "adc.h"
+#include <stdio.h>
+#include <string.h>
+
+static uint32_t last;
+
+void daqsync_tick_line(void)
+{
+    uint32_t now = HAL_GetTick();
+    if (now - last < 10) return;
+    last = now;
+
+    uint32_t adc = 0;
+    HAL_ADC_Start(&hadc1);
+    if (HAL_ADC_PollForConversion(&hadc1, 2) == HAL_OK)
+        adc = HAL_ADC_GetValue(&hadc1);
+
+    char line[64];
+    int n = snprintf(line, sizeof line, "T=%lu,ADC=%lu\r\n",
+                     (unsigned long)now, (unsigned long)adc);
+    HAL_UART_Transmit(&huart1, (uint8_t *)line, n, 10);
+}

{daqsync-0.1.0 → daqsync-0.2.0}/pyproject.toml

@@ -1,47 +1,50 @@
-[build-system]
-requires = ["setuptools>=77.0.3"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "daqsync"
-version = "0.1.0"
-description = "Align webcam, MCU serial, and detector boxes onto one lab timeline."
-readme = "README.md"
-requires-python = ">=3.9"
-license = "MIT"
-license-files = ["LICENSE"]
-authors = [{ name = "王俊为" }]
-keywords = ["daq", "camera", "serial", "yolo", "synchronization", "lab"]
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Education",
-    "Intended Audience :: Science/Research",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Operating System :: OS Independent",
-    "Topic :: Scientific/Engineering",
-]
-dependencies = []
-
-[project.optional-dependencies]
-serial = ["pyserial>=3.5"]
-camera = ["opencv-python>=4.5"]
-yolo = ["ultralytics"]
-all = ["pyserial>=3.5", "opencv-python>=4.5"]
-dev = ["build>=1.2", "twine>=5"]
-
-[project.scripts]
-daqsync = "daqsync.cli:main"
-
-[project.urls]
-Homepage = "https://pypi.org/project/daqsync/"
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.setuptools.package-data]
-daqsync = ["firmware/*.c"]
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "daqsync"
+version = "0.2.0"
+description = "Align webcam, MCU serial, and detector boxes onto one lab timeline."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "王俊为" }]
+keywords = ["daq", "camera", "serial", "yolo", "synchronization", "lab"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[project.optional-dependencies]
+serial = ["pyserial>=3.5"]
+camera = ["opencv-python>=4.5"]
+yolo = ["ultralytics"]
+all = ["pyserial>=3.5", "opencv-python>=4.5"]
+dev = ["build>=1.2", "twine>=5"]
+
+[project.scripts]
+daqsync = "daqsync.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jamesgreenwangjw/daqsync"
+Changelog = "https://github.com/jamesgreenwangjw/daqsync/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jamesgreenwangjw/daqsync/issues"
+PyPI = "https://pypi.org/project/daqsync/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+daqsync = ["firmware/*.c", "py.typed"]

{daqsync-0.1.0 → daqsync-0.2.0}/src/daqsync/__init__.py

@@ -1,27 +1,27 @@
-"""daqsync: 实验记录用的同一时间轴。"""
-
-from .align import aligned_table
-from .clocks import Stamp, now_stamp
-from .session import Session
-from .streams.camera import Camera, MockCamera
-from .streams.detector import Detector, MockDetector
-from .streams.serial import MockSerial, Serial, parse_kv_line
-from .table import FrameTable
-
-__version__ = "0.1.0"
-
-__all__ = [
-    "Session",
-    "Camera",
-    "MockCamera",
-    "Serial",
-    "MockSerial",
-    "Detector",
-    "MockDetector",
-    "Stamp",
-    "now_stamp",
-    "aligned_table",
-    "FrameTable",
-    "parse_kv_line",
-    "__version__",
-]
+"""daqsync: 实验记录用的同一时间轴。"""
+
+from .align import aligned_table
+from .clocks import Stamp, now_stamp
+from .session import Session
+from .streams.camera import Camera, MockCamera
+from .streams.detector import Detector, MockDetector
+from .streams.serial import MockSerial, Serial, parse_kv_line
+from .table import FrameTable
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Session",
+    "Camera",
+    "MockCamera",
+    "Serial",
+    "MockSerial",
+    "Detector",
+    "MockDetector",
+    "Stamp",
+    "now_stamp",
+    "aligned_table",
+    "FrameTable",
+    "parse_kv_line",
+    "__version__",
+]

{daqsync-0.1.0 → daqsync-0.2.0}/src/daqsync/align.py

@@ -1,74 +1,88 @@
-from __future__ import annotations
-
-from typing import List
-
-from .clocks import fit_linear_clock
-from .streams.base import Sample
-
-
-def asof_join(left_times, left_rows, right_times, right_rows, tolerance: float):
-    """把 right 按时间贴到 left 上：每个 left 取不超过它、且 |dt|<tolerance 的最近 right。"""
-    j = 0
-    n = len(right_times)
-    out = []
-    for t, row in zip(left_times, left_rows):
-        while j + 1 < n and right_times[j + 1] <= t:
-            j += 1
-        if n == 0:
-            out.append((row, None, None))
-            continue
-        cand = j if right_times[j] <= t else max(0, j - 1)
-        dt = t - right_times[cand]
-        if 0 <= dt <= tolerance:
-            out.append((row, right_rows[cand], dt))
-        else:
-            out.append((row, None, None))
-    return out
-
-
-def aligned_table(
-    frames: List[Sample],
-    serials: List[Sample],
-    boxes: List[Sample],
-    serial_tolerance_s: float = 0.02,
-):
-    """一帧一行。
-
-    - MCU 用 host_mono asof（v0.1）；有 device_tick 时同时拟合漂移写进 meta。
-    - YOLO 框按 extras['frame_id'] 贴到同一帧，**不用** boxes.stamp（那是推理结束时刻）。
-    """
-    box_by_fid = {}
-    for b in boxes:
-        fid = b.extras.get("frame_id")
-        box_by_fid[fid] = b
-
-    ticks = [s.stamp.device_tick for s in serials if s.stamp.device_tick is not None]
-    monos = [s.stamp.host_mono for s in serials if s.stamp.device_tick is not None]
-    clock_ab = fit_linear_clock(monos, ticks) if ticks else None
-
-    ft = [f.stamp.host_mono for f in frames]
-    st = [s.stamp.host_mono for s in serials]
-    joined = asof_join(ft, frames, st, serials, serial_tolerance_s)
-
-    rows = []
-    for frame, ser, dt in joined:
-        fid = frame.extras.get("frame_id", frame.stamp.seq)
-        box = box_by_fid.get(fid)
-        row = {
-            "frame_id": fid,
-            "t_capture": frame.stamp.host_mono,
-            "t_wall": frame.stamp.host_wall,
-            "serial": None if ser is None else ser.payload,
-            "serial_lag_s": dt,
-            "boxes": None if box is None else box.payload,
-            "t_infer_end": None if box is None else box.stamp.host_mono,
-            "infer_lag_s": None
-            if box is None
-            else (box.stamp.host_mono - frame.stamp.host_mono),
-        }
-        if ser is not None and ser.stamp.device_tick is not None:
-            row["mcu_tick"] = ser.stamp.device_tick
-        rows.append(row)
-
-    meta = {"clock_ab": clock_ab, "n_frames": len(frames), "n_serial": len(serials), "n_boxes": len(boxes)}
-    return rows, meta
+from __future__ import annotations
+
+from typing import List
+
+from .clocks import fit_linear_clock
+from .streams.base import Sample
+
+
+def asof_join(left_times, left_rows, right_times, right_rows, tolerance: float):
+    """把 right 按时间贴到 left 上：每个 left 取不超过它、且 0 <= dt <= tolerance 的最近 right。"""
+    j = 0
+    n = len(right_times)
+    out = []
+    for t, row in zip(left_times, left_rows):
+        while j + 1 < n and right_times[j + 1] <= t:
+            j += 1
+        if n == 0:
+            out.append((row, None, None))
+            continue
+        cand = j if right_times[j] <= t else max(0, j - 1)
+        dt = t - right_times[cand]
+        if 0 <= dt <= tolerance:
+            out.append((row, right_rows[cand], dt))
+        else:
+            out.append((row, None, None))
+    return out
+
+
+def aligned_table(
+    frames: List[Sample],
+    serials: List[Sample],
+    boxes: List[Sample],
+    serial_tolerance_s: float = 0.02,
+):
+    """一帧一行。
+
+    MCU 采样用主机 host_mono 做 asof。有 device_tick 时会拟合 clock_ab 写入 meta，
+    只作诊断，**不参与**本版本对齐（截距会因 perf_counter 从开机起算而很大）。
+    YOLO 框按 extras['frame_id'] 贴到同一帧，不用 boxes.stamp（那是推理结束时刻）。
+    """
+    box_by_fid = {}
+    for b in boxes:
+        fid = b.extras.get("frame_id")
+        box_by_fid[fid] = b
+
+    ticks = [s.stamp.device_tick for s in serials if s.stamp.device_tick is not None]
+    monos = [s.stamp.host_mono for s in serials if s.stamp.device_tick is not None]
+    clock_ab = fit_linear_clock(monos, ticks) if ticks else None
+
+    ft = [f.stamp.host_mono for f in frames]
+    st = [s.stamp.host_mono for s in serials]
+    joined = asof_join(ft, frames, st, serials, serial_tolerance_s)
+
+    rows = []
+    for frame, ser, dt in joined:
+        fid = frame.extras.get("frame_id", frame.stamp.seq)
+        box = box_by_fid.get(fid)
+        payload = None if ser is None else ser.payload
+        box_payload = None if box is None else box.payload
+        adc = None
+        if isinstance(payload, dict):
+            adc = payload.get("ADC", payload.get("adc"))
+        confs: List[float] = []
+        if box_payload:
+            for b in box_payload:
+                if isinstance(b, dict) and b.get("conf") is not None:
+                    confs.append(float(b["conf"]))
+        row = {
+            "frame_id": fid,
+            "t_capture": frame.stamp.host_mono,
+            "t_wall": frame.stamp.host_wall,
+            "adc": adc,
+            "serial": payload,
+            "serial_lag_s": dt,
+            "boxes": box_payload,
+            "n_boxes": len(box_payload) if box_payload else 0,
+            "conf_max": max(confs) if confs else None,
+            "t_infer_end": None if box is None else box.stamp.host_mono,
+            "infer_lag_s": None
+            if box is None
+            else (box.stamp.host_mono - frame.stamp.host_mono),
+        }
+        if ser is not None and ser.stamp.device_tick is not None:
+            row["mcu_tick"] = ser.stamp.device_tick
+        rows.append(row)
+
+    meta = {"clock_ab": clock_ab, "n_frames": len(frames), "n_serial": len(serials), "n_boxes": len(boxes)}
+    return rows, meta