前言
启元 Q1 是启元机器人（PrimeBot）面向消费级市场推出的双足人形机器人：88cm 身高、15kg 量级、全身 22 个可编程关节，既支持高层动作编排（招手、比心、跳舞等预设动作与神经网络动作），也开放 1000Hz 的底层关节控制。对开发者更友好的一点是，它的 SDK 直接构建在 ROS 2 之上——二开门槛从"逆向私有协议"降到了"会用 ROS 2"，这让不少爱好者第一时间就想上手。
但真动手时，这些现实问题拦住了大多数人，尤其是 Windows 用户：
- 手里没机器——Q1 刚开启交付，而官方示例都假设真机在线，一个都跑不动；
- 用的是 Windows——官方环境要求 Ubuntu 22.04 + ROS 2，Windows 不在支持列表，光系统差异就够折腾一轮；
- 内置 17 个预设动作，未必有你想要的那个——比如敬礼。
如果我说一个Q1SDK,一个仿真平台、一台只有 Windows 的电脑，也能在今天之内让你看到它抬手敬礼——你会不会想试试？本文就走通这条路：WSL2 搭好官方环境 → 最小编译 SDK → MuJoCo/RViz 双仿真 → 手调姿态 + 限位投影 + 120fps 轨迹，做出真机可直接播放的敬礼动作。
全程 8 个坑如实记录在第七节——其中一个让笔者重启了四次电脑才定位。真机执行未实测，调用代码与前置条件已备好，机器到货后同一条链路直接复用。
一、环境与版本盘点
本次最终实测环境：
| 组件 | 版本 | 获取方式 |
|---|---|---|
| Q1 SDK | v1.0.0.0 | 启元开发者社区（dev.primebot.com/download ） |
| Q1 仿真模型包 | q1_v3 | 启元开发者社区（dev.primebot.com/download ） |
| Windows 11 | 26200.9711（Home China） | 本机 |
| WSL | 3.0.3.0（内核 6.18.54.1-1） | GitHub microsoft/WSL Releases 官方 MSI |
| Ubuntu | 22.04.5 LTS | 清华 TUNA ubuntu-cloud-images 镜像 |
| ROS 2 | Humble（ros-base + colcon） | 清华 TUNA ros2 镜像 |
| MuJoCo | 3.16.0 | PyPI（清华镜像） |
硬件：Intel Core Ultra 7 255HX / 32GB 内存，16GB 内存的机器即可完成本文全部步骤。动手前先约定两点，能省掉后面一半的坑：Linux 环境与所有数据放 D 盘（WSL 的 vhdx 支持自定义位置）；编译路径不含中文（官方 FAQ 明确要求）。
二、WSL2 安装与 Ubuntu 22.04 落盘
2.1 启用功能与安装 WSL
以管理员身份运行 PowerShell，启用两个 Windows 功能后重启：
dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart重启后安装 WSL 官方 MSI（Releases 页下载wsl.3.0.3.0.x64.msi，367MB）。不使用wsl --install的原因见第七节坑 1——它在非交互环境下会静默挂死。MSI 下载后建议核验：SHA256 值可从 Releases API 返回中获取（3.0.3.0 x64 为ae977286…1f211），Get-AuthenticodeSignature应显示微软签名有效。
2.2 导入 Ubuntu 22.04 到 D 盘
从清华镜像下载 rootfs 后导入（不装在 C 盘）：
curl -L -o D:\primebot\downloads\ubuntu-jammy-wsl.rootfs.tar.gz https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz mkdir D:\primebot\wsl\Ubuntu-22.04 wsl --import Ubuntu-22.04D:\primebot\wsl\Ubuntu-22.04 D:\primebot\downloads\ubuntu-jammy-wsl.rootfs.tar.gz --version 2导入后默认以 root 登录，创建日常用户并启用 systemd（用户名以 dev 为例）：
wsl -d Ubuntu-22.04 -u root useradd -m -G sudo -s /bin/bash dev echo "dev ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/dev && chmod 440 /etc/sudoers.d/dev printf '[user]\ndefault=dev\n[boot]\nsystemd=true\n' > /etc/wsl.conf exit wsl --terminate Ubuntu-22.04 && wsl -d Ubuntu-22.04 # 重启发行版生效三、安装 ROS 2 Humble
WSL 内以 dev 用户执行。先换 Ubuntu 主源为清华镜像，再配置 ROS 2 源——密钥必须从 rosdistro 仓库获取（镜像站的 key.gpg 地址已 404，详见第七节坑 3）：
sudo sed -i 's|http://archive.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g; s|http://security.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g' /etc/apt/sources.list sudo apt update && sudo apt install -y curl gnupg lsb-release curl -fsSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key | sudo tee /usr/share/keyrings/ros2.gpg > /dev/null echo "deb [signed-by=/usr/share/keyrings/ros2.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/ros2.list sudo apt update sudo apt install -y ros-humble-ros-base ros-dev-tools python3-colcon-common-extensions \ python3-dev python3-pip ros-humble-rosidl-default-generators ros-humble-rosidl-default-runtime echo 'source /opt/ros/humble/setup.bash' >> ~/.bashrc按官方指南的说明，真机联调前还需把内核 UDP 缓冲调大（FastDDS 大消息依赖，默认 208KB 不够）：
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 && sysctl net.core.rmem_max # 应输出 25165824四、SDK 消息包编译与验证
SDK 解压后关键目录：aimdk_msgs/（消息包，mc/hal/interaction/agent/common 五层）、examples/（Python 与 C++ 各 19 个示例）、接口说明.md（约 1.28 万行接口文档）。全量编译会从源码构建 OpenCV 4.13.0 等大件，耗时以几十分钟计；做消息链路验证只需最小编译：
mkdir -p ~/workspace && cp -r /mnt/d/primebot/sdk_q1-v1.0.0.0 ~/workspace/sdk_q1 cd ~/workspace/sdk_q1 source /opt/ros/humble/setup.bash colcon build --packages-select aimdk_msgs --cmake-args -DCMAKE_BUILD_TYPE=Release source install/setup.bash && echo 'source ~/workspace/sdk_q1/install/setup.bash' >> ~/.bashrc验证两件事——接口数量与定义可查：
ros2 interface list | grep -c aimdk_msgs # 输出 54 ros2 interface show aimdk_msgs/srv/PlayTts五、仿真调试：MuJoCo 与 RViz 两条路线
5.1 MuJoCo：带电机执行器的物理仿真
pip3 install mujoco pillow -i https://pypi.tuna.tsinghua.edu.cn/simple python3 -m mujoco.viewer --mjcf /mnt/d/primebot/q1_v3/xml/q1_v3_mc.xmlWSLg 会把 3D 窗口直接投到 Windows 桌面。仿真包三个模型分工明确：``（22 关节被动模型，看结构与物理）、q1_v3_full_range.xml（放宽限位）、q1_v3_mc.xml（每关节带 motor 执行器，做控制实验）。查看器里按住 Ctrl 拖拽机器人任意部位可施加外力。
5.2 RViz：关节滑块调试台
官方仿真包的 launch 文件是 ROS 1 格式且引用的 URDF 文件名与包内实际不符（ROS 2 下必败，见第七节坑 5），用 ROS 2 原生节点手动拉起三件套：
sudo apt install -y ros-humble-rviz2 ros-humble-robot-state-publisher ros-humble-joint-state-publisher-gui mkdir -p ~/workspace/q1_sim sed 's|filename="../meshes/|filename="file:///mnt/d/primebot/q1_v3/meshes/|g' \ /mnt/d/primebot/q1_v3/urdf/q1_v3.urdf > ~/workspace/q1_sim/q1_v3_abs.urdf { printf 'robot_state_publisher:\n ros__parameters:\n robot_description: |\n'; sed 's/^/ /' ~/workspace/q1_sim/q1_v3_abs.urdf; } > ~/workspace/q1_sim/rsp_params.yaml # 终端 1：--params-file 必须放在 --ros-args 之后（坑 6） ros2 run robot_state_publisher robot_state_publisher --ros-args --params-file ~/workspace/q1_sim/rsp_params.yaml # 终端 2：注意包名和可执行名都要写（坑 6） ros2 run joint_state_publisher_gui joint_state_publisher_gui # 终端 3：RViz 中 Fixed Frame 设为 pelvis，Add → RobotModel（话题 /robot_description） ros2 run rviz2 rviz2这套"滑块 → joint_states → TF → RViz 刷新"的链路就是机器人可视化调试的最小闭环，也是下一节制作动作的工作台。
六、核心功能实战：做一个能上真机的"敬礼"动作
Q1 内置动作表（3001 招手 ~ 3048 跳舞 C 等 17 个）没有敬礼。自定义动作走SetMcPresetMotion的 CSV 通道：固定 10 列关节角（双臂 8 + 腰 2），采样率严格 120fps。整个过程分四步，配套脚本在仓库motion/目录。
6.1 RViz 滑块手调目标姿态
在 RViz 关节滑块调试台环境里拖滑块找到满意的敬礼姿态。调好后joint_state_publisher_gui以 50Hz 持续发布/joint_states话题，另开终端执行一次即可抓全 22 个关节值：
ros2 topic echo /joint_states --once6.2 限位校验：滑块范围 ≠ 真机限位
这是全程最隐蔽的一个坑（坑 7）。手调姿态里right_elbow_joint = -0.87（负肘弯）在 RViz 完全合法，但 Q1 关节限位表规定肘关节 ∈ [0, 3.142]——真机不执行负值。处理办法是把目标姿态代入正运动学，在真机限位盒内做投影搜索：以手调姿态的手端位置为目标，MuJoComj_forward网格搜索最近的合法关节组合（完整实现见仓库motion/make_salute_csv.py）。实测手调目标点与合法可达点最近距离 7.3cm——Q1 每臂仅 4 自由度（肩 3 + 肘 1，无腕关节），"手贴太阳穴"在运动学上本就在可达域边缘，这类量化结论只有在仿真里、在真机试错之前才能拿到。
6.3 生成 120fps 轨迹与仿真回放
合法姿态确定后，用五次多项式（min-jerk）插值生成平滑轨迹——与官方 CSV 示例的曲线形态一致：
def quintic(t): return 10*t**3 - 15*t**4 + 6*t**5 # 轨迹 = 静息 -> 敬礼(1.1s) -> 定格(1.0s) -> 复位(1.1s)，共 384 帧 @120fps回放验证用仓库motion/render_preview.py：逐帧加载 CSV 在 MuJoCo 中渲染，确认平滑无抖动后导出。
七、踩坑总表：8 个实测坑
主线里提到的坑在这里统一给出根因与解法，按排查成本从高到低排序。坑 2 是本文耗时最长的故障（四次重启才定位），优先自查。
| # | 现象 | 根因 | 解法 |
|---|---|---|---|
| 1 | wsl --install 挂起 30 分钟无输出 | 非交互环境下商店组件获取阻塞 | 改用 DISM + 官方 MSI 离线安装（第二节） |
| 2 | 功能显示"已启用"，wsl --import 却报 HCS_E_SERVICE_NOT_AVAILABLE，重启三次无效 | 启动盘不足10GB：CBS 开机投影载荷需数 GB 暂存空间，不足则每轮开机放弃重试——vmcompute.exe 等文件从未落地，pending.xml 永不消化，形成"永远差一次重启"的假象 | 清理 C 盘至 10GB 以上空闲，再重启一次即恢复 |
| 3 | apt update 报 NO_PUBKEY F42ED6FBAB17C654 | 镜像站 key.gpg 已 404；且 curl | gpg 管道中 curl 失败不报错，生成 0 字节密钥文件，极难察觉 | 从 rosdistro 仓库取 ros.key（1167 字节），检查密钥文件 >1KB（第三节） |
| 4 | GitHub 下载 WSL MSI 极慢/断连 | 国际链路质量（实测单连接 42~71KB/s，同机 TUNA 20MB/s） | Ubuntu/ROS 资源走 TUNA；GitHub 独有资源用多线程分段下载（仓库 tools/segdl.sh，实测 1.4MB/s） |
| 5 | 官方仿真包 launch 报 Unrecognized entity: param | 包内是 ROS 1 格式（catkin/format2/ 语法），且引用的 URDF 文件名与实际不符——SolidWorks 导出后未做 ROS 2 适配 | ROS 2 三进程手动启动（5.2 节），官方包一个字不动 |
| 6 | Failed to open URDF file: --params-file / ros2 run 报缺参数 | –params-file 未跟在 --ros-args 后被当作 URDF 路径；ros2 run 需要包名+可执行名两个参数 | 严格按 5.2 节命令顺序 |
| 7 | RViz 里能调出的姿态，按值生成 CSV 后真机做不出 | URDF 滑块范围宽于真机限位（如肘关节允许负值） | 姿态值必须经限位投影后再生成轨迹（6.2 节） |
| 8 | git-bash 调 wsl.exe 时 /mnt/… 参数报路径不存在 | MSYS 路径自动转换改写了参数 | 命令前加 MSYS_NO_PATHCONV=1，或 wsl – bash -s < script.sh 喂 stdin；wsl.exe 输出为 UTF-16，管道中需 iconv -f UTF-16LE -t UTF-8 |
另有三条官方 FAQ 已覆盖的真机阶段预警，提前记录：多网卡环境（网线直连时建议禁 WiFi）、防火墙拦 UDP 大端口（ufw）、ROS_DOMAIN_ID需与机器人一致。
八、小结
回头看，这条"没有真机"的路线走完时，手里已经有了这些：一套合格的官方环境（WSL2 3.0.3 + Ubuntu 22.04.5 + ROS 2 Humble，全部落盘 D 盘）、一个通过最小编译并验证过 54 个接口的 SDK 工作空间、两条随时可用的仿真路线（MuJoCo 物理仿真与 RViz 滑块调试台），以及一个 384 帧、120fps、可直接上真机的敬礼动作文件。
比产出更值钱的是两条经验。其一，遇到"状态显示正确但行为异常"，先查资源类前提（磁盘、网络）再考虑重试——坑 2 的 启动盘空间问题让博主空耗了三次重启；其二，仿真的价值不在"看到机器人动"，而在真机试错之前拿到限位、可达域这类量化结论——6.2 节那个 7.3cm，是文档里查不到、只有算过才知道的数字。
本文用到的 SDK、仿真包与接口文档均来自启元机器人开发者社区：https://dev.primebot.com/ 。
下载页还提供各机型 SDK、工具链与文档，开发者模式与权限说明见《快速入门与集成指南》。
配套脚本全部开源：https://atomgit.com/qq_57761637/q1-sdk-salute。
