SDK说明_四川天链机器人股份有限公司

一、概述

fd_api ROS 2 SDK 是天链机器人外设的 ROS 2 通信中间件接口层，定义了 fd_api 与机器人硬件节点之间的 Topic 通信协议。 C++ 和 Python SDK 底层均通过此处定义的 Topic 发布控制指令、订阅状态数据。

SDK 使用 ROS 2 标准的发布/订阅（Publisher / Subscriber）模式，通过预定义的 Topic 名称和消息类型，实现上位机与机器人外设节点的解耦通信。

核心特性

标准 ROS 2 通信
基于 Topic 的发布/订阅模型

统一 Topic 映射
C++ / Python 共用同一套 Topic 定义

消息类型明确
使用 std_msgs / sensor_msgs / 自定义消息

可配置 Topic 名
诊断、闲置状态 Topic 可自定义

单位自动转换
m→mm、rad→deg、编码器→角度均在 SDK 层完成

多后端兼容
RoHand / Inspire 使用不同的 Topic 通道

通信架构

上位机应用
fd_api C++ / Python SDK

▼ 发布 Control Topic ▲ 订阅 State Topic

ROS 2 通信层
预定义 Topic · 标准消息类型

▼ 转发指令 ▲ 上报数据

机器人外设节点
升降 · 头部 · 腰部 · 手部

二、支持的操作系统与软件版本

操作系统

平台	支持版本	架构
Ubuntu	20.04 LTS / 22.04 LTS	amd64 (x86_64)
兼容 ROS 2 的 Linux 发行版	—	amd64 (x86_64)

ARM 架构（如 Jetson 系列）如需使用，请联系技术支持获取交叉编译方案。

软件依赖

组件	版本要求	说明
ROS 2	Humble / Galactic / Foxy	通信中间件
Python	≥ 3.8	Python SDK 运行时
C++ 标准	C++17	C++ SDK 编译要求
编译器	GCC ≥ 9.4	支持 C++17
colcon	≥ 1.2	ROS 2 构建工具

ROS 2 依赖包

# ROS 2 Humble (Ubuntu 22.04)
sudo apt install ros-humble-std-msgs ros-humble-diagnostic-msgs

# ROS 2 Galactic (Ubuntu 20.04)
sudo apt install ros-galactic-std-msgs ros-galactic-diagnostic-msgs

# ROS 2 Foxy (Ubuntu 20.04)
sudo apt install ros-foxy-std-msgs ros-foxy-diagnostic-msgs

Topic 名称约定：所有 Topic 均位于 /fd_robot/ 命名空间下，便于权限管理和多机器人区分。诊断和闲置状态 Topic 可在 SDK 初始化时通过 diagnostics_topic 和 robot_idle_topic 参数自定义。

三、SDK 结构

3.1 通信节点结构

ROS 2 节点
├── fd_api_control              # Control 节点 — 发布控制指令
│   ├── Publisher: /fd_robot/lifting_motor/velocity_cmd
│   ├── Publisher: /fd_robot/lifting_motor/position_set_speed_cmd
│   ├── Publisher: /fd_robot/lifting_motor/position_cmd
│   ├── Publisher: /fd_robot/lifting_motor/status
│   ├── Publisher: /fd_robot/head_down_move
│   ├── Publisher: /fd_robot/head_up_move
│   ├── Publisher: /fd_robot/waist_motor/velocity_cmd
│   ├── Publisher: /fd_robot/waist_motor/position_cmd
│   ├── Publisher: /fd_robot/fd_hand_controller/joint_command
│   └── Publisher: /fd_robot/manipulator/{left,right}_Setmovetgt
│
└── fd_api_state                # State 节点 — 订阅状态数据
    ├── Subscriber: /fd_robot/lifting_motor/current_pose
    ├── Subscriber: /fd_robot/head/current_pose
    ├── Subscriber: /fd_robot/waist_motor/motor_info
    ├── Subscriber: /fd_robot/fd_hand_controller/joint_states
    ├── Subscriber: /fd_robot/manipulator/{left,right}_Getcopen
    ├── Subscriber: /diagnostics (可配置)
    └── Subscriber: /fd_robot/robot_idle_status (可配置)

3.2 通信拓扑

Control 节点 (fd_api_control)
发布 10 个 Topic → 外设节点

State 节点 (fd_api_state)
订阅 7 个 Topic ← 外设节点

四、ROS 接口映射 — 控制发布

以下为各 SDK API 对应的 ROS 2 Topic 及消息类型：

4.1 升降控制 (Lift)

SDK API	ROS Topic	消息类型
lift_up / lift_down	/fd_robot/lifting_motor/velocity_cmd	std_msgs/Float32
lift_set_pos / lift_pos	/fd_robot/lifting_motor/position_set_speed_cmd	std_msgs/Float32
	/fd_robot/lifting_motor/position_cmd	std_msgs/Float32
