Skip to content

CLAUDE.md

Latest commit

 

History

History
163 lines (132 loc) · 7.62 KB

CLAUDE.md

File metadata and controls

163 lines (132 loc) · 7.62 KB

CLAUDE.md

任何项目都务必遵守的规则（极其重要！！！）

Communication

  • 永远使用简体中文进行思考和对话

Documentation

  • 编写 .md 文档时，也要用中文
  • 正式文档写到项目的 docs/ 目录下
  • 用于讨论和评审的计划、方案等文档，写到项目的 discuss/ 目录下

代码框架

  • 代码必须简单清晰，易于理解
  • 编写代码的硬性指标，包括以下原则： （1）对于 Python 等动态语言，尽可能确保每个代码文件不要超过 300 行 （2）对于 C++ 、C 等静态语言，尽可能确保每个代码文件不要超过 400 行 （3）每层文件夹中的文件，尽可能不超过 8 个。如有超过，需要规划为多层子文件夹
  • 除了硬性指标以外，还需要时刻关注优雅的架构设计，避免出现以下可能侵蚀我们代码质量的「坏味道」： （1）僵化 (Rigidity): 系统难以变更，任何微小的改动都会引发一连串的连锁修改。 （2）冗余 (Redundancy): 同样的代码逻辑在多处重复出现，导致维护困难且容易产生不一致。 （3）循环依赖 (Circular Dependency): 两个或多个模块互相纠缠，形成无法解耦的“死结”，导致难以测试与复用。 （4）脆弱性 (Fragility): 对代码一处的修改，导致了系统中其他看似无关部分功能的意外损坏。 （5）晦涩性 (Obscurity): 代码意图不明，结构混乱，导致阅读者难以理解其功能和设计。 （6）数据泥团 (Data Clump): 多个数据项总是一起出现在不同方法的参数中，暗示着它们应该被组合成一个独立的对象。 （7）不必要的复杂性 (Needless Complexity): 用“杀牛刀”去解决“杀鸡”的问题，过度设计使系统变得臃肿且难以理解。
  • 【非常重要！！】无论是你自己编写代码，还是阅读或审核他人代码时，都要严格遵守上述硬性指标，以及时刻关注优雅的架构设计。
  • 【非常重要！！】无论何时，一旦你识别出那些可能侵蚀我们代码质量的「坏味道」，都应当立即询问用户是否需要优化，并给出合理的优化建议。

Run & Debug

  • 必须首先在项目的 scripts/ 目录下，维护好 Run & Debug 需要用到的全部 .sh 脚本
  • 对于所有 Run & Debug 操作，一律使用 scripts/ 目录下的 .sh 脚本进行启停。永远不要直接使用 npm、pnpm、uv、python 等等命令
  • 如果 .sh 脚本执行失败，无论是 .sh 本身的问题还是其他代码问题，需要先紧急修复。然后仍然坚持用 .sh 脚本进行启停
  • Run & Debug 之前，为所有项目配置 Logger with File Output，并统一输出到 logs/ 目录下

Python

  • 数据结构尽可能全部定义成强类型。如果个别场景不得不使用未经结构化定义的 dict，需要先停下来征求用户的同意
  • Python 虚拟环境永远使用 .venv 作为目录名
  • 必须使用 uv，而不是 pip、poetry、conda、python3、python。包括依赖管理、构建、调试启动等所有环节
  • 项目的根目录必须保持简洁，只保留必须存在的文件
  • main.py 内容也要简洁。只保留必须存在的代码
  • 每一个.py文件都必须包含一个Main函数，用于测试当前文件是否能正常运行。

C++

  • 代码风格遵循 Google C++ Style Guide
  • 代码尽可能简单，避免过度设计
  • 代码必须使用 .cpp 作为文件扩展名

依赖

-- 需要添加依赖时，必须先征求用户的同意。

输出与日志

  • 输出PROJECT_STATUS.md 必须包含项目的主要功能、特性、优势、局限性等信息.包括每次更新的主要变化、优化点、新功能等。
  • 简单任务或者临时性的输出，可以不是用日志系统。
  • 工程简单或者本身就没有使用日志系统，可以不使用日志系统。直接使用原始数据输出。例如python用print(),C++使用cout。
  • 日志文件必须使用简体中文
  • 日志文件必须输出到 logs/ 目录下
  • 日志文件必须包含时间戳、模块名、日志等级、日志内容等信息
  • 日志文件必须按时间顺序排列
  • 日志文件必须定期清理，避免过大占用磁盘空间
  • 日志文件必须包含项目的主要功能、特性、优势、局限性等信息.包括每次更新的主要变化、优化点、新功能等。

