Custom Flight Area

Interface Changes

The interfaces in this chapter are new on Autel Nest2 and are not available on EVO Nest.

Custom flight areas define the geographic boundaries within which the aircraft is allowed to operate.

Synchronization flow: the cloud issues an update command → the dock requests the flight area file list → the dock downloads the files and pushes them to the aircraft → the dock reports the synchronization status. During flight, the dock continuously reports the position of the aircraft relative to the flight area boundaries.

The custom flight area file name is fixed to fence.yaml.

Click to download the custom flight area template file: Custom Flight Area File Protocol Template

Event

Custom Flight Area Alert Push

Topic: thing/product/{gateway_sn}/events

Direction: up

Method: flight_areas_drone_location

Data:

Column	Name	Type	constraint	Description
drone_locations	Aircraft Custom Flight Area Distance Information	array	{"size":"-","item_type":"struct"}	List of positional relationships between the aircraft and each custom flight area
»area_id	Flight Area ID	text		Unique identifier of the custom flight area
»area_distance	Distance to the Flight Area Boundary	float	{"unit_name":"meter / m"}	Distance from the aircraft to the boundary of the flight area
»is_in_area	Whether Inside the Custom Flight Area	bool		true indicates that the aircraft is inside the flight area

Notes:

• Evaluated every 2 seconds, and reported only while the aircraft is in flight. Nothing is reported when the aircraft is in the dock, offline, or its telemetry is stale.
• Only areas the aircraft is inside of, or whose boundary is closer than the proximity threshold, are reported. No message is sent when no area matches.
• need_reply is 0, so no reply from the cloud is required.

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"drone_locations": [
			{
				"area_distance": 100.11,
				"area_id": "d275c4e1-d864-4736-8b5d-5f5882ee9bdd",
				"is_in_area": true
			}
		]
	},
	"method": "flight_areas_drone_location",
	"need_reply": 0,
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655
}

Custom Flight Area File Synchronization Status

Reports the progress of synchronizing the flight area file from the cloud to the device.

Topic: thing/product/{gateway_sn}/events

Direction: up

Method: flight_areas_sync_progress

Data:

Column	Name	Type	constraint	Description
status	Synchronization Status	enum_string	{"wait_sync":"Waiting for synchronization","synchronizing":"Synchronizing","synchronized":"Synchronized","fail":"Failed","switch_fail":"Enable switch failed"}	Synchronization status of the flight area file
reason	Return Code	int	{"0":"Success","1":"Failed to parse the file information returned by the cloud","2":"Failed to get the file information from the aircraft","3":"Failed to download the file from the cloud","4":"Link switchover failed","5":"Failed to transfer the file","6":"Disable failed","7":"Failed to delete the custom flight area","8":"The aircraft failed to load the operating area data","9":"Enable failed","10":"The enhanced transmission of the dock cannot be disabled, so the operating area data cannot be synchronized","11":"The aircraft failed to power on, so the operating area data cannot be synchronized","12":"Checksum verification failed","13":"Synchronization timed out"}	A non-zero value indicates an error
file	Custom Flight Area File	struct		Information about the flight area file being synchronized
»name	Custom Flight Area File Name	text		Name of the flight area file
»checksum	File Signature Digest	text		SHA256 signature of the file. This field is an empty string when the flight areas are being cleared

Notes:

• When the aircraft is offline or in flight, the dock downloads the file to local storage and reports wait_sync. Pushing it to the aircraft is deferred until the next pre-takeoff sequence, which is not a failure.
• This event is also reported when the flight areas are cleared, with file.checksum set to an empty string.

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"file": {
			"checksum": "8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4",
			"name": "fence.yaml"
		},
		"reason": 0,
		"status": "synchronized"
	},
	"method": "flight_areas_sync_progress",
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655
}

Service

Custom Flight Area Update Command

Issued after the flight area data changes. The dock replies immediately and then sends a flight_areas_get request to pull the latest file list.

Topic: thing/product/{gateway_sn}/services

Direction: down

Method: flight_areas_update

Data: null

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": null,
	"method": "flight_areas_update",
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655
}

Topic: thing/product/{gateway_sn}/services_reply

Direction: up

Method: flight_areas_update

Data:

Column	Name	Type	constraint	Description
result	Return Code	int		A non-zero value indicates an error

Note: This reply only indicates that the command was received. The synchronization result is reported through the flight_areas_sync_progress event.

Example:

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

Requests

Custom Flight Area File Retrieval

Sent after the dock receives the flight_areas_update command, or once its MQTT subscriptions are ready, to pull the current flight area file list from the cloud.

Topic: thing/product/{gateway_sn}/requests

Direction: up

Method: flight_areas_get

Data: null

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {},
	"method": "flight_areas_get",
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655
}

Topic: thing/product/{gateway_sn}/requests_reply

Direction: down

Method: flight_areas_get

Data:

Column	Name	Type	constraint	Description
result	Return Code	int		A non-zero value indicates an error
output	Output	struct		Result of the flight area file list query
»files	Custom flight area file list. An empty array means there is no custom flight area	array	{"size":"-","item_type":"struct"}	Current flight area file list on the cloud
»»name	File Name	text		Name of the flight area file
»»url	File URL	text		File download address. Only http:// and https:// are supported
»»checksum	File Signature Digest	text		SHA256 signature of the file
»»size	File Size	int	{"unit_name":"byte"}	Size of the file in bytes

Notes:

• The dock downloads the files as soon as it receives the reply, so the download address must still be valid at that moment.
• An empty files array means all custom flight areas on both the dock and the aircraft are to be deleted.
• If any download address is invalid, the dock discards the entire batch to avoid a partially synchronized flight area.

Example:

{
	"bid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"data": {
		"output": {
			"files": [
				{
					"checksum": "8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4",
					"name": "fence.yaml",
					"size": 500,
					"url": "https://storage.example.com/flight-area/fence.yaml?expires=1654074568&signature=xxxxxxxx"
				}
			]
		},
		"result": 0
	},
	"method": "flight_areas_get",
	"tid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
	"timestamp": 1654070968655
}