启元 Q1 SDK 无真机环境搭建：Ubuntu 22.04 + ROS 2 Humble 编译与自环验证

摘要

想给启元 Q1 做二次开发，手里却没有机器本体，第一步到底能不能走完？本文给出一条不需要真机的验证路径：在 Ubuntu 22.04 + ROS 2 Humble 上完整编译官方 primebot-q1-sdk，再用 ros2 interface show 读取消息契约、检查 FastDDS 环境变量、向 /aima/hal/touch/state 灌入伪造消息做本机自环，三层证据证明工具链已经打通。文中包含原生、Docker、WSL2 三种环境方案的对比取舍，20971520 字节 socket buffer 与 25165824 内核参数的匹配方法，apt 源、rosdep 与代理的网络配置，以及 6 条按频率排序的编译报错逐条拆解。读完你能得到一台随时可以接机器人的开发机。

📌 版本声明：本文基于启元机器人官方 GitHub 组织 PrimebotTech 的 primebot-q1-sdk与《PrimeBot SDK 快速入门与集成指南》编写，目标系统为 Ubuntu 22.04.x LTS + ROS 2 Humble，SDK 随包提供 OpenCV 4.13.0 源码。文中实测输出均来自 Ubuntu 22.04 容器环境；未接机器人的部分已在对应位置注明。若使用其他系统或版本组合，结论可能不同。

文章目录

• • 摘要
  • 一、先把问题定义清楚：没有机器人，这条路能走到哪一步
  • 二、四个包一条依赖链：先认清再动手
  • 三、三种环境方案：原生、容器与 WSL2 的取舍
  • 四、依赖与网络：apt 源、rosdep、国内镜像与代理
  • • 4.1 从公共依赖到三类语言环境
    • 4.2 apt 源、rosdep 与代理：国内网络的三种解法
  • 五、编译：一条命令，但要盯住三个输出
  • 六、FastDDS 内核参数：二十兆缓冲区怎么才不算白设
  • • 6.1 为什么偏偏是 20M
    • 6.2 profile 里的两个数与内核的两个参数
    • 6.3 临时、持久化与验证
  • 七、不接机器人，怎么证明环境真的通了
  • • 7.1 第一层：消息契约能被读出来
    • 7.2 第二层：DDS 环境变量被自动挂上
    • 7.3 第三层：本机自环收发（无真机的关键一招）
  • 八、六条编译报错，按出现频率排
  • 九、适用边界与风险提示
  • 十、总结
  • 参考资料

一、先把问题定义清楚：没有机器人，这条路能走到哪一步

很多教程一上来就让你 ping 10.1.1.101。问题是，没有机器人时这条命令永远是 Destination Host Unreachable，于是新手会误以为"环境没配好"，其实是顺序错了——连通性验证属于阶段二，拿它检验阶段一的工具链，得到的只能是误判。把阶段分清，是没有真机时最省时间的习惯。

按官方《快速入门与集成指南》给出的系统架构，一次完整的二开链路被切成三段：

本文只做阶段 ①，并用"DDS 自环"把阶段 ② 的配置部分提前验证掉。这是没有真机时唯一诚实的做法：你能证明的是"编译与配置正确"，不能证明的是"机器人会照做"。

那么"编译通过"到底证明了什么？多数人的理解停留在"生成了二进制文件"，这个理解太浅。SDK 的核心是 aimdk_msgs 里的 .msg / .srv 定义，这是你的程序和机器人之间唯一的契约。ROS 2 的 rosidl 生成器会把这些纯文本契约编译成 C++ 结构体和 Python 类：字段名、字段类型、默认值规则全部在编译期固定。编译成功，意味着契约本身没有语法错误、类型系统接受它、生成器版本匹配；ros2 interface show 能读出结构，意味着生成产物被正确安装并注册进了 ROS 类型系统。这两件事都不需要机器人参与，却是后续一切通信的地基。反过来想：如果契约在编译期就是错的，非要等到真机联调才发现"字段对不上"，那才是真正浪费时间的排错——你甚至分不清是消息定义错了、环境没加载，还是机器人没上线。

还有一层常被忽略的价值：分层验证让故障模式保持清晰。工具链层的失败永远表现为"编不过、读不到、导不入"，通信层的失败才表现为"连不上、收不到、时通时通"。没有真机时先把前者关掉，等真机到手，剩下的问题就只剩下后者——而后者的大头（开发者模式、网段、DomainID）又都不需要改代码。反过来，如果跳过自环直接上真机，几种故障会同时糊在"连不上"这一个现象里，那种排错才是真正的黑洞。

可能有读者会问：自己发、自己收，岂不是"既当运动员又当裁判员"？关键在于证据的指向。自环并不声称证明了任何机器人行为，它只证明"在这台机器上，消息类型、RMW 实现、命名空间、环境变量这四段配置没有一处断裂"——而这四段恰好是接真机时唯一不变的部分。机器人换任何一台，这四段都不需要重验；真正随机器不同的是 IP、开发者模式与 DomainID，那些属于阶段二，等有了机器再验也不迟。

图1：开发PC、运控板、大脑板经局域网FastDDS互联的官方架构

二、四个包一条依赖链：先认清再动手

官方 README 只列了目录结构，但真正决定"编译会不会失败"的，是 colcon 要按依赖顺序构建的四个包。这一点在指南 3.2 节里才被点出来：