版本控制

  • 版本控制系统使用 Git
  • 版本控制系统必须包含 .gitignore 文件，用于排除不需要提交的文件

项目概述

SimpleSensorSync 是一个为机器人和传感器融合系统设计的多传感器同步解决方案。它使用专用同步板为相机、激光雷达、IMU 和 GPS 等各种传感器提供精确的时间协调。

核心组件

  • infinite_sense_core/: 提供同步功能的主库
    • Synchronizer 类: 网络、USB 和传感器管理的主协调器
    • Messenger: 基于 ZeroMQ 的数据交换通信系统
    • TriggerManager: 处理传感器同步的 PWM/PPS 触发信号
    • NetManager: 网络通信 (支持 PTP 协议)
    • UsbManager: 同步板控制的串口通信
    • Sensor: 传感器抽象基类

关键技术

  • ZeroMQ: 主要消息/通信协议
  • PTP (精确时间协议): 网络时间同步
  • PWM/PPS: 传感器硬件触发信号
  • JSON: 数据序列化格式
  • CMake: 构建系统，使用 C++17 标准

目录结构

  • infinite_sense_core/: 核心同步库
    • include/: 头文件，包括主 API (infinite_sense.h)
    • src/: 实现文件
    • third_party/: 串口和 UDP 通信库
  • example/: 演示用法的示例应用
    • NetCam/: 工业网络相机集成 (支持 ROS1/ROS2)
    • CustomCam/: 自定义相机 SDK 集成模板
    • VideoCam/: 视频相机示例
  • tools/monitor/: 系统状态监控工具

构建命令

基本构建

# 创建构建目录并编译
mkdir -p build && cd build
cmake ..
make -j$(nproc)

平台特定说明

  • 支持 ARM (aarch64) 和 x86_64 架构
  • NetCam 示例自动检测平台并链接相应库
  • 构建系统根据可用包条件编译 ROS1/ROS2 支持

依赖项

  • 必需: ZeroMQ, CMake 3.16+, C++17 编译器
  • 可选: ROS1 (catkin), ROS2 (ament), OpenCV (用于相机示例)

开发工作流

添加新传感器支持

  1. 扩展 infinite_sense_core/include/sensor.h 中的 Sensor 基类
  2. 实现传感器特定的初始化和触发处理
  3. 在 example/ 目录中按照 CustomCam 模板创建示例
  4. 更新 CMakeLists.txt 以链接传感器 SDK 库

集成模式

  • ROS 集成: 示例展示了双 ROS1/ROS2 支持模式
  • 硬件抽象: 使用 TriggerManager 进行同步板通信
  • 数据流: 传感器数据 → JSON 序列化 → ZeroMQ 消息传递
  • 时间同步: 结合 PTP (网络) + PWM/PPS (硬件) 实现精确同步

配置

  • 通过 Synchronizer::UseSensor() 配置传感器
  • 通过 SetNetLink() 设置网络用于 PTP 同步
  • 通过 SetUsbLink() 设置串口用于同步板通信
  • 通过 SetLogPath() 配置日志

测试和验证

使用内置监控工具监视系统状态：

# 构建并运行监控器
cd build/tools/monitor
./monitor

重要实现说明

  • 系统需要硬件同步板 (V3/V4/MINI 版本)
  • 网络相机需要正确的 PTP 配置以实现亚微秒精度
  • 串口通信使用特定协议进行同步板控制
  • ZeroMQ 处理所有组件间的消息传递和 JSON 序列化
  • 构建系统自动处理 ROS1/ROS2 条件编译

支持的硬件

完整的设备兼容性列表请参考 README.md，包括：

  • RealSense 深度相机 (PWM 同步)
  • 主要厂商的工业相机 (PWM 同步)
  • 3D 激光雷达传感器 (PPS 同步)
  • IMU 设备 (PWM 同步)
  • GPS/RTK 系统 (NMEA 同步)