Wayline Management

Interface Changes

✓ available, — not available. Interfaces not listed are identical on EVO Nest and Autel Nest2.

Method	Function	EVO Nest	Autel Nest2	Notes
flighttask_stop	Stop Task	—	✓	Used for frog jump tasks
flighttask_progress_get	Query Task Progress	—	✓	Used for frog jump tasks
return_specific_home	Return to Specified Dock	—	✓	Used for frog jump tasks
flight_task_poi	POI Task	✓	✓
flight_task_poi_progress	POI Task Execution Result Event Notification	✓	✓
cancel_flight_task_poi	Cancel POI Task	✓	✓

Report Wayline Task Progress

Topic: thing/product/{gateway_sn}/events

Direction: up

Method: flighttask_progress

Data:

Column	Name	Type	constraint	Description
output	Content	struct		Task progress output result
»ext	Extension content	struct		Task progress extension info
»»current_waypoint_index	Current waypoint index being executed	int		Index of current waypoint being executed
»»media_count	Number of media files generated during this wayline task execution	int		Number of media files captured in this task
»»flight_id	Task ID	text		Associated wayline task ID
»»break_point	Wayline breakpoint info	struct	Optional field, used to report breakpoint info for this wayline task to the cloud	Optional field, used to report breakpoint info
»»»index	Breakpoint index	int		Wayline breakpoint index
»»»state	Breakpoint state	enum_int	{"0":"On way segment","1":"On waypoint"}	Breakpoint state enum value
»»»progress	Current way segment progress	int	{"max":"100","min":"0"}	Current way segment execution progress percentage
»»»wayline_id	Wayline ID	int		Wayline ID where breakpoint is located
»»»latitude	Breakpoint latitude	float	{"max":"90","min":"-90","unit":"degrees / °"}	Breakpoint position latitude
»»»longitude	Breakpoint longitude	float	{"max":"180","min":"-180","unit":"degrees / °"}	Breakpoint position longitude
»»»height	Breakpoint height relative to earth ellipsoid	float	{"unit":"meters / m"}	Breakpoint height relative to ellipsoid
»status	Task status	enum_string	{"pending":"Start execution","canceled":"Canceled or terminated","failed":"Failed","in_progress":"Executing","ok":"Execution successful","partially_done":"Partially completed","paused":"Paused","return":"Return"}	Task execution status
»progress	Progress	struct		Task execution progress
»»current_step	Execution step	enum_int	{"0":"Initial state","1":"Pre-startup check, whether aircraft is executing wayline","2":"Pre-startup check, whether dock has exited work mode","3":"Pre-startup check, wayline execution in progress","4":"Pre-startup check, returning home","5":"Wayline execution enters preparation state, waiting for task dispatch","6":"Dock enters work state","7":"Enter startup check preparation and cover opening preparation","8":"Wait for flight system to be ready, push connection establishment","9":"Wait for RTK source monitoring to report values","10":"Check if RTK is ready","14":"Download task file","15":"Task file uploading","17":"Aircraft takeoff parameter settings, alternate landing point settings, takeoff altitude settings","18":"Aircraft flyto takeoff parameter settings","19":"Home point settings","20":"Trigger wayline execution","21":"Wayline execution in progress","22":"Return home","23":"Aircraft landing at dock","24":"Close cover after landing","29":"Get media file count","46":"Upload images","47":"Task completed","0xFFFD":"Wait for service response after completion","0xFFFE":"No specific status","0xFFFF":"UNKNOWN"}	Current execution step
»»percent	Progress value	int	{"max":"100","min":"0"}	Current progress percentage
result	Result	int	Return 0 for success, non-zero for failure (see error codes for failure reasons)	Return code, non-0 represents error

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"
}

Issue Task

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flighttask_prepare

Data:

