适用对象：第一次接触 Q1 / PrimeBot 机器人 SDK、ROS 2 和 DDS 的开发者。本文以 SDK v1.0.0.0 为依据，示例优先选用只读状态订阅与 TTS 服务调用。低层关节控制涉及真实硬件，务必先完成安全检查。

版本边界：本文源码目录为 sdk_q1-v1.0.0.0。SDK 当前以 ROS 2 接口作为开发入口；不要把它当成 HTTP SDK，也不要默认当前版本所有开发者模式菜单都已开放。

SDK 能做什么

Q1 SDK 的接口定义由 aimdk_msgs 提供，业务程序通常以 ROS 2 Node 的形式运行，通过 Topic、Service 或 Action 与机器人上的节点通信。SDK 底层使用 ROS 2 与 FastDDS，开发程序可以运行在开发 PC、运控板或大脑板上；开发 PC 调试时需要与机器人处于可互通的网络环境。

源码中包含：

目录	作用
aimdk_msgs/	自定义 ROS 2 消息、服务和动作接口，以及 FastDDS 配置
examples/python/	Python 订阅、服务、图像与运动控制示例
examples/cpp/	C++ ROS 2 示例
examples/ruckig_for_primebot/	关节轨迹生成相关依赖
examples/opencv/	OpenCV 源码包

常见功能按接口形态可这样理解：

• Topic：持续状态或事件流，例如 /aima/hal/bms/state 电池状态、/aima/hal/touch/state 触摸事件、关节状态。
• Service：请求一次、返回一次，例如 TTS 播报服务。
• Action：适用于有持续过程或状态反馈的任务；具体名称和字段以当前版本的接口定义及 接口说明.md 为准。

开发时先查接口定义和示例，不要仅凭 Topic 名猜消息字段。接口名称、消息类型、QoS 和部署模式都需要匹配。

开发前准备

支持环境

SDK 指南推荐 Ubuntu 22.04 + ROS 2 Humble。指南注明当前不支持在 macOS 或 Windows 上开发。因此即使 SDK 源码存放在 macOS 上，也应在 Ubuntu 22.04 环境（实体机、虚拟机或符合指南的容器）中构建和运行，不要直接在 macOS 终端执行 colcon build。

基础依赖包括：

• Ubuntu 22.04
• ROS 2 Humble
• python3-colcon-common-extensions
• SDK 示例所需的编译依赖；C++ 示例还涉及 OpenCV 与 Ruckig
• 能访问机器人 ROS 2 网络的有线或局域网连接

检查 ROS 2 环境：

lsb_release -d
echo "$ROS_DISTRO"
which ros2

预期发行版为 humble，which ros2 应返回 ROS 2 命令路径。如果 ROS_DISTRO 为空，先加载系统 ROS 环境：

source /opt/ros/humble/setup.bash

安装 colcon 扩展：

sudo apt update
sudo apt install -y python3-colcon-common-extensions

验证：

colcon --help

准备源码路径

SDK 指南建议构建路径使用英文字符，避免空格和特殊字符。当前源码示例位置是 sdk_q1-v1.0.0.0，这是 macOS 路径；在 Ubuntu 环境中必须先把 SDK 拷贝或挂载到 Ubuntu 可访问的英文路径，例如 ~/work/sdk_q1-v1.0.0.0，并在该环境里执行后续命令。

如果在虚拟机或容器中使用共享目录，先确认文件确实可见：

ls ~/work/sdk_q1-v1.0.0.0

应能看到 aimdk_msgs、examples、README.md 和快速入门指南等内容。

网络与机器人模式配置

开启开发者模式

机器人标准模式下，外部设备可能无法发现 ROS 2 节点。按厂商指南使用 PrimeBot 控制 APP 进入开发者功能，选择需要的开发模式并保存；配置变更需要按提示重新上下电才会生效。开发者模式可能影响原有模块或维保条件，开启前先阅读 SDK 附带的《友好用户使用声明》和产品说明。

SDK v1.0.0.0 的指南指出：当前默认通过 ROS 2 通信；目前明确生效的选项包括“运动控制 - 低层运控开发”，其它领域能力不能仅凭菜单项推断为已开放。

