驾驶舱平台事件
| 事件 | 含义 |
|---|---|
cockpit.live.lifecycle | 直播通道的生命周期变化 |
cockpit.emergency-stop | 急停被触发或受理 |
ctx.events.on(事件名, handler)，并且清单里要声明 platform:events 权限。ctx.events.on 返回一个可释放的订阅句柄，用完可以 dispose()，宿主卸载时插件运行时也会回收。cockpit.live.lifecycle：直播生命周期
type Payload = {
phase: 'started' | 'first-frame' | 'stopped' | 'channel-changed'
liveId: string
cameraIndex: string | null
timestamp: number // 宿主桥接事件时的 Date.now()
}| phase | 含义 | 可以开始逐帧处理吗 |
|---|---|---|
started | 直播通道建联成功 | 否——不保证首帧已渲染 |
first-frame | 首帧渲染完成 | 是 |
stopped | 通道停止（或主码流从 playing 变为非 playing） | 应停止逐帧业务并清理临时资源 |
channel-changed | 相机/通道切换 | 先按旧画面失效处理，等新的 first-frame |
first-frame 之后做；started 不够。stopped），按 liveId + phase 做幂等处理。droneSn 不派发；SDK 事件带的 SN 与当前路由不一致时丢弃。示例：只在首帧后处理，停止时清理
let readyLiveId: string | null = null
const off = await ctx.events.on('cockpit.live.lifecycle', ({ payload }) => {
if (payload.phase === 'first-frame') {
readyLiveId = payload.liveId
startFrameProcessing(payload.liveId)
}
if ((payload.phase === 'stopped' || payload.phase === 'channel-changed')
&& readyLiveId === payload.liveId) {
readyLiveId = null
stopFrameProcessing()
}
})cockpit.emergency-stop：急停
type Payload = {
timestamp: number
source?: string // 仅 SDK 提供时才有
}cockpit:telemetry / cockpit:flight-task 确认设备实际状态。不要收到事件就当任务成功收尾，也不要假设急停一定来自你自己的插件（可能是宿主上的手动操作触发的）。const off = await ctx.events.on('cockpit.emergency-stop', ({ payload }) => {
ctx.logger.warn('急停已触发或受理', payload)
showEmergencyPending() // 进入"待确认"，继续查状态
})什么时候用事件、什么时候用状态
| 需求 | 用什么 |
|---|---|
| 当前是否已有任意直播出首帧 | cockpit:context 的 liveReady 水位 |
| 精确知道哪路流首帧/停止/换通道 | cockpit.live.lifecycle 事件 |
| 控制权、相机、云台、激光的当前值 | cockpit:telemetry |
| 任务进度和终态 | cockpit:flight-task |
| 急停被触发/受理的通知 | cockpit.emergency-stop，之后查状态 |
常见问题
| 现象 | 原因与处理 |
|---|---|
| 订阅了但收不到事件 | 清单没声明 platform:events；或当前不在驾驶舱宿主（其他宿主不派发平台事件） |
| 想收到订阅之前的直播事件 | 事件不缓存不重放；激活时先读 cockpit:context.liveReady 兜底 |
收到重复的 stopped | 平台会在码流状态下降沿兜底补发；按 liveId + phase 幂等处理 |
| 急停事件后设备还在飞 | 事件只代表触发/受理；设备终态要看遥测/飞行任务状态 |
修改于 2026-10-22 07:06:56