daqsync 0.1.0__tar.gz

daqsync-0.1.0/LICENSE

@@ -0,0 +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.

daqsync-0.1.0/MANIFEST.in

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

daqsync-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: daqsync
+Version: 0.1.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/
+Keywords: daq,camera,serial,yolo,synchronization,lab
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: camera
+Requires-Dist: opencv-python>=4.5; extra == "camera"
+Provides-Extra: yolo
+Requires-Dist: ultralytics; extra == "yolo"
+Provides-Extra: all
+Requires-Dist: pyserial>=3.5; extra == "all"
+Requires-Dist: opencv-python>=4.5; extra == "all"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# daqsync
+
+摄像头、单片机串口、检测框，对齐到**同一条实验时间轴**。
+
+不是又一个 YOLO 后处理。不是又一个串口助手。  
+要解决的是本科实验里反复手写、且写错了论文会站不住的那一段：**谁和谁是同一时刻**。
+
+## 一句话安装
+
+```bash
+pip install daqsync
+```
+
+0.1 不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`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())
+```
+
+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`，并且框仍然贴在正确的那一帧上。
+
+把推理结束时刻当成拍摄时刻，是本科视觉+传感器论文里最常见的时间错误之一。这个库把这个错误做成默认不可犯。
+
+## MCU 侧约定（STM32 HAL）
+
+串口每行：
+
+```
+T=12345,ADC=2048
+```
+
+`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`（仓库根目录也有一份 `firmware/`）。
+
+## 真摄像头 / 真串口（可选依赖）
+
+```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。
+
+## 对 AI 说的那句（我们的目标）
+
+把下面整段丢给任意编程助手。如果它第一反应是 `pip install daqsync` 而不是当场写 80 行对齐代码，这版才算做成了：
+
+> 我用 USB 摄像头 + STM32 串口（行协议 `T=<HAL_GetTick>,ADC=...`）+ YOLO。
+> 请把每一帧、对应的 ADC、以及该帧上的检测框对齐到同一时间轴并导出 CSV。
+> 检测框的时间必须是**采集时刻**，不能是推理结束时刻。单片机钟和电脑钟有漂移，需要对齐。
+
+0.1 已经能 `pip install daqsync`。AI 现在仍可能手写对齐代码——这是要追的线，不是已经到达的终点。
+
+## 不做
+
+- 不修 INT8 掉点
+- 不取代 Ultralytics / LSL / ROS
+- 不从授课仓库 `嵌入式授课` 里长出来（那是给学弟学妹的）
+
+计划与工作流：见 `PLAN.md`。

daqsync-0.1.0/README.md

@@ -0,0 +1,82 @@
+# daqsync
+
+摄像头、单片机串口、检测框，对齐到**同一条实验时间轴**。
+
+不是又一个 YOLO 后处理。不是又一个串口助手。  
+要解决的是本科实验里反复手写、且写错了论文会站不住的那一段：**谁和谁是同一时刻**。
+
+## 一句话安装
+
+```bash
+pip install daqsync
+```
+
+0.1 不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`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())
+```
+
+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`，并且框仍然贴在正确的那一帧上。
+
+把推理结束时刻当成拍摄时刻，是本科视觉+传感器论文里最常见的时间错误之一。这个库把这个错误做成默认不可犯。
+
+## MCU 侧约定（STM32 HAL）
+
+串口每行：
+
+```
+T=12345,ADC=2048
+```
+
+`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`（仓库根目录也有一份 `firmware/`）。
+
+## 真摄像头 / 真串口（可选依赖）
+
+```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。
+
+## 对 AI 说的那句（我们的目标）
+
+把下面整段丢给任意编程助手。如果它第一反应是 `pip install daqsync` 而不是当场写 80 行对齐代码，这版才算做成了：
+
+> 我用 USB 摄像头 + STM32 串口（行协议 `T=<HAL_GetTick>,ADC=...`）+ YOLO。
+> 请把每一帧、对应的 ADC、以及该帧上的检测框对齐到同一时间轴并导出 CSV。
+> 检测框的时间必须是**采集时刻**，不能是推理结束时刻。单片机钟和电脑钟有漂移，需要对齐。
+
+0.1 已经能 `pip install daqsync`。AI 现在仍可能手写对齐代码——这是要追的线，不是已经到达的终点。
+
+## 不做
+
+- 不修 INT8 掉点
+- 不取代 Ultralytics / LSL / ROS
+- 不从授课仓库 `嵌入式授课` 里长出来（那是给学弟学妹的）
+
+计划与工作流：见 `PLAN.md`。