配置同网段网络

指南给出的常见默认地址为：

设备	示例 IP
开发 PC 有线网卡	10.1.1.99/24
机器人运控板	10.1.1.100
机器人大脑板	10.1.1.101

实际机器人地址以设备配置为准。先用操作系统网络设置将 PC 有线网卡配置到相同子网，再测试连通性：

ping -c 3 10.1.1.100
ping -c 3 10.1.1.101

如果地址不同，替换成现场配置。先确保链路可达，再继续排 ROS 2；ping 不通时直接调程序通常没有意义。

检查 ROS_DOMAIN_ID

ROS 2 节点只会在同一个 Domain 内互相发现。若机器人使用默认 Domain 0，开发 PC 不要意外设置成其它值：

echo "ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-未设置（通常为 0）}"

确认现场配置一致后再设置。不要为了“试试看”随意改成不同 Domain，否则节点会彼此不可见。

编译 SDK

在 Ubuntu 环境中打开新终端，加载 ROS 2 并进入 SDK 根目录：

source /opt/ros/humble/setup.bash
cd ~/work/sdk_q1-v1.0.0.0

首次构建执行：

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

成功时末尾会显示类似 Summary: ... packages finished，且没有包处于 failed 状态。若只想先构建消息包，可按 colcon 包选择规则构建 aimdk_msgs，但完整示例的依赖还需要额外构建。

编译完成后加载工作区：

source install/setup.bash

每个新终端都需要先加载 ROS 2，再加载 SDK 工作区。可以把以下两行放在开发终端的启动脚本中；路径要换成自己的实际工作区：

source /opt/ros/humble/setup.bash
source ~/work/sdk_q1-v1.0.0.0/install/setup.bash

SDK 的 aimdk_msgs 环境钩子会在未手动指定 DDS 配置时设置 FastDDS 实现和 profiles 路径。不要直接编辑 install/setup.bash，它是构建产物，重建可能覆盖。需要调整 DDS profile 时修改 aimdk_msgs/config/fastdds_profiles.xml 后重新构建。

验证自定义消息已被 ROS 2 识别：

ros2 interface show aimdk_msgs/msg/Bms
ros2 interface show aimdk_msgs/srv/PlayTts

如果提示找不到接口，优先检查当前终端是否 source 了正确的 install/setup.bash，以及 colcon build 是否成功。

先用 ROS 2 命令验证

用命令行验证能把问题分层：先确认接口类型，再确认机器人节点发现，最后确认业务数据是否到达。

查看节点和 Topic

ros2 node list
ros2 topic list

能看到节点表示 DDS 发现至少部分正常，不代表每个 Topic 都有数据。对电池状态做一次只读检查：

timeout 5 ros2 topic echo /aima/hal/bms/state --once

有输出表示当前能收到一条 BMS 消息。若超时，不要立刻判断 SDK 编译失败：该 Topic 可能没有数据源、网络未通，或 QoS/接口环境未正确加载。

查看类型和发布频率：

ros2 topic info /aima/hal/bms/state --verbose
ros2 topic hz /aima/hal/bms/state

验证触摸 Topic

触摸属于事件型数据，只有发生对应触摸事件时才可能有消息。指南提供了本机模拟发布与订阅的办法，可用于验证消息类型解析：

终端 A：

source /opt/ros/humble/setup.bash
source ~/work/sdk_q1-v1.0.0.0/install/setup.bash
ros2 topic pub /aima/hal/touch/state aimdk_msgs/msg/TouchState \
  '{header: {}, event_type: 1}' -r 1

终端 B：

source /opt/ros/humble/setup.bash
source ~/work/sdk_q1-v1.0.0.0/install/setup.bash
ros2 topic echo /aima/hal/touch/state

这段测试是开发机模拟数据，不代表真实触摸传感器或机器人控制链路已验证。停止发布时在终端 A 按 Ctrl+C。

调用 TTS Service

先确认服务存在：

ros2 service list | grep -i PlayTts

然后按 SDK 指南调用：

