航线管理

接口变更说明

✓ 提供该接口，— 未提供。未列出的接口 EVO Nest 与 Autel Nest2 一致。

Method	功能	EVO Nest	Autel Nest2	说明
flighttask_stop	终止任务	—	✓	蛙跳任务用
flighttask_progress_get	查询任务进度	—	✓	蛙跳任务用
return_specific_home	指定机巢返航	—	✓	蛙跳任务用
flight_task_poi	兴趣点任务	✓	✓
flight_task_poi_progress	兴趣点任务执行结果事件通知	✓	✓
cancel_flight_task_poi	取消兴趣点任务	✓	✓

上报航线任务进度

Topic: thing/product/gateway_sn/events

Direction: up

Method: flighttask_progress

Data:

Column	Name	Type	constraint	Description
output	内容	struct		任务进度输出结果
»ext	扩展内容	struct		任务进度扩展信息
»»current_waypoint_index	当前执行到的航点数	int		当前执行到的航点序号
»»media_count	本次航线任务执行产生的媒体文件数量	int		本次任务已拍摄的媒体文件数
»»flight_id	任务 ID	text		关联的航线任务ID
»»break_point	航线断点信息	struct	可选字段，用于告知云端本次航线任务断点信息	可选字段，用于告知断点信息
»»»index	断点序号	int		航线断点序号
»»»state	断点状态	enum_int	"0":"在航段上","1":"在航点上"	断点状态枚举值
»»»progress	当前航段进度	int	"max":"100","min":"0"	当前航段执行进度百分比
»»»wayline_id	航线 ID	int		断点所在的航线ID
»»»latitude	断点纬度	float	"max":"90","min":"-90","unit":"度 / °"	断点位置纬度
»»»longitude	断点经度	float	"max":"180","min":"-180","unit":"度 / °"	断点位置经度
»»»height	断点相对地球椭球面高度	float	"unit":"米 / m"	断点相对椭球面高度
»status	任务状态	enum_string	"pending":"开始执行","canceled":"取消或终止","failed":"失败","in_progress":"执行中","ok":"执行成功","partially_done":"部分完成","paused":"暂停","return":"返航"	任务执行状态
»progress	进度	struct		任务执行进度
»»current_step	执行步骤	enum_int	"0":"初始状态","1":"启动前检查，无人机是否在执行航线中","2":"启动前检查，机巢是否退出工作模式","3":"启动前检查，航线执行中","4":"启动前检查，返航中","5":"航线执行进入准备状态，开始等待任务下发","6":"机巢进入工作状态","7":"进入开机检查准备工作和开盖准备工作","8":"等待飞行系统准备就绪，推送连接建立","9":"等待 RTK 源监听有值上报","10":"检查 RTK 是否就绪","14":"下载任务文件","15":"任务文件上传中","17":"无人机起飞参数设置，备降点设置，起飞高度设置","18":"无人机 flyto 起飞参数设置","19":"Home 点设置","20":"触发执行航线","21":"航线执行中","22":"返航","23":"无人机降落机巢","24":"降落以后的关盖","29":"获取媒体文件数量","46":"上传图片","47":"任务完成","0xFFFD":"结束后等待服务回包","0xFFFE":"无具体状态","0xFFFF":"UNKNOWN"	当前执行步骤
»»percent	进度值	int	"max":"100","min":"0"	当前进度百分比
result	结果	int	返回0成功，非零失败（失败原因见错误码）	返回码，非0代表错误

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"output": {
			"ext": {
				"current_waypoint_index": 3,
				"flight_id": "flight_id",
				"media_count": 6
			},
			"progress": {
				"current_step": 19,
				"percent": 100
			},
			"status": "ok"
		},
		"result": 0
	},
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655,
	"method": "flighttask_progress"
}

下发任务

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_prepare

Data:

