自定义飞行区
功能概述
自定义飞行区用于圈定飞行器允许作业的地理范围。云端维护飞行区数据，机巢把飞行区文件同步到飞行器，并在飞行中上报飞行器与飞行区边界的位置关系。
飞行区以文件形式下发，文件名固定为 fence.yaml，一个文件可定义多个飞行区。
点击下载自定义飞行区文件协议模板：fence.yaml
接口及字段的解释请查看本页中的“接口详细实现”。如果出现错误，请通过返回的错误码在 错误码 章节中查询对应的错误描述。
飞行区定义
飞行区类型
| type | 含义 | 说明 |
|---|---|---|
| 1 | 仅区内可飞 | 飞行器只能在该区域内作业 |
| 2 | 区内禁飞 | 飞行器不得进入该区域 |
图形类型
| graphics | 含义 | 坐标与半径 |
|---|---|---|
| 1 | 圆形 | coordinate 取第 1 个点作为圆心，radius 为半径（米） |
| 2 | 多边形 | coordinate 为闭合顶点环，首尾坐标相同，radius 不生效 |
主要字段
| 字段 | 说明 |
|---|---|
| id | 飞行区唯一标识，上报位置关系时作为 area_id |
| name | 飞行区名称，id 为空时作为 area_id |
| coordinate | 扁平坐标数组 [纬度, 经度, 纬度, 经度, ...]，两两成对 |
| lower / upper | 高度下限 / 上限，单位米 |
| buffer.horizontal | 水平缓冲，单位米，同时作为位置关系上报的近区阈值 |
| buffer.vertical | 垂直缓冲，单位米 |
| startTime / endTime | 有效期起止，毫秒时间戳 |
交互时序图
同步时机
机巢下载飞行区文件后是否立即推送到飞行器，取决于飞行器状态：
| 飞行器状态 | 机巢行为 | 同步状态 |
|---|---|---|
| 在舱且在线 | 下载文件、更新本地飞行区，推送到飞行器并确认飞行器加载完成 | synchronized |
| 飞行中 | 仅把文件下载到本地暂存，不改变飞行器当前使用的飞行区 | wait_sync |
| 离线 | 下载文件并更新本地飞行区，暂不推送 | wait_sync |
说明：
- 文件下载地址有时效，机巢收到文件列表后立即下载，因此文件总会先保存到本地；延后的推送由机巢在飞行器下次起飞前自动补齐，云端无需重新下发。
- 飞行器飞行中收到新飞行区时，继续使用起飞前已加载的飞行区，避免飞行途中飞行区边界发生变化。
- 空文件列表表示删除机巢与飞行器上的全部自定义飞行区，删除同样遵循上表的时机规则；文件列表中存在无效下载地址时，机巢丢弃整批文件，避免飞行区只同步一部分。
位置关系上报
飞行器飞行中，机巢每 2 秒评估一次飞行器与各飞行区的位置关系，上报飞行区 ID、到边界的距离以及是否位于飞行区内部。仅上报“位于飞行区内”或“距边界小于近区阈值（该飞行区的 buffer.horizontal）”的飞行区；飞行器在舱、离线或遥测数据过期时不上报。
接口详细实现
- 自定义飞行区更新指令
- 自定义飞行区文件获取
- 自定义飞行区文件同步状态
- 自定义飞行区告警信息推送