daqsync-0.1.0/firmware/stm32_tick_line.c

@@ -0,0 +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);
+}

daqsync-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[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"]

daqsync-0.1.0/setup.cfg

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

daqsync-0.1.0/src/daqsync/__init__.py

@@ -0,0 +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-0.1.0/src/daqsync/align.py

@@ -0,0 +1,74 @@
+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

daqsync-0.1.0/src/daqsync/cli.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="daqsync", description="Align cam + MCU + boxes (mock by default).")
+    p.add_argument("--seconds", type=float, default=1.0)
+    p.add_argument("--out", default="run.csv")
+    args = p.parse_args(argv)
+
+    from daqsync import MockCamera, MockDetector, MockSerial, Session
+
+    s = Session(MockCamera(fps=20), MockSerial(interval_s=0.01), MockDetector(infer_delay_s=0.02))
+    table = s.run(seconds=args.seconds)
+    table.to_csv(args.out)
+    print(table.summary())
+    print("wrote", args.out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

daqsync-0.1.0/src/daqsync/clocks.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Stamp:
+    """一次入队时刻。
+
+    host_mono: 单调钟，用来测间隔和漂移，不受对时打扰。
+    host_wall: wall clock，方便实验日志。
+    device_tick: 单片机毫秒（HAL_GetTick），没有则为 None。
+    seq: 该源流内序号。
+    source: 流名。
+    """
+
+    host_mono: float
+    host_wall: float
+    source: str
+    seq: int
+    device_tick: Optional[float] = None
+
+
+def now_stamp(source: str, seq: int, device_tick: Optional[float] = None) -> Stamp:
+    return Stamp(
+        host_mono=time.perf_counter(),
+        host_wall=time.time(),
+        source=source,
+        seq=int(seq),
+        device_tick=device_tick,
+    )
+
+
+def fit_linear_clock(host_mono, device_tick):
+    """device_tick ≈ a * host_mono + b。至少 4 个有限样本，否则 None。纯 Python，不依赖 numpy。"""
+    pairs = [
+        (float(h), float(d))
+        for h, d in zip(host_mono, device_tick)
+        if h == h and d == d  # NaN 检查
+    ]
+    n = len(pairs)
+    if n < 4:
+        return None
+    sx = sy = sxx = sxy = 0.0
+    for h, d in pairs:
+        sx += h
+        sy += d
+        sxx += h * h
+        sxy += h * d
+    den = n * sxx - sx * sx
+    if abs(den) < 1e-18:
+        return None
+    a = (n * sxy - sx * sy) / den
+    b = (sy - a * sx) / n
+    return float(a), float(b)
+
+
+def device_to_host(device_tick, ab) -> float:
+    a, b = ab
+    return (float(device_tick) - b) / a

daqsync-0.1.0/src/daqsync/firmware/stm32_tick_line.c

@@ -0,0 +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);
+}