Column	Name	Type	constraint	Description
flight_id	计划 ID	text		待准备的航线任务ID
execute_time	开始执行时间	int	"length":13	任务开始执行时间毫秒时间戳，必填。
task_type	任务类型	enum_int	"0":"立即任务","1":"定时任务"	立即任务和定时任务均由 execute_time 指定执行时间。立即任务媒体上传优先级最高。
wayline_type	航线类型	enum_int	"0":"普通航点航线"	可选字段，默认 0
file	航线文件对象	struct		航线文件信息
»url	文件 URL	text		航线文件下载地址
»fingerprint	文件 MD5 签名	text		航线文件MD5校验值
rth_altitude	返航高度	int	"max":1500,"min":20,"unit_name":"米 / m"	可选字段。相对地面高度
out_of_control_action	遥控器失控动作	enum_int	"0":"返航","1":"悬停","2":"降落"	可选字段。失控动作，当前固定传的值是 0，即返航。注意该枚举值定义跟飞控跟机巢定义的不一致，机巢端会进行转换。
exit_wayline_when_rc_lost	航线失控动作	enum_int	"0":"继续执行航线任务","1":"退出航线任务，执行遥控器失控动作"	保持跟 KMZ 文件一致
wayline_precision_type	航线精度类型	enum_int	0:"GPS 任务"， 1： "高精度RTK任务"	航线精度类型
barrier_switch_state	避障开关	enum_int	0：关闭避障， 1， 打开避障
takeoff_altitude	起飞高度	int		相对地面高度
first_waypoint_speed	去首航点的速度	int		飞往首航点的速度
return_speed	返航速度	int		返航速度
media_upload_method	媒体文件上传方式	enum_int	0:落地上传， 1:变飞边传	媒体文件上传方式
rth_mode	返航模式	enum_int	"0":"智能高度返航","1":"设定高度返航"	可选字段，默认 0
wayline_file_type	航线文件类型	enum_int	"0":"航点航线文件"	可选字段，默认 0
break_point	航线断点信息	struct	可选字段，用于断点续飞，若下发该字段，航线任务会从字段指定的断点位置开始执行。	可选字段。断点续飞的断点信息
»index	断点序号	int		断点序号
»state	断点状态	enum_int	"0":"在航段上","1":"在航点上"	断点状态枚举值
»progress	当前航段进度	int	"max":100,"min":0	当前航段执行进度百分比
»latitude	断点纬度	float	"max":90,"min":-90,"unit_name":"度 / °"	断点位置纬度
»longitude	断点经度	float	"max":180,"min":-180,"unit_name":"度 / °"	断点位置经度
»height	断点高度	float	"unit_name":"米 / m"	断点相对椭球面高度
»wayline_id	航线 ID	int	下发断点执行需要带上进度上报中上报的这个ID	断点所在的航线ID
flight_safety_advance_check	飞行安全预检查	bool	"0":"关闭","1":"开启"	可选字段，默认为 0。设置一键起飞和航线任务中的飞行安全是否预先检查。值为 0 表示关闭，1 表示开启。飞行安全预先检查表示：飞行器执行任务前，检查自身作业区文件是否与云端一致，如果不一致则拉取文件更新，如果一致则不处理。

Example:

{
  "timestamp" : "1715693761421",
  "data" : {
    "flight_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", 
    "execute_time" : "1715693761357",
    "task_type" : 0,
    "wayline_type" : 0,
    "file" : {
      "url" : "https://storage.example.com/wayline/example-wayline.aut",
      "fingerprint" : "ebf5f3c1ee5228edd96943ade9dda33d"
    },
    "rth_altitude" : 100,
    "exit_wayline_when_rc_lost" : 0,
    "alternate_land_point" : {
      "longitude" : 114.2304316,
      "latitude" : 23.0358027,
      "safe_land_height" : 10,
      "is_configured" : 1
    },
    "wayline_precision_type" : 1,
    "takeoff_altitude" : 100,
    "first_waypoint_speed" : 10,
    "return_speed" : 10,
    "media_upload_method" : 0
  },
  "method" : "flighttask_prepare",
  "tid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "bid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "gateway" : "NM1923371013"
} 

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_prepare

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

Example:

{
    "bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "data": {
        "result": 0
    },
    "gateway": "NM1923371013",
    "tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "timestamp": 1715693761468,
    "method": "flighttask_prepare"
}

执行任务

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_execute

Data:

Column	Name	Type	constraint	Description
flight_id	计划 ID	text		待执行的航线任务ID
max_speed	最大飞行速度	double	"unit_name":"米每秒 / m/s"	可选字段，默认 10
multi_dock_task	蛙跳任务信息	struct		可选字段，用于 A 机巢起飞、B 机巢降落的蛙跳任务
»dock_infos	机巢列表	array	"size": -, "item_type": struct	参与本次任务的机巢信息
»»sn	机巢序列号	text		机巢 SN
»»dock_type	机巢角色	enum_string	"takeoff":"起飞机巢","landing":"降落机巢"	本机巢在任务中承担的角色
»»home_position	返航点	struct		该机巢的返航点
»»»home_position_is_valid	返航点是否有效	enum_int	"0":"无效","1":"有效"	返航点有效性
»»»latitude	返航点纬度	double	"max":90,"min":-90	返航点纬度
»»»longitude	返航点经度	double	"max":180,"min":-180	返航点经度
»»»height	返航点高度	double	"unit_name":"米 / m"	返航点高度
»»alternate_land_point	备降点	struct		该机巢的备降点，字段同 flighttask_prepare
»wireless_link_topo	图传链路配对信息	struct		可选字段，蛙跳任务的图传链路配对参数
»»mesh_key	组网标识	text		两台机巢需使用相同的组网标识
»»pair_type	配对类型	int		配对类型
»»pair_method	配对方式	int		配对方式
»»node_id	节点编号	int		本机巢在组网中的节点编号

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"flight_id": "xxxxxxx"
	},
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1234567890123,
	"method": "flighttask_execute"
}

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_execute

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"result": 0
	},
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1234567890123,
	"method": "flighttask_execute"
}

一键返航

Topic: thing/product/gateway_sn/services

Direction: down

Method: return_home

Data: null

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: return_home

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误
output	输出	struct		服务执行的输出结果
»status	任务状态	enum_string	"canceled":"取消或终止","failed":"失败","in_progress":"执行中","ok":"执行成功","paused":"暂停","rejected":"拒绝","sent":"已下发","timeout":"超时"	返航任务执行状态

航线暂停

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_pause

Data: null

Example:

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_pause

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

航线恢复

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_recovery

Data: null

Example:

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_recovery

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

取消任务

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_undo

Data:

Column	Name	Type	constraint	Description
flight_ids	计划 ID	array	"size": -, "item_type": text	需取消的航线任务ID列表

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"flight_ids": [
			"aaaaaaa",
			"bbbbbbb"
		]
	},
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1234567890123,
	"method": "flighttask_undo"
}

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_undo

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"result": 0
	},
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1234567890123,
	"method": "flighttask_undo"
}

取消返航

返航后，无人机会退出航线模式，此时取消返航，无人机会悬停

Topic: thing/product/gateway_sn/services

Direction: down

Method: return_home_cancel

Data: null

Example:

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: return_home_cancel

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

一键降落

Topic: thing/product/gateway_sn/services

Direction: down

Method: landing

Data:

Column	Name	Type	constraint	Description
flight_id	计划 ID	text		可选字段，缺省取当前正在执行的任务 ID
precision_landing	是否精准降落	bool		可选字段，默认 false

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: landing

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

指定机巢返航

用于 A 机巢起飞、B 机巢降落的蛙跳任务，指定无人机返航到哪一台机巢。只能指定本机巢或本次蛙跳任务的对端机巢，其它 SN 一律拒绝。

Topic: thing/product/gateway_sn/services

Direction: down

Method: return_specific_home

Data:

Column	Name	Type	constraint	Description
home_dock_sn	返航机巢序列号	text		必填，目标返航机巢的 SN

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: return_specific_home

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误
output	输出	struct		服务执行的输出结果
»status	执行状态	enum_string	"ok":"执行成功","rejected":"拒绝"	指令执行状态
»reason	拒绝原因	text		仅在被拒绝时返回

终止任务

蛙跳任务中，当一台机巢的任务结束后，需要下发此指令到另一台机巢终止任务。若指定任务正是本机巢当前任务，机巢会走取消流程完成回滚收尾；若不是当前任务，仅返回结果不做处理。

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_stop

Data:

Column	Name	Type	constraint	Description
flight_id	计划 ID	text		必填，待终止的航线任务 ID
reason	终止原因	int		可选字段，默认 0

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_stop

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误
output	输出	struct		服务执行的输出结果
»status	执行状态	enum_string	"ok":"执行成功","rejected":"拒绝"	指令执行状态
»flight_id	计划 ID	text		请求中的任务 ID
»stopped	是否已终止	bool		指定任务是否为当前任务并已执行终止

查询任务进度

蛙跳任务中，一台机巢向另一台机巢查询航线任务的执行状态与进度。

Topic: thing/product/gateway_sn/services

Direction: down

Method: flighttask_progress_get

Data:

Column	Name	Type	constraint	Description
flight_id	计划 ID	text		可选字段，待查询的航线任务 ID
target_sn	目标机巢序列号	text		可选字段，原样回显到应答中

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flighttask_progress_get

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误
output	输出	struct		服务执行的输出结果
»flight_id	计划 ID	text		请求中的任务 ID
»target_sn	目标机巢序列号	text		请求中的目标机巢 SN
»busy	是否有任务在执行	bool		机巢当前是否正在执行航线任务
»current_flight_id	当前任务 ID	text		机巢当前正在执行的任务 ID，空闲时为空
»is_same_flight	是否为同一任务	bool		请求的任务 ID 是否为当前正在执行的任务
»status	任务状态	enum_string	"idle":"空闲","pending":"开始执行","in_progress":"执行中","paused":"暂停","return":"返航","ok":"执行成功","partially_done":"部分完成","failed":"失败","canceled":"取消或终止"	当前任务状态
»progress	进度	struct		当前任务进度
»»current_step	当前航点序号	int		当前执行到的航点序号
»»percent	进度值	int	"max":100,"min":0	任务执行百分比
»last_terminal	上一次任务终态	struct		可选字段，机巢已回到空闲时仍可据此判断上次任务结果
»»flight_id	计划 ID	text		上一次任务的 ID
»»outcome	结果	text		上一次任务的终态

兴趣点任务执行结果事件通知

Topic: thing/product/gateway_sn/events

Direction: up

Method: flight_task_poi_progress

Data:

Column	Name	Type	constraint	Description
fly_to_id	飞向目标点 ID	text		飞向目标点的任务ID
status	状态	enum_string	"wayline_cancel":"取消飞向目标点","wayline_failed":"执行失败","wayline_ok":"执行成功，已飞向目标点","wayline_progress":"执行中"	POI环绕任务状态
result	返回码	int		非 0 代表错误
remaining_distance	剩余任务距离	float	"step":0.1,"unit_name":"米 / m"	飞向目标点的剩余距离
remaining_time	剩余任务时间	float	"step":0.1,"unit_name":"秒 / s"	飞向目标点的剩余时间
planned_path_points	规划的轨迹点列表	array	"size": -, "item_type": struct	规划的飞行轨迹点列表
»latitude	轨迹点纬度(角度值)	double	"max":90,"min":-90	轨迹点纬度，角度值，南纬是负，北纬是正，精度到小数点后6位
»longitude	轨迹点经度(角度值)	double	"max":180,"min":-180	轨迹点经度，角度值，东经是正，西经是负，精度到小数点后6位
»height	轨迹点高度	float	"step":0.1,"unit_name":"米 / m"	轨迹点高度,椭球高

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"fly_to_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
		"planned_path_points": [
			{
				"height": 123.234,
				"latitude": 13.23,
				"longitude": 123.234
			}
		],
		"remaining_distance": 0,
		"remaining_time": 0,
		"result": 0,
		"status": "wayline_progress",
		"way_point_index": 0
	},
	"need_reply": 1,
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 16540709686556,
	"method": "flight_task_poi_progress"
}

兴趣点任务

Topic: thing/product/gateway_sn/services

Direction: down

Method: flight_task_poi

Data:

Column	Name	Type	constraint	Description
id	任务id	int		POI任务唯一标识
type	任务类型	enum_int	1: 无人机朝向兴趣点，不动,3: 飞向兴趣点位置后，朝向兴趣点	POI任务类型
lat	纬度	long	兴趣点任务纬度(WGS84),纬度 * 1E7,采⽤⼩端编码,即低有效字节	POI目标点纬度
lon	经度	long	兴趣点任务点经度(WGS84),经度 * 1E7 ,采⽤⼩端编码,即低有效字节	POI目标点经度
alt	高度	long	兴趣点任务点⾼度单位mm, 采⽤⼩端编码,即低有效字节在前	POI目标点高度

Example:

{
  "data" : {
    "id" : 1001, 
    "type" : 1, 
    "lat" : 23.0000000, 
    "lon" : 113.0000000,
    "alt" : 10
  },
  "method" : "flight_task_poi",
  "tid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "bid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
} 

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: flight_task_poi

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

Example:

{
    "bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "data": {
        "result": 0
    },
    "tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "timestamp": 1715693761468,
    "method": "flight_task_poi"
}

取消兴趣点任务

Topic: thing/product/gateway_sn/services

Direction: down

Method: cancel_flight_task_poi

Data:

Example:

{
  "data" : {
  },
  "method" : "cancel_flight_task_poi",
  "tid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "bid" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
} 

Topic: thing/product/gateway_sn/services_reply

Direction: up

Method: cancel_flight_task_poi

Data:

Column	Name	Type	constraint	Description
result	返回码	int		非 0 代表错误

Example:

{
    "bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "data": {
        "result": 0
    },
    "tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "timestamp": 1715693761468,
    "method": "cancel_flight_task_poi"
}