关键认知：官方不提供预编译的 OpenCV .so，而是给源码让你在自己机器的 CPU 架构、glibc、C++ ABI 上编译。这不是偷懒，是必然——OpenCV 与 FFmpeg 的组合维度太多，任何预编译二进制都只能在一种环境里"碰巧"工作，给源码是唯一对所有人都可控的办法。代价就是 colcon build 一次跑二十分钟属正常现象，不要以为卡死了；反过来，如果 aimdk_opencv 段秒过，反而要警惕：要么构建缓存生效，要么依赖没找到被静默跳过。

#mermaid-svg-gmxjeI8L4MB4HumS{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-gmxjeI8L4MB4HumS .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-gmxjeI8L4MB4HumS .error-icon{fill:#552222;}#mermaid-svg-gmxjeI8L4MB4HumS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-gmxjeI8L4MB4HumS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-gmxjeI8L4MB4HumS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-gmxjeI8L4MB4HumS .marker.cross{stroke:#333333;}#mermaid-svg-gmxjeI8L4MB4HumS svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-gmxjeI8L4MB4HumS p{margin:0;}#mermaid-svg-gmxjeI8L4MB4HumS .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-gmxjeI8L4MB4HumS .cluster-label text{fill:#333;}#mermaid-svg-gmxjeI8L4MB4HumS .cluster-label span{color:#333;}#mermaid-svg-gmxjeI8L4MB4HumS .cluster-label span p{background-color:transparent;}#mermaid-svg-gmxjeI8L4MB4HumS .label text,#mermaid-svg-gmxjeI8L4MB4HumS span{fill:#333;color:#333;}#mermaid-svg-gmxjeI8L4MB4HumS .node rect,#mermaid-svg-gmxjeI8L4MB4HumS .node circle,#mermaid-svg-gmxjeI8L4MB4HumS .node ellipse,#mermaid-svg-gmxjeI8L4MB4HumS .node polygon,#mermaid-svg-gmxjeI8L4MB4HumS .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-gmxjeI8L4MB4HumS .rough-node .label text,#mermaid-svg-gmxjeI8L4MB4HumS .node .label text,#mermaid-svg-gmxjeI8L4MB4HumS .image-shape .label,#mermaid-svg-gmxjeI8L4MB4HumS .icon-shape .label{text-anchor:middle;}#mermaid-svg-gmxjeI8L4MB4HumS .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-gmxjeI8L4MB4HumS .rough-node .label,#mermaid-svg-gmxjeI8L4MB4HumS .node .label,#mermaid-svg-gmxjeI8L4MB4HumS .image-shape .label,#mermaid-svg-gmxjeI8L4MB4HumS .icon-shape .label{text-align:center;}#mermaid-svg-gmxjeI8L4MB4HumS .node.clickable{cursor:pointer;}#mermaid-svg-gmxjeI8L4MB4HumS .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-gmxjeI8L4MB4HumS .arrowheadPath{fill:#333333;}#mermaid-svg-gmxjeI8L4MB4HumS .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-gmxjeI8L4MB4HumS .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-gmxjeI8L4MB4HumS .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gmxjeI8L4MB4HumS .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-gmxjeI8L4MB4HumS .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gmxjeI8L4MB4HumS .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-gmxjeI8L4MB4HumS .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-gmxjeI8L4MB4HumS .cluster text{fill:#333;}#mermaid-svg-gmxjeI8L4MB4HumS .cluster span{color:#333;}#mermaid-svg-gmxjeI8L4MB4HumS div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-gmxjeI8L4MB4HumS .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-gmxjeI8L4MB4HumS rect.text{fill:none;stroke-width:0;}#mermaid-svg-gmxjeI8L4MB4HumS .icon-shape,#mermaid-svg-gmxjeI8L4MB4HumS .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-gmxjeI8L4MB4HumS .icon-shape p,#mermaid-svg-gmxjeI8L4MB4HumS .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-gmxjeI8L4MB4HumS .icon-shape .label rect,#mermaid-svg-gmxjeI8L4MB4HumS .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-gmxjeI8L4MB4HumS .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-gmxjeI8L4MB4HumS .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-gmxjeI8L4MB4HumS :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

apt 公共依赖colcon / rosidl / python3-dev

aimdk_msgs生成 C++/Python 消息

aimdk_opencvOpenCV 4.13.0 源码编译

ruckig_for_primebotC++ 库 + nanobind Python 模块

aimdk_examples_cpp19 个示例节点

install/setup.bash

这张依赖链还解释了一个常见困惑：为什么编译顺序必须是 aimdk_msgs 打头。消息包是其他包的"词汇表"——示例节点的 .cpp 要 #include "aimdk_msgs/msg/xxx.hpp"，没有它，后面全部无从谈起。colcon 按 package.xml 的依赖声明做拓扑排序，任何一环缺失，都会在最后一个包集中爆雷。所以排错要倒着看：先确认最上游的 aimdk_msgs 是否 Finished，再逐层往下查，而不是盯着最后那个报错的包发呆。

还有一个工程细节值得提前知道：OpenCV 源码编译是四个包里最重的一环，数万个源文件里绝大部分与 RTSP 无关。如果暂时不需要视频流，可以先用 colcon build –packages-up-to aimdk_msgs 把消息包单独编出来——它是唯一不依赖 OpenCV 与 Ruckig 的包，一分钟内就能给你一个可用的类型系统，先把第七节的第一层验证跑通，再回头补全量编译。这种"先最小可用、再完整构建"的顺序，能把"环境不通"和"编译太慢"两个焦虑分开解决，比一上来就干等二十分钟要可控得多。

顺带认清 19 个示例节点的价值：aimdk_examples_cpp 里的每个节点都对应一类官方接口的最小用法——读 BMS、听触摸、拉视频流、下关节指令。把它们当作"可运行的接口文档"来读，比直接翻几百 KB 的接口说明更快建立直觉；第七节选自环话题时，我也是从这些示例里挑的消息体最简的那个。