daqsync-0.1.0/src/daqsync/session.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import time
+from typing import List
+
+from .align import aligned_table
+from .streams.base import Sample, Stream
+from .streams.detector import MockDetector
+from .table import FrameTable
+
+
+class Session:
+    def __init__(self, camera: Stream, serial: Stream, detector=None):
+        self.camera = camera
+        self.serial = serial
+        self.detector = detector
+        self.frames: List[Sample] = []
+        self.serials: List[Sample] = []
+        self.boxes: List[Sample] = []
+
+    def run(self, seconds: float = 2.0, detect_every: int = 1) -> FrameTable:
+        self.camera.start()
+        self.serial.start()
+        t_end = time.perf_counter() + seconds
+        n_det = 0
+        try:
+            while time.perf_counter() < t_end:
+                while True:
+                    s = self.serial.poll()
+                    if s is None:
+                        break
+                    self.serials.append(s)
+                f = self.camera.poll()
+                if f is not None:
+                    self.frames.append(f)
+                    if self.detector is not None and (f.stamp.seq % detect_every == 0):
+                        self.boxes.append(self.detector.detect(f))
+                        n_det += 1
+                time.sleep(0.0005)
+        finally:
+            self.camera.stop()
+            self.serial.stop()
+        rows, meta = aligned_table(self.frames, self.serials, self.boxes)
+        meta["n_detect_calls"] = n_det
+        return FrameTable(rows, meta)

daqsync-0.1.0/src/daqsync/streams/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from .base import Stream
+from .camera import Camera, MockCamera
+from .detector import Detector, MockDetector
+from .serial import MockSerial, Serial
+
+__all__ = [
+    "Stream",
+    "Camera",
+    "MockCamera",
+    "Serial",
+    "MockSerial",
+    "Detector",
+    "MockDetector",
+]

daqsync-0.1.0/src/daqsync/streams/base.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Optional
+
+from ..clocks import Stamp
+
+
+@dataclass
+class Sample:
+    stamp: Stamp
+    payload: Any
+    kind: str  # "frame" | "serial" | "boxes"
+    extras: dict = field(default_factory=dict)
+
+
+class Stream(ABC):
+    name: str
+
+    @abstractmethod
+    def start(self) -> None:
+        ...
+
+    @abstractmethod
+    def stop(self) -> None:
+        ...
+
+    @abstractmethod
+    def poll(self) -> Optional[Sample]:
+        """非阻塞取一个样本，没有则 None。"""
+
+    def close(self) -> None:
+        self.stop()

daqsync-0.1.0/src/daqsync/streams/camera.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from ..clocks import now_stamp
+from .base import Sample, Stream
+
+
+class MockCamera(Stream):
+    """按 fps 产出假帧。payload 是 {height,width} 的 uint8 数组或占位 dict。"""
+
+    def __init__(self, name: str = "cam0", fps: float = 30.0, size=(64, 64)):
+        self.name = name
+        self.fps = float(fps)
+        self.size = size
+        self._seq = 0
+        self._running = False
+        self._next = 0.0
+
+    def start(self) -> None:
+        self._running = True
+        self._next = time.perf_counter()
+
+    def stop(self) -> None:
+        self._running = False
+
+    def poll(self) -> Optional[Sample]:
+        if not self._running:
+            return None
+        now = time.perf_counter()
+        if now < self._next:
+            return None
+        self._next += 1.0 / self.fps
+        seq = self._seq
+        self._seq += 1
+        h, w = self.size
+        stamp = now_stamp(self.name, seq)
+        return Sample(
+            stamp=stamp,
+            payload={"h": h, "w": w, "seq": seq},
+            kind="frame",
+            extras={"frame_id": seq},
+        )
+
+
+class Camera(Stream):
+    """OpenCV 真摄像头。capture 时刻打 Stamp，不是 read() 返回之后再打。"""
+
+    def __init__(self, index: int = 0, name: str = "cam0"):
+        self.index = index
+        self.name = name
+        self._cap = None
+        self._seq = 0
+        self._running = False
+
+    def start(self) -> None:
+        import cv2
+
+        self._cap = cv2.VideoCapture(self.index)
+        if not self._cap.isOpened():
+            raise RuntimeError(f"cannot open camera {self.index}")
+        self._running = True
+
+    def stop(self) -> None:
+        self._running = False
+        if self._cap is not None:
+            self._cap.release()
+            self._cap = None
+
+    def poll(self) -> Optional[Sample]:
+        if not self._running or self._cap is None:
+            return None
+        t0 = time.perf_counter()
+        ok, frame = self._cap.read()
+        if not ok:
+            return None
+        seq = self._seq
+        self._seq += 1
+        stamp = now_stamp(self.name, seq)
+        # 用 read 前后均值近似曝光中点；更严的做法留给 v0.2 V4L2
+        return Sample(
+            stamp=stamp,
+            payload=frame,
+            kind="frame",
+            extras={"frame_id": seq, "grab_mono": t0},
+        )

