Skip to content

Add sensor integration knowledge base#1

Draft
Copilot wants to merge 14 commits into
mainfrom
copilot/create-sensor-access-knowledge-repo
Draft

Add sensor integration knowledge base#1
Copilot wants to merge 14 commits into
mainfrom
copilot/create-sensor-access-knowledge-repo

Conversation

Copilot AI commented Apr 25, 2026

Copy link
Copy Markdown
  • 创建根 CMakeLists.txtcmake/CompilerWarnings.cmake
  • 创建 D_hal_design/CMakeLists.txt(INTERFACE 库 + 安装规则)
  • 创建 D_hal_design/tests/test_compile.cpptest_types.cpp
  • 创建 .gitignore.github/workflows/ci.ymlscripts/build.sh

代码审查 & 修复:

  • Bug Add sensor integration knowledge base #1 修复:sensor_timestamp.hppoperator< 只比较 nsoperator== 比较 ns+domain,违反严格弱序;fix: operator< 增加 domain 作为 tie-breaker
  • Bug #2 修复:hal_factory.hpp REGISTER_HAL 宏 — 静态变量名 _hal_reg_##Impl 不含 Factory 信息;fix: 改为 _hal_reg_##Factory##_##Impl##_##__LINE__
  • Security:.github/workflows/ci.yml 缺少显式 permissions: contents: read;已补充

测试扩展(13 组新增,共 26 组):

  • test_sensor_timestamp_ordered_set:验证 Bug Add sensor integration knowledge base #1 修复(std::set 存储跨域时间戳)
  • test_hal_factory_register_create:注册/创建/重注册/未知 key 返回 nullptr
  • test_hal_factory_enumerate:enumerator 注册与 enumerateDevices()
  • test_calibration_defaults:CameraIntrinsics / CameraExtrinsics / IMUCalibration / DepthMetadata 默认值
  • test_camera_config_defaults:CameraConfig 全字段默认值
  • test_sync_config_defaults:SyncConfig 全字段默认值
  • test_image_frame_defaults:ImageFrame / FrameSet 默认值
  • test_lidar2d_defaults:Lidar2DConfig / LaserScanData 默认值
  • test_imu_defaults:ImuConfig / ImuData 默认值(含四元数 identity)
  • test_error_info_defaults:ErrorInfo 默认值
  • test_device_info_defaults:DeviceInfo / ConnectionType 默认值
  • test_pointcloud_defaults:PointXYZI / PointCloudXYZI 默认值
  • test_audio_config_defaults:AudioConfig 默认值
Original prompt

目标与范围

  • 建一个“传感器接入知识库(Repository)”,沉淀 接入流程、数据链路、编码传输、标定与同步、驱动与诊断、性能与稳定性 等可复用知识。
  • 覆盖:相机(USB/MIPI/GMSL/以太网)、毫米波雷达、激光雷达、IMU/GNSS、超声波、麦克风阵列等(可按团队实际裁剪)。

贡献方式(建议)

  • 每篇内容尽量包含:背景/目标 → 架构图 → 接入步骤 → 常见坑 → 性能指标 → Debug 方法 → Checklist → 参考资料
  • 统一术语:接口(MIPI CSI-2、GMSL2、GigE Vision)、编码(H.264/H.265)、传输(RTP/RTSP、WebRTC、HTTP-FLV/HLS)、总线(CAN、Ethernet)、时间同步(PTP/1588、GPIO/TTL)。

A. 相机接入 → 视频编码 → 传输/分发:端到端流程框目

A1. 物理与链路层(Camera → Host)

  1. 传感器与接口选型
    • USB UVC / MIPI CSI-2 / GMSL2 / GigE / Ethernet (RTSP/ONVIF) 等
    • 带宽预算:分辨率 × 帧率 × bit-depth × 格式(RAW/YUV/RGB)
  2. 驱动与设备枚举
    • Linux:V4L2、UVC、厂商 SDK、内核驱动(sensor + ISP bridge)
    • 设备节点:/dev/videoX、媒体控制(media controller)、I2C 设备等
  3. 取流与缓冲
    • DMA/零拷贝(DMABUF)、环形缓冲、丢帧策略
    • 延迟 vs 吞吐的权衡(队列深度、线程模型)

A2. 图像链路(ISP/预处理)

  1. RAW → ISP(若是 RAW sensor)
    • 去马赛克、白平衡、降噪、畸变校正、HDR 合成等
  2. 颜色空间与格式转换
    • RGB ↔ YUV(NV12/I420),对编码器友好
  3. 叠加与预处理
    • OSD/时间戳、水印、裁剪、缩放、畸变校正(用于算法或显示)