lift_stop	/fd_robot/lifting_motor/status	std_msgs/String 值: `"motor_stop"`

4.2 头部控制 (Head)

SDK API	ROS Topic	消息类型
head_set_pos / head_pos	/fd_robot/head_down_move (kLower)	std_msgs/Float32
	/fd_robot/head_up_move (kUpper)	std_msgs/Float32
head_stop	同上，发送 `0.0`	std_msgs/Float32

4.3 腰部控制 (Waist)

SDK API	ROS Topic	消息类型
waist_front / waist_back / waist_stop	/fd_robot/waist_motor/velocity_cmd	VelControlMsg
waist_set_pos / waist_pos	/fd_robot/waist_motor/position_cmd	PosControlMsg

4.4 手部控制 (Hand)

SDK API	ROS Topic	消息类型
hand_move (RoHand)	/fd_robot/fd_hand_controller/joint_command	sensor_msgs/JointState
hand_move (Inspire)	/fd_robot/manipulator/{left,right}_Setmovetgt	std_msgs/Int32
hand_stop (Inspire)	/fd_robot/manipulator/{left,right}_Setestop	Setestop

五、ROS 接口映射 — 状态订阅

各 SDK 状态获取 API 对应的 ROS 2 订阅源：

SDK API	ROS Topic	消息类型 / 转换
lift_*_pos	/fd_robot/lifting_motor/current_pose	std_msgs/Float32 m → mm 转换
head_*_pos	/fd_robot/head/current_pose	sensor_msgs/JointState rad → deg 转换
waist_*_pos	/fd_robot/waist_motor/motor_info	MotorInfoMsg 编码器 → deg 转换
hand_*_pos (RoHand)	/fd_robot/fd_hand_controller/joint_states	sensor_msgs/JointState
hand_*_pos (Inspire)	/fd_robot/manipulator/{left,right}_Getcopen	Getcopen 1Hz 轮询
health_*	/diagnostics (可配置)	diagnostic_msgs/DiagnosticArray
runtime_*_idle_state	/fd_robot/robot_idle_status (可配置)	std_msgs/String 值 `"Idle"` 为 true

单位转换：SDK 内部自动完成单位换算—— 升降位置 m→mm、头部角度 rad→deg、腰部编码器→角度，上层应用直接使用物理单位（mm / deg），无需额外转换。

六、消息类型说明

6.1 标准消息

消息类型	包名	用途
std_msgs/Float32	std_msgs	升降速度/位置、头部角度控制
std_msgs/Int32	std_msgs	Inspire 手部目标值
std_msgs/String	std_msgs	升降停止指令、机器人闲置状态
sensor_msgs/JointState	sensor_msgs	头部/手部关节状态
diagnostic_msgs/DiagnosticArray	diagnostic_msgs	外设诊断/健康信息

6.2 自定义消息

消息类型	所在包	用途
VelControlMsg	腰部电机驱动包	腰部速度控制指令
PosControlMsg	腰部电机驱动包	腰部位置控制指令
MotorInfoMsg	腰部电机驱动包	腰部电机状态上报（含编码器值）
Getcopen	Inspire 手部驱动包	Inspire 手部开度反馈
Setestop	Inspire 手部驱动包	Inspire 手部急停指令

自定义消息依赖：自定义消息类型由对应的硬件驱动包提供。使用 colcon build 编译时，确保驱动包已包含在工作空间中。

七、注意事项

Topic 命名空间冲突：所有 Topic 默认位于 /fd_robot/ 命名空间下。同一 ROS 2 网络中仅应运行一套机器人外设节点，避免 Topic 冲突。

实机安全：在实机上运行前，请确认所有外设节点已正常启动，可通过 ros2 topic list 确认相关 Topic 已发布。

Inspire 手部轮询：Inspire 手部位置通过 Getcopen Topic 以 1Hz 频率轮询获取，实时性低于 RoHand 的 JointState 订阅方式。

手部 Topic 差异：RoHand 使用 /fd_robot/fd_hand_controller/ 下的 Topic， Inspire 使用 /fd_robot/manipulator/ 下的 Topic，两者互不干扰。

单位转换：SDK 内部自动完成单位换算：升降位置 m → mm、头部角度 rad → deg、腰部编码器值 → 角度。直接订阅原始 Topic 获取的数据需要自行处理单位转换。

Topic 可配置：诊断 Topic 和机器人闲置状态 Topic 的名称可通过 State::Options::diagnostics_topic 和 State::Options::robot_idle_topic 参数自定义，以适应不同的机器人系统集成需求。

SDK说明

fd_api ROS 2 SDK 说明