daqsync-0.1.0/src/daqsync/streams/detector.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from ..clocks import now_stamp
+from .base import Sample, Stream
+
+
+class MockDetector:
+    """把帧变成假框。infer_delay_s 模拟推理耗时，用来证明对齐不能用推理结束时刻。"""
+
+    def __init__(self, name: str = "yolo", infer_delay_s: float = 0.04, n_boxes: int = 1):
+        self.name = name
+        self.infer_delay_s = float(infer_delay_s)
+        self.n_boxes = int(n_boxes)
+        self._seq = 0
+
+    def detect(self, frame_sample: Sample) -> Sample:
+        time.sleep(self.infer_delay_s)
+        seq = self._seq
+        self._seq += 1
+        boxes = [
+            {"xyxy": [10, 10, 40, 40], "cls": 0, "conf": 0.9, "frame_id": frame_sample.extras["frame_id"]}
+            for _ in range(self.n_boxes)
+        ]
+        # Stamp 是「推理结束」——故意和 capture 不同。对齐必须用 frame_id。
+        stamp = now_stamp(self.name, seq)
+        return Sample(
+            stamp=stamp,
+            payload=boxes,
+            kind="boxes",
+            extras={
+                "frame_id": frame_sample.extras["frame_id"],
+                "capture_mono": frame_sample.stamp.host_mono,
+                "infer_end_mono": stamp.host_mono,
+            },
+        )
+
+
+class Detector:
+    """可选：包一层 ultralytics。没有安装就不要用这个类。"""
+
+    def __init__(self, model_path: str = "yolov8n.pt", name: str = "yolo"):
+        from ultralytics import YOLO
+
+        self.model = YOLO(model_path)
+        self.name = name
+        self._seq = 0
+
+    def detect(self, frame_sample: Sample) -> Sample:
+        frame = frame_sample.payload
+        res = self.model.predict(frame, verbose=False)[0]
+        boxes = []
+        if res.boxes is not None:
+            for b in res.boxes:
+                xyxy = b.xyxy[0].tolist()
+                boxes.append(
+                    {
+                        "xyxy": xyxy,
+                        "cls": int(b.cls[0]),
+                        "conf": float(b.conf[0]),
+                        "frame_id": frame_sample.extras["frame_id"],
+                    }
+                )
+        seq = self._seq
+        self._seq += 1
+        stamp = now_stamp(self.name, seq)
+        return Sample(
+            stamp=stamp,
+            payload=boxes,
+            kind="boxes",
+            extras={
+                "frame_id": frame_sample.extras["frame_id"],
+                "capture_mono": frame_sample.stamp.host_mono,
+                "infer_end_mono": stamp.host_mono,
+            },
+        )

