一、概述

fd_api 是天链机器人外设的 Python 软件开发工具包（SDK）， 提供统一、便捷的接口用于控制机器人升降、头部、腰部、手部四大外设模块， 并支持实时状态读取与异步订阅。

SDK 底层基于 ROS 2 通信机制实现，封装了底层 Topic 发布/订阅细节， 上层应用无需关心 ROS 节点通信逻辑，通过简洁的 Python API 即可快速集成机器人控制功能。

核心特性

适用场景

• 机器人上位机应用程序开发
• 机器人遥操作与远程监控系统
• 机器人自动化流程集成
• 机器人状态数据采集与可视化

接口说明

详细的 Control / State 接口定义与使用方法请参见 《fd_api Python 接口文档》。

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

操作系统

软件依赖

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

Python 依赖

三、SDK 结构

3.1 包目录结构

fd_api/                          # ROS 2 功能包根目录
├── package.xml                  # ROS 2 包元信息
├── CMakeLists.txt               # 构建配置（C++ + Python 混合编译）
├── setup.py                     # Python 模块安装配置
│
├── include/                     # C++ 头文件（Python SDK 不直接使用）
│   └── fd_api/
│       ├── control.h            # C++ Control 类声明
│       ├── state.h              # C++ State 类声明
│       ├── types.h              # C++ 枚举类型定义
│       └── robot_state_types.h  # C++ 健康状态数据结构
│
├── fd_api/                      # Python 模块目录 ★
│   ├── __init__.py              # 模块入口，导出全部公开 API
│   ├── control.py               # Control 类 — 外设控制接口
│   ├── state.py                 # State 类 — 外设状态读取/订阅
│   ├── types.py                 # 枚举类型定义
│   ├── waist_angle.py           # 腰部编码器 ↔ 角度转换工具
│   └── robot_state_types.py     # 健康状态数据类
│
├── resource/                    # ROS 2 资源文件
├── test/                        # 测试代码
│   ├── api_test_node.cpp        # C++ 交互测试
│   └── api_test_node_for_python_api.py  # Python 交互测试
│
└── launch/                      # 启动文件（可选）

3.2 模块分层

3.3 模块文件说明

3.4 Control 类 — 控制接口

3.5 State 类 — 状态接口

3.6 辅助工具

四、快速开始

4.1 环境准备

确保已安装 ROS 2 并完成环境配置：

source /opt/ros/humble/setup.bash

4.2 编译安装

# 在工作空间下编译
colcon build --packages-select fd_api

# 加载环境
source install/setup.bash

4.3 导入使用

from fd_api import Control, State, HeadType, HandType

# ── 控制示例 ──
ctrl = Control()
ctrl.init({"node_name": "my_control"})
ctrl.lift_up(0.5)                    # 以速度 0.5 上升
ctrl.head_pos(HeadType.kLower, 30.0) # 下头转到 30°

# ── 状态示例 ──
state = State()
state.init({"node_name": "my_state"})
pos = state.lift_get_current_pos()   # 读取升降位置
print(f"当前升降位置: {pos} mm")

五、注意事项