一、概述

fd_api C++ SDK 是天链机器人外设的 C++ 共享库，提供高效、低延迟的接口用于控制机器人底盘、升降、头部、腰部、手部、机械臂六大外设模块，并支持实时状态读取与异步订阅。适用于对性能要求较高的 C++ 上位机应用。

SDK 底层基于 ROS 2（rclcpp）通信机制实现，采用 PIMPL（Pointer to Implementation） 惯用法设计，对外头文件不包含任何 ROS 头文件，使用者无需依赖 ROS 2 构建环境即可编译引用。

提供与 Python SDK 一致的接口语义，便于多语言团队协作维护。

核心特性

适用场景

• 高性能机器人上位机应用程序开发
• 实时机器人遥操作与远程监控系统
• 工业自动化流程集成
• 嵌入式 / 边缘计算节点部署

接口说明

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

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

操作系统

软件依赖

ROS 2 依赖包

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

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

三、SDK 结构

3.1 包目录结构

fd_api/                          # ROS 2 功能包根目录
├── package.xml                  # ROS 2 包元信息
├── CMakeLists.txt               # 构建配置（C++ + Python 混合编译）
├── setup.py                     # Python 模块安装配置
│
├── include/                     # C++ 对外头文件 ★
│   └── fd_api/
│       ├── control.h            # Control 类声明
│       ├── state.h              # State 类声明（含回调类型）
│       ├── types.h              # 枚举类型定义
│       └── robot_state_types.h  # 健康状态数据结构
│
├── src/                         # C++ 实现源文件
│   ├── control.cpp              # Control 实现（PIMPL）
│   ├── state.cpp                # State 实现（PIMPL）
│   └── ...                      # 内部实现文件
│
├── fd_api/                      # Python 模块目录
│   └── ...
│
├── test/
│   ├── api_test_node.cpp        # C++ 交互测试节点
│   └── api_test_node_for_python_api.py
│
└── launch/

3.2 模块分层

3.3 头文件说明

四、类型体系

C++ SDK 共定义 13 个类型，按用途分为三类：

4.1 基础枚举

4.2 外设标识与健康

4.3 C++ 独有类型

五、快速开始

5.1 环境准备

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

source /opt/ros/humble/setup.bash

5.2 编译安装

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

# 加载环境
source install/setup.bash

5.3 最小接入示例

#include "fd_api/control.h"
#include "fd_api/state.h"

fd_robot::Control control;
fd_robot::State   state;

// C++ 版 Init 可能返回 false，需检查
if (!control.Init()) { return -1; }
if (!state.Init())   { return -1; }

// 控制：升降到位 400mm
control.lift_set_pos(400.0f);

// 状态：同步读当前升降位置（出参 + bool 表示是否有效）
float pos = 0.0f;
if (state.lift_get_current_pos(pos)) {
    // 使用 pos
}

5.4 运行交互测试

ros2 run fd_api api_test_node

启动后进入菜单，可按按键交互测试各外设的控制与状态功能。详细接口使用请参见 《fd_api C++ 接口文档》。

六、接口速览

以下是 Control / State 两大模块的接口分组总览。C++ 版接口命名全部为 snake_case（如 lift_set_pos）。

6.1 Control 接口（7 组）

6.2 State 接口（8 组）

七、注意事项