FlyShotHost/docs/collaborative-robot-flyshot-start-api.md

协作机器人飞拍接口

本文仅保留协作机器人后端需要调用的两个接口：设置运行速度、启动已存在的飞拍任务。不包含初始化、连接、使能、任务上传或任务管理。

服务地址示例：http://<飞拍服务地址>:<端口>。

1. 设置运行速度

POST /set_speedRatio/
Content-Type: application/json

请求体：

{
  "speed": 0.7
}

字段	类型	范围	说明
speed	number	0.01 ～ 1.0	运行速度倍率；1.0 为全速，0.7 为 70% 速度。

成功响应：200 OK

{
  "message": "set_speedRatio executed",
  "returnCode": 0
}

参数不在范围内时返回 400 Bad Request：

{
  "detail": "Speed ratio must be between 0.01 and 1.0."
}

应在启动飞拍前设置速度。当前接口不约定任务执行过程中的动态改速。

2. 启动飞拍任务

POST /execute_flyshot/
Content-Type: application/json

请求体：

{
  "name": "协作机器人飞拍任务名",
  "move_to_start": true,
  "method": "icsp",
  "save_traj": false,
  "use_cache": true,
  "wait": false
}

字段	类型	说明
name	string	已存在的飞拍任务名称。
move_to_start	boolean	是否先移动到飞拍轨迹起点；建议为 true。
method	string	轨迹规划方法；使用 "icsp"。
save_traj	boolean	是否保存规划导出信息；启动任务时使用 false。
use_cache	boolean	是否复用规划缓存；建议为 true。
wait	boolean	false 表示启动后立即返回；本接口使用 false。

成功响应：200 OK

{
  "status": "FlyShot executed",
  "success": true
}

wait=false 时，200 仅表示任务已接受并开始调度，不表示飞拍已经完成。

启动失败时返回 500 Internal Server Error：

{
  "detail": "具体失败原因"
}

3. 调用顺序

POST /set_speedRatio/  →  收到 returnCode = 0  →  POST /execute_flyshot/

curl 示例：

curl -X POST 'http://<飞拍服务地址>:<端口>/set_speedRatio/' \
  -H 'Content-Type: application/json' \
  -d '{"speed":0.7}'

curl -X POST 'http://<飞拍服务地址>:<端口>/execute_flyshot/' \
  -H 'Content-Type: application/json' \
  -d '{"name":"协作机器人飞拍任务名","move_to_start":true,"method":"icsp","save_traj":false,"use_cache":true,"wait":false}'