三、三种环境方案：原生、容器与 WSL2 的取舍

官方给了两种环境方案（Docker 工具链与本机手装），加上社区里常见的 WSL2，实际有三条路。我的建议不变：第一次上手用 Docker，长期开发落原生，WSL2 只作为读代码与轻量编译的过渡。

Docker 路线的核心价值是"跳过"：官方 docker_x86_native_x86 镜像内已预置指南 2.1.7 节所列的全部编译依赖，你不需要在本机装一个包，就能拿到 Summary: 4 packages finished，适合先建立信心的人。镜像选择上，docker_x86_native_x86 编译 x86 产物、直接在开发 PC 运行；docker_x86_cross_arm 交叉编译 ARM 产物、用于板载部署。第一次验证请选前者——你要的是在自己机器上看到四行 Finished，不是给板子准备二进制。顺带一提，Windows 上的 Docker Desktop 默认就跑在 WSL2 里，所以"用 Docker"和"用 WSL2"在实践中经常是同一套内核，区别只在你看得见的那一层：Docker 给你的是一个构建沙箱，WSL2 给你的是一整个 Linux 开发机。要注意的还有容器边界：源码目录要挂载进容器，UID 映射有时会让构建产物属主变成 root，回头在本机 git status 一片红；联调还要把网络与显示显式放进去，这些都是容器隔离性的对价。

WSL2 路线能编译，是因为它的用户态就是完整的 Ubuntu 22.04，ROS 2 Humble 的 apt 包原样可用。但 DDS 节点发现默认依赖多播（multicast），WSL2 默认 NAT 网络模式下，多播流量进出物理局域网并不顺畅，换到较新 Windows 的镜像网络模式才有明显改善；等真要接机器人时，你很可能要把整套验证在原生 Linux 上重做一遍。另一个隐性成本是文件 IO：OpenCV 源码编译涉及数万个小文件，放在 /mnt/c 这类跨系统文件系统上会慢一个数量级，必须放进 WSL 原生 ext4 分区。另外要区分：WSL2 里跑 Docker Desktop 与直接跑 colcon 是两回事——前者只是构建沙箱，后者才是完整开发机，别把"WSL 能用 Docker"错当成"WSL 适合开发"。

原生路线是官方唯一明确推荐的环境，也是唯一在"编译—联调—可视化"全链路都没有额外折损的选择，代价是依赖要自己装——这正是下一节的主题。如果三条路都想试试，推荐的顺序是：Docker 一晚拿到编译结果，原生装环境做长期开发，WSL2 留给出差时在笔记本上读代码。切换环境时唯一要带走的是 SDK 源码本身——编译产物与 install/ 目录都是环境绑定的，换机器必须重编，这一点没有捷径。

图2：原生Ubuntu、Docker与WSL2三种环境方案的选型对比

四、依赖与网络：apt 源、rosdep、国内镜像与代理

4.1 从公共依赖到三类语言环境

指南 2.1.7 把依赖分成公共、C++、Python 三组，建议完整安装。我把三组合并成一条龙脚本，可以整段粘贴，也可以按注释截取：

# ========== A. 公共依赖（无论 C++ 还是 Python 都绕不开）==========
sudo apt update && sudo apt install -y \\
python3-colcon-common-extensions \\
python3-dev \\
python3-pip \\
ros-humble-rosidl-default-generators \\
ros-humble-rosidl-default-runtime

# 自检：能显示版本号（如 0.20.x）才算真正装上了
pip3 show colcon-core | head -3

# ========== B. C++ 专用：OpenCV 从源码编，但底层编解码仍依赖系统库 ==========
sudo apt install -y \\
git cmake build-essential pkg-config \\
libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \\
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \\
libyaml-cpp-dev ffmpeg

# ruckig 默认同时构建 Python 模块，必须装 nanobind
python3 -m pip install –user nanobind

# ========== C. Python 专用：示例里 get_video_stream.py 需要 cv2 ==========
pip3 install numpy opencv-python
python3 -c "import numpy, cv2; print(numpy.__version__, cv2.__version__)"

这段命令来自官方指南 2.1.7，但每一组都有"不装会怎样"的后果，值得说透。A 组五个包里，colcon 是构建入口，rosidl-default-generators 负责把 .msg 编译成 C++/Python 代码，python3-dev 给 C 扩展提供头文件——缺 rosidl 生成器，aimdk_msgs 直接编不出来，而它是整条链的上游。B 组八个包没有一个是可省的：libavcodec-dev 等四个是 FFmpeg 头文件，供 get_video_stream 示例通过 RTSP 解码；libgstreamer1.0-dev 是 OpenCV videoio 的另一条后端；nanobind 是 Ruckig 生成 Python 绑定的唯一途径。如果你跳过 nanobind，编译会在 ruckig_for_primebot 阶段失败，而报错信息里通常不会出现 “nanobind” 三个字，这是最浪费时间的一个坑。C 组两条自检是我加的：先把 numpy 与 cv2 的导入跑通，比等到 python3 demo.py 报 ModuleNotFoundError 再回头查要省事得多。

安装方式上还有一个 Ubuntu 22.04 特有的坑：系统的 Python 3.10 起启用了 PEP 668 保护，直接 pip3 install 可能报 externally-managed-environment。解法有三——用 –user 装进用户目录（本文示例默认如此）、建 venv 虚拟环境、或者改用 python3-xxx 的 apt 版本。不建议直接 –break-system-packages，那等于把系统 Python 的依赖树交给裸 pip，将来升级 ROS 2 相关包时容易撞见难以追溯的冲突。apt 管系统级依赖、pip 管 Python 生态包，这条边界守住，环境才能长期可维护。