A3. 编码(Encode)

  1. 编码器选择
    • 硬编:NVENC / V4L2 M2M / MediaCodec(平台相关:Orin、RK、Intel)
    • 软编:x264/x265(CPU 压力大,灵活)
  2. 编码标准与关键参数
    • H.264 / H.265(HEVC)
    • GOP(I 帧间隔)、码率(CBR/VBR)、profile/level、B 帧、低延迟模式
  3. 输出封装(Container/Packet)
    • AnnexB / AVCC、MP4/TS/FLV、RTP payload 等
  4. 质量与延迟评估
    • 端到端延迟分解:采集→ISP→排队→编码→封包→网络→解码→渲染
    • 关键指标:latency、jitter、丢包恢复、码率稳定性、CPU/GPU 占用

A4. 传输协议与工作流(HTTP / RTP / WebRTC 等)

这里用“工作流向”来描述:谁生产码流 → 谁封装 → 谁分发 → 谁消费

A4.1 RTP/RTSP(常见于摄像头/局域网)

  • 工作流向
    • Camera/Server(推 RTP 包) → RTSP Server(会话控制) → Client(拉流解码)
  • 适用
    • 局域网监控、机器人内网预览
  • 关注点
    • UDP 丢包、jitter buffer、NAT 穿透差、客户端兼容性

A4.2 WebRTC(低延迟实时交互)

  • 工作流向
    • Encoder(生成帧/码流) → WebRTC stack(SRTP/拥塞控制) → Browser/App
  • 适用
    • 远程遥操作、实时视频对讲、弱网自适应
  • 关注点
    • 信令(WebSocket/HTTP)、ICE/STUN/TURN、码率自适应、延迟最优

A4.3 HTTP-FLV / HLS / DASH(偏“分发/回放”)

  • 工作流向
    • Encoder → Mux(FLV/TS/MP4 segment) → HTTP Server/CDN → Client
  • 适用
    • 大规模分发、可回放、跨网络稳定
  • 关注点
    • 延迟通常更高(HLS 传统 3–10s,可用 Low-Latency HLS 降到亚秒级~几秒)

A4.4 HTTP 上传/下载(自定义协议/REST)

  • 工作流向
    • 设备端编码 → HTTP POST 上传片段/关键帧 → 服务端存储/转码/审核 → 下游消费
  • 适用
    • 事件上报、离线取证、数据回传
  • 关注点
    • 断点续传、文件切片、鉴权、限流、存储成本

A5. 时钟同步与触发(你提到的 “GPIO”)

  1. GPIO/TTL 触发(硬同步)
    • 用途:多相机同步曝光/帧对齐;与雷达/激光雷达对齐
    • 工作流向
      • Trigger Source(主时钟/MCU)→ GPIO 线 → 多传感器触发输入 → 同步采样
  2. PTP/IEEE1588(以太网时间同步)
    • 用途:分布式设备统一时间基准(相机/雷达/交换机)
  3. 时间戳策略
    • “采集时刻”还是“到达时刻”?硬件时间戳 vs 软件时间戳
    • 记录:frame_id、sensor_time、host_time、ptp_time

A6. 解码、渲染与下游算法

  • 解码:硬解/软解,buffer 模型
  • 显示:OpenGL/Vulkan、GStreamer sink、浏览器播放器
  • 算法:检测/跟踪/SLAM 订阅帧(尽量零拷贝,定义清晰的帧格式与元数据)

A7. 诊断与可观测性(强烈建议单独成章)

  • 日志:采集/编码/传输各阶段关键事件
  • 监控:fps、drop rate、bitrate、latency、queue depth、温度/功耗
  • 抓包/抓帧:tcpdump/wireshark、保存关键帧、编码器统计
  • 故障注入:限带宽、丢包、抖动、CPU 降频

B. 传感器分类知识库目录(待扩建)

B1. 相机(Camera)

  • 接口与硬件:MIPI/GMSL/USB/GigE/以太网相机
  • Linux 侧:V4L2、GStreamer、驱动/ISP、DMABUF
  • 编码与传输:H264/H265、RTSP/WebRTC/HTTP(HLS/FLV)
  • 标定:内参/外参、畸变模型、时间同步
  • Debug:黑屏/花屏/丢帧/延迟/码率不稳

B2. 毫米波雷达(mmWave Radar)

  • 基本原理:FMCW、距离/速度/角度估计
  • 接入:CAN/Ethernet/UART、厂商 SDK、协议解析
  • 输出:点云/目标列表/栅格,坐标系与时间戳
  • 误差与标定:安装角、延迟、速度偏差

