本页面向初次接触 roboto_imu 的开发者，帮助你建立对项目的整体认知：它是什么、能解决什么问题、内部如何组织，以及下一步该去哪里学习。阅读完本页后，你将清楚该库的适用范围、核心特性，并拥有一张可以继续深入的知识地图。

1. 项目简介

roboto_imu 是 Roboto（RoboParty）平台专为惯性测量单元（IMU）设计的驱动库，当前版本 1.1.3，采用 Apache-2.0 许可证发布。它同时提供 C++ 原生 SDK 与 Python 绑定，让机器人、自动驾驶或工业控制领域的开发者能够快速接入超核电子（HiPNUC）系列 IMU 设备。库内部封装了 CAN（J1939 / CANopen）与串口（UART）两种底层通信方式，上层只需通过统一的 IMUDriver 接口即可读取四元数、角速度、线加速度和温度等传感器数据，无需关心底层协议细节。对于 Python 用户，模块名为 imu_py；对于 C++ 用户，只需包含 imu_driver.hpp 即可。

Sources: README_CN.md package.xml

2. 核心能力一览

为了让你快速判断该库是否满足需求，下面从“接口/协议支持”和“传感器数据接口”两个维度进行概括。接口方面，目前同时覆盖 CAN 总线与 UART 串口，每种接口对应不同的通信协议与数据输出；数据接口方面，所有测量值均通过 IMUDriver 基类的虚函数提供，返回值已经过单位换算，可直接用于算法开发。

Sources: README_CN.md README_CN.md imu_driver.hpp

3. 系统架构与代码结构

3.1 分层架构

整个库采用四层架构：应用层、SDK 抽象层、驱动实现层、协议传输与解析层。应用层可以是 Python 脚本或 C++ 应用程序；SDK 抽象层由 IMUDriver 基类与工厂方法 create_imu() 组成，负责向上屏蔽硬件差异；驱动实现层目前为 HipnucIMUDriver，它根据构造参数决定使用 CAN 还是串口，并在各自接收线程的回调函数中完成数据解析与单位转换；最底层是 IMUSocketCAN（单例管理 SocketCAN 接口）与 IMUSerialPort（串口 UART 接口），它们分别将 Linux can_frame 或原始字节流交给 C 语言编写的协议解析器（J1939、CANopen、HI91、NMEA）。所有传感器数据在写入共享结构体时均通过 std::shared_mutex 保护，保证并发读取安全。

graph TD
    A[应用层<br/>Python / C++] -->|调用 create_imu| B[SDK 抽象层<br/>IMUDriver + 工厂模式]
    B -->|实例化| C[驱动实现层<br/>HipnucIMUDriver]
    C -->|CAN 帧回调| D[协议传输层<br/>IMUSocketCAN]
    C -->|串口数据回调| E[协议传输层<br/>IMUSerialPort]
    D -->|can_frame| F[硬件接口层<br/>CAN 总线]
    E -->|字节流| G[硬件接口层<br/>UART 串口]
    C -->|调用解析| H[协议解析层<br/>J1939 / CANopen / HI91 / NMEA]

Sources: imu_driver.hpp imu_driver.cpp hipnuc_imu_driver.hpp hipnuc_imu_driver.cpp socket_can.hpp serial_port.hpp

3.2 目录结构

项目的源码与构建脚本组织如下，展开到两级目录，方便你快速定位感兴趣的文件：

roboto_imu/
├── include/
│   └── imu_driver.hpp          # 抽象基类 + 工厂模式
├── src/
│   ├── imu_driver.cpp          # 工厂方法 create_imu()
│   ├── pybind_module.cpp       # Python 绑定 (imu_py)
│   ├── drivers/
│   │   └── hipnuc/             # 超核驱动 + C 协议解码器
│   │       ├── hipnuc_imu_driver.hpp / .cpp
│   │       ├── hipnuc_dec.h / .c        # 私有协议
│   │       ├── hipnuc_j1939_parser.h / .c  # J1939
│   │       ├── hipnuc_can_common.h
│   │       ├── canopen_parser.h / .c
│   │       └── nmea_decode.h / .c
│   └── protocol/
│       ├── can/
│       │   └── socket_can.hpp / .cpp    # SocketCAN 单例
│       └── serial/
│           └── serial_port.hpp / .cpp   # UART 接口
├── cmake/
│   └── roboto_imuConfig.cmake
├── debian/
│   ├── control
│   ├── postinst
│   └── postrm
├── init_imu.sh
└── .github/
    └── workflows/
        └── build-deb.yml

Sources: README_CN.md

4. 构建与部署概览

项目以 CMake 为核心构建系统，根目录 CMakeLists.txt 设定 C++17 标准、O3 优化，并查找 spdlog、fmt、pybind11、Python3 等依赖。若系统安装了 ament_cmake，构建流程会自动导出 ROS 2 的 ament 包配置，支持通过 colcon build --packages-select roboto_imu 编译；若处于纯部署环境，可运行 build_deb.sh 生成 Debian 安装包，该脚本会处理安装前缀 /opt/roboparty、维护者脚本与 udev 规则，最终产出可在 ARM64 设备上直接安装的 .deb 文件。GitHub Actions 工作流 build-deb.yml 在 ubuntu-22.04-arm 运行器上持续执行编译与打包，并在推送形如 imu-v* 的标签时自动发布到 GitHub Release。

Sources: CMakeLists.txt build_deb.sh .github/workflows/build-deb.yml

5. 推荐阅读路线

为了帮助初学者循序渐进地掌握本项目，建议按照以下顺序阅读文档：先从 快速开始 获得第一条可运行的示例代码；随后查阅 环境依赖与安装 确认系统依赖与工具链；接着根据你的开发语言选择 Python SDK 快速上手 或 C++ SDK 快速上手；在能够成功读取数据后，再通过 整体架构与模块划分 深入理解模块职责与交互方式。完成上述阅读后，你可以根据实际硬件继续浏览 CAN 接口配置指南 或 串口接口配置指南，亦可前往 工厂模式与抽象驱动设计 探究代码层面的设计思想。

Sources: README_CN.md

6. 许可证与维护

roboto_imu 采用 Apache License 2.0 开源协议，由 RoboParty 团队维护。你可以在遵守许可证条款的前提下，自由地在商业或研究项目中使用、修改和分发本软件。