本页面向初次使用 roboto_imu 的开发者，系统讲解从零开始准备编译环境、安装系统依赖、完成源码编译或 Debian 包部署的全过程。阅读完本页后，你将拥有一套可正常编译和运行 IMU 驱动程序的环境。如果你已经熟悉系统配置，可直接跳至 快速开始 查看编译命令与第一个示例程序；若仅需了解接口接线，请前往 CAN 接口配置指南 或 串口接口配置指南。

Sources: README_CN.md, CMakeLists.txt

系统要求

roboto_imu 采用现代 C++ 设计，对编译器和构建工具有明确的最低版本要求。在开始前，请确认你的系统满足以下条件。

项目默认启用 ccache 作为编译器启动器以加速重复构建，并开启 -O3 与 -march=native 优化。如果你使用交叉编译，-march=native 会自动关闭。

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

依赖总览

本项目的依赖可分为编译时依赖与运行时依赖两类。编译时依赖必须在执行 cmake 之前安装到位；运行时依赖则在程序执行或 Debian 包安装时按需解析。

graph TD
    subgraph 编译时依赖
        A[CMake 3.12+] --> B[spdlog]
        A --> C[fmt]
        A --> D[pybind11]
        A --> E[Python3-dev]
        A --> F[pthread]
        A --> G[ament_cmake<br/>可选]
    end

    subgraph 运行时依赖
        H[roboto-base >= 1.0.0]
        I[can-utils]
        J[udev 服务]
    end

    B --> K[libimu.a]
    C --> K
    D --> L[imu_py.so]
    E --> L
    F --> M[libimu_protocol.a]
    H --> N[.deb 包安装]
    I --> O[init_imu.sh 配置脚本]

从依赖关系可以看出，spdlog、fmt、pybind11 与 Python3 是贯穿 C++ 核心库与 Python SDK 的关键支柱；ament_cmake 仅在 ROS 2 工作空间内被需要，且 CMake 通过 find_package(ament_cmake QUIET) 静默探测，不会阻塞非 ROS 环境的构建。Debian 包额外声明了 roboto-base 运行时依赖，确保系统底层库环境一致。

Sources: CMakeLists.txt, package.xml, debian/control

安装构建依赖

在 Ubuntu 或 Debian 系统上，你可以通过 apt 一次性安装所有必需的编译依赖。以下命令摘取自 CI 工作流，已在 ubuntu-22.04-arm 环境中验证通过。

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
    build-essential cmake ccache dpkg-dev \
    libspdlog-dev libfmt-dev \
    python3-dev pybind11-dev

如果你计划在 ROS 2 工作空间内编译，还需要额外安装 ament_cmake 及 colcon。以 ROS 2 Humble 为例：

sudo apt-get install -y ros-humble-ament-cmake ros-humble-pybind11-vendor
# 或安装完整 colcon 构建工具
sudo apt-get install -y python3-colcon-common-extensions

对于需要使用 IMU 配置脚本（init_imu.sh）的开发者，建议同时安装 can-utils，它提供了 cansend 等命令行工具，用于通过 CAN 总线修改设备波特率和输出数据类型。若你仅使用串口通信，则可跳过此步骤。

Sources: .github/workflows/build-deb.yml, package.xml, init_imu.sh

编译与安装

roboto_imu 提供三种安装路径，分别对应开发、集成与部署三种场景。你可以根据自身环境选择最合适的一条。

方式一：ROS 2 colcon 构建

将本仓库克隆至你的 ROS 2 工作空间 src 目录下，执行标准 colcon 构建流程。构建完成后，ament_cmake 会自动导出头文件目录与库目标，其他 ROS 2 包可通过 find_package(roboto_imu) 直接引用。

cd ~/ros2_ws/src
# 克隆或放置 roboto_imu 目录
cd ~/ros2_ws
colcon build --packages-select roboto_imu
source install/setup.bash

此方式下，ament_cmake 会执行 ament_export_libraries 与 ament_export_include_directories，确保依赖本包的其他 ROS 2 组件能够正确链接。

Sources: CMakeLists.txt, package.xml

方式二：纯 CMake 手动构建

如果你不使用 ROS 2，或者希望将本库集成至独立的 CMake 项目，可直接调用 CMake。以下命令以 Release 模式编译静态库与 Python 模块。

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

默认情况下，库文件（libimu.a、libhipnuc_imu.a、libimu_protocol.a）与头文件将安装至 CMake 默认前缀（通常是 /usr/local）。你可以通过 CMAKE_INSTALL_PREFIX 指定自定义路径：

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/roboparty
make -j$(nproc)
sudo make install

