OTA升级

更新时间：2026-10-28 13:54:32

APP端触发设备固件升级

/**
 * 检查app可升级版本
 * @param checkReq - [AppOTAReq]
 * @public
 */
declare function checkAppVersion(checkReq: AppOTAReq): Promise<AppOTARsp | undefined>;

/**
 * 获取单个设备升级状态
 * @param checkReq - [OTADeviceReq]
 * @public
 */
declare function checkProgress(checkReq: OTADeviceReq): Promise<OTAProgressRsp | undefined>;

/**
 * 检测是否有可更新版本
 * @param checkReq - 检测版本请求参数
 * @public
 */
declare function checkVersion(checkReq: OTACheckReq): Promise<OTACheckRsp | undefined>;


/**
 * 触发升级
 * @param devices - iotId列表
 * @public
 */
declare function confirmUpgrade(devices: string[]): Promise<void>;

/**
 * 单个设备触发升级
 * @param singleConfirmReq - [OTADeviceReq]
 * @public
 */
declare function confirmUpgradeSingle(singleConfirmReq: OTADeviceReq): Promise<void>;


export declare namespace RTCXDeviceOTAMgr {
    export {
        checkVersion,
        confirmUpgrade,
        confirmUpgradeSingle,
        checkProgress,
        checkAppVersion
    }
}

获取可更新版本

/**
 * 检测是否有可更新版本
 * @param checkReq - 检测版本请求参数
 * @public
 */
declare function checkVersion(checkReq: OTACheckReq): Promise<OTACheckRsp | undefined>;

示例

import { RTCXDeviceOTAMgr, RTCXDeviceMgrTypes } from '@rtcx/websdk'

const iotId = ref(route.query.iotId as string)

// 1. 检查版本
const fetchVersion = async () => {
  if (!iotId.value) return ElMessage.warning('缺少设备 iotId')
  loading.value = true
  try {
    const res = await RTCXDeviceOTAMgr.checkVersion({ iotId: iotId.value } as RTCXDeviceMgrTypes.OTACheckReq)
    if (res) {
      newVersionInfo.value = res
      hasNewVersion.value = true
    } else {
      hasNewVersion.value = false
    }
  } catch (e) {
    ElMessage.error('检测版本失败')
  } finally {
    loading.value = false
  }
}

单个设备触发升级

/**
 * 单个设备触发升级
 * @param singleConfirmReq - [OTADeviceReq]
 * @public
 */
declare function confirmUpgradeSingle(singleConfirmReq: OTADeviceReq): Promise<void>;

示例

import { RTCXDeviceOTAMgr, RTCXDeviceMgrTypes } from '@rtcx/websdk'

const handleUpgrade = async () => {
  try {
    await ElMessageBox.confirm(
      '确认要触发设备 OTA 升级吗？升级过程中请确保设备在线且勿断电。',
      '升级确认',
      {
        confirmButtonText: '确认升级',
        cancelButtonText: '取消',
        type: 'warning',
      }
    )

    isUpgrading.value = true
    await RTCXDeviceOTAMgr.confirmUpgradeSingle({ iotId: iotId.value } as RTCXDeviceMgrTypes.OTADeviceReq)
    ElMessage.success('升级指令已下发，正在查询进度...')
    startPolling()
  } catch (e: unknown) {
    if (e !== 'cancel') {
      ElMessage.error('触发升级失败')
      isUpgrading.value = false
    }
  }
}

批量设备触发升级

/**
 * 触发升级
 * @param devices - iotId列表
 * @public
 */
declare function confirmUpgrade(devices: string[]): Promise<void>;

示例

import { RTCXDeviceOTAMgr, RTCXDeviceMgrTypes } from '@rtcx/websdk'

const handleUpgrade = async (iotId: string) => {
  try {
    await RTCXDeviceOTAMgr.confirmUpgrade({ iotId: iotId } as RTCXDeviceMgrTypes.OTADeviceReq)
    ElMessage.success('升级指令已下发，正在查询进度...')
    startPolling()
  } catch (e: unknown) {
    if (e !== 'cancel') {
      ElMessage.error('触发升级失败')
    }
  }
}

获取升级状态

App通过轮询方式调用接口，查询升级状态。当升级状态为成功或失败时结束轮询。

/**
 * 获取单个设备升级状态
 * @param checkReq - [OTADeviceReq]
 * @public
 */
declare function checkProgress(checkReq: OTADeviceReq): Promise<OTAProgressRsp | undefined>;

示例

import { RTCXDeviceOTAMgr, RTCXDeviceMgrTypes } from '@rtcx/websdk'



const startPolling = () => {
  stopPolling()
  fetchProgress() // 立即查一次
  pollingTimer = window.setInterval(fetchProgress, 10000) // 每10秒查一次
}

const stopPolling = () => {
  if (pollingTimer) {
    clearInterval(pollingTimer)
    pollingTimer = null
  }
}

const fetchProgress = async () => {
  try {
    const res = await checkProgress({ iotId: iotId.value } as RTCXDeviceMgrTypes.OTADeviceReq)


    const otaStatus = res?.status
    const isSuccess = otaStatus === RTCXDeviceMgrTypes.OTAUpgradeStatusEnum.SUCCEEDED
    const isFinished = isSuccess || otaStatus === RTCXDeviceMgrTypes.OTAUpgradeStatusEnum.FAILED

    if (isFinished) {
      stopPolling()
      isUpgrading.value = false
      if (isSuccess) {
        ElMessage.success('设备升级成功！')
      } else {
        ElMessage.error('设备升级失败')
      }
    }
  } catch (e) {
    console.error('查询进度失败', e)
  }
}