4.2 apt 源、rosdep 与代理：国内网络的三种解法

依赖装不上，一半是网络问题。Ubuntu 官方源与 rosdep 的索引都在境外，直连时快时慢。这里给出三种解法及其取舍，请按你的网络环境选用，镜像地址与代理端口以实际配置为准：

# —- 解法一：换国内 apt 镜像（以清华源为例，长期受益）—-
sudo sed -i.bak 's|archive.ubuntu.com|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list
sudo sed -i.bak 's|security.ubuntu.com|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list
sudo apt update

# —- 解法二：rosdep 的 rosdistro 索引换国内镜像 —-
# rosdep init/update 默认从 GitHub 拉索引，国内常卡住不动
export ROSDISTRO_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/rosdistro/index-v4.yaml
rosdep update

# —- 解法三：走本机代理（以 Clash 的 7897 混合端口为例）—-
export http_proxy=http://127.0.0.1:7897
export https_proxy=http://127.0.0.1:7897
# 机器人网段务必走直连，别让联调流量绕路代理
export no_proxy=localhost,127.0.0.1,10.1.1.0/24

三种解法的边界很清楚：换镜像一劳永逸，但镜像同步有延迟，极少数刚发布的包可能暂时没有；rosdep 索引镜像只解决 rosdep update 卡死这一类问题，与 apt 源互不干扰，可以同时用；代理最通用，能兜住镜像覆盖不到的境外资源，但它只代理 TCP 层的 HTTP(S) 流量——DDS 的多播与 UDP 数据不过代理。所以代理解决的是"装依赖"，解决不了"连机器人"，后者靠的是 no_proxy 排除机器人网段，加上第六节的内核参数。把这三者的边界想清楚，就不会在"代理开着却连不上机器人"的伪问题上空转半小时。

顺便说清 rosdep 的定位：它解析的是 package.xml 里的 <depend> 声明，把"这个包需要哪些系统库"自动翻译成对应发行版的 apt 包名。SDK 的编译其实不强制依赖它——官方指南让你手动装的就是全部所需；但只要你开始写自己的包、或者集成第三方 ROS 2 包，rosdep 就是绕不开的一环。这也是为什么它值得在环境阶段就配好：索引卡死这种事，等到编译进行到一半才遇到，格外挫败。

镜像与代理也不是二选一。实践中常见的组合是：apt 换国内镜像（体量最大、收益最高），rosdep 索引换镜像（解决卡死），GitHub 上的零星资源走代理（兜底）。三者叠加不会冲突，因为它们作用在不同的流量上；真正会冲突的是同时给 apt 配镜像又配代理——流量绕一大圈，反而更慢。

五、编译：一条命令，但要盯住三个输出

# 1. 解压（官方以 primebot_sdk.tar.gz 分发；GitHub 上是源码目录，效果相同）
tar -xzf primebot_sdk.tar.gz
cd primebot_sdk

# 2. 编译：Release 一定要显式指定，默认是空 build type
colcon build –cmake-args -DCMAKE_BUILD_TYPE=Release

# 3. 加载环境（每个新终端都要执行，路径必须是绝对路径）
source /path/to/your/primebot_sdk/install/setup.bash

第三条的路径必须换成你的绝对路径，官方文档专门用加粗强调过。原因是 install/setup.bash 里写的是相对自身的路径前缀，用 ~ 或相对路径 source 在部分 shell 下会解析失败；而"没加载环境"的报错要到运行期才出现，很容易被误判成编译问题。三个步骤各自独立：解压只是铺开源码，编译产出 build/ 与 install/ 两套目录，source 则把编译产物注册进当前 shell——后两个动作每个新终端都要重做，漏掉任意一个，都会在下一节以"命令找不到"或"类型不存在"的形式回来找你。

执行完 colcon build 后，请盯住三处输出：

💡 为什么必须 Release：ruckig_for_primebot 是实时轨迹规划库，Debug 版本单次 update() 的耗时可能是 Release 的数倍。你在开发机上用 Debug 编译、到板子上跑 Release，会发现"控制周期超时"的行为完全不同，属于典型的自找麻烦。

如果只改了一个文件想快速重编，colcon build 会跳过未改动的包，但 C++ 示例的增量编译偶尔会因头文件依赖判断失误而链到旧库——遇到"改了代码却没生效"时，先删掉 build/ 与 install/ 再来一次，比逐行查 CMake 快。每次构建的详细日志在 log/latest_build/ 目录下，排查失败时那里有完整命令行与错误上下文，比终端回滚出来的片段更可靠。

三个观察点里最容易被误判的是第二个：aimdk_opencv 段"没有日志"不等于成功。判断它是否真的在工作，可以另开一个终端用 top 看 cc1plus 进程是否占着 CPU——编译是 CPU 密集型活，处理器闲着而进度不动，说明构建根本没跑起来，或者早已卡在等待依赖上。

图3：四行完成输出加汇总的编译成功终端锚点

六、FastDDS 内核参数：二十兆缓冲区怎么才不算白设

这是整个环境里最容易被跳过、又最值得花十分钟理解的一节。

6.1 为什么偏偏是 20M

DDS 的可靠性不靠 TCP 重传那套，而是靠发送端缓冲排队加接收端缓冲抗抖动。像 /aima/hal/joint/state 这类高频话题，瞬时突发流量远超平均速率，如果 UDP socket 缓冲区太小，内核会直接丢包；DDS 层能否补救取决于 QoS 配置，补救不了就表现为"时通时不通"或帧率不足。官方因此把默认 profile 的 socket buffer 设成 20M，并在指南 6.7 节明确要求开发 PC 的内核上限同步调大。

