FlightHub SDK 调用时序图

时序图

一、初始化

1.1 设置 WebSocket 鉴权头

应用层 → FlightHubSDK: setWebSocketAuthHeaders(headers)
FlightHubSDK → 应用层: FlightHubSdkErrorCode

说明：
在 SDK 初始化之前，需先设置 WebSocket 连接的鉴权请求头（如 Token、Authorization 等）。返回 FlightHubSdkErrorCode，0 表示设置成功。

1.2 设置 HTTP 请求头

应用层 → FlightHubSDK: setHttpHeaders(headers)
FlightHubSDK → 应用层: FlightHubSdkErrorCode

说明：
设置 SDK 内部发起 HTTP 请求时携带的公共请求头（如认证凭据、API Key 等）。返回 FlightHubSdkErrorCode，0 表示设置成功。

1.3 SDK 初始化

应用层 → FlightHubSDK: initialize(config)
FlightHubSDK → 应用层: FlightHubSdkErrorCode

说明：
调用 initialize(config) 完成 SDK 初始化，传入配置参数 config。返回 FlightHubSdkErrorCode，返回 0 表示初始化成功，其他值表示初始化失败，后续流程不可继续。

FlightHubSdkConfig 配置项：

配置方法	参数类型	是否必填	说明
`setNotificationServerAddress(String)`	String	必填	通知服务器地址（WebSocket 地址）
`setAddress(String)`	String	必填	服务器地址
`setPort(String)`	String（不是 int！）	必填	服务器端口，⚠️ 传数字也必须传字符串，如 `"30812"`
`setLogLevel(String)`	String（不是 int！）	选填	日志级别，如 `"debug"` / `"info"`
`setLogToConsole(boolean)`	boolean	选填	是否将日志输出到控制台
`setShowVersionInfo(boolean)`	boolean	选填	初始化时是否打印版本信息
`setLogFilePath(String)`	String	选填	日志文件路径
`setLogMaxFileSize(long)`	long	选填	单个日志文件大小上限（字节）
`setLogMaxFiles(int)`	int	选填	日志文件最大保留数量
`setDrtcConfigPath(String)`	String	选填	DRTC Native SDK 配置文件路径（如 `drtc_config_node.json`）

KOC3 变化：
config.setToken() 已删除，不再通过 config 注入 token，请改用 setHttpHeaders() / setWebSocketAuthHeaders() 注入鉴权信息。
新增 setDrtcConfigPath() 用于配置 DRTC 链路。
setWebSocketAuthHeaders 和 setHttpHeaders 必须在 initialize 之前完成调用。
⚠️ setPort() 和 setLogLevel() 的参数类型均为 String，不是 int。

代码示例：

二、获取设备

2.1 获取工作空间实例

应用层 → FlightHubSDK: getWorkspaceInstance()
FlightHubSDK → 应用层: Workspace

说明：
调用 getWorkspaceInstance() 获取工作空间实例 Workspace。KOC3 中 Workspace 采用模块化设计，所有业务方法均通过子模块获取。

KOC3 变化： getWorkspaceInstance(sessionId) / getWorkspaceInstance(bindingUuid) 等带参重载已删除（session 机制移除），请使用无参版本。

Workspace 主要子模块获取方法（KOC3）：

子模块	获取方法	说明
设备管理	`getDeviceManageModule()`	设备列表、详情、改名、解绑
固件管理	`getFirmwareManageModule()`	固件升级全流程
航线管理	`getWaylineManageModule()`	航线库 CRUD、导入、下载
飞行任务	`getFlightTaskModule()`	任务创建、编辑、执行
飞行记录	`getFlightTaskRecordModule()`	历史任务记录
媒体服务	`getMediaServiceModule()`	媒体文件管理
安全服务	`getSafetyServiceModule()`	飞行区域、解锁证书、离线地图
HMS	`getHMSModule()`	历史健康告警查询
日志管理	`getLogManagementModule()`	设备日志管理
维保管理	`getMaintenanceManagementModule()`	报修工单管理
PSDK 资源	`getPsdkResourceModule()`	喊话器资源管理
AI Box	`getAIBoxModule()`	AI Box 应用管理
AI 告警	`getAIAlertModule()`	AI 智能告警 ⭐新增
机载AI管理	`getAIInsideManageModule()`	机载AI统一管理 ⭐新增
Element	`getElementModule()`	地图元素管理 ⭐新增
直播同步	`getLiveSyncModule()`	直播同步管理 ⭐新增
闪光灯	`getFlashLedModule()`	频闪灯配置 ⭐新增
三维重建	`getTerraBuildModule()`	模型重建任务