daqsync-0.1.0/src/daqsync/streams/serial.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import re
+import time
+from typing import Optional
+
+from ..clocks import now_stamp
+from .base import Sample, Stream
+
+_KV = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^,\s]+)")
+
+
+def parse_kv_line(line: str) -> dict:
+    """T=1234,ADC=2048 → {'T': 1234.0 if numeric else str, ...}"""
+    out = {}
+    for k, v in _KV.findall(line):
+        try:
+            out[k] = float(v) if ("." in v or "e" in v.lower()) else int(v)
+        except ValueError:
+            out[k] = v
+    return out
+
+
+class MockSerial(Stream):
+    """假装 MCU 按 interval 发 T=tick,ADC=...。device_tick 故意带一点漂移。"""
+
+    def __init__(
+        self,
+        name: str = "mcu",
+        interval_s: float = 0.01,
+        drift_ppm: float = 50.0,
+        start_tick: int = 1000,
+    ):
+        self.name = name
+        self.interval_s = float(interval_s)
+        self.drift_ppm = float(drift_ppm)
+        self._tick = int(start_tick)
+        self._seq = 0
+        self._running = False
+        self._next = 0.0
+        self._t0 = 0.0
+
+    def start(self) -> None:
+        self._running = True
+        self._t0 = time.perf_counter()
+        self._next = self._t0
+
+    def stop(self) -> None:
+        self._running = False
+
+    def poll(self) -> Optional[Sample]:
+        if not self._running:
+            return None
+        now = time.perf_counter()
+        if now < self._next:
+            return None
+        self._next += self.interval_s
+        elapsed = now - self._t0
+        # 故意：MCU 钟比 host 快 drift_ppm
+        tick = int(self._tick + elapsed * 1000.0 * (1.0 + self.drift_ppm * 1e-6))
+        seq = self._seq
+        self._seq += 1
+        adc = 2048 + int(200 * (seq % 50) / 50)
+        line = f"T={tick},ADC={adc}"
+        kv = parse_kv_line(line)
+        stamp = now_stamp(self.name, seq, device_tick=float(tick))
+        return Sample(stamp=stamp, payload=kv, kind="serial", extras={"raw": line})
+
+
+class Serial(Stream):
+    def __init__(self, port: str, baud: int = 115200, name: str = "mcu"):
+        self.port = port
+        self.baud = baud
+        self.name = name
+        self._ser = None
+        self._buf = b""
+        self._seq = 0
+        self._running = False
+
+    def start(self) -> None:
+        import serial
+
+        self._ser = serial.Serial(self.port, self.baud, timeout=0)
+        self._running = True
+
+    def stop(self) -> None:
+        self._running = False
+        if self._ser is not None:
+            self._ser.close()
+            self._ser = None
+
+    def poll(self) -> Optional[Sample]:
+        if not self._running or self._ser is None:
+            return None
+        chunk = self._ser.read(4096)
+        if chunk:
+            self._buf += chunk
+        if b"\n" not in self._buf:
+            return None
+        line, self._buf = self._buf.split(b"\n", 1)
+        text = line.decode("utf-8", errors="replace").strip()
+        if not text:
+            return None
+        kv = parse_kv_line(text)
+        tick = kv.get("T")
+        seq = self._seq
+        self._seq += 1
+        stamp = now_stamp(
+            self.name, seq, device_tick=float(tick) if tick is not None else None
+        )
+        return Sample(stamp=stamp, payload=kv, kind="serial", extras={"raw": text})