为什么不用 TCP？因为机器人控制对延迟的敏感远高于对丢包的敏感：丢一帧关节状态可以等下一帧，晚到两百毫秒却可能让控制器基于旧世界模型做决策。DDS 用 UDP 加大缓冲区的组合，正是在这两者之间取平衡——把瞬时突发流量托在缓冲区里，用内存换时序的确定性。这也解释了为什么问题总是先在高频话题上暴露：平均速率不高，突发才致命。

6.2 profile 里的两个数与内核的两个参数

SDK 通过 ament_environment_hooks 自动加载 FastDDS 配置，安装后的文件在 <sdk-install>/share/aimdk_msgs/config/fastdds_profiles.xml，关键片段如下：

<!– aimdk_msgs/config/fastdds_profiles.xml：默认只启用 UDP 传输 –>
<transport_descriptor>
<transport_id>aimdk_udp_transport</transport_id>
<type>UDPv4</type>
<sendBufferSize>20971520</sendBufferSize>
<receiveBufferSize>20971520</receiveBufferSize>
</transport_descriptor>

<!– 可选：多网卡环境下绑定本机通信网卡 IP，切勿填写机器人 IP –>
<interfaceWhiteList>
<address>127.0.0.1</address>
<address>10.1.1.99</address>
</interfaceWhiteList>

两个 20971520 是 20×1024×1024，即 20M 字节。注意这是 profile 的请求值，不是实际生效值——实际拿到的缓冲区是 min(请求值, 内核上限)。内核上限小于请求值时，FastDDS 不会报错，只会静默使用一个更小的缓冲区，该丢的包照丢。这就是"配置明明设了 20M 却还在丢帧"的根因。对应的内核参数必须满足 >= 关系：

25165824 是 24M，比 20M 刻意大一档，留 4M 余量给同机其他 socket。不建议随手改小：改完不满足 rmem_max >= receiveBufferSize，等于改了个寂寞。反过来也有人问：能不能把内核设得更大，比如 64M？可以，但没有必要——缓冲区是上限而非预分配，设大了不费内存，却也治不了"根本没建连"那类问题，排查时还会给人"已经调过了"的虚假安全感。

6.3 临时、持久化与验证

# 临时生效（重启失效，适合快速验证）
sudo sysctl -w net.core.rmem_max=25165824
sudo sysctl -w net.core.wmem_max=25165824

# 持久化：写入 /etc/sysctl.d/，重启后由 sysctl –system 自动重放
sudo tee /etc/sysctl.d/99-primebot-sdk.conf >/dev/null <<'EOF'
net.core.rmem_max = 25165824
net.core.wmem_max = 25165824
EOF
sudo sysctl –system

# 验证：输出值必须大于等于 20971520
sysctl net.core.rmem_max net.core.wmem_max

这里有两个容易想当然的点。第一，sysctl -w 只改当前运行内核，重启即失效；持久化要靠 /etc/sysctl.d/ 写文件加 sysctl –system 重放，两步都做才算数。第二，验证不能省——sysctl net.core.rmem_max 的输出小于 20971520，后面所有通信排查都是无源之水。这两个参数仅适用于 Ubuntu/Linux，其他系统的参数名与设置方式不同，不要照抄。

还有两个可选项值得知道。其一，SDK 的 profile 里预留了 aimdk_shm_transport 描述符但默认不启用——同机多进程场景（比如自环时跑多个节点）启用 SHM 能绕过 UDP 直接走共享内存，延迟和 CPU 占用都更低；跨机器通信它无能为力，所以默认关着。其二，interfaceWhiteList 绑定本机 IP 只解决"多网卡选错出口"的问题，填成机器人 IP 反而会让本机监听不到正确网卡。内存方面不必担心"24M 是不是浪费"：rmem_max 是上限而非预分配，实际占用随流量走；但同机跑十几个 DDS 进程时，要按进程数核算总量。

图4：二十兆socket缓冲区与二十四兆内核上限的匹配链

七、不接机器人，怎么证明环境真的通了

这是本文的核心。编译成功只说明"代码能生成二进制"，不说明"消息能被解析、DDS 能被加载"。我按可信度从低到高做了三件事，全部不需要机器人。

7.1 第一层：消息契约能被读出来

source /opt/ros/humble/setup.bash
source /path/to/your/primebot_sdk/install/setup.bash

# 第一层：消息契约可读
ros2 interface list | grep aimdk_msgs | head -20
ros2 interface show aimdk_msgs/msg/TouchState
python3 -c "from aimdk_msgs.msg import TouchState; \\
print(TouchState.get_fields_and_field_types())"

# 第二层：DDS 环境变量被自动挂上
echo $RMW_IMPLEMENTATION
echo $FASTRTPS_DEFAULT_PROFILES_FILE
grep -E "sendBufferSize|receiveBufferSize" \\
$(dirname $FASTRTPS_DEFAULT_PROFILES_FILE)/fastdds_profiles.xml

预期输出里能看到 aimdk_msgs/msg/ 与 aimdk_msgs/srv/ 两组类型，ros2 interface show 则会把 TouchState 的字段结构原样打印出来。第一层不需要任何网络，是最纯粹的"工具链是否正确"证明：rosidl 把 .msg 文本编译成类型、安装进 share 目录、注册进 ROS 类型系统，三步任何一步断了，这条命令都会以 Invalid network type 或"查不到类型"失败。Python 导入是同一契约的另一半证据——它证明生成的不只是 C++ 头文件，你的 Python 业务代码同样拿得到类型定义。如果这层挂了，问题一定在编译链而不是通信链，排错范围直接砍半。这一层还隐含一个方法论：它是整个验证链里唯一"零依赖"的一层——不碰网络、不碰 DDS、不碰内核参数。测试理论里管这叫隔离故障域：越靠近底层的检查，失败原因越单一。把最便宜的测试放在最前面，失败时你需要同时考虑的变量就最少，这就是三层顺序不可调换的原因。

