API(HTTP)_四川天链机器人股份有限公司

一、概述

机械臂 HTTP 接口，通过 8000 端口 访问，服务运行于 大脑（192.168.2.201）。控制可通过 HTTP 请求 或 ROS 话题 两种方式完成。

二、HTTP 基础信息

项目	值
Base URL	`http://192.168.2.201:8000`
API 文档	http://192.168.2.201:8000/docs
双臂标识	`armleft` / `armright`
机械臂 IP	`192.168.2.14`（控制器网口直连大脑以太网口）

三、状态查询接口

3.1 获取关节角度

方法	路径
`GET`	`/api/arm/joint_angles`

请求参数	说明
无	—

响应字段	类型 / 说明
`success`	bool
`armleft_joint_angle`	弧度数组（左臂）
`armright_joint_angle`	弧度数组（右臂）
`armleft_joint_angle_deg`	度数组（左臂）
`armright_joint_angle_deg`	度数组（右臂）
`message`	string

3.2 获取双臂末端姿态

方法	路径
`GET`	`/api/arm/end_pose`

响应字段	说明
`armleft_end_pose`	`{position[x,y,z], orientation[x,y,z,w]}`
`armright_end_pose`	`{position[x,y,z], orientation[x,y,z,w]}`

3.3 获取机械臂末端执行器状态

方法	路径
`GET`	`/api/arm/end_effector/state`

响应字段	说明
`message`	末端类型
`joints`	`[{name, position, velocity, effort}]`

四、控制接口

4.1 初始化机械臂

方法	路径
`POST`	`/api/arm/init`

{
    "robot_name": "armleft"
}

{
    "success": true,
    "message": "ok"
}

4.2 暂停机械臂运动

方法	路径
`POST`	`/api/arm/pause`

{
    "robot_name": "armleft"
}

{
    "success": true,
    "message": "ok"
}

4.3 机械臂运动（关节轨迹）

方法	路径
`POST`	`/api/arm/move`

请求参数

{
    "robot_name": "armleft",
    "trajectory": [[关节角...], [关节角...]],
    "unit": "deg",
    "block": 0,
    "timeout": 30.0
}

参数	类型	说明
`robot_name`	string	机械臂标识
`trajectory`	array	关节角度轨迹二维数组
`unit`	string	角度单位 `deg` / `rad`
`block`	int	是否阻塞（1 阻塞等待完成）
`timeout`	float	超时时间（秒）

成功响应

{
    "success": true,
    "message": "ok"
}

失败响应

{
    "success": false,
    "status": -1,
    "message": "invalid args"
}

提示：使用 block=1 时接口会阻塞直到运动完成；关节角度单位通过 unit 参数切换 deg / rad。

4.4 机械臂移动到目标位置（笛卡尔）

方法	路径
`POST`	`/api/arm/move_to_target`

{
    "robot_name": "armleft",
    "target": [0.5, 0.1, 0.3]
}

{
    "status": 1,
    "success": true,
    "message": "ok"
}

4.5 单独控制各个关节

方法	路径
`POST`	`/api/arm/joint_control`

{
    "direction": 1,
    "joint_move_angle": "5",
    "joint_name": "joint7",
    "robot_name": "armleft",
    "speed": 30
}

参数	类型	说明
`direction`	int	方向（1 正 / -1 负）
`joint_move_angle`	string	移动角度量
`joint_name`	string	关节名称（如 `joint7`）
`robot_name`	string	机械臂标识
`speed`	int	速度

{
    "status": 1,
    "message": "joint control success"
}

4.6 机械臂末端沿着基坐标系移动

方法	路径
`POST`	`/api/arm/end_move`

{
    "robot_name": "armright",
    "axis": "x",
    "distance": 0.05
}

参数	类型	说明
`robot_name`	string	机械臂标识
`axis`	string	坐标轴 `x` / `y` / `z`
`distance`	float	移动距离（米）

{
    "status": 1,
    "success": true,
    "message": "ok"
}

4.7 设置机械臂末端执行位置

方法	路径
`POST`	`/api/arm/end_effector/set`

{
    "left": {
        "left_jaw": {
            "position": 0
        }
    },
    "left_type": "gripper"
}

{
    "success": true,
    "message": "已发布末端执行器命令 ...",
    "joints": [...]
}

五、预设位姿接口

5.1 保存机械臂固定姿态

方法	路径
`POST`	`/api/arm/save_pose`

{
    "robot_name": "armleft",
    "location_name": "my_pose",
    "joint_angles": [0.0, -30.0, ...]
}

参数	类型	说明
`robot_name`	string	机械臂标识
`location_name`	string	位姿名称
`joint_angles`	array	关节角度数组

{
    "success": true,
    "message": "ok"
}

5.2 机械臂移动到预设位置

方法	路径
`POST`	`/api/arm/move_to_saved_pose`

{
    "robot_name": "armleft",
    "location_name": "after_grasp",
    "block": 1
}

参数	类型	说明
`robot_name`	string	机械臂标识
`location_name`	string	已保存的位姿名称
`block`	int	是否阻塞等待完成

{
    "success": true,
    "message": "移动指令发送成功"
}

六、注意事项

① 实机运行前确认机械臂已上使能
确保机械臂驱动已正常启动并处于使能状态，否则控制指令无法执行。

② 急停后需要重新上使能
触发急停开关后，机械臂驱动将断开使能，须重新上使能后方可继续运动。

③ 阻塞模式
使用 block=1 时，接口会阻塞直到运动完成，适用于需要同步等待的场景。

④ 关节角度单位
通过 unit 参数切换 deg（度）与 rad（弧度），默认值请参考具体接口说明。

⑤ 关节限位
各关节限位为初始零位的相对弧度，具体范围请见产品文档附图。

API(HTTP)

机械臂 HTTP 接口说明