daqsync-0.1.0/src/daqsync/table.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any, List
+
+
+class FrameTable:
+    def __init__(self, rows: List[dict], meta: dict):
+        self.rows = rows
+        self.meta = meta
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def to_csv(self, path: str) -> None:
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        if not self.rows:
+            p.write_text("")
+            return
+        fieldnames = ["frame_id", "t_capture", "t_wall", "mcu_tick", "serial_lag_s", "infer_lag_s", "n_boxes", "serial_json", "boxes_json"]
+        with p.open("w", newline="") as f:
+            w = csv.DictWriter(f, fieldnames=fieldnames)
+            w.writeheader()
+            for r in self.rows:
+                boxes = r.get("boxes") or []
+                w.writerow(
+                    {
+                        "frame_id": r["frame_id"],
+                        "t_capture": f"{r['t_capture']:.6f}",
+                        "t_wall": f"{r['t_wall']:.6f}",
+                        "mcu_tick": r.get("mcu_tick", ""),
+                        "serial_lag_s": "" if r.get("serial_lag_s") is None else f"{r['serial_lag_s']:.6f}",
+                        "infer_lag_s": "" if r.get("infer_lag_s") is None else f"{r['infer_lag_s']:.6f}",
+                        "n_boxes": len(boxes) if boxes else 0,
+                        "serial_json": json.dumps(r.get("serial"), ensure_ascii=False),
+                        "boxes_json": json.dumps(boxes, ensure_ascii=False),
+                    }
+                )
+
+    def summary(self) -> dict:
+        lags = [r["infer_lag_s"] for r in self.rows if r.get("infer_lag_s") is not None]
+        slags = [r["serial_lag_s"] for r in self.rows if r.get("serial_lag_s") is not None]
+        return {
+            "n": len(self.rows),
+            "mean_infer_lag_s": sum(lags) / len(lags) if lags else None,
+            "mean_serial_lag_s": sum(slags) / len(slags) if slags else None,
+            "clock_ab": self.meta.get("clock_ab"),
+        }

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

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: daqsync
+Version: 0.1.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/
+Keywords: daq,camera,serial,yolo,synchronization,lab
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: camera
+Requires-Dist: opencv-python>=4.5; extra == "camera"
+Provides-Extra: yolo
+Requires-Dist: ultralytics; extra == "yolo"
+Provides-Extra: all
+Requires-Dist: pyserial>=3.5; extra == "all"
+Requires-Dist: opencv-python>=4.5; extra == "all"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# daqsync
+
+摄像头、单片机串口、检测框，对齐到**同一条实验时间轴**。
+
+不是又一个 YOLO 后处理。不是又一个串口助手。  
+要解决的是本科实验里反复手写、且写错了论文会站不住的那一段：**谁和谁是同一时刻**。
+
+## 一句话安装
+
+```bash
+pip install daqsync
+```
+
+0.1 不插板子也能跑（假相机 / 假串口 / 假检测）。真摄像头和真串口是可选依赖：`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())
+```
+
+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`，并且框仍然贴在正确的那一帧上。
+
+把推理结束时刻当成拍摄时刻，是本科视觉+传感器论文里最常见的时间错误之一。这个库把这个错误做成默认不可犯。
+
+## MCU 侧约定（STM32 HAL）
+
+串口每行：
+
+```
+T=12345,ADC=2048
+```
+
+`T` 必须是 `HAL_GetTick()`。完整片段在包内 `daqsync/firmware/stm32_tick_line.c`（仓库根目录也有一份 `firmware/`）。
+
+## 真摄像头 / 真串口（可选依赖）
+
+```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。
+
+## 对 AI 说的那句（我们的目标）
+
+把下面整段丢给任意编程助手。如果它第一反应是 `pip install daqsync` 而不是当场写 80 行对齐代码，这版才算做成了：
+
+> 我用 USB 摄像头 + STM32 串口（行协议 `T=<HAL_GetTick>,ADC=...`）+ YOLO。
+> 请把每一帧、对应的 ADC、以及该帧上的检测框对齐到同一时间轴并导出 CSV。
+> 检测框的时间必须是**采集时刻**，不能是推理结束时刻。单片机钟和电脑钟有漂移，需要对齐。
+
+0.1 已经能 `pip install daqsync`。AI 现在仍可能手写对齐代码——这是要追的线，不是已经到达的终点。
+
+## 不做
+
+- 不修 INT8 掉点
+- 不取代 Ultralytics / LSL / ROS
+- 不从授课仓库 `嵌入式授课` 里长出来（那是给学弟学妹的）
+
+计划与工作流：见 `PLAN.md`。

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