7.2 第二层：DDS 环境变量被自动挂上

接着看同一段输出里的后三条命令。按官方 6.7 节的说明，source install/setup.bash 会在你没有手动设置 DDS 配置的前提下自动设置 RMW_IMPLEMENTATION=rmw_fastrtps_cpp 和两个 profile 文件变量。这一步的价值在于：很多"连不上机器人"的问题，根因就是你以为加载了 SDK 环境，实际上 RMW_IMPLEMENTATION 还是空值，于是用了默认的 CycloneDDS，和机器人侧的 FastDDS 各自发现各自的。两条 grep 出来的 20971520，则顺手把第六节的参数链闭环了——环境变量对、文件在、数值对，三者缺一不可。

RMW_IMPLEMENTATION 值得多说一句：它是 ROS 2 的"中间件实现"开关，同一套 rclcpp API 底下可以换不同的 DDS 厂商实现，常见的有 rmw_fastrtps_cpp（eProsima FastDDS）与 rmw_cyclonedds_cpp（Eclipse CycloneDDS）。两者发现机制与默认配置不同，跨实现的互通性有限。机器人侧用 FastDDS，开发 PC 就必须用 FastDDS——SDK 通过环境钩子自动挂载，就是为了消灭"一边一个实现"这种最难排查的不对称。

顺带一提，ros2 interface list | grep aimdk_msgs 出来的类型数量本身也是一条信息：它应当覆盖接口说明里的全部 Service/Topic。如果数量明显偏少，说明有 .msg 没被安装——这通常不是编译失败，而是工作空间里混进了旧的 install/ 目录，先清理再重编，比逐条比对清单高效。

7.3 第三层：本机自环收发（无真机的关键一招）

没有机器人，但可以自己发、自己收。官方示例里的触摸话题是最佳标的，因为它的消息体极简：

# 终端 A：模拟机器人发布触摸事件（event_type=1 表示单次点击）
ros2 topic pub /aima/hal/touch/state aimdk_msgs/msg/TouchState \\
'{header: {}, event_type: 1}' -r 1

# 终端 B：订阅并打印
ros2 topic echo /aima/hal/touch/state

终端 B 应该每秒刷出一段 header / event_type: 1 / —。选 TouchState 做标的不是偶然：它只有 header 与 event_type 两个字段，header 传空字典合法（stamp 默认 0、frame_id 默认空串），不需要猜任何默认值。这条链路跑通，等于证明了四件事：消息包能用、FastDDS 能用、/aima/ 命名空间能被解析、你的终端环境变量全都对。等真机到手，把终端 A 换成机器人进程，代码一行不用改。

也要说清自环的边界：它证明的是"这条链路在你机器上是通的"，不证明机器人侧的进程活着、开发者模式开着、网段对齐。自环通过而真机连不上，问题一定在机器人侧或网络侧；自环都通过不了，却先去折腾网线，那是顺序颠倒。把这两类故障分开，正是这套验证方法最大的产出。

如果想把这套验证固化下来，可以把三层命令写成一个 env_check.sh：依次执行 interface show、环境变量检查、十秒自环，任何一步非零退出即打印"停在哪一层"。这样换机器、换容器、团队新人入职时都是一条命令，而不是凭记忆敲七八行。脚本本身也是文档——它把"什么算通过"变成了可执行的判定，而不是口口相传的经验。

终端B（订阅）

FastDDS 域

终端A（模拟发布）

终端B（订阅）

FastDDS 域

终端A（模拟发布）

#mermaid-svg-n6Zpm2f6MlzNb7dy{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-n6Zpm2f6MlzNb7dy .error-icon{fill:#552222;}#mermaid-svg-n6Zpm2f6MlzNb7dy .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-n6Zpm2f6MlzNb7dy .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-n6Zpm2f6MlzNb7dy .marker{fill:#333333;stroke:#333333;}#mermaid-svg-n6Zpm2f6MlzNb7dy .marker.cross{stroke:#333333;}#mermaid-svg-n6Zpm2f6MlzNb7dy svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-n6Zpm2f6MlzNb7dy p{margin:0;}#mermaid-svg-n6Zpm2f6MlzNb7dy .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-n6Zpm2f6MlzNb7dy text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-n6Zpm2f6MlzNb7dy .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-n6Zpm2f6MlzNb7dy .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-n6Zpm2f6MlzNb7dy #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-n6Zpm2f6MlzNb7dy .sequenceNumber{fill:white;}#mermaid-svg-n6Zpm2f6MlzNb7dy #sequencenumber{fill:#333;}#mermaid-svg-n6Zpm2f6MlzNb7dy #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-n6Zpm2f6MlzNb7dy .messageText{fill:#333;stroke:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-n6Zpm2f6MlzNb7dy .labelText,#mermaid-svg-n6Zpm2f6MlzNb7dy .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .loopText,#mermaid-svg-n6Zpm2f6MlzNb7dy .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-n6Zpm2f6MlzNb7dy .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-n6Zpm2f6MlzNb7dy .noteText,#mermaid-svg-n6Zpm2f6MlzNb7dy .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-n6Zpm2f6MlzNb7dy .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-n6Zpm2f6MlzNb7dy .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-n6Zpm2f6MlzNb7dy .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-n6Zpm2f6MlzNb7dy .actorPopupMenu{position:absolute;}#mermaid-svg-n6Zpm2f6MlzNb7dy .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-n6Zpm2f6MlzNb7dy .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-n6Zpm2f6MlzNb7dy .actor-man circle,#mermaid-svg-n6Zpm2f6MlzNb7dy line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-n6Zpm2f6MlzNb7dy :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

