一概述
本手册收录天链机器人复合机器人的 HTTP 接口,供外部客户二次开发集成。共 两套独立 HTTP 服务:
| 服务 |
端口 |
接口数 |
主要职责 |
web_interface |
5000 |
35 |
整机控制网关:升降、腰/头颈关节、Demo 抓取、商品点位管理、机器人状态查询、简易机械臂透传 |
fd_arm_http |
8000 |
15 |
机械臂完整控制:上下电、轨迹运动、笛卡尔运动、预设位姿管理、夹爪/灵巧手末端控制 |
两套服务端口不同、路径命名与响应字段约定也不同,请勿混用。机械臂关节数量由机型 profile 决定,文档示例数组仅为示意,实际以硬件返回为准。各服务均内置 /docs(Swagger)与 /redoc 在线调试页面。
⚠
安全提示:全部接口无鉴权,仅限内网可信环境调用,禁止公网暴露。
二服务总览
两套独立 HTTP 服务,端口、BaseURL 与职责如下:
ℹ
章节编号说明:正文使用「一~六」标识主要章节;接口分组编号使用「4.x」表示 web_interface 服务、「5.x」表示 fd_arm_http 服务,与原文档分组编号保持一致。
| 服务名称 |
端口 |
主要职责 |
BaseURL |
web_interface |
5000 |
整机控制网关:升降、腰/头颈关节、Demo 抓取、商品点位管理、机器人状态查询,以及少量机械臂透传接口。 |
http://:5000 |
fd_arm_http |
8000 |
机械臂完整控制:上下电、轨迹运动、笛卡尔运动、预设位姿管理、夹爪/灵巧手末端控制。 |
http://:8000 |
机械臂能力分层(重要)
ℹ
web_interface(:5000) 部分臂控接口会透传转发请求到 fd_arm_http(:8000);转发失败返回 {"status":-1,"message":"xxx"}。
/selectArmFuncState 的 PowerOnArm / PowerOffArm 走本机 ArmClient 上下电;openRemo / closeRemo 启停遥操作。二者均不调用 :8000 的 initialize_robotarm / stop_robotarm。
完整臂控(轨迹、move_to_target、预设位姿 CRUD、夹爪/灵巧手)请直连 :8000;web 层未代理这些路径。
| 维度 |
web_interface (:5000) |
fd_arm_http (:8000) |
| 路径风格 |
多为 camelCase |
多为 snake_case |
| 响应字段 |
常用 status(语义不统一,见下节) |
常用 success(部分兼有 status) |
| 交互调试 |
各服务均内置 /docs(Swagger)与 /redoc 在线调试页面 |
| 安全 |
全接口无鉴权,仅限可信内网,禁止公网暴露 |
三通用调用约定
| 约定 |
说明 |
| Content-Type |
多数 POST 使用 application/json;web 侧部分点位接口对 Body 做手动 JSON 解析 |
| HTTP 状态码 |
多数业务错误仍返回 HTTP 200,错误信息在响应 Body 的 message 字段中;参数校验失败或内部异常时,部分接口可能返回 400 / 500 |
| Demo 抓取为异步 |
POST /catchProductRequest 立即返回,无 HTTP 完成回调。进度用 GET /robotStatus;中断用 POST /breakDisplay |
| 工作流类型 |
traditional / big_model 可通过 setWorkflowType 切换;grasp_put_demo_enable=true 时旁路前两者 |
错误码速查表(全局)
| 返回位置 |
成功值 |
失败值 |
含义 / 适用接口 |
建议动作 |
| web status(数值) |
1 |
-1 |
升降、机械臂遥操作、工作流、删除商品 |
失败时优先读取 message 字段判断原因 |
| web status(数值) |
0 |
负数 |
点位、商品列表查询 |
负数绝对值对应业务错误码,以 message 为准 |
| web status(字符串) |
"1" |
"0" |
recordProductsInfo 商品录入 |
类型为字符串,勿用数值比较 |
| fd_arm success |
true |
false |
:8000 全部接口;部分运动接口兼有 status |
false 时读取 message 定位失败原因 |
| HTTP 状态码 |
200 |
400 / 500 |
参数校验失败或内部异常 |
400 检查请求参数格式;500 联系技术支持 |
| 透传转发 |
— |
status:-1 |
web 层透传 :8000 失败 |
确认 :8000 服务可达后重试 |
fd_arm_http(:8000)返回约定
主要使用布尔字段 success(true / false)+ message;部分运动接口会同时返回 status 字段。
!操作安全 · 高危接口清单
下列接口会改变机器人运动状态、清除数据或触发急停,请在调用前确认现场安全。建议首次对接时先在低速、空载、无障碍物环境下验证。
ℹ
调用频率建议:状态轮询(如 GET /robotStatus)建议 ≥ 200 ms;运动指令建议等待当前指令完成后再下发下一次,避免指令堆积。
四web_interface(:5000)接口
BaseURL:http://:5000 — 整机控制网关:升降、腰/头颈关节、Demo 抓取、商品点位管理、机器人状态查询,以及少量机械臂透传接口。 臂控分组中透传接口依赖 :8000 服务可达;机械臂完整控制见第五章。
4.1 查询模块1 个接口
GET/4.1.1
服务状态与文档入口
返回 web_interface 服务状态。交互式调试文档见 /docs(Swagger)与 /redoc。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
service |
string |
"web_interface" |
由成功响应示例推断 |
status |
string |
"ok" |
由成功响应示例推断 |
docs |
string |
"/docs" |
由成功响应示例推断 |
4.2 升降控制5 个接口
POST/setLiftAction高危4.2.1
升降控制
直线升降模组运动。distance 等于字符串 "None" 时为速度模式,否则为位置模式(目标高度,单位米)。
⚠
null 与字符串 "None" 行为不同:速度模式请务必传字符串 "None",而非 JSON null。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"指令已接收" |
由成功响应示例推断 |
current_pose |
string |
"0.300" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
direction |
string | int |
可选 |
"0" |
速度模式方向:0 正向,1 反向 |
speed |
string |
可选 |
"0.0" |
速度(m/s) |
distance |
string |
可选 |
"0.0" |
目标位置(米);传字符串 "None" = 速度模式 |
POST/liftStopAction高危4.2.2
停止升降运动
停止当前升降运动。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"已停止" |
由成功响应示例推断 |
POST/liftHoming4.2.3
升降原点设置
将升降当前位置设置为原点(零位)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"原点已设置" |
由成功响应示例推断 |
POST/liftClearError高危4.2.4
升降错误清除
清除升降电机的一般错误。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"错误已清除" |
由成功响应示例推断 |
GET/liftInfo4.2.5
获取升降状态信息
查询升降当前位置,单位米,保留 3 位小数。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
object |
{"position":"0.300"} |
由成功响应示例推断 |
4.3 腰部、头颈关节接口3 个接口
POST/moveJoint高危4.3.1
腰部、颈部关节控制
控制腰部或头颈关节运动到目标角度(度),可设置速度。
ℹ
角度范围:waist 0~30;head1 / head2 -30~30。速度默认 5 °/s;腰部钳位上限 6,头颈上限 20。
⚠
速度超限不会失败:status 仍为 1,message 提示 speed clamped(自动截断到上限)。
⚠
非法 joint_name 时 status 仍为 1,仅 message 为 "Invalid Joint Name"——判断失败请以 message 为准。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"success" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
joint_name |
string |
可选 |
"waist" |
waist(腰)/ head1(俯仰)/ head2(偏航) |
angle |
float |
可选 |
0.0 |
目标角度(度) |
speed |
float |
可选 |
5.0 |
速度 °/s(腰部钳位 1~6,头颈钳位 1~20) |
GET/getWaistJoint4.3.2
腰部关节角度查询
查询腰部当前关节角度(度)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
object |
{"waist":12.5} |
由成功响应示例推断 |
GET/getHeadJoint4.3.3
颈部关节角度查询
查询颈部上下关节当前角度(度)。head1 = 上头(俯仰),head2 = 下头(偏航)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
object |
{"head1":5,"head2":-3} |
由成功响应示例推断 |
4.4 臂控与遥操作(透传 :8000)6 个接口
本组接口依赖 fd_arm_http(:8000)服务可达;转发失败时返回 {"status":-1,"message":"xxx"}。
GET/getJointAngle4.4.1
获取双臂关节角度
获取双臂关节角度。成功时透传 fd_arm_http :8000/get_joint_angle 的响应;转发失败返回 status = -1。
ℹ
关节数 N 由机型 robot_profile 决定(示例常为 7 元数组),实际以硬件返回为准。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
bool |
— |
透传下游结果 |
message |
string |
— |
string |
armleft_joint_angle / armright_joint_angle |
— |
— |
N 个关节角,弧度 |
armleft_joint_angle_deg / armright_joint_angle_deg |
— |
— |
N 个关节角,度 |
GET/getEndPose4.4.2
获取双臂末端姿态
获取双臂末端法兰/工具位姿。成功时透传 :8000/get_end_pose 的响应。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
bool |
— |
bool |
message |
string |
— |
string |
armleft_end_pose / armright_end_pose |
— |
— |
position [x,y,z](米);orientation [x,y,z,w] 四元数 |
POST/jointControl4.4.3
单关节步进控制
单关节点动步进。转发至 :8000/joint_control,成功时透传下游响应。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"joint control success" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
joint_name |
string |
必填 |
— |
joint1 ~ jointN |
direction |
int |
必填 |
— |
0 正向,1 反向 |
speed |
int |
可选 |
30 |
速度百分比 1–100 |
joint_move_angle |
string |
可选 |
"None" |
步进角度(度);"None" = 速度模式 |
smooth_through_waypoints |
bool |
可选 |
配置值 |
不填时使用机器配置 |
POST/moveArmDirection4.4.4
末端沿轴直线移动
末端沿指定坐标系某轴平移。转发至 :8000/move_arm_direction。
ℹ
阻塞模式(block=1)时网关超时为 请求 timeout + 5 秒。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
axis |
string |
必填 |
— |
x / y / z 轴 |
distance |
float |
必填 |
— |
平移距离(米),正负代表方向 |
frame |
string |
可选 |
"base" |
base / tool 坐标系 |
block |
int |
可选 |
0 |
0 非阻塞;1 阻塞 |
timeout |
float |
可选 |
30.0 |
运动超时(秒) |
is_move |
bool |
可选 |
true |
false 时仅规划不执行运动 |
smooth_through_waypoints |
bool |
可选 |
配置值 |
省略时读取机器配置 |
speed |
int |
可选 |
20 |
速度百分比 1–100 |
123
curl -s -X POST "http://<ROBOT_IP>:5000/moveArmDirection" \ -H "Content-Type: application/json" \ -d '{"robot_name":"armleft","axis":"z","distance":0.05,"frame":"base","block":0,"speed":20}'
12345678
{ "robot_name": "armleft", "axis": "z", "distance": 0.05, "frame": "base", "block": 0, "speed": 20}
12345
{ "success": true, "status": 1, "message": "ok"}
POST/selectArmFuncState高危4.4.5
设置机械臂功能(上下电 / 遥操作)
双臂上下电,或启停遥操作。上下电走本机 ArmClient;遥操作走本机遥操作控制服务。
⚠
旧动作名 openArm / closeArm 不支持,请使用 PowerOnArm / PowerOffArm。
ℹ
PowerOnArm / PowerOffArm 不调用 :8000 的 initialize_robotarm / stop_robotarm,二者相互独立。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
function |
string |
必填 |
— |
PowerOnArm / PowerOffArm / openRemo / closeRemo |
GET/getTeleoperationStatus4.4.6
遥操作模式状态查询
查询遥操作进程是否在运行(检测 teleop_fd_robot_ros_dual / teleop_fd_robot_ros_single 进程)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
object |
{"running":false} |
由成功响应示例推断 |
4.5 Demo 抓取工作流接口7 个接口
Demo 抓取为异步:POST /catchProductRequest 立即返回、无 HTTP 完成回调;进度用 GET /robotStatus 查询,中断用 POST /breakDisplay。
POST/setWorkflowType4.5.1
切换工作流类型
切换工作流类型并持久化(仅切换配置,不触发流程执行)。取值 traditional 或 big_model。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"工作流已切换为 big_model" |
由成功响应示例推断 |
workflowType |
string |
"big_model" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
workflowType |
string |
可选 |
"traditional" |
traditional / big_model |
POST/catchProductRequest4.5.2
商品抓取请求
触发商品抓取工作流。HTTP 立即返回(异步),无完成回调。
ℹ
进度查询:GET /robotStatus;中断执行:POST /breakDisplay。
ℹ
工作流分流:traditional / big_model 由 setWorkflowType 决定;grasp_put_demo_enable = true 时旁路前两者。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"request success" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
productId |
string | int |
可选 |
"0" |
任务 uuid |
POST/breakDisplay高危4.5.3
打断演示工作流
打断当前演示工作流(清空队列、停止底盘、返回待机点与升降高度)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"break requested" |
由成功响应示例推断 |
GET/GetIsBigData高危4.5.4
获取大数据推理开关
查询内存中的 is_big_data 开关状态(不涉及持久化)。
⚠
原文档疑误:原手册本节示例(含请求 Body 与 POST curl)与 SetIsBigData 完全重复,疑为文档编辑错误。按接口语义,GET 版本应无请求 Body,以下示例已按语义修正。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
isBigData |
boolean |
true |
由成功响应示例推断 |
POST/SetIsBigData4.5.5
设置大数据推理开关
设置内存中的 big_model 分流开关,不持久化(重启后失效)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
isBigData |
boolean |
true |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
isBigData |
bool |
可选 |
false |
true → big_model 分流 |
GET/GetGraspPutDemoEnable4.5.6
获取 grasp_put_demo 使能
查询 grasp_put_demo 使能开关状态。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
enable |
boolean |
false |
由成功响应示例推断 |
POST/SetGraspPutDemoEnable4.5.7
设置 grasp_put_demo 使能
持久化 grasp_put_demo_enable 开关。为 true 时 catchProductRequest 只走 grasp_put_demo 流程。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
enable |
boolean |
true |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
enable |
bool |
可选 |
false |
使能开关 |
4.6 商品任务管理接口3 个接口
GET/getProductInfo4.6.1
获取产品信息
返回商品/任务全量列表。Query 参数当前被忽略。成功时 status 多为 0。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
array<object> |
[{"uuid":"a1b2c3d4-...","name":"商品A","image_path":"","chassis_pos_id":0,"chassis_pos":[1,2,0,0,0,1.57],"lift_pos_mm":300… |
由成功响应示例推断 |
1
curl -s "http://<ROBOT_IP>:5000/getProductInfo"
123456789101112131415161718192021222324252627282930313233343536373839
{ "status": 0, "message": "ok", "data": [ { "uuid": "a1b2c3d4-...", "name": "商品A", "image_path": "", "chassis_pos_id": 0, "chassis_pos": [ 1, 2, 0, 0, 0, 1.57 ], "lift_pos_mm": 300, "left_arm_pos": [ 0, 0, 0, 0, 0, 0, 0 ], "right_arm_pos": [ 0, 0, 0, 0, 0, 0, 0 ] } ]}
POST/recordProductsInfo高危4.6.2
记录商品信息
采集当前底盘位姿、双臂关节角、升降高度并写入任务库。
⚠
本接口 status 为字符串 "1"(成功)/ "0"(失败),与其余接口的数值型 status 不同,解析时注意类型。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
string |
"1" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
productName |
string |
可选 |
"" |
商品名称 |
productUuid |
string |
可选 |
"" |
任务 uuid |
POST/deleteProductById高危4.6.3
删除商品信息
按 uuid 删除商品记录。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"deleted successed" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
id |
string |
必填 |
— |
任务 uuid |
4.7 点位管理接口4 个接口
GET|POST/getLocationList4.7.1
获取点位信息
查询点位列表。GET 与 POST 行为相同,均只读 Query 参数、不读 Body。成功时 status 多为 0。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
data |
array<object> |
[{"id":"uuid-string","location_name":"货架A","pose":{"x":1,"y":2,"z":0},"yaw":1.57,"location_type":1,"height":"0.3000","ar… |
由成功响应示例推断 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
Query 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
id |
string |
可选 |
— |
点位 uuid,传入时查询单条 |
location_type |
int |
可选 |
— |
1 放置点,2 充电站 |
1
curl -s "http://<ROBOT_IP>:5000/getLocationList"
12345678910111213141516171819
{ "data": [ { "id": "uuid-string", "location_name": "货架A", "pose": { "x": 1, "y": 2, "z": 0 }, "yaw": 1.57, "location_type": 1, "height": "0.3000", "armPose": "{...}" } ], "status": 0, "message": "ok"}
1234
{ "status": -1, "message": "location list select error"}
POST/setLocationPoint4.7.2
设置点位信息
保存当前机器人位姿为点位。服务端自动采集 SLAM 位姿、机械臂关节角、升降高度;location_type 固定为 1。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
result |
string |
"new-uuid-string" |
由成功响应示例推断 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"data insert success" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
location_name |
string |
必填 |
— |
点位名称 |
POST/updateLocationPoint4.7.3
修改点位信息
按 uuid 部分更新点位字段,仅传需要修改的字段。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
data |
boolean |
true |
由成功响应示例推断 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"更新点位信息成功" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
id |
string |
必填 |
— |
点位 uuid |
location_name |
string |
可选 |
— |
名称 |
x, y, z |
float |
可选 |
— |
坐标 |
yaw |
float |
可选 |
— |
航向角 |
location_type |
int |
可选 |
— |
1 放置点 / 2 充电站 |
height |
string |
可选 |
— |
升降高度(米) |
armPose |
string |
可选 |
— |
机械臂关节 |
POST/deleteLocation高危4.7.4
删除点位
按 id 删除指定点位,或一次性删除全部点位。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"location deleted" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
id |
string |
可选 |
二选一 |
点位 uuid |
deleteAll |
int |
可选 |
二选一 |
传 1 删除全部点位 |
4.8 状态与感知接口4 个接口
GET/robotStatus高危4.8.1
机器人状态获取
返回机器人诊断状态数组(ROS DiagnosticArray)。
⚠
首次数据到达之前调用可能异常,客户端请做好重试处理。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
header |
object |
{"timestamp":{"sec":0,"nanosec":0},"frame_id":""} |
由成功响应示例推断 |
status_array |
array<object> |
[{"index":0,"status_level":"OK","status_level_code":0,"name":"node_name","message":"...","hardware_id":"...","values":{}… |
由成功响应示例推断 |
status_count |
number |
1 |
由成功响应示例推断 |
1
curl -s "http://<ROBOT_IP>:5000/robotStatus"
123456789101112131415161718192021
{ "header": { "timestamp": { "sec": 0, "nanosec": 0 }, "frame_id": "" }, "status_array": [ { "index": 0, "status_level": "OK", "status_level_code": 0, "name": "node_name", "message": "...", "hardware_id": "...", "values": {} } ], "status_count": 1}
GET/robotHardwareInfo4.8.2
机器人硬件身份信息
查询 SN 及 startup.yaml 核心字段(机型、底盘型号、末端类型、升降/URDF 型号等)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
data |
object |
{"sn":"W2-S48127102-999999","model":"hh_y2","chassis_model":"woosh","left_end_effector":"inspire_gripper","right_end_eff… |
由成功响应示例推断 |
GET/imageCapture4.8.3
抓拍
触发拍照并返回图片 URL(通常为 /capture/<camera>_image.png)。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
Image_url |
string |
"http://..." |
由成功响应示例推断 |
status |
number |
1 |
由成功响应示例推断 |
error |
string |
"" |
由成功响应示例推断 |
GET/getEmergencyStop高危4.8.4
获取急停状态
查询急停开关状态。
ℹ
emergency_status 为字符串 "true" / "false"(非布尔值);上电尚未收到信号时默认为 "false"。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
0 |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
emergency_status |
string |
"false" |
由成功响应示例推断 |
4.9 静态资源1 个接口
GET/capture/{filename}4.9.1
抓拍图片静态访问
访问抓拍图片文件。示例文件名:left_image.png、head_image.png、right_image.png。
4.10 系统接口1 个接口
POST/restoreAudioVolume4.10.1
恢复播放器音量
恢复现场播放器的音量设置。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"音量已恢复" |
由成功响应示例推断 |
五fd_arm_http(:8000)接口
BaseURL:http://:8000 — 机械臂完整控制:上下电、轨迹运动、笛卡尔运动、预设位姿管理、夹爪/灵巧手末端控制。 关节自由度 N 由机型 robot_profile 决定,示例中的 7 元数组仅作示意;本服务未在 web_interface 全量代理,完整能力请直连本端口。
5.1 查询接口4 个接口
GET/5.1.1
服务状态
返回 fd_arm_http 服务状态。交互式调试文档见 /docs(Swagger)与 /redoc。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
service |
string |
"fd_arm_http" |
由成功响应示例推断 |
status |
string |
"ok" |
由成功响应示例推断 |
GET/get_joint_angle5.1.2
获取双臂关节角度
获取左右臂当前关节角,同时返回弧度与度两套数值。
ℹ
每臂数组长度为 N(由 robot_profile 的 dof 决定,非固定 7),实际以硬件返回为准。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
armleft_joint_angle |
array<number> |
[0,-0.0175,0,1.5708,0,0,0.0001] |
由成功响应示例推断 |
armright_joint_angle |
array<number> |
[1.334,0.346,-1.416,1.539,-0.186,0.379,0.819] |
由成功响应示例推断 |
armleft_joint_angle_deg |
array<number> |
[0,-1,0,90,0,0,0] |
由成功响应示例推断 |
armright_joint_angle_deg |
array<number> |
[76.3912,19.833,-81.1277,88.1869,-10.6643,21.7012,46.9295] |
由成功响应示例推断 |
message |
string |
"双臂模式, 返回双臂角度" |
由成功响应示例推断 |
1
curl -s http://<ROBOT_IP>:8000/get_joint_angle
12345678910111213141516171819202122232425262728293031323334353637383940
{ "success": true, "armleft_joint_angle": [ 0, -0.0175, 0, 1.5708, 0, 0, 0.0001 ], "armright_joint_angle": [ 1.334, 0.346, -1.416, 1.539, -0.186, 0.379, 0.819 ], "armleft_joint_angle_deg": [ 0, -1, 0, 90, 0, 0, 0 ], "armright_joint_angle_deg": [ 76.3912, 19.833, -81.1277, 88.1869, -10.6643, 21.7012, 46.9295 ], "message": "双臂模式, 返回双臂角度"}
1234
{ "success": false, "message": "机械臂未初始化或未接收到数据"}
GET/get_end_pose5.1.3
获取双臂末端姿态
获取左右臂末端位姿。position 为 [x,y,z](米),orientation 为 [x,y,z,w] 四元数。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
armleft_end_pose |
object |
{"position":[0.35,0.12,0.48],"orientation":[0,0.707,0,0.707]} |
由成功响应示例推断 |
armright_end_pose |
object |
{"position":[0.35,-0.12,0.48],"orientation":[0,0.707,0,0.707]} |
由成功响应示例推断 |
message |
string |
"双臂模式, 返回双臂末端姿态(XYZ, [x, y, z, w])" |
由成功响应示例推断 |
1
curl -s http://<ROBOT_IP>:8000/get_end_pose
123456789101112131415161718192021222324252627282930
{ "success": true, "armleft_end_pose": { "position": [ 0.35, 0.12, 0.48 ], "orientation": [ 0, 0.707, 0, 0.707 ] }, "armright_end_pose": { "position": [ 0.35, -0.12, 0.48 ], "orientation": [ 0, 0.707, 0, 0.707 ] }, "message": "双臂模式, 返回双臂末端姿态(XYZ, [x, y, z, w])"}
1234
{ "success": false, "message": "机械臂未初始化或未接收到数据"}
GET/get_manipulator_states5.1.4
获取末端执行器状态
获取灵巧手/夹爪当前关节状态。joints 每项含 name / position / velocity / effort,数值范围约 0~1000。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"左臂末端执行器为灵巧手" |
由成功响应示例推断 |
joints |
array<object> |
[{"name":"left_hand_pinky","position":976,"velocity":0,"effort":0},{"name":"left_hand_index","position":500,"velocity":2… |
由成功响应示例推断 |
1
curl -s http://<ROBOT_IP>:8000/get_manipulator_states
123456789101112131415161718
{ "success": true, "message": "左臂末端执行器为灵巧手", "joints": [ { "name": "left_hand_pinky", "position": 976, "velocity": 0, "effort": 0 }, { "name": "left_hand_index", "position": 500, "velocity": 250, "effort": 100 } ]}
1234
{ "success": false, "message": "未接收到末端执行器状态数据"}
5.2 机械臂运动控制接口6 个接口
POST/initialize_robotarm高危5.2.1
初始化 / 上电指定机械臂
对指定机械臂上电,并设置运动速度百分比。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright / both |
speed |
int |
可选 |
20 |
速度百分比 1–100 |
POST/stop_robotarm高危5.2.2
暂停指定机械臂运动
暂停指定机械臂的当前运动。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright / both |
POST/move_robotarm5.2.3
关节空间轨迹移动
按关节空间轨迹点序列移动机械臂。每个 waypoint 为 N 个关节值。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright / both |
trajectory |
list[list[float]] |
必填 |
— |
轨迹点序列,每个点长度 = N |
unit |
string |
可选 |
"deg" |
deg / rad |
block |
int |
可选 |
0 |
0 非阻塞 / 1 阻塞 |
timeout |
float |
可选 |
30.0 |
运动超时(秒) |
smooth_through_waypoints |
bool |
可选 |
配置值 |
轨迹插值;省略取默认配置 |
speed |
int |
可选 |
20 |
插值速度百分比 1–100 |
123
curl -s -X POST http://<ROBOT_IP>:8000/move_robotarm \ -H "Content-Type: application/json" \ -d '{"robot_name":"armleft","trajectory":[[0,0,0,90,0,0,0]],"unit":"deg","block":0}'
12345678910111213141516
{ "robot_name": "armleft", "trajectory": [ [ 0, 0, 0, 90, 0, 0, 0 ] ], "unit": "deg", "block": 0}
12345
{ "status": 1, "success": true, "message": "ok"}
12345
{ "success": false, "status": -1, "message": "invalid args"}
POST/joint_control5.2.4
单关节步进控制
单关节点动。可指定步进角度(度),或 joint_move_angle="None" 走速度模式。HTTP 立即返回,运动在后台执行。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
message |
string |
"joint control success" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
joint_name |
string |
必填 |
— |
joint1 ~ jointN |
direction |
int |
必填 |
— |
0 正向 / 1 负向 |
speed |
int |
可选 |
30 |
速度百分比 1–100 |
joint_move_angle |
string |
可选 |
"None" |
步进角度(度);"None" 表示速度模式 |
smooth_through_waypoints |
bool |
可选 |
配置值 |
默认取配置 |
123
curl -s -X POST http://<ROBOT_IP>:8000/joint_control \ -H "Content-Type: application/json" \ -d '{"robot_name":"armleft","joint_name":"joint1","direction":0,"speed":30,"joint_move_angle":"None"}'
1234567
{ "robot_name": "armleft", "joint_name": "joint1", "direction": 0, "speed": 30, "joint_move_angle": "None"}
1234
{ "status": 1, "message": "joint control success"}
1234
{ "status": -1, "message": "无效的robot_name。可用选项: ['armleft', 'armright']"}
POST/move_to_target高危5.2.5
移动到相机系目标点
按相机坐标系目标点 [x,y,z](米)规划并执行运动。
⚠
需已保存 before_grasp 预设位姿;目标点过近可能导致规划失败。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
target |
list[float] |
必填 |
— |
相机系 XYZ,长度 3,单位米 |
123
curl -s -X POST http://<ROBOT_IP>:8000/move_to_target \ -H "Content-Type: application/json" \ -d '{"robot_name":"armright","target":[0.5,0.1,0.3]}'
12345678
{ "robot_name": "armright", "target": [ 0.5, 0.1, 0.3 ]}
12345
{ "status": 1, "success": true, "message": "ok"}
12345
{ "success": false, "status": -1, "message": "before_grasp not saved"}
POST/move_arm_direction5.2.6
末端沿轴平移
沿指定坐标系某轴平移末端一段距离(米)。
ℹ
is_move=false 仅规划不执行运动,可用于预校验。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
axis |
string |
必填 |
— |
x / y / z |
distance |
float |
必填 |
— |
平移距离(米),正负表示方向 |
frame |
string |
可选 |
"base" |
base / tool / end |
block |
int |
可选 |
0 |
0 非阻塞 / 1 阻塞 |
timeout |
float |
可选 |
30.0 |
运动超时(秒) |
is_move |
bool |
可选 |
true |
false 仅规划不运动 |
smooth_through_waypoints |
bool |
可选 |
配置值 |
默认取配置 |
speed |
int |
可选 |
20 |
速度百分比 1–100 |
5.3 预设位姿管理4 个接口
POST/move_to_location5.3.1
移动到预设位姿
将指定臂移动到已保存的命名预设位姿。可用 /get_arm_locations 查询可用名称。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
status |
number |
1 |
由成功响应示例推断 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
location_name |
string |
必填 |
— |
预设名,如 zero / home / before_grasp |
block |
int |
可选 |
0 |
0 非阻塞 / 1 阻塞 |
timeout |
float |
可选 |
30.0 |
运动超时(秒) |
use_joint_motion |
bool |
可选 |
false |
是否使用关节运动方式 |
smooth_through_waypoints |
bool |
可选 |
配置值 |
默认取配置 |
speed |
int |
可选 |
20 |
速度百分比 1–100 |
POST/get_arm_locations5.3.2
获取预设位姿名称列表
列出指定机械臂已保存的全部预设位姿名称。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
all_location_name |
array<string> |
["zero","home","before_grasp","after_grasp"] |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
POST/save_arm_location5.3.3
保存预设位姿
将关节角(度,长度 N)保存为命名预设;省略 joint_angles 则保存当前位姿。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
location_name |
string |
必填 |
— |
自定义位姿名称 |
joint_angles |
list[float] |
可选 |
当前位置 |
关节角(度,N 个);省略则保存当前位姿 |
POST/delete_arm_location高危5.3.4
删除预设位姿
删除指定臂上的命名预设位姿。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"ok" |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
robot_name |
string |
必填 |
— |
armleft / armright |
location_name |
string |
必填 |
— |
要删除的位姿名称 |
5.4 末端执行器(灵巧手 / 夹爪)1 个接口
POST/set_manipulator_states高危5.4.1
设置末端执行器(灵巧手 / 夹爪)
设置左右手末端关节目标值(约 0~1000)。
⚠
left_type / right_type 至少填一个,否则返回失败。
ℹ
类型别名:inspire_hand → hand;inspire_gripper / jodell_epg_gripper / two_finger_gripper → gripper。
响应字段
| 字段 |
类型 |
示例值 |
说明 |
success |
boolean |
true |
由成功响应示例推断 |
message |
string |
"已发布末端执行器命令 (左=hand)" |
由成功响应示例推断 |
joints |
array<object> |
[{"name":"left_hand_pinky","position":500,"velocity":0,"effort":0}] |
由成功响应示例推断 |
请求 Body 参数
| 字段 |
类型 |
必填 |
默认 |
说明 |
left_type |
string |
可选 |
— |
hand / gripper 及其别名;与 right_type 至少其一 |
right_type |
string |
可选 |
— |
同 left_type |
left / left_joints |
object | list |
可选 |
— |
左手关节目标 |
right / right_joints |
object | list |
可选 |
— |
右手关节目标 |
六附录 · 总索引
全部 35+15 个接口索引,点击跳转到对应章节。
A · web_interface(:5000) — 共 35 个
B · fd_arm_http(:8000) — 共 15 个
本网页版相对原文档补全了缺失的 Content-Type 标注与被截断语句,并对原文档疑似编辑错误处(GetIsBigData 示例重复)做了显式标注。
变更记录
C · 常见问题(FAQ)
调用接口无响应 / 连不上
1) 确认机器人 IP 可达(ping <ROBOT_IP>);2) 确认端口 5000 与 8000 已开放;3) 确认机器人端对应服务进程已启动;4) 接口无鉴权,但仅限内网,检查是否跨网段访问。
返回的 status / success 到底是 1 还是 true?
web_interface(:5000) 常用 status,升降/臂控遥操作等返回 1 成功、-1 失败;点位/商品查询等返回 0 成功、负数失败;recordProductsInfo 返回字符串 "1" / "0"。fd_arm_http(:8000) 主要用布尔 success。具体请参见 通用调用约定 中的错误码速查表。
为什么 :5000 的臂控接口返回 status:-1?
web_interface 部分臂控接口会把请求透传给 fd_arm_http(:8000),如果 :8000 不可达或 :8000 返回失败,就会透传为 {"status":-1,"message":"..."}。请确认 :8000 服务可达、机械臂已上电初始化。
POST 请求报 400 Bad Request
检查是否携带 Content-Type: application/json;检查 JSON 字段名、类型、必填项是否与通用调用约定及对应接口参数表一致;部分 web 侧点位接口对手动 JSON 解析容忍度低,建议使用标准 JSON 序列化。
Demo 抓取没有完成回调,怎么知道结束了?
POST /catchProductRequest 立即返回受理结果,实际为异步执行。请轮询 GET /robotStatus 观察状态变化;如需中断,调用 POST /breakDisplay。
臂控接口中的数组长度为什么和示例不一样?
示例中的 7 元数组仅为示意,实际关节数量由机型 robot_profile 决定。生产环境请以 /get_joint_angle 返回的数组长度为准。
| 日期 |
版本 |
变更内容 |
| 2026-08-12 |
V1.0-0812 |
原文档发布:《天链机器人 HTTP 接口参考手册(客户对接版)V1.0-0812》 |