本页面向初次接触 roboto_imu 的开发者，目标是在 10 分钟内完成首次编译并读取到 IMU 传感器数据。你将了解项目的最小依赖、三种编译方式、以及 Python 与 C++ 的最小可运行示例。更详细的依赖安装步骤请参考 环境依赖与安装，接口的深层配置逻辑请参考 CAN 接口配置指南 与 串口接口配置指南。

Sources: README_CN.md, CMakeLists.txt

准备工作

在编译之前，请确认你的系统已安装以下依赖库。roboto_imu 基于 C++17 构建，同时依赖 spdlog、fmt 与 pybind11 提供日志与 Python 绑定能力。如果你处于 ROS 2 工作空间，则还需要 ament_cmake。

硬件方面，当前版本仅支持 超核电子 (HiPNUC) 系列 IMU，通信接口可选择 CAN (can0 等) 或串口 (/dev/ttyUSB0 等)。下表列出了当前已验证的设备组合。

Sources: CMakeLists.txt, package.xml, README_CN.md

项目架构一览

roboto_imu 采用工厂模式 + 抽象驱动的分层设计。对上层应用而言，只需通过统一的 IMUDriver::create_imu() 工厂方法创建实例，无需关心底层是 CAN 帧解析还是串口字节流解码。底层协议层由 SocketCAN 单例与 SerialPort 分别管理，二者均运行在独立的实时接收线程中，通过回调函数将原始数据注入驱动层的解析器。

graph TD
    A[用户代码 Python/C++] -->|create_imu| B[IMUDriver 抽象基类]
    B --> C[HipnucIMUDriver 具体实现]
    C -->|CAN 帧回调| D[IMUSocketCAN 单例]
    C -->|串口字节回调| E[IMUSerialPort]
    D -->|原始 CAN 帧| F[hipnuc_j1939_parser]
    E -->|原始字节流| G[hipnuc_dec 私有协议解码]
    F -->|sensor_data| C
    G -->|sensor_data| C
    B -->|get_quat / get_ang_vel / get_lin_acc| A

Sources: include/imu_driver.hpp, src/imu_driver.cpp, src/drivers/hipnuc/hipnuc_imu_driver.hpp

编译与安装

本项目提供三种编译入口，根据你的使用场景任选其一即可。

方式一：ROS 2 colcon 构建（推荐，如果你在 ROS 2 工作空间内）

cd /path/to/your/ros2_ws/src
# 将本仓库克隆或软链接至 src 目录下
colcon build --packages-select roboto_imu
source install/setup.bash

方式二：纯 CMake 构建（无 ROS 2 依赖）

cd /path/to/roboto_imu
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

方式三：打包为 Debian 安装包（用于部署）

cd /path/to/roboto_imu
./build_deb.sh
# 生成 roboto-imu_1.1.3_*.deb
sudo dpkg -i roboto-imu_1.1.3_*.deb

执行 build_deb.sh 时可通过环境变量 WITH_ROS=1 启用 ROS 2 模式，脚本会自动探测 /opt/ros 下已安装的发行版并 source 对应环境；默认 WITH_ROS=0 为独立部署模式。构建完成后，C++ 头文件安装至 include/，静态库与 Python 模块安装至 lib/。

Sources: CMakeLists.txt, build_deb.sh, package.xml

第一个示例程序

编译完成后，你可以通过 Python 或 C++ 在 5 行代码内获取到 IMU 实时数据。以下示例假设你已通过 CAN 连接 HiPNUC 设备，且 can0 接口已配置为与 IMU 相同的波特率（默认 500K 或 1M）。

Python 最小示例

from imu_py import IMUDriver

imu = IMUDriver.create_imu(
    imu_id=0x08,
    interface_type="can",
    interface="can0",
    imu_type="HIPNUC",
    baudrate=0
)

print("Quaternion:", imu.get_quat())      # [w, x, y, z]
print("Angular Velocity:", imu.get_ang_vel())  # [x, y, z] rad/s
print("Linear Accel:", imu.get_lin_acc())      # [x, y, z] m/s²
print("Temperature:", imu.get_temperature())   # °C

C++ 最小示例

#include "imu_driver.hpp"
#include <iostream>

int main() {
    auto imu = IMUDriver::create_imu(0x08, "can", "can0", "HIPNUC");

    auto q = imu->get_quat();           // {w, x, y, z}
    auto g = imu->get_ang_vel();        // {x, y, z} rad/s
    auto a = imu->get_lin_acc();        // {x, y, z} m/s²
    float t = imu->get_temperature();   // °C

    return 0;
}

接口说明速查表：

若使用串口，仅需将 interface_type 改为 "serial"，interface 改为设备路径（如 "/dev/ttyUSB0"），并将 baudrate 设为实际值（常见为 115200）。工厂方法内部会根据 interface_type 自动实例化对应的协议层对象并启动接收线程。

Sources: src/pybind_module.cpp, include/imu_driver.hpp, src/drivers/hipnuc/hipnuc_imu_driver.cpp

接口快速启动

在运行示例代码前，请确保主机侧的硬件接口已正确初始化。以下是两条最常用的一行命令，足够让绝大多数初学者先跑起来；完整的原理与排错请移步对应专题页。

CAN 接口最小初始化

sudo ip link set can0 up type can bitrate 1000000

如果你手头有多台 IMU 挂在同一条 CAN 总线上，create_imu 中的 imu_id 参数对应设备的节点地址（如 0x08），SocketCAN 单例会按 can_id & 0x7F 提取地址并分发到正确的驱动回调。若需修改设备波特率或输出数据类型，可使用仓库附带的 init_imu.sh 脚本，它会通过 J1939 管理报文将目标设备配置为 1M 波特率并开启四元数输出。

串口接口最小初始化

# 确认设备节点存在
ls /dev/ttyUSB* 
# 若权限不足，可将当前用户加入 dialout 组
sudo usermod -aG dialout $USER

串口波特率支持 9600 / 19200 / 38400 / 57600 / 115200 / 230400 / 460800 / 921600，默认使用 8N1 无硬件流控配置。IMUSerialPort::open() 内部会启动独立的 SCHED_FIFO 实时接收线程，通过 select 阻塞读取并在收到数据后触发回调。

Sources: init_imu.sh, src/protocol/can/socket_can.hpp, src/protocol/serial/serial_port.cpp

下一步读什么

完成本页的快速上手后，建议按照以下顺序深入阅读，逐步建立对代码库的系统认知。

1. Python SDK 快速上手 — 了解 Python 模块的导入路径、虚拟环境注意事项，以及更丰富的数据读取示例。
2. C++ SDK 快速上手 — 学习如何在 CMake 项目中引入 roboto_imu 作为外部依赖、链接静态库的正确方式。
3. CAN 接口配置指南 或 串口接口配置指南 — 根据你的硬件接口深入排错与调优。
4. 整体架构与模块划分 — 从全局视角理解工厂模式、抽象驱动与协议层的协作关系。