Column	Name	Type	constraint	Description
flight_id	Plan ID	text		Wayline task ID to prepare
execute_time	Start execution time	int	{"length":13}	Task start execution time in milliseconds timestamp. Required.
task_type	Task type	enum_int	{"0":"Immediate task","1":"Scheduled task"}	Immediate tasks and scheduled tasks are both executed at the time specified by execute_time. Immediate task media upload has the highest priority.
wayline_type	Wayline type	enum_int	{"0":"Normal waypoint wayline"}	Optional, defaults to 0. Wayline type
file	Wayline file object	struct		Wayline file info
»url	File URL	text		Wayline file download URL
»fingerprint	File MD5 signature	text		Wayline file MD5 checksum
rth_altitude	Return home altitude	int	{"max":1500,"min":20,"unit_name":"meters / m"}	Optional. Relative to ground height
out_of_control_action	RC loss of control action	enum_int	{"0":"Return home","1":"Hover","2":"Land"}	Optional. Loss of control action, current fixed value is 0, i.e., return home. Note that this enumeration value definition is inconsistent with flight controller and dock definitions, dock side will convert.
exit_wayline_when_rc_lost	Wayline loss of control action	enum_int	{"0":"Continue executing wayline task","1":"Exit wayline task, execute RC loss of control action"}	Keep consistent with KMZ file
wayline_precision_type	Wayline precision type	enum_int	{0:"GPS task", 1: "High precision RTK task"}	Wayline precision type
barrier_switch_state	Obstacle avoidance switch	enum_int	{0: Turn off obstacle avoidance, 1: Turn on obstacle avoidance}
takeoff_altitude	Takeoff altitude	int		Relative to ground height
first_waypoint_speed	Speed to first waypoint	int		Speed when flying to first waypoint
return_speed	Return speed	int		Return home speed
media_upload_method	Media file upload method	enum_int	{0: Ground upload, 1: Upload while flying}	Media file upload method
rth_mode	Return home mode	enum_int	{"0":"Smart altitude return","1":"Preset altitude return"}	Optional field, defaults to 0
wayline_file_type	Wayline file type	enum_int	{"0":"Waypoint wayline file"}	Optional field, defaults to 0
break_point	Wayline breakpoint info	struct	Optional field, for breakpoint resume. If this field is sent, wayline task will start from the breakpoint position specified in the field.	Optional. Breakpoint info for breakpoint resume
»index	Breakpoint index	int		Breakpoint index
»state	Breakpoint state	enum_int	{"0":"On way segment","1":"On waypoint"}	Breakpoint state enum value
»progress	Current way segment progress	int	{"max":100,"min":0}	Current way segment execution progress percentage
»latitude	Breakpoint latitude	float	{"max":90,"min":-90,"unit_name":"degrees / °"}	Breakpoint position latitude
»longitude	Breakpoint longitude	float	{"max":180,"min":-180,"unit_name":"degrees / °"}	Breakpoint position longitude
»height	Breakpoint height	float	{"unit_name":"meters / m"}	Breakpoint height relative to the ellipsoid
»wayline_id	Wayline ID	int	Must include this ID from progress report when issuing breakpoint execution	Wayline ID where breakpoint is located
flight_safety_advance_check	Flight safety pre-check	bool	{"0":"Disabled","1":"Enabled"}	Optional, defaults to 0. Sets whether flight safety is pre-checked before one-key takeoff and wayline tasks. Value 0 means disabled, 1 means enabled. Flight safety pre-check means: before executing a task, the aircraft checks whether its working area files are consistent with the cloud, pulls file updates if inconsistent, does nothing if consistent.

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	Return code	int		Non-0 represents error

Example:

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

Execute Task

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flighttask_execute

Data:

Column	Name	Type	constraint	Description
flight_id	Plan ID	text		Wayline task ID to execute
max_speed	Maximum flight speed	double	{"unit_name":"meters per second / m/s"}	Optional field, defaults to 10
multi_dock_task	Frog jump task info	struct		Optional field, used for frog jump tasks that take off from dock A and land at dock B
»dock_infos	Dock list	array	{"size": -, "item_type": struct}	Info of the docks participating in this task
»»sn	Dock serial number	text		Dock SN
»»dock_type	Dock role	enum_string	{"takeoff":"Takeoff dock","landing":"Landing dock"}	Role this dock plays in the task
»»home_position	Home point	struct		Home point of this dock
»»»home_position_is_valid	Whether home point is valid	enum_int	{"0":"Invalid","1":"Valid"}	Home point validity
»»»latitude	Home point latitude	double	{"max":90,"min":-90}	Home point latitude
»»»longitude	Home point longitude	double	{"max":180,"min":-180}	Home point longitude
»»»height	Home point height	double	{"unit_name":"meters / m"}	Home point height
»»alternate_land_point	Alternate landing point	struct		Alternate landing point of this dock, same fields as in flighttask_prepare
»wireless_link_topo	Video link pairing info	struct		Optional field, video link pairing parameters for the frog jump task
»»mesh_key	Mesh key	text		Both docks must use the same mesh key
»»pair_type	Pairing type	int		Pairing type
»»pair_method	Pairing method	int		Pairing method
»»node_id	Node ID	int		Node ID of this dock in the mesh

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	Return code	int		Non-0 represents error

Example:

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

One-click Return Home

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	Return code	int		Non-0 represents error
output	Output	struct		Service execution output result
»status	Task status	enum_string	{"canceled":"Canceled or terminated","failed":"Failed","in_progress":"Executing","ok":"Execution successful","paused":"Paused","rejected":"Rejected","sent":"Sent","timeout":"Timeout"}	Return home task execution status

Wayline Pause

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	Return code	int		Non-0 represents error

Wayline Resume

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	Return code	int		Non-0 represents error

Cancel Task

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flighttask_undo

Data:

Column	Name	Type	constraint	Description
flight_ids	Plan ID	array	{"size": -, "item_type": text}	List of wayline task IDs to cancel

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	Return code	int		Non-0 represents error

Example:

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

Cancel Return Home

After return home, the aircraft will exit wayline mode. At this point, canceling return home will cause the aircraft to hover.

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	Return code	int		Non-0 represents error

One-click Landing

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: landing

Data:

Column	Name	Type	constraint	Description
flight_id	Plan ID	text		Optional field, defaults to the task currently being executed
precision_landing	Whether to use precision landing	bool		Optional field, defaults to false

Topic: thing/product/{gateway_sn}/services_reply

Direction: up

Method: landing

Data:

Column	Name	Type	constraint	Description
result	Return code	int		Non-0 represents error

Return to Specified Dock

Used for frog jump tasks that take off from dock A and land at dock B, specifying which dock the aircraft returns to. Only the local dock or the peer dock of the current frog jump task can be specified; any other SN is rejected.

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: return_specific_home

Data:

Column	Name	Type	constraint	Description
home_dock_sn	Return dock serial number	text		Required, SN of the target return dock

Topic: thing/product/{gateway_sn}/services_reply

Direction: up

Method: return_specific_home

Data:

Column	Name	Type	constraint	Description
result	Return code	int		Non-0 represents error
output	Output	struct		Service execution output result
»status	Execution status	enum_string	{"ok":"Execution successful","rejected":"Rejected"}	Command execution status
»reason	Rejection reason	text		Returned only when rejected

Stop Task

In a frog jump task, once the task on one dock has finished, this command must be sent to the other dock to stop its task. If the specified task is the current task of this dock, the dock runs the cancel flow to complete the rollback; if it is not the current task, the dock only returns the result without taking action.

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flighttask_stop

Data:

Column	Name	Type	constraint	Description
flight_id	Plan ID	text		Required, ID of the wayline task to stop
reason	Stop reason	int		Optional field, defaults to 0

Topic: thing/product/{gateway_sn}/services_reply

Direction: up

Method: flighttask_stop

Data:

Column	Name	Type	constraint	Description
result	Return code	int		Non-0 represents error
output	Output	struct		Service execution output result
»status	Execution status	enum_string	{"ok":"Execution successful","rejected":"Rejected"}	Command execution status
»flight_id	Plan ID	text		Task ID from the request
»stopped	Whether stopped	bool		Whether the specified task was the current task and has been stopped