收到即证明 4 项配置全部生效

publish /aima/hal/touch/state

每 1s 一次事件

图5：从消息契约到自环收发的三层无真机验证

八、六条编译报错，按出现频率排

逐条说透背后的逻辑：

第 1 条：apt 装完 colcon 后，当前 shell 的命令哈希表还是旧的，于是 command not found。hash -r 强制刷新缓存即可；若你是 pip3 install –user 装的，还要确认 ~/.local/bin 在 PATH 里。不刷新缓存的代价不是"多试一次"，而是误判成"包没装上"去重装，越弄越乱。

第 2 条：examples/cpp/CMakeLists.txt 用 foreach 遍历 EXAMPLE_TARGETS，按目标名去 src/ 找同名 .cpp，找不到就直接报 Missing example source。修复不是改 CMake，而是让文件名与目标名严格一致——这个设计的用意是"加示例只需加一行"，反噬就是名字对不上时毫无商量余地。

第 3 条：ROS 2 的 CMake 工具链对中文路径、空格、特殊字符的解析非常脆弱，官方 6.3 节把这条列为"重要"。路径问题最阴险的地方在于报错信息指向编译器内部，看起来像工具链坏了，实际只是目录名。动手编译前先 pwd 看一眼，能省一小时。

第 4 条：缺 nanobind 时 Ruckig 的 Python 模块生成失败，但失败点在上游配置检测，报错文本里往往只有 CMake 的内部行号。这条没有捷径，记住"动 ruckig 先装 nanobind"就行。

第 5 条：没 source 的终端里不存在 aimdk_msgs 类型，ros2 topic echo 连反序列化都做不了。ROS 2 的环境是 per-shell 的，这不是缺陷而是设计——每个终端可以叠加不同的工作空间。习惯它，而不是绕过它。

第 6 条：即第六节的内核参数问题。它在自环场景就能复现，不必等真机：本机跑 100Hz 高频话题，缓冲区不足照样丢包。这也是我把"内核参数"从常见问题里单独提成一节的原因——它不是真机专属问题。

六条报错背后有一条共同规律：四条（1、4、5、6）是环境问题，两条（2、3）是路径与顺序问题。环境问题靠对照清单逐项排除，路径问题靠动手前检查——pwd 看一眼、pip3 show 跑一下，成本都是几秒钟。编译失败的排查顺序应该是：先看 Summary 确认哪个包失败，再回到第二节的依赖链定位该包的依赖，最后才逐行读报错。跳过前两步直接读报错，是新手最常走的弯路。

还有一条元规则：报错信息永远是最后的证据，而不是第一证据。先确认环境（依赖装没装、路径对不对、环境变量在不在），再读报错——ROS 2 工具链的报错经常是"下游炸裂、上游病因"，照着报错行去改，多半修的是症状，病根还在下一轮编译里等着你。

图6：六条高频编译报错的现象根因对策速查

九、适用边界与风险提示

这套流程能证明的：依赖完整、消息可生成、DDS 配置可加载、示例可执行。 这套流程不能证明的：任何机器人行为。包括但不限于运动模式切换、关节限位、力控表现、传感器数据质量。

先说平台边界。官方在指南 2.1.3 节写得很直白：暂不支持在 Mac、Windows 系统下进行开发。这不是态度问题，是事实问题——ROS 2 Humble 官方只为 Ubuntu 22.04 发布二进制包，rosidl 生成器、FastRTPS 的预编译库都没有 Windows/macOS 版本；SDK 里的 OpenCV 与 Ruckig 源码包也没有为这两个平台配置构建路径。硬要上，等于把整条工具链从源码搭一遍，省下的半天时间会以"诡异链接错误"的形式还回来。Windows 上值得做的只有读文档、读 URDF、看 display.launch 与 gazebo.launch 这类纯文本工作。根子在于 ROS 2 的发行版支持矩阵：Humble 官方目标平台就是 Ubuntu 22.04（Jammy）上的 amd64 与 arm64，Windows 与 macOS 均无对等支持。SDK 又叠加了 FastRTPS 预编译库与两个源码包，跨平台成本被再次放大。理解了这层，就能想明白为什么官方把"装不上依赖"的解法做进了 Docker 镜像，而不是逐个平台出教程。

再说版本漂移，这是离线分析最容易被忽视的风险。URDF 仓库的目录名带着版本号（如 Q1-V2.0-URDF-0601），而 display.launch 里写的是 $(find Q1-V2.0-URDF-0601)——包名是硬编码的，URDF 换一版，包名就变，launch 直接 find 不到包。SDK 的 .msg 同样可能随版本增删字段，本文引用的字段与参数以 2026-10 版为准。对策很朴素：在工程 README 里固定记录 SDK 版本、URDF 包名与日期，升级时先 diff 两份 .msg 再改业务代码，不要凭记忆迁移。同类问题也出现在 URDF 的几份变体上：显示用、运动学用、全范围版三份文件的关节限位数值并不一致，直接混用会得到互相矛盾的结论。版本漂移的防范从来不靠记性，而是靠每次分析都记录输入文件的版本标识。

三个必须提前知道的真机风险：

