上纬启元 Q1 机器人开发说明（接口说明 + SDK 快速入门与集成指南 + Q1 SDK v0.1.2.7）

上纬启元机器人开发说明（Q1）

启元 Q1 人形机器人的开发说明与 SDK 集成资料。本仓库提供 SDK 快速入门、系统集成指南与完整接口文档，帮助开发者完成环境配置、连接验证，并基于 ROS2 Humble + FastDDS 进行 Python / C++ 二次开发。

适用本体：Q1（v2d0）· SDK 版本：v0.1.2.7-R · 开发系统：Ubuntu 22.04 + ROS2 Humble

📦 本仓库内容

文件	说明
PrimeBot_SDK快速入门与集成指南.md	环境配置、连接验证、Python/C++ 集成、开发者模式、常见问题
接口说明.md	完整 API 接口文档（运动 / 交互 / 硬件抽象三大模块）
`sdk_q1-v2d0-v0.1.2.7-R.zip`	Q1（v2d0）SDK 包 v0.1.2.7-R，解压后按《快速入门》编译使用

🧭 系统架构

+----------------------+        +----------------------+        +----------------------+
|   开发 PC / 外部设备   |        |        运控板         |        |        大脑板         |
|   (Ubuntu 22.04)     |        |    IP: 10.1.1.100    |        |    IP: 10.1.1.101    |
|   SDK 用户程序        | ◀════▶ | HAL / MC / 交互服务   | ◀════▶ | 核心算法 / 供应商程序 |
|   ROS2 节点          | FastDDS|   ROS2 节点          | FastDDS|   ROS2 节点          |
+----------------------+        +----------------------+        +----------------------+
          ╚═══════════════════ 局域网 FastDDS（ROS2 通信总线）═══════════════════╝

开发 PC / 外部设备：开发者主要开发与运行环境（Ubuntu 22.04 + ROS2 Humble），经局域网接入机器人。
运控板（10.1.1.100）：运动控制大脑，负责硬件抽象（HAL）、运控算法（MC）与语音/表情等基础交互服务。
大脑板（10.1.1.101）：高阶感知与导航大脑，运行核心 AI 算法、感知规划与供应商程序。
通信：所有节点经局域网物理连接，基于 FastDDS 作为 ROS2 通信总线，实现跨设备高性能数据交换。

⚙️ 环境要求

项	要求
操作系统	Ubuntu 22.04.x LTS（暂不支持 Mac / Windows 开发）
中间件	ROS2 Humble
通信	基于 FastDDS 的 ROS2 通信
网络	开发 PC 与机器人有线直连（推荐），同一子网

运控板 / 大脑板本身也支持直接进行二次开发，流程一致。

🚀 快速开始

1. 配置网络（有线直连，推荐）　将开发 PC 有线网卡设为静态 IP：

Address: 10.1.1.99    Netmask: 255.255.255.0    Gateway: 留空

2. 验证连通

ping 10.1.1.101   # 大脑板
ping 10.1.1.100   # 运控板

无线 AP（SSID Q1-<sn后10位>）仅供临时调试，高频控制数据易延迟丢包，正式开发请用有线；勿同时用有线+无线下发控制指令。

3. 编译与运行　解压 SDK 包后，按《快速入门与集成指南》第 2 章完成编译、命令行交互验证与示例运行。

🧩 开发集成（Python & C++）

指南提供两种集成方式，详见文档第 3 章：

语言	方式 A	方式 B
Python	在 SDK 内部开发	作为第三方依赖集成
C++	在 SDK 内部新增节点	作为独立第三方库集成

📡 API 接口概览

完整请求/响应结构、话题载荷与 CLI 调试见接口说明.md。接口分三大模块：

模块	能力	主要接口
运动控制	运控高层	运动模式查询/设置、全身动作、预设动作、走跑速度控制、输入源控制、自定义上肢关节控制
	运控低层	关节控制命令 / 关节状态反馈
交互控制	语音控制	TTS 语音合成、音量、静音、音频文件播放、音频码流录制/播放
	屏幕控制	播放表情与视频
硬件抽象	传感与外设	头部触摸状态、相机单帧 JPEG / RTSP 视频流、电源管理（BMS）、整机灯语控制