Query Task Progress

In a frog jump task, one dock queries the execution status and progress of the wayline task on the other dock.

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flighttask_progress_get

Data:

Column	Name	Type	constraint	Description
flight_id	Plan ID	text		Optional field, ID of the wayline task to query
target_sn	Target dock serial number	text		Optional field, echoed back in the reply

Topic: thing/product/{gateway_sn}/services_reply

Direction: up

Method: flighttask_progress_get

Data:

Column	Name	Type	constraint	Description
result	Return code	int		Non-0 represents error
output	Output	struct		Service execution output result
»flight_id	Plan ID	text		Task ID from the request
»target_sn	Target dock serial number	text		Target dock SN from the request
»busy	Whether a task is executing	bool		Whether the dock is currently executing a wayline task
»current_flight_id	Current task ID	text		ID of the task the dock is currently executing, empty when idle
»is_same_flight	Whether it is the same task	bool		Whether the requested task ID is the task currently being executed
»status	Task status	enum_string	{"idle":"Idle","pending":"Start execution","in_progress":"Executing","paused":"Paused","return":"Return","ok":"Execution successful","partially_done":"Partially completed","failed":"Failed","canceled":"Canceled or terminated"}	Current task status
»progress	Progress	struct		Current task progress
»»current_step	Current waypoint index	int		Index of the waypoint currently being executed
»»percent	Progress value	int	{"max":100,"min":0}	Task execution percentage
»last_terminal	Last task terminal state	struct		Optional field, lets the caller determine the last task result even after the dock returns to idle
»»flight_id	Plan ID	text		ID of the last task
»»outcome	Outcome	text		Terminal state of the last task

POI Task Execution Result Event Notification

Topic: thing/product/{gateway_sn}/events

Direction: up

Method: flight_task_poi_progress

Data:

Column	Name	Type	constraint	Description
fly_to_id	Fly-to target point ID	text		Fly-to target point task ID
status	Status	enum_string	{"wayline_cancel":"Cancel fly-to target point","wayline_failed":"Execution failed","wayline_ok":"Execution successful, flown to target point","wayline_progress":"Executing"}	POI orbit task status
result	Return code	int		Non-0 represents error
remaining_distance	Remaining task distance	float	{"step":0.1,"unit_name":"meters / m"}	Remaining distance to fly-to target point
remaining_time	Remaining task time	float	{"step":0.1,"unit_name":"seconds / s"}	Remaining time to fly-to target point
planned_path_points	Planned trajectory point list	array	{"size": -, "item_type": struct}	List of planned flight trajectory points
»latitude	Trajectory point latitude (angle value)	double	{"max":90,"min":-90}	Trajectory point latitude, angle value, south is negative, north is positive, precision to 6 decimal places
»longitude	Trajectory point longitude (angle value)	double	{"max":180,"min":-180}	Trajectory point longitude, angle value, east is positive, west is negative, precision to 6 decimal places
»height	Trajectory point height	float	{"step":0.1,"unit_name":"meters / m"}	Trajectory point height, ellipsoid height

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"
}

POI Task

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flight_task_poi

Data:

Column	Name	Type	constraint	Description
id	Task ID	int		POI task unique identifier
type	Task type	enum_int	{1: Aircraft faces POI, stationary, 3: Fly to POI position then face POI}	POI task type
lat	Latitude	long	POI task latitude (WGS84), latitude * 1E7, little-endian encoding, i.e., low significant byte first	POI target point latitude
lon	Longitude	long	POI task longitude (WGS84), longitude * 1E7, little-endian encoding, i.e., low significant byte first	POI target point longitude
alt	Altitude	long	POI task point altitude unit mm, little-endian encoding, i.e., low significant byte first	POI target point altitude

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	Return code	int		Non-0 represents error

Example:

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

Cancel POI Task

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	Return code	int		Non-0 represents error

Example:

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