功能介绍#
设备管理模块覆盖司空 2 私有化版中设备从入网到运维的全生命周期管理,包含:设备列表管理:组织 / 项目两个维度的设备清单、设备拓扑(机场 / 遥控器 / 飞行器三层关系)、设备与项目的工作绑定关系切换。
设备配置:HMS 健康事件的拉取与维护、设备物模型属性的查询与下发(设备影子)/ NTP / 网络速度检测 / 机库网络 / 4G APN、SIM 卡套餐、RTK 网络账号、自定义 RTK 标定、对频与中继扫描、项目级设备参数读写,以及对设备下发自定义配置指令的"通用指令通道"。
设备先入网到组织,再绑定到具体项目;同一台设备同一时间只能属于一个工作项目。
大多数控制 / 配置 / 运维类指令走 IoT 异步通道:调用方下发后会拿到任务标识,需要轮询 查询组织设备指令执行进度 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}) 查执行结果。
设备离线、网络不稳、指令超时等场景会返回对应错误码,参见 错误码。 接口使用流程#
设备管理模块的能力总览(以"切镜头 / 设置图传清晰度 / 实时控制指令下发 / 自定义 RTK 标定"为入口的典型链路):上图中"控制权获取 / 飞行器镜头切换 / 图传清晰度设置"实际归属在 实时控制 模块,本模块负责拓扑、状态、配置;触发飞行器源端硬件变化的指令请配合阅读实时控制教程。
设备配置类指令下发与执行进度查询(通用 cmds 通道):
1.
设备清单与项目绑定:先通过 查询组织设备运维列表 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices) 拿到组织设备清单,按业务需要用 修改组织设备的当前工作项目 (PUT /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/active-project) 切设备到目标项目(一次只切一台,body {device_sn, active_project_uuid},传 active_project_uuid: "" 表示解绑),再用 获取项目当前拓扑列表 (GET /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies) 与 获取项目设备列表 (GET /openapi/v2.0/manage/api/v1/projects/{uuid}/devices) 渲染项目维度的设备视图。
2.
HMS 健康事件:定时调用 获取组织设备 HMS 事件列表 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/hms) 拉新告警,用户查看后调用 更新组织设备 HMS 已读时间 (PUT /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/hms) 标记已读;项目维度查询用 批量获取项目设备 HMS 事件 (POST /openapi/v2.0/manage/api/v1/projects/{uuid}/topologies/hms/batch-get)。
3.
设备影子下发:调用 更新组织设备影子配置 (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows)(或项目版 POST /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/shadows)下发物模型属性变更,再用 查询组织设备物模型属性当前值 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}) 拿最 新值。
4.
网络管理 / RTK / SIM / 对频:通过对应的"配置类"接口完成;其中 NTP / 机库网络 / 4G APN / 中继扫描结果走 manage-devices/cmds/{method} 异步通道,调用 查询组织设备指令执行进度 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}) 取结果。
5.
通用配置指令通道:spec 移除了一批 V1.0 的"查询类专用 cmds 端点"(device_check / fileupload_list / storage_config_get / get_operator_gps / ai_box_app_* / load_ai_model_progress / flight_areas_get / offline_map_get* 等),保留的"配置类 指令"统一通过 对组织设备下发自定义指令 (POST /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/cmds/{method}) 走,{method} 取值由设备物模型决定,以 SDK 文档为准。
设备影子物模型下发#
功能介绍#
设备影子模块用于在云端缓存设备物模型属性的"期望值"并向设备下发,适用于 NTP 服务器配置、网络参数、相机默认设置等需要长期保持的配置项。下发是异步通道(IoT),云端持久化"期望值"后由设备在上线 / 收到指令时拉取生效。组织维度用 更新组织设备影子配置 (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows),对组织内任意设备下发;项目维度用 更新项目设备影子配置 (POST /openapi/v2.0/manage/api/v1/projects/{proj_uuid}/topologies/shadows),仅对项目拓扑内的设备下发。
查询单个物模型属性的最新值用 查询组织设备物模型属性当前值 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}),{property} 是物模型属性名。
接口使用流程#
1.
准备物模型属性的"期望值"(具体属性名与值由设备机型物模型决定,以 SDK 文档为准)。
2.
调用 更新组织设备影子配置 (POST /openapi/v2.0/manage/api/v1/organizations/{org_uuid}/manage-devices/shadows)(或项目版)下发;接口立即返回,不代表设备已生效。
3.
通过 查询组织设备物模型属性当前值 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/shadows/{property}) 轮询单个属性的最新值,确认设备已拉取该期望值。
RTK 网络账号与自定义 RTK 标定#
功能介绍#
RTK 配置模块用于查询设备的 RTK 网络账号信息,以及触发自定义网络 RTK 标定(用户手动输入精确坐标,让设备完成高精度位置校准)。自定义 RTK 标定要求用户输入的标定坐标与设备卫星定位坐标距离 ≤ 50 米;超过该距离会返回错误码 210262("标定失败,手动标定坐标和卫星定位坐标距离过远"),需重新核对坐标后再试。
接口使用流程#
1.
通过 查询设备的 RTK 网络账号信息 (GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/devices/{sn}/rtk_account_info) 确认该设备 RTK 账号已配置。
2.
用户在地图上点选 / 手动输入精确坐标,调用 自定义网络 RTK 标定 (POST /openapi/v2.0/manage/api/v1/organizations/{uuid}/manage-devices/rtk_calibration) 发起标定。
3.
处理标定结果:成功直接展示完成;失败按错误码处理(210262 距离过远要求用户重新选点;210263 位置未收敛建议等待设备 GPS 稳定后再试)。