2.2 获取设备列表

应用层 → Workspace: getDeviceManageModule()
Workspace → 应用层: DeviceManageModule
应用层 → DeviceManageModule: getDeviceList(callback)
DeviceManageModule → 应用层: callback(List<DeviceTopo>, FlightHubError)

说明：
KOC3 中设备列表通过 DeviceManageModule 获取，调用链为：
workspace.getDeviceManageModule().getDeviceList(callback)

结果通过 callback 回调返回：

List<DeviceTopo>：设备拓扑列表，DeviceTopo 本身不直接提供 SN/名称等字段，需要通过 getDevice() 获取网关设备（Device 类型），或通过 getSubDevices() 获取子设备列表（List<Device>）

Device（网关设备或子设备）包含 getDeviceSn()、getDeviceName()、getModelKey()、isOnline() 等字段方法

FlightHubError：错误信息，error.getErrorCode() == 0 表示成功

⚠️ 易错点：DeviceTopo 没有 getDeviceSn() 方法，必须先 topo.getDevice() 拿到 Device 对象再调用 getDeviceSn()，直接 topo.getDeviceSn() 会编译报错（找不到该方法）。

遍历子设备示例：

KOC3 变化： v2.0.x 中 workspace.getDeviceList(callback) → KOC3 改为 workspace.getDeviceManageModule().getDeviceList(callback)。

2.3 获取飞机实例

应用层 → FlightHubSDK: getDroneInstance(drone_sn)
FlightHubSDK → 应用层: Drone

说明：
传入飞机序列号 drone_sn，获取对应的飞机实例 Drone。KOC3 中 Drone 仅保留 get*Module() getter。

Drone 子模块获取方法（KOC3）：

子模块	获取方法	说明
相机控制	`getCameraControlModule()`	拍照/录像/云台/变焦/热成像
飞行控制	`getFlightControlModule()`	返航/急停/摇杆
DRC 链路	`getDrcModule()`	DRC 链路建立/断开
OSD 监听	`getDroneOsdModule()`	飞机状态数据订阅
控制权	`getControlAuthModule()`	飞行控制权/载荷控制权
飞行参数	`getFlightSettingsModule()`	限高/返航高度/避障等参数
一键起飞	`getTakeoffModule()`	一键起飞
PSDK 控制	`getPsdkControlModule()`	喊话器/探照灯/Widget
HMS	`getDeviceHMSModule()`	飞机健康告警
在线状态	`getDeviceStateModule()`	在线/离线状态监听
航线控制	`getFlightTaskControlModule()`	任务暂停/恢复
FlyTo	`getFlyToPointModule()`	指点飞行
POI	`getPoiModule()`	POI 环绕
直播	`getLiveDeviceModule()`	直播可用范围/观众数
AI Box	`getAIBoxModule()`	AI Box 应用 ⭐新增
机载AI	`getOnboardAiModule()`	机载AI控制 ⭐新增
设备调试	`getDeviceDebugModule()`	远程调试

2.4 获取机场实例

应用层 → FlightHubSDK: getDockInstance(dock_sn)
FlightHubSDK → 应用层: Dock

说明：
传入机场序列号 dock_sn，获取对应的机场实例 Dock。KOC3 中 Dock 仅保留 get*Module() getter。

Dock 子模块获取方法（KOC3）：

子模块	获取方法	说明
OSD 监听	`getDockOsdModule()`	机场状态数据订阅
机场控制	`getDockControlModule()`	舱盖/充电/空调/补光灯
直播设备	`getLiveDeviceModule()`	直播可用范围/在线观众数
在线状态	`getDeviceStateModule()`	在线/离线状态监听
HMS	`getDeviceHMSModule()`	机场健康告警
网络测速	`getNetworkTestModule()`	机场网络测速
RTK 标定	`getRtkCalibrationModule()`	RTK 精度标定
设备调试	`getDeviceDebugModule()`	远程调试
航线控制	`getFlightTaskControlModule()`	任务暂停/恢复

三、直播功能

以下为可选流程，适用于需要使用实时视频直播功能的场景。

3.1 监听可用视频流信息

应用层 → Dock: getLiveDeviceModule()
Dock → 应用层: LiveDeviceModule
应用层 → LiveDeviceModule: listenLiveAvailableRange(callback)
LiveDeviceModule → 应用层: int listenId
LiveDeviceModule → 应用层: callback(List<LiveInfo>)

说明：
KOC3 中直播监听通过 LiveDeviceModule 实现，调用链为：
dock.getLiveDeviceModule().listenLiveAvailableRange(callback)

方法同步返回 int listenId，用于后续调用 cancelListenLiveAvailableRange(listenId) 取消监听。

KOC3 变化： KOC2中 dock.listenLiveAvailableRange(cb) → KOC3 改为 dock.getLiveDeviceModule().listenLiveAvailableRange(cb)。

3.2 获取视频流对象

应用层 → Dock: getLiveStream(liveInfo)
Dock → 应用层: LiveModule

说明：
根据监听回调中获取的 liveInfo，通过机场实例 Dock 获取视频流模块 LiveModule，后续拉流均通过该实例进行。LiveModule 接口无破坏性变化说明详见《SDK 变更概述 - 未变化的模块》。

3.3 开始拉流

应用层 → LiveModule: start(callback)
LiveModule → 应用层: callback(FlightHubError)

说明：
调用 start(callback) 启动视频流拉取，error.getErrorCode() == 0 表示成功。

3.4 订阅直播流数据

应用层 → LiveModule: subscribeLiveStream(callback)
LiveModule → 应用层: int listenId
LiveModule → 应用层: callback(byte[] data, FrameInfo frameInfo)

说明：
注册视频帧数据订阅，持续回调视频帧数据：

byte[] data：H.264/H.265 编码码流

FrameInfo frameInfo：帧信息（帧类型、时间戳等）

SEI 数据订阅（KOC3 可用）：

接口	方法名	说明
AI 检测框	`subscribeAiSeiInfo(callback)`	AI 目标检测框 SEI
AR 相机位姿	`subscribeArSeiInfo(callback)`	AR SEI（相机位置与姿态）
视场角	`subscribeFovSeiInfo(callback)`	FOV SEI（传感器尺寸与焦距）
防抖裁剪	`subscribeEisSeiInfo(callback)`	EIS SEI（电子防抖裁剪区域）
辅助影像	`subscribeAssistantSeiInfo(callback)`	辅助影像朝向 SEI

⚠️ 取消订阅命名易错点：LiveModule 的取消订阅方法统一是 unSubscribeXxx(int listenId) 前缀（如 unSubscribeLiveStream、unSubscribeAiSeiInfo），不是本文档其他模块常见的 cancelListenXxx(int listenId) 前缀，两种命名在 SDK 里同时存在，调用时请以 javadoc 实际方法名为准，不要凭记忆套用。

3.5 停止拉流

应用层 → LiveModule: stop()
LiveModule → 应用层: （无返回值）

说明：
调用 stop() 停止视频流并释放资源，同步调用，无返回值。

四、操控功能（需先建立 DRC 链路）

以下为可选流程，适用于需要主动控制飞机执行拍照、录像等操控动作的场景。
执行任何 DRC 操控指令前，必须先通过 DrcModule 成功建立 DRC 链路。
KOC3 架构变化：相机操控方法已从 Drone 直接调用改为通过 CameraControlModule 调用，并统一加 drc 前缀。

4.1 建立 DRC 链路

应用层 → Drone: getDrcModule()
Drone → 应用层: DrcModule
应用层 → DrcModule: connectDrcLink(callback)
DrcModule → 应用层: callback(FlightHubError)

说明：
KOC3 中 DRC 链路通过 DrcModule 管理，调用链为：
drone.getDrcModule().connectDrcLink(callback)

error.getErrorCode() == 0 表示链路建立成功，后续操控指令方可下发。

KOC3 变化： v2.0.x 中 drone.connectDrcLink(cb) → KOC3 改为 drone.getDrcModule().connectDrcLink(cb)。

4.2 拍照

应用层 → Drone: getCameraControlModule()
Drone → 应用层: CameraControlModule
应用层 → CameraControlModule: drcTakePhoto(payload_index, callback)
CameraControlModule → 应用层: callback(FlightHubError)

说明：
KOC3 中拍照通过 CameraControlModule 调用：
drone.getCameraControlModule().drcTakePhoto(payloadIndex, callback)

KOC3 变化： v2.0.x 中 drone.takePhoto(payloadIndex, cb) → KOC3 改为 drone.getCameraControlModule().drcTakePhoto(payloadIndex, cb)。

4.3 开始录像

应用层 → CameraControlModule: drcStartRecord(payload_index, callback)
CameraControlModule → 应用层: callback(FlightHubError)

说明：
drone.getCameraControlModule().drcStartRecord(payloadIndex, callback)

KOC3 变化： v2.0.x 中 drone.startRecord(payloadIndex, cb) → KOC3 改为 drone.getCameraControlModule().drcStartRecord(payloadIndex, cb)。

4.4 停止录像

应用层 → CameraControlModule: drcStopRecord(payload_index, callback)
CameraControlModule → 应用层: callback(FlightHubError)

说明：
drone.getCameraControlModule().drcStopRecord(payloadIndex, callback)

4.5 断开 DRC 链路

应用层 → DrcModule: disconnectDrcLink(callback)
DrcModule → 应用层: callback(FlightHubError)

说明：
操控任务完成后，调用 drone.getDrcModule().disconnectDrcLink(callback) 主动断开 DRC 链路，释放相关资源。

五、退出

应用层 → FlightHubSDK: shutdown()
FlightHubSDK → 应用层: FlightHubSdkErrorCode

说明：
调用 shutdown() 关闭 SDK，释放所有内部资源。返回 0 表示关闭成功。

六、完整调用流程总览

应用层
  │
  ├─ [初始化]
  │    ├─ 1. setWebSocketAuthHeaders(headers)       → 设置 WebSocket 鉴权头
  │    ├─ 2. setHttpHeaders(headers)                → 设置 HTTP 请求头
  │    └─ 3. initialize(config)                     → 初始化 SDK（不再使用 config.setToken）
  │              ├─ config.setNotificationServerAddress(addr)    → 必填
  │              ├─ config.setAddress(addr)                      → 必填
  │              ├─ config.setPort(port)                         → 必填
  │              └─ config.setDrtcConfigPath(path)               → 选填（DRTC场景）
  │
  ├─ [获取设备]
  │    ├─ 4. getWorkspaceInstance()                 → 获取工作空间实例（无参）
  │    ├─ 5. workspace.getDeviceManageModule()       → 获取设备管理模块 ⭐新增
  │    ├─ 6. getDeviceList(callback)                → 获取设备拓扑列表（经由 DeviceManageModule）
  │    ├─ 7. getDroneInstance(drone_sn)             → 获取飞机实例 Drone
  │    └─ 8. getDockInstance(dock_sn)               → 获取机场实例 Dock
  │
  ├─ [直播功能]（可选）
  │    ├─ 9.  dock.getLiveDeviceModule()            → 获取直播设备模块 ⭐新增
  │    ├─ 10. listenLiveAvailableRange(callback)    → 监听可用视频流，返回 int listenId
  │    ├─ 11. dock.getLiveStream(liveInfo)          → 获取视频流对象 LiveModule
  │    ├─ 12. start(callback)                       → 开始拉流（via LiveModule）
  │    ├─ 13. subscribeLiveStream(callback)         → 订阅视频帧数据，返回 int listenId
  │    └─ 14. stop()                               → 停止拉流（via LiveModule）
  │
  ├─ [操控功能]（可选，需先建立 DRC 链路）
  │    ├─ 15. drone.getDrcModule()                  → 获取 DRC 模块 ⭐新增
  │    ├─ 16. connectDrcLink(callback)              → 建立 DRC 链路（via DrcModule）
  │    │        （确认 error.getErrorCode() == 0 后执行以下操控）
  │    ├─ 17. drone.getCameraControlModule()        → 获取相机控制模块 ⭐新增
  │    ├─ 18. drcTakePhoto(payload_index, callback) → 拍照（via CameraControlModule）
  │    ├─ 19. drcStartRecord(payload_index, callback)→ 开始录像（via CameraControlModule）
  │    ├─ 20. drcStopRecord(payload_index, callback) → 停止录像（via CameraControlModule）
  │    └─ 21. disconnectDrcLink(callback)           → 断开 DRC 链路（via DrcModule）
  │
  └─ [退出]
       └─ 22. shutdown()                            → 关闭 SDK，释放资源

七、支持产品

设备类型	产品名称
机场	大疆机场 1
机场	大疆机场 2
机场	大疆机场 3
无人机	御 3 行业版
无人机	Matrice 4T / 4E
无人机	M400 RTK

详细参数请访问 DJI 大疆企业官网查看对应机型。

八、注意事项

初始化顺序不可颠倒：必须先调用 setWebSocketAuthHeaders 和 setHttpHeaders 完成鉴权配置，再调用 initialize(config)。

KOC3 不再使用 config.setToken()：token 已从 FlightHubSdkConfig 中删除，鉴权信息统一通过 setHttpHeaders / setWebSocketAuthHeaders 注入。

全模块化架构：KOC3 中 Drone/Dock/Workspace 仅保留 get*Module() getter，所有业务方法均通过子模块调用。直接调用 drone.takePhoto() 等旧方式会导致编译失败。

设备列表通过 DeviceManageModule 获取：workspace.getDeviceManageModule().getDeviceList(callback)，不再直接 workspace.getDeviceList(callback)。

DRC 操控通过子模块调用：drone.getDrcModule().connectDrcLink(cb)，相机操控通过 drone.getCameraControlModule().drcTakePhoto() 等，方法名统一加 drc 前缀。

直播监听通过 LiveDeviceModule：dock.getLiveDeviceModule().listenLiveAvailableRange(cb)，不再直接 dock.listenLiveAvailableRange(cb)。

session 机制已移除：KOC3 删除了 registerWorkspaceToken / getSessionInfo / getWorkspaceInstance(sessionId) 等 session 相关方法，所有实例获取均通过无参形式或传入 sn 字符串。

HMS 方法名统一：listenAircraftHMS → listenDeviceHMS（通过 drone.getDeviceHMSModule()）；listenDockHMS → listenDeviceHMS（通过 dock.getDeviceHMSModule()）。

Available 监听方法已全部删除：KOC3 删除了所有 listenXxxAvailable 系列方法，请直接调用功能接口，通过回调错误码判断是否成功。

10.

资源释放：使用完毕后务必调用 shutdown() 释放 SDK 资源。

接口调用时序图

FlightHub SDK 调用时序图

目录

时序图

一、初始化

1.1 设置 WebSocket 鉴权头

1.2 设置 HTTP 请求头

1.3 SDK 初始化

二、获取设备

2.1 获取工作空间实例

2.2 获取设备列表

2.3 获取飞机实例

2.4 获取机场实例

三、直播功能

3.1 监听可用视频流信息

3.2 获取视频流对象

3.3 开始拉流

3.4 订阅直播流数据

3.5 停止拉流

四、操控功能（需先建立 DRC 链路）

4.1 建立 DRC 链路

4.2 拍照

4.3 开始录像

4.4 停止录像

4.5 断开 DRC 链路

五、退出

六、完整调用流程总览

七、支持产品

八、注意事项

接口调用时序图

FlightHub SDK 调用时序图#

目录#

时序图#

一、初始化#

1.1 设置 WebSocket 鉴权头#

1.2 设置 HTTP 请求头#

1.3 SDK 初始化#

二、获取设备#

2.1 获取工作空间实例#

2.2 获取设备列表#

2.3 获取飞机实例#

2.4 获取机场实例#

三、直播功能#

3.1 监听可用视频流信息#

3.2 获取视频流对象#

3.3 开始拉流#

3.4 订阅直播流数据#

3.5 停止拉流#

四、操控功能（需先建立 DRC 链路）#

4.1 建立 DRC 链路#

4.2 拍照#

4.3 开始录像#

4.4 停止录像#

4.5 断开 DRC 链路#

五、退出#

六、完整调用流程总览#

七、支持产品#

八、注意事项#

FlightHub SDK 调用时序图

目录

时序图

一、初始化

1.1 设置 WebSocket 鉴权头

1.2 设置 HTTP 请求头

1.3 SDK 初始化

二、获取设备

2.1 获取工作空间实例

2.2 获取设备列表

2.3 获取飞机实例

2.4 获取机场实例

三、直播功能

3.1 监听可用视频流信息

3.2 获取视频流对象

3.3 开始拉流

3.4 订阅直播流数据

3.5 停止拉流

四、操控功能（需先建立 DRC 链路）

4.1 建立 DRC 链路

4.2 拍照

4.3 开始录像

4.4 停止录像

4.5 断开 DRC 链路

五、退出

六、完整调用流程总览

七、支持产品

八、注意事项