• 开发者模式会改变维保状态。官方在启用须知里写得很明确：开启开发者功能后"不再享受维保服务"。这是不可逆的口头契约，动手前请想清楚。
• 运控板算力极度紧张。指南 2.1.6 明确"不建议在此部署应用或存储大数据"。把训练脚本、日志、模型权重放到运控板，后果是运控抖动。
• 不要动系统目录。二开程序只应写 /home/user/、/robot/persist/log/、/opt。写 /etc 导致服务拉不起来时，官方明确建议"停止一切危险操作并联系售后"，且不支持自行强刷固件。

最后是留证习惯：遇到无法自行定位的问题时，按官方 6.8 节的建议导出日志再反馈——附上机器人软件版本、SDK 版本、复现步骤三件套，比一句"连不上"高效得多。开发机上同样值得保留 log/ 目录，它是你回溯"上次明明是好的"的唯一凭据。

#mermaid-svg-TASgWmomY73miIwm{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-TASgWmomY73miIwm .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-TASgWmomY73miIwm .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-TASgWmomY73miIwm .error-icon{fill:#552222;}#mermaid-svg-TASgWmomY73miIwm .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TASgWmomY73miIwm .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-TASgWmomY73miIwm .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TASgWmomY73miIwm .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TASgWmomY73miIwm .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-TASgWmomY73miIwm .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TASgWmomY73miIwm .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TASgWmomY73miIwm .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TASgWmomY73miIwm .marker.cross{stroke:#333333;}#mermaid-svg-TASgWmomY73miIwm svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TASgWmomY73miIwm p{margin:0;}#mermaid-svg-TASgWmomY73miIwm defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-TASgWmomY73miIwm g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-TASgWmomY73miIwm g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-TASgWmomY73miIwm g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-TASgWmomY73miIwm g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-TASgWmomY73miIwm g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-TASgWmomY73miIwm .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-TASgWmomY73miIwm .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-TASgWmomY73miIwm .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-TASgWmomY73miIwm .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-TASgWmomY73miIwm .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-TASgWmomY73miIwm .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-TASgWmomY73miIwm .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-TASgWmomY73miIwm .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-TASgWmomY73miIwm .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-TASgWmomY73miIwm .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-TASgWmomY73miIwm .edgeLabel .label text{fill:#333;}#mermaid-svg-TASgWmomY73miIwm .label div .edgeLabel{color:#333;}#mermaid-svg-TASgWmomY73miIwm .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-TASgWmomY73miIwm .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-TASgWmomY73miIwm .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-TASgWmomY73miIwm .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-TASgWmomY73miIwm .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-TASgWmomY73miIwm .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TASgWmomY73miIwm .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TASgWmomY73miIwm #statediagram-barbEnd{fill:#333333;}#mermaid-svg-TASgWmomY73miIwm .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TASgWmomY73miIwm .cluster-label,#mermaid-svg-TASgWmomY73miIwm .nodeLabel{color:#131300;}#mermaid-svg-TASgWmomY73miIwm .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-TASgWmomY73miIwm .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-TASgWmomY73miIwm .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-TASgWmomY73miIwm .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-TASgWmomY73miIwm .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-TASgWmomY73miIwm .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-TASgWmomY73miIwm .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-TASgWmomY73miIwm .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-TASgWmomY73miIwm .note-edge{stroke-dasharray:5;}#mermaid-svg-TASgWmomY73miIwm .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-TASgWmomY73miIwm .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-TASgWmomY73miIwm .statediagram-note text{fill:black;}#mermaid-svg-TASgWmomY73miIwm .statediagram-note .nodeLabel{color:black;}#mermaid-svg-TASgWmomY73miIwm .statediagram .edgeLabel{color:red;}#mermaid-svg-TASgWmomY73miIwm #dependencyStart,#mermaid-svg-TASgWmomY73miIwm #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-TASgWmomY73miIwm .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-TASgWmomY73miIwm :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

接真机 + 开发者模式 + 网段对齐

本机自环（仅验证配置）

ros2 node/topic/service 全部可见

开始写业务代码

node list 为空

DomainID/网卡/防火墙

编译就绪

通信就绪

业务就绪

排查

这张状态图把全文结论画在了一起：编译就绪是唯一不需要真机的入口，而通信就绪有两条路——接真机，或者自环。自环那一支只验证配置，这也是它被画成平行分支而不是升级路径的原因；真正进入业务阶段之前，ros2 node list 为空时先查 DomainID、网卡与防火墙，而不是先怀疑自己的代码。

十、总结

回到开头的问题：没有机器人，能不能先把启元 Q1 的开发环境跑通？能，而且值得先做。因为 SDK 的编译链路和真机是解耦的——aimdk_msgs 生成消息契约、aimdk_opencv 编源码、ruckig_for_primebot 出轨迹库，这三件事都不需要机器人参与；真正需要机器人的，只有 DDS 发现之后的那一段。把"编译即验证契约"这个认知建立起来，你就再也不会用 ping 去检验工具链了。

本文给出的路径分四步：选环境（首次 Docker、长期原生、WSL2 只过渡）、装依赖（三组安装加三种网络解法）、编译（一条命令盯三个输出）、验证（ros2 interface show 读契约、环境变量自动挂载、触摸话题自环收发）。其中 20971520 与 25165824 这组数字值得单独记住：它们是 profile 请求值与内核上限的匹配关系，只改一边等于没改，这也是自环阶段"有节点无数据"类问题的总根因。

需要提醒的是，本文验证的是工具链，不是能力。三层验证全部通过之后，你的机器就处于"插上网线、打开开发者模式、重启一次"即可接管的状态——剩下的，只是把终端 A 从 ros2 topic pub 换成真实的机器人进程。

参考资料