Custom Flight Area
Overview
Custom flight areas define the geographic scope in which the aircraft is allowed to operate. The cloud maintains the flight area data, while the dock synchronizes the flight area file to the aircraft and reports the position of the aircraft relative to the flight area boundaries during flight.
Flight area data is issued as a file. The file name is fixed as fence.yaml, and one file can define multiple flight areas.
Click to download the custom flight area file template: fence.yaml
Refer to the "Detailed Interface Implementation" section for the interfaces and field descriptions. If any error occurs, check the corresponding error description using the error codes listed in the Error Codes section.
Flight Area Definition
Flight Area Type
| type | Meaning | Description |
|---|---|---|
| 1 | Flyable area only | The aircraft can operate only inside this area |
| 2 | No-fly area | The aircraft must not enter this area |
Shape Type
| graphics | Meaning | Coordinates and Radius |
|---|---|---|
| 1 | Circle | The first point in coordinate is the center, and radius is the radius (m) |
| 2 | Polygon | coordinate is a closed vertex ring with identical first and last points; radius does not apply |
Main Fields
| Field | Description |
|---|---|
| id | Unique identifier of the flight area, reported as area_id |
| name | Name of the flight area, used as area_id when id is empty |
| coordinate | Flat coordinate array [latitude, longitude, latitude, longitude, ...] in pairs |
| lower / upper | Lower / upper altitude limit, in meters |
| buffer.horizontal | Horizontal buffer in meters, also used as the proximity threshold for position reporting |
| buffer.vertical | Vertical buffer, in meters |
| startTime / endTime | Start and end of the validity period, in millisecond timestamps |
Interaction Sequence Diagram
Synchronization Timing
Whether the dock pushes the downloaded flight area file to the aircraft immediately depends on the aircraft status:
| Aircraft Status | Dock Behavior | Sync Status |
|---|---|---|
| In the dock and online | Downloads the file, updates the local flight areas, pushes it to the aircraft and confirms loading | synchronized |
| In flight | Only downloads the file to local staging, without changing the flight areas currently in use | wait_sync |
| Offline | Downloads the file and updates the local flight areas, without pushing it | wait_sync |
Note:
- The download URL has a validity period. The dock downloads the file immediately after receiving the file list, so the file is always saved locally. A deferred push is completed by the dock before the next takeoff, and the cloud does not need to issue the command again.
- When new flight areas arrive while the aircraft is in flight, the aircraft keeps using the flight areas loaded before takeoff, so that the boundaries do not change during flight.
- An empty file list means deleting all custom flight areas on the dock and the aircraft, and deletion follows the same timing rules listed above. If any download URL in the file list is invalid, the dock discards the entire batch to avoid synchronizing only part of the flight areas.
Position Reporting
While the aircraft is in flight, the dock evaluates the position of the aircraft relative to each flight area every 2 seconds and reports the flight area ID, the distance to the boundary and whether the aircraft is inside the area. Only flight areas that the aircraft is inside of, or whose boundary is closer than the proximity threshold (buffer.horizontal of that flight area), are reported. Nothing is reported when the aircraft is in the dock, offline, or when the telemetry data is outdated.
Detailed Interface Implementation
- Custom Flight Area Update Command
- Custom Flight Area File Retrieval
- Custom Flight Area File Synchronization Status
- Custom Flight Area Alert Push