1. 为什么 Jetson Thor 的环境配置和普通 x86 主机完全不是一回事如果你之前一直在 x86 台式机或者普通笔记本上折腾 ROS2第一次拿到 Jetson Thor 这类 ARM64 边缘计算平台时大概率会经历一段相当别扭的适应期。我自己从 Jetson Orin 一路用到 Thor踩过的坑足够写满一个笔记本。很多人以为环境配置就是装个系统、配个源、apt install 一把梭但在 Thor 上这套思路会让你在第一个星期就卡死。Jetson Thor 的核心定位是面向具身智能和人形机器人场景的高性能边缘计算模组它跑的是 NVIDIA 自家的 JetPack 系统底层是 ARM64 架构的 Ubuntu。这意味着三件事第一大量 x86 上现成的二进制包在这里根本装不上必须从源码编译第二NVIDIA 的 CUDA、TensorRT、cuDNN 版本和系统镜像强绑定不能像 PC 上那样随便升级驱动第三人形机器人常用的 Unitree SDK、ROS2 中间件、实时通信库在 ARM64 上的编译行为和 x86 有微妙差异尤其是涉及 SIMD 指令和内存对齐的部分。所以这篇内容我打算按真实上手顺序来讲从拿到机器后的系统确认到 ROS2 的安装与中间件选型再到 Unitree SDK 的编译接入最后是 VSCode 远程开发环境的搭建。每一步我都会说清楚为什么这么做以及不这么做会怎样这些是官方文档里通常不会写、但实际会卡住你半天的东西。提示本文所有操作基于 JetPack 6.x 系列镜像和 Ubuntu 22.04ROS2 Humble 的官方支持版本。如果你拿到的是更新或更旧的镜像部分包名和路径需要自行核对但整体思路一致。2. 拿到机器后的第一件事把系统底细摸清楚2.1 确认 JetPack 版本与 L4T 版本很多人上来就开始装东西结果装到一半发现 CUDA 版本对不上。正确的第一步是先确认三个版本号JetPack 版本、L4TLinux for Tegra版本、CUDA 版本。这三个是绑定的查清楚才能决定后面装哪个版本的 PyTorch、TensorRT 和 ROS2 相关包。# 查看 L4T 版本 cat /etc/nv_tegra_release # 查看 JetPack 版本部分镜像有 cat /etc/nv_boot_control.conf # 查看 CUDA 版本 nvcc --version # 查看系统架构 uname -muname -m应该输出aarch64如果不是说明你拿到的不是 ARM64 镜像后面所有编译都要重新考虑。L4T 版本号里的R36对应 JetPack 6.xR35对应 JetPack 5.x这个对应关系一定要记住因为 NVIDIA 的很多文档是按 L4T 版本组织的。2.2 换源这件事Thor 上要格外小心国内环境下换 apt 源是常规操作但 Jetson 平台有个坑NVIDIA 自己的源repo.download.nvidia.com里放的是 CUDA、TensorRT 这些核心包如果你把整个sources.list替换成普通的 Ubuntu 镜像源NVIDIA 的包就找不到了。我的做法是只替换 Ubuntu 官方部分保留 NVIDIA 源不动# 备份原配置 sudo cp /etc/apt/sources.list.d/nvidia-l4t-apt-source.list /etc/apt/sources.list.d/nvidia-l4t-apt-source.list.bak # 只修改 ubuntu 主源把 ports.ubuntu.com 换成国内镜像 sudo sed -i s|ports.ubuntu.com|mirrors.tuna.tsinghua.edu.cn|g /etc/apt/sources.list注意 Jetson 是 ARM64用的是ports.ubuntu.com而不是archive.ubuntu.com这个细节很多人会搞错换成archive之后 apt update 会直接报错找不到包。2.3 磁盘空间与散热的前置检查Thor 的 eMMC 或者 NVMe 容量有限ROS2 全套加上 Unitree SDK 的依赖轻松吃掉二三十个 G。装之前先看一眼df -h如果根分区剩余不到 30G建议先把 Docker 镜像目录、ROS2 工作空间这些重定向到大容量存储上。另外 Thor 在高负载编译时发热明显如果你是在封闭机箱里跑编译大型包比如带 CUDA 的 PyTorch时最好确认散热方案到位否则会触发降频编译时间翻倍。3. ROS2 Humble 在 ARM64 上的安装与中间件抉择3.1 为什么选 Humble 而不是最新版ROS2 的版本选择在 Jetson 上不是越新越好。Humble 是 Ubuntu 22.04 的官方长期支持版本而 JetPack 6.x 的底层正好是 22.04两者匹配度最高。如果你硬上 Jazzy 或者 Rolling会遇到大量依赖包在 ARM64 上没有预编译版本的问题最后被迫从源码编译整个 ROS2那个时间成本不是一般项目能承受的。安装走官方 apt 流程即可但有几个 ARM64 特有的注意点# 添加 ROS2 源 sudo apt install software-properties-common sudo add-apt-repository universe sudo apt update sudo apt install curl -y sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] \ http://packages.ros.org/ros2/ubuntu $(. /etc/os-release echo $UBUNTU_CODENAME) main | \ sudo tee /etc/apt/sources.list.d/ros2.list /dev/null sudo apt update sudo apt install ros-humble-desktop -yros-humble-desktop这个包在 ARM64 上是有的但体积很大包含 RViz2、Gazebo 相关组件。如果你只是做底层通信和 SDK 接入装ros-humble-ros-base就够了能省下好几个 G 的空间和大量编译依赖。3.2 CycloneDDS 为什么是人形机器人场景的首选ROS2 默认的中间件是 Fast DDS但在人形机器人这种多节点、高频传感器数据、对延迟敏感的场景下CycloneDDS 往往表现更稳。原因有几个CycloneDDS 的配置更透明网络发现机制在复杂网络环境下更可控它的零拷贝zero-copy支持在共享内存场景下延迟更低而且 Unitree 的官方 SDK 示例里大量使用 CycloneDDS生态匹配度更好。安装和切换sudo apt install ros-humble-rmw-cyclonedds-cpp -y # 临时切换 export RMW_IMPLEMENTATIONrmw_cyclonedds_cpp # 永久写入 echo export RMW_IMPLEMENTATIONrmw_cyclonedds_cpp ~/.bashrc但光切换还不够CycloneDDS 默认配置在某些网络下会发现不到节点。建议写一个配置文件!-- ~/cyclonedds.xml -- CycloneDDS xmlnshttps://cdds.io/config Domain idany General NetworkInterfaceAddressauto/NetworkInterfaceAddress AllowMulticasttrue/AllowMulticast /General Internal Watermarks WhcHigh500kB/WhcHigh /Watermarks /Internal /Domain /CycloneDDS然后通过环境变量指定export CYCLONEDDS_URIfile://$HOME/cyclonedds.xml注意NetworkInterfaceAddress如果写auto在多网卡机器上可能选错网卡导致节点互相发现不了。人形机器人上通常有有线网口连执行器、WiFi 连上位机这时候要明确指定网卡名比如eth0或wlan0。3.3 零拷贝配置别被名字骗了ROS2 的零拷贝loaned messages在 ARM64 上确实能用但它有严格前提发布者和订阅者必须在同一个进程内或者通过共享内存传输且消息类型要支持。很多人以为开了零拷贝就万事大吉结果发现延迟没降反升原因是配置不当导致走了网络回环。实际配置时重点是确认rmw_cyclonedds_cpp启用了共享内存并且ROS_LOCALHOST_ONLY没有误开。如果你做的是单机内的传感器数据处理零拷贝收益明显如果是跨机器通信零拷贝基本用不上别在这上面浪费时间。4. Unitree SDK 在 Thor 上的编译接入实战4.1 依赖梳理先搞清楚 SDK 到底要什么Unitree 的 SDK无论是 unitree_sdk2 还是 unitree_ros2在 ARM64 上编译最常见的失败原因是依赖缺失。核心依赖包括依赖项作用ARM64 注意点CMake 3.16构建系统系统自带版本通常够用Eigen3矩阵运算apt 安装即可注意头文件路径Boost网络与线程部分组件需从源码编译yaml-cpp配置解析apt 版本可能偏旧CycloneDDS通信中间件必须与 ROS2 用的版本一致这里最容易被忽略的是 CycloneDDS 版本一致性。如果你 ROS2 用的是 apt 装的 CycloneDDS而 SDK 编译时链接了另一个版本运行时会出现符号冲突表现为节点启动就崩报一堆undefined symbol。4.2 从源码编译 SDK 的完整流程# 创建工作空间 mkdir -p ~/unitree_ws/src cd ~/unitree_ws/src # 克隆 SDK以 unitree_sdk2 为例 git clone https://github.com/unitreerobotics/unitree_sdk2.git # 安装依赖 sudo apt install libeigen3-dev libboost-all-dev libyaml-cpp-dev -y # 编译 cd ~/unitree_ws colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPERelease--symlink-install在开发阶段很有用改 Python 脚本不用重新 build。CMAKE_BUILD_TYPERelease在 Thor 上尤其重要Debug 模式下编译出来的二进制体积大、运行慢人形机器人的实时控制循环扛不住。编译过程中如果报cannot find -lcyclonedds说明链接器找不到 CycloneDDS 库。解决办法是确认 ROS2 环境已经 source并且LD_LIBRARY_PATH包含 CycloneDDS 的库路径source /opt/ros/humble/setup.bash echo $LD_LIBRARY_PATH4.3 编译通过但运行报错的排查思路这是最折磨人的阶段。编译成功不代表能跑常见问题有三类第一类是权限问题。人形机器人的执行器通信通常需要访问特定网络接口或串口普通用户没权限。解决方式是配置 udev 规则或者把用户加入dialout组sudo usermod -aG dialout $USER # 需要重新登录生效第二类是实时性不足。Thor 默认内核不是实时内核控制循环的抖动可能达到毫秒级。如果 SDK 里有硬实时要求需要评估是否要打 RT 补丁或者用chrt提升线程优先级sudo chrt -f 80 ./your_control_node第三类是网络配置。Unitree 的执行器通常走特定网段Thor 上的网卡要配成对应网段的静态 IP否则 SDK 初始化时连不上设备报超时。5. VSCode 远程开发环境让 Thor 上的开发不再痛苦5.1 为什么强烈建议用远程开发而不是直接在 Thor 上写代码Thor 通常装在机器人本体上你不可能抱着机器人写代码。直接在 Thor 的终端里用 vim 改代码效率低到令人发指。正确做法是在你的主力开发机上用 VSCode通过 Remote-SSH 连到 Thor代码在 Thor 上编译运行编辑体验在你熟悉的机器上。这个方案的关键是 SSH 连接要稳定。Thor 和开发机最好走有线网络WiFi 在编译大包时容易断连导致编译中断。5.2 Remote-SSH 配置与 C/C 环境搭建在 VSCode 里装Remote - SSH扩展然后配置~/.ssh/configHost thor HostName 192.168.1.100 User your_username ForwardAgent yes连上之后在远程环境里装 C/C 扩展和 CMake Tools。这里有个坑VSCode 的扩展分本地和远程C/C 扩展必须装在远程端Thor 上否则智能提示和跳转不工作。c_cpp_properties.json的配置要包含 ROS2 和 SDK 的头文件路径{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /opt/ros/humble/include/**, /usr/include/eigen3, ${workspaceFolder}/install/** ], defines: [], compilerPath: /usr/bin/gcc, cStandard: c17, cppStandard: c17, intelliSenseMode: linux-gcc-arm64 } ], version: 4 }intelliSenseMode一定要设成linux-gcc-arm64设成 x64 会导致部分宏定义解析错误智能提示给出错误的类型推断。5.3 Python 环境与调试配置人形机器人项目里 Python 脚本通常用于上层逻辑和调试工具。Thor 上系统自带的 Python 是 3.10ROS2 Humble 也是基于 3.10所以不要随便用 conda 建一个 3.11 的环境会和 ROS2 的 Python 包冲突。如果确实需要独立环境用venv并且--system-site-packagespython3 -m venv --system-site-packages ~/venv/thor source ~/venv/thor/bin/activate这样既能装自己的包又能访问 ROS2 的 Python 模块。调试配置在.vscode/launch.json里指定python路径为 venv 里的解释器即可。6. 那些让我熬夜的坑真实排查记录6.1 编译 PyTorch 时内存爆掉在 Thor 上从源码编译带 CUDA 的 PyTorch是很多人绕不过去的一步。我第一次编译时机器直接卡死SSH 断连。原因是编译过程峰值内存占用超过 20G而 Thor 的共享内存有限。解决办法是限制编译并行度export MAX_JOBS4 python setup.py installMAX_JOBS设成 CPU 核心数的一半左右比较稳妥。另外可以临时加大 swapsudo fallocate -l 16G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile编译完记得关掉 swap否则 eMMC 寿命会受影响。6.2 CycloneDDS 节点发现失败的完整排查链路有一次两个节点死活发现不了对方ros2 node list只能看到本机的。排查过程是这样的第一步确认RMW_IMPLEMENTATION两边一致都是rmw_cyclonedds_cpp。不一致的话一个用 Fast DDS 一个用 CycloneDDS根本不在一个通信域里。第二步检查ROS_DOMAIN_ID是否一致。这个最容易被忽略两台机器 domain id 不同等于在两个平行世界。第三步用ros2 multicast receive和ros2 multicast send测试多播是否通。如果不通说明网络设备屏蔽了多播需要在 CycloneDDS 配置里改用单播发现指定 peers 列表。第四步检查防火墙。Ubuntu 默认的 ufw 如果开着会拦多播。sudo ufw status看一眼必要时放行或者直接关掉。这个链路走下来基本能定位 90% 的节点发现问题。剩下的 10% 通常是网卡选错回到 3.2 节说的NetworkInterfaceAddress配置。6.3 Unitree SDK 初始化超时的几种可能SDK 初始化超时报错信息通常很模糊只说连接失败。实际原因可能是执行器没上电、网线没插好、IP 网段不匹配、或者 SDK 版本和固件版本不兼容。我的排查顺序是先用ping确认物理连通再用 SDK 自带的测试工具单独测一个执行器最后才怀疑版本兼容性。一上来就怀疑版本问题往往会走很多弯路。7. 环境配好之后怎么验证整套链路是通的环境配置的终点不是装完了而是能跑通一个完整链路。我通常用一个最小验证流程启动一个 ROS2 节点发布话题用另一个节点订阅并打印同时确认 Unitree SDK 能读到执行器状态最后在 RViz2 里可视化一个简单的 TF 变换。这个流程能同时验证 ROS2 通信、中间件配置、SDK 接入和可视化工具任何一环出问题都会暴露出来。具体命令# 终端1发布 ros2 run demo_nodes_cpp talker # 终端2订阅 ros2 run demo_nodes_cpp listener # 终端3查看节点和话题 ros2 node list ros2 topic list ros2 topic echo /chatter如果 talker 和 listener 能正常通信说明 ROS2 和 CycloneDDS 配置没问题。接下来跑 SDK 的示例程序确认能读到执行器数据。最后启动 RViz2添加 TF 显示看坐标系是否正常。这套验证跑通之后你的 Thor 环境才算真正可用。后面再往上叠导航、运动规划、感知这些模块才有稳固的地基。我个人在实际操作中的体会是Jetson Thor 的环境配置最耗时的部分从来不是装而是排查为什么装不上、为什么跑不起来。把版本对应关系、中间件配置、网络发现这三件事吃透后面的事情会顺很多。另外强烈建议每配好一个环节就做一次快照或者记录Thor 这种平台一旦环境搞乱重装系统的成本比 x86 高得多。