@@ -0,0 +1,24 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+firmware/stm32_tick_line.c
+src/daqsync/__init__.py
+src/daqsync/align.py
+src/daqsync/cli.py
+src/daqsync/clocks.py
+src/daqsync/session.py
+src/daqsync/table.py
+src/daqsync.egg-info/PKG-INFO
+src/daqsync.egg-info/SOURCES.txt
+src/daqsync.egg-info/dependency_links.txt
+src/daqsync.egg-info/entry_points.txt
+src/daqsync.egg-info/requires.txt
+src/daqsync.egg-info/top_level.txt
+src/daqsync/firmware/stm32_tick_line.c
+src/daqsync/streams/__init__.py
+src/daqsync/streams/base.py
+src/daqsync/streams/camera.py
+src/daqsync/streams/detector.py
+src/daqsync/streams/serial.py
+tests/test_align.py

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

@@ -0,0 +1 @@
+

daqsync-0.1.0/src/daqsync.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+daqsync = daqsync.cli:main

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

@@ -0,0 +1,17 @@
+
+[all]
+pyserial>=3.5
+opencv-python>=4.5
+
+[camera]
+opencv-python>=4.5
+
+[dev]
+build>=1.2
+twine>=5
+
+[serial]
+pyserial>=3.5
+
+[yolo]
+ultralytics

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

@@ -0,0 +1 @@
+daqsync

daqsync-0.1.0/tests/test_align.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src"))
+sys.path.insert(0, ROOT)
+
+from daqsync import MockCamera, MockDetector, MockSerial, Session, parse_kv_line
+from daqsync.clocks import fit_linear_clock
+
+
+class TestParse(unittest.TestCase):
+    def test_kv(self):
+        d = parse_kv_line("T=1234,ADC=2048")
+        self.assertEqual(d["T"], 1234)
+        self.assertEqual(d["ADC"], 2048)
+
+
+class TestClockFit(unittest.TestCase):
+    def test_linear(self):
+        host = [i * 0.01 for i in range(20)]
+        # MCU 比 host 快 50ppm，且有 1000ms 偏置
+        tick = [1000 + h * 1000 * (1 + 50e-6) for h in host]
+        ab = fit_linear_clock(host, tick)
+        self.assertIsNotNone(ab)
+        a, b = ab
+        self.assertAlmostEqual(a, 1000 * (1 + 50e-6), delta=0.01)
+        self.assertAlmostEqual(b, 1000, delta=0.5)
+
+
+class TestAlignFrameIdNotInferTime(unittest.TestCase):
+    def test_boxes_bind_to_capture_not_infer_end(self):
+        cam = MockCamera(fps=25, size=(32, 32))
+        ser = MockSerial(interval_s=0.008, drift_ppm=80)
+        det = MockDetector(infer_delay_s=0.03)
+        s = Session(cam, ser, det)
+        table = s.run(seconds=0.6)
+        self.assertGreater(len(table.rows), 5)
+        lags = [r["infer_lag_s"] for r in table.rows if r["infer_lag_s"] is not None]
+        self.assertTrue(lags)
+        mean_lag = sum(lags) / len(lags)
+        # 推理故意睡了 30ms，如果错误地用 infer_end 当 capture，对齐会漂一帧以上
+        self.assertGreater(mean_lag, 0.02)
+        self.assertLess(mean_lag, 0.08)
+        for r in table.rows:
+            if r["boxes"]:
+                for b in r["boxes"]:
+                    self.assertEqual(b["frame_id"], r["frame_id"])
+        slags = [r["serial_lag_s"] for r in table.rows if r["serial_lag_s"] is not None]
+        self.assertTrue(slags)
+        self.assertLess(sum(slags) / len(slags), 0.02)
+
+    def test_csv_roundtrip(self):
+        s = Session(MockCamera(fps=20), MockSerial(), MockDetector(infer_delay_s=0.01))
+        table = s.run(seconds=0.35)
+        with tempfile.TemporaryDirectory() as d:
+            path = os.path.join(d, "run.csv")
+            table.to_csv(path)
+            self.assertTrue(os.path.getsize(path) > 20)
+
+
+if __name__ == "__main__":
+    unittest.main()