安装完成后，非 ROS 2 的 CMake 项目可通过 find_package(roboto_imu CONFIG) 定位本库。配置模块 roboto_imuConfig.cmake 会自动查找 fmt 与 spdlog，并导出 roboto_imu::roboto_imu 接口目标。

Sources: CMakeLists.txt, cmake/roboto_imuConfig.cmake

方式三：打包为 Debian 安装包

对于生产环境部署，推荐使用仓库根目录下的 build_deb.sh 脚本生成 .deb 包。该脚本会自动处理版本号、架构探测、安装路径填充与维护者脚本打包。

cd roboto_imu
./build_deb.sh
sudo dpkg -i roboto-imu_1.1.3_*.deb

脚本默认采用独立部署模式（WITH_ROS=0），安装前缀固定为 /opt/roboparty，包含 C++ 头文件、静态库、Python 模块以及 init_imu.sh 工具脚本。如果你需要生成带有 ROS 2 ament 元数据的包，可显式启用 ROS 2 模式：

WITH_ROS=1 ./build_deb.sh

此时脚本会自动扫描 /opt/ros 下已安装的发行版（按 jazzy → iron → humble → rolling 优先级），并 source 对应环境后再执行编译。

Sources: build_deb.sh, debian/control

安装后配置

无论采用哪种安装方式，完成安装后还需执行几项系统级配置，确保 Python 模块可被正确导入、串口设备拥有访问权限、以及 Debian 包变更即时生效。

动态链接器缓存更新

Debian 包的维护者脚本会在安装和卸载时自动调用 ldconfig，刷新系统的共享库缓存。如果你通过 make install 手动安装至非标准路径（如 /opt/roboparty/lib），建议手动执行一次：

sudo ldconfig /opt/roboparty/lib

Sources: debian/postinst, debian/postrm

udev 规则重载

若安装包内包含 udev 规则文件（用于串口设备权限或别名映射），维护者脚本会在安装后自动重载规则并触发设备事件，无需手动干预。

# 等效于 debian/postinst 内部自动执行的逻辑
sudo udevadm control --reload-rules
sudo udevadm trigger

Sources: build_deb.sh, debian/postinst

串口设备权限

当使用串口连接 IMU 时，普通用户通常需要具备访问 /dev/ttyUSB* 或 /dev/ttyACM* 的权限。最稳健的做法是将当前用户加入 dialout 组，然后重新登录或重启会话使权限生效：

sudo usermod -aG dialout $USER
# 注销并重新登录，或执行：
newgrp dialout

加入 dialout 组后，你便无需每次使用 sudo 即可打开串口设备。

Sources: README_CN.md

Python 模块路径

通过 Debian 包安装时，Python 绑定模块（imu_py.so）会被放置于 /opt/roboparty/lib/python3.x/site-packages/ 目录下。为了让 Python 解释器能够找到该模块，你需要确保上述路径出现在 sys.path 中。常见做法包括：

• 设置环境变量：export PYTHONPATH=/opt/roboparty/lib/python3.10/site-packages:$PYTHONPATH
• 在虚拟环境中创建 .pth 文件指向该目录
• 使用 ROS 2 时通过 source /opt/roboparty/setup.bash（如适用）

如果你通过 colcon build 编译，Python 模块通常已经位于工作空间的 install 目录下，source 对应的 setup.bash 即可自动配置路径。

Sources: CMakeLists.txt, build_deb.sh

验证安装

完成上述步骤后，可通过以下方式快速验证环境是否就绪。

验证 C++ 头文件与库：

# 检查头文件是否存在
ls /opt/roboparty/include/imu_driver.hpp
# 检查静态库是否生成
ls /opt/roboparty/lib/libimu.a

验证 Python 模块：

python3 -c "import imu_py; print('Python SDK 导入成功')"

若导入失败并提示 ModuleNotFoundError，请检查 PYTHONPATH 是否包含正确的 site-packages 目录。

验证 CAN 工具链（CAN 用户）：

which cansend
# 应输出 /usr/bin/cansend

Sources: CMakeLists.txt, init_imu.sh

常见问题速查

Sources: CMakeLists.txt, debian/control

下一步

环境就绪后，你可以按照以下顺序继续探索 roboto_imu：

1. 快速开始 — 在 10 分钟内完成首次编译并读取传感器数据，包含 Python 与 C++ 的最小可运行示例。
2. Python SDK 快速上手 — 深入了解 Python 模块的导入细节、虚拟环境配置与更丰富的数据读取示例。
3. C++ SDK 快速上手 — 学习如何在独立 CMake 项目中通过 find_package 引入本库，并正确链接静态库目标。
4. CAN 接口配置指南 或 串口接口配置指南 — 根据你的硬件连接方式，完成主机侧接口初始化与排错。