ros2 service call /aimdk_5Fmsgs/srv/PlayTts aimdk_msgs/srv/PlayTts \
  '{header: {}, tts_req: {text: "你好，我是启元机器人", priority_level: {value: 6}, domain: "sdk_test", is_interrupted: true}}'

服务返回 success=True 表示请求被服务接受；声音是否实际播放，还应结合机器人状态和现场表现确认。若服务名在目标设备上不同，以 ros2 service list 和当前 SDK 接口说明为准。

Python 核心用法

订阅 BMS 状态

SDK 自带 examples/python/get_bms_state.py。下面是一个最小化、可独立保存为 bms_monitor.py 的订阅程序：

#!/usr/bin/env python3
import rclpy
from rclpy.node import Node
from rclpy.qos import qos_profile_sensor_data
from aimdk_msgs.msg import Bms


class BmsMonitor(Node):
    def __init__(self):
        super().__init__("bms_monitor")
        self.subscription = self.create_subscription(
            Bms,
            "/aima/hal/bms/state",
            self.on_bms,
            qos_profile_sensor_data,
        )
        self.get_logger().info("Listening to /aima/hal/bms/state")

    def on_bms(self, msg: Bms):
        self.get_logger().info(
            f"battery={msg.remaining_capacity_percentage}% "
            f"voltage={msg.voltage / 1000.0:.3f}V "
            f"current={msg.current / 1000.0:.3f}A "
            f"temperature={msg.temperature:.1f}C"
        )


def main():
    rclpy.init()
    node = BmsMonitor()
    try:
        rclpy.spin(node)
    except KeyboardInterrupt:
        pass
    finally:
        node.destroy_node()
        rclpy.shutdown()


if __name__ == "__main__":
    main()

运行前在同一个终端加载环境：

source /opt/ros/humble/setup.bash
source ~/work/sdk_q1-v1.0.0.0/install/setup.bash
python3 bms_monitor.py

代码对应的 ROS 2 基本流程是：初始化 rclpy、创建 Node、创建订阅、由 spin 驱动回调、退出时销毁节点并关闭 rclpy。BMS 消息中 voltage 单位是 mV，current 单位是 mA；示例除以 1000 转成 V 和 A。电流正负方向以消息定义为准（充电为正、放电为负）。

调用 Service 的代码结构

如果需要在自己的 Python 节点里调用 TTS，可参照下面的 ROS 2 Client 结构。具体请求字段请以 PlayTts.srv 和消息定义为准；调用前也可以先用上一节的 ros2 service call 命令验证服务名与网络：

import rclpy
from rclpy.node import Node
from aimdk_msgs.msg import CommonRequest
from aimdk_msgs.srv import PlayTts


class TtsClient(Node):
    def __init__(self):
        super().__init__("tts_client")
        self.client = self.create_client(PlayTts, "/aimdk_5Fmsgs/srv/PlayTts")

    def speak(self, text: str):
        if not self.client.wait_for_service(timeout_sec=5.0):
            self.get_logger().error("PlayTts service is not available")
            return False

        request = PlayTts.Request()
        common_request = CommonRequest()
        common_request.header.stamp = self.get_clock().now().to_msg()
        request.header = common_request
        request.tts_req.text = text
        request.tts_req.priority_level.value = 6
        request.tts_req.domain = "sdk_test"
        request.tts_req.is_interrupted = True

        future = self.client.call_async(request)
        rclpy.spin_until_future_complete(self, future, timeout_sec=10.0)
        if not future.done() or future.result() is None:
            self.get_logger().error("PlayTts request timed out or failed")
            return False

        response = future.result()
        success = response.tts_resp.is_success
        self.get_logger().info(f"TTS success={success}, response={response}")
        return success


def main():
    rclpy.init()
    node = TtsClient()
    try:
        node.speak("你好，我是启元机器人")
    finally:
        node.destroy_node()
        rclpy.shutdown()


if __name__ == "__main__":
    main()

说明：ROS 2 生成消息类的请求字段类型由接口生成结果决定。若 header 或嵌套字段赋值与本机生成类型不匹配，请执行 ros2 interface show aimdk_msgs/srv/PlayTts，并以接口输出和 SDK examples/python 中对应实现为准。CLI 示例是验证服务可达性的首选基准。

关节控制示例应该如何看

SDK 的 examples/python/joint_control.py 展示了较完整的控制链路：订阅 /aima/hal/joint/state，发布 /aima/hal/joint/command，用 Ruckig 做速度、加速度和 jerk 约束下的轨迹生成。运行参数包括 joint_names、target_positions，可选刚度/阻尼和默认运动限制。

先阅读示例，不建议新手直接复制参数对真实机器人下发。该示例明确要求：关闭机器人本体运控模块、将机器人平放或悬挂、完成安全防护；目标关节名和目标弧度必须对应实际机型。错误的目标角、增益或控制模式会导致不可预期的硬件动作。

C++ 集成入口

C++ 示例位于 examples/cpp，以 ROS 2 rclcpp 为节点框架，依赖 aimdk_msgs；部分示例还使用 OpenCV 或 Ruckig。新手建议先从同目录已有示例入手，而不是复制一个不完整的单文件程序：

1. 阅读 examples/cpp/CMakeLists.txt 中目标名与源文件的对应关系。
2. 查看示例的 package.xml，确认依赖声明。
3. 参考同类示例创建 rclcpp::Node、Publisher/Subscription/Client。
4. 在工作区根目录运行 colcon build，再 source install/setup.bash。

如果将节点放进独立 ROS 2 工作区，需要把 aimdk_msgs 安装结果纳入构建环境，并在包的 package.xml 与 CMake 中声明 ROS 2 和消息包依赖。具体写法按 examples/cpp 现有包结构保持一致。

FastDDS 与 UDP 缓冲区

SDK 默认 profile 使用 UDPv4，发送和接收 socket buffer 分别为 20971520 字节（20 MiB）。Linux 内核允许的 UDP 缓冲区上限应不小于对应 profile 值；SDK 指南示例采用 24 MiB，即 25165824：

sudo sysctl -w net.core.rmem_max=25165824
sudo sysctl -w net.core.wmem_max=25165824
sysctl net.core.rmem_max net.core.wmem_max

以上命令临时生效，重启后失效。确认需要持久化后，再按团队系统管理规范配置 /etc/sysctl.d/。SDK 加载环境时会自动选择其 FastDDS profile，但不会替你修改 Linux 内核参数。

遇到多网卡通信不稳时，先检查 DDS 实际使用的接口，再考虑在 aimdk_msgs/config/fastdds_profiles.xml 中配置 interfaceWhiteList。白名单填写运行 SDK 设备上、连接机器人网络的本机 IP，例如 PC 的 10.1.1.99，不是机器人的 IP。改完需要重新构建并重新 source。

常见问题与排查顺序

排查时按“环境 → 网络 → 发现 → 接口 → 数据 → 业务”逐层推进，不要同时修改多个变量，否则很难判断哪个变化起作用。

现象	优先检查	建议命令/处理
ros2: command not found	ROS 2 环境未安装或未 source	source /opt/ros/humble/setup.bash，再 which ros2
colcon: command not found	colcon 未安装或用户路径未加入 PATH	sudo apt install python3-colcon-common-extensions，再开新终端验证
Cannot determine type	自定义消息环境未加载或构建失败	source 正确的 install/setup.bash；执行 ros2 interface show aimdk_msgs/msg/Bms
ros2 node list 看不到机器人节点	网络、开发者模式、Domain 或 DDS 网卡	先 ping 两块板卡；核对开发者模式与 ROS_DOMAIN_ID；排除多网卡冲突
节点可见但 Topic 无消息	Topic 没发布、事件尚未发生、QoS 或 UDP 数据被挡	ros2 topic info --verbose；确认数据源；触发事件；检查防火墙与 UDP buffer
Service not available	服务端未运行、服务名错误或网络数据面异常	用 ros2 service list 核对名称，确认节点与接口环境，再检查防火墙/网络
colcon build 路径相关报错	路径含中文、空格或特殊字符	将 SDK 放到英文、无空格目录重新构建
编译缺少头文件/库	系统依赖未装、ROS 发行版不匹配	检查 Ubuntu 22.04、Humble 和 SDK 指南列出的三方依赖
高频数据丢帧或不稳定	UDP socket buffer 与内核上限不匹配、DDS 绑定错网卡	检查 FastDDS profile、sysctl 值和 ip addr，必要时绑定本机通信 IP

节点不可见

1. 确认机器人已开机，APP 已启用开发者模式且配置已生效。
2. 用 ping 验证 PC 到运控板、大脑板的网络连通性。
3. 对比 ROS_DOMAIN_ID，确认两侧相同；机器人默认通常为 0。
4. 多网卡场景先临时断开无关 Wi-Fi/热点，避免 DDS 选错接口。
5. 确认每个终端都加载了 ROS 2 与 SDK 环境，且使用同一 ROS 2 发行版。

节点能见但收不到消息

1. ros2 topic info <topic> --verbose 检查发布者、订阅者和 QoS。
2. 确认 Topic 是周期数据还是事件数据；触摸等事件 Topic 没触发时不会凭空产生消息。
3. 确认接口类型存在：ros2 interface show <type>。
4. 检查主机防火墙及 UDP 传输。若排查防火墙，不建议长期关闭防火墙；在受控网络中验证后，应改为配置必要的放行规则。
5. 对高频或大数据链路检查 FastDDS buffer 与 Linux 内核上限。

编译失败

• 确认执行 source /opt/ros/humble/setup.bash 后才运行 colcon build。
• 确认系统是 SDK 指南支持的 Ubuntu 22.04 + ROS 2 Humble。
• 将源码移动到全英文且无空格路径。
• 根据第一个实际编译错误补齐依赖；不要只看最后的 failed 汇总。
• C++ 示例相关的 OpenCV/Ruckig 依赖以 examples/cpp/package.xml 与 SDK 快速入门指南为准。

低层控制安全须知

机器人关节与运动接口会直接影响真实硬件。SDK 随附声明及示例要求在低层控制前关闭机器人本体运控模块，并将机器人平放或悬挂。建议同时做到：

• 先在不连接执行器的环境理解消息字段与控制周期。
• 由熟悉该机型的人确认关节名、单位、限位、增益和控制权归属。
• 保持急停和断电手段可用，清空机器人周边人员与障碍物。
• 第一次验证只使用经过审核的小范围目标，不照搬示例中的动作目标。
• 不绕过安全保护；遇到异常抖动、异响或动作不可控时立即停止程序并按现场安全流程处理。

如果无法确认运控模块状态或安全边界，不要运行 joint_control.py 或发布关节指令，先联系设备负责方确认。

建议的新手实践顺序

1. 在 Ubuntu 22.04 + ROS 2 Humble 中确认 ros2 与 colcon 可用。
2. 将源码放到英文路径，构建 SDK 并 source 工作区。
3. 用 ros2 interface show 确认消息类型已安装。
4. 先做只读 BMS Topic 订阅，熟悉 Node、QoS 和回调。
5. 再用 CLI 验证 TTS Service，理解请求/响应和服务可用性等待。
6. 最后才评估 C++ 集成、板载部署或低层控制，并按机器人安全流程审批。

走完前五步，你已经具备开发普通 ROS 2 业务节点所需的基本链路认知：知道程序在哪运行、接口从哪里来、环境如何加载，以及通信故障该从哪一层查。后续每接入一种能力，都先对照 接口说明.md、消息定义和同类示例确认契约，再开始写业务逻辑。

参考资料

• SDK 源码包内 README.md
• PrimeBot_SDK快速入门与集成指南.md
• 接口说明.md
• 友好用户使用声明.md
• ROS 2 Humble 安装文档：https://docs.ros.org/en/humble/Installation.html
• ROS 2 通信排查文档：https://docs.ros.org/en/humble/How-To-Guides/Installation-Troubleshooting.html
• FastDDS 文档：https://fast-dds.docs.eprosima.com/en/latest/
• 启元机器人开发者社区:https://dev.primebot.com/