B3. 激光雷达(LiDAR)

  • 型号与接口:UDP(常见)、以太网时间同步、厂商驱动
  • 点云格式:packet → frame、ring、intensity、timestamp
  • 标定:外参、时间同步、去畸变(motion compensation)
  • 性能:点频、丢包、MTU、交换机配置

B4. IMU / GNSS

  • 采样率、噪声模型、对齐与标定
  • 时间同步与融合:EKF/因子图输入要求(timestamp 质量)
  • 接口:SPI/I2C/UART/CAN

B5. 超声波 / 其他(如麦克风阵列)

  • 采样与驱动、协议解析、同步与滤波
  • 典型 Debug Checklist

C. 统一模板(建议大家按这个写)

1. 这篇文章要解决什么问题?

2. 数据链路图(从物理线到应用)

3. 关键接口/协议/格式(列清单)

4. 关键参数与默认值(表格)

5. 性能指标与验收标准

6. 常见问题与排查步骤(Checklist)

7. 参考资料/链接/抓包样例/配置片段

Copilot AI changed the title [WIP] Establish sensor access knowledge repository Add sensor integration knowledge base Apr 25, 2026
Copilot AI requested a review from YYCB April 25, 2026 04:00
Copilot finished work on behalf of YYCB April 25, 2026 04:00
Copilot finished work on behalf of YYCB April 25, 2026 04:02
Copilot AI and others added 2 commits April 25, 2026 09:13
Critical:
- C-1: errorCodeToString / bytesPerPixel / pixelEncodingToString made inline
- C-2: health_status comment fixed (std::string is NOT atomic)
- C-3: partialMatch() BGR8 wildcard bug fixed via explicit match_any_format flag

High:
- H-1: angle_resolution int (0.01° units) -> float angle_resolution_deg (degrees)
- H-2: DeviceInfo::connection string -> enum class ConnectionType
- H-3: AudioConfig::device_type string -> enum class AudioDeviceType
- H-4: getIntrinsics/getExtrinsics/getIMUCalibration unified to StreamIndex param
- H-5: FrameSet::ir split into ir_left + ir_right for stereo IR support
- H-6: error_circle fully documented
- H-7: polling API getColorFrame/getDepthFrame/getIRFrame/getPointCloud add timeout_ms

Medium:
- M-1: CameraConfig::usb_port renamed to gmsl_port
- M-3: ImuDeviceInfo gains model/serial_number/firmware_version
- M-4: Lidar3DConfig::defaultsFor(LidarModel) factory method added
- M-5: PointCloudXYZI::valid_count semantics documented
- M-6: IMUCalibration::scale_bias formula clarified with corrected_SI = R*raw + b
- M-7: DOAResult::elevation_deg documents 2D-array always-zero behaviour
- M-8: std::hash<StreamIndex> specialisation added
- M-9: ISyncManager::isSynced() behaviour documented for all SyncModes

Low:
- L-1: SensorTimestamp gains >, <=, >= operators and deltaNs()
- L-5: ring_buffer_depth valid range [2,32] documented
- L-6: DepthMetadata gains valid flag
- L-8: enumerateDevices() snapshot-copies enumerator map before calling (deadlock fix)
- L-9: audio_hal.hpp lifecycle comment startCapture -> startStreaming

All 20 headers pass g++ -std=c++17 -Wall -Wextra -Wpedantic -fsyntax-only

Agent-Logs-Url: https://github.com/YYCB/sensor_repository/sessions/7630daeb-0200-4ca2-b765-2680eaeb25af

Co-authored-by: YYCB <23326150+YYCB@users.noreply.github.com>
- lidar_2d_types: clarify mask 32-bit limitation in comment
- sync_manager: document SoftwareTrigger temporal behaviour of isSynced()
- health_status: rephrase thread-safety comment (writer needs mutex, caller copy is safe)
- calibration_types: add concrete scale_bias row-0 example in comment
- camera_types: add MIN_RING_BUFFER_DEPTH constexpr
- hal_factory: document O(N) snapshot overhead in enumerateDevices comment
- lidar_3d_types: explain why valid_count is retained alongside points.size()

Agent-Logs-Url: https://github.com/YYCB/sensor_repository/sessions/7630daeb-0200-4ca2-b765-2680eaeb25af

Co-authored-by: YYCB <23326150+YYCB@users.noreply.github.com>
…missions; expand tests to 26 groups

Agent-Logs-Url: https://github.com/YYCB/sensor_repository/sessions/c97005c9-a948-47e6-806b-e2fbe3a02a6e

Co-authored-by: YYCB <23326150+YYCB@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants