企业官网建设流程全解析

适用对象：第一次接触 Q1 / PrimeBot 机器人 SDK、ROS 2 和 DDS 的开发者。本文以 SDKv1.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 调试时需要与机器人处于可互通的网络环境。

源码中包含：

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

• 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-decho"$ROS_DISTRO"whichros2

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

source/opt/ros/humble/setup.bash

安装 colcon 扩展：

sudoaptupdatesudoaptinstall-ypython3-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 附带的《友好用户使用声明》和产品说明。

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

配置同网段网络

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

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

ping-c310.1.1.100ping-c310.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.bashcd~/work/sdk_q1-v1.0.0.0

首次构建执行：

colcon build --cmake-args-DCMAKE_BUILD_TYPE=Release

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

编译完成后加载工作区：

sourceinstall/setup.bash

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

source/opt/ros/humble/setup.bashsource~/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

ros2nodelist ros2 topic list

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

timeout5ros2 topicecho/aima/hal/bms/state--once

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

查看类型和发布频率：

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

验证触摸 Topic

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

终端 A：

source/opt/ros/humble/setup.bashsource~/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}'-r1

终端 B：

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

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

调用 TTS Service

先确认服务存在：

ros2servicelist|grep-iPlayTts

然后按 SDK 指南调用：

ros2servicecall /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 python3importrclpyfromrclpy.nodeimportNodefromrclpy.qosimportqos_profile_sensor_datafromaimdk_msgs.msgimportBmsclassBmsMonitor(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")defon_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")defmain():rclpy.init()node=BmsMonitor()try:rclpy.spin(node)exceptKeyboardInterrupt:passfinally:node.destroy_node()rclpy.shutdown()if__name__=="__main__":main()

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

source/opt/ros/humble/setup.bashsource~/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命令验证服务名与网络：

importrclpyfromrclpy.nodeimportNodefromaimdk_msgs.msgimportCommonRequestfromaimdk_msgs.srvimportPlayTtsclassTtsClient(Node):def__init__(self):super().__init__("tts_client")self.client=self.create_client(PlayTts,"/aimdk_5Fmsgs/srv/PlayTts")defspeak(self,text:str):ifnotself.client.wait_for_service(timeout_sec=5.0):self.get_logger().error("PlayTts service is not available")returnFalserequest=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=6request.tts_req.domain="sdk_test"request.tts_req.is_interrupted=Truefuture=self.client.call_async(request)rclpy.spin_until_future_complete(self,future,timeout_sec=10.0)ifnotfuture.done()orfuture.result()isNone:self.get_logger().error("PlayTts request timed out or failed")returnFalseresponse=future.result()success=response.tts_resp.is_success self.get_logger().info(f"TTS success={success}, response={response}")returnsuccessdefmain():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，并以接口输出和 SDKexamples/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 2rclcpp为节点框架，依赖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：

sudosysctl-wnet.core.rmem_max=25165824sudosysctl-wnet.core.wmem_max=25165824sysctlnet.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。

常见问题与排查顺序

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

节点不可见

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/