固件升级

更新时间：2025-12-16 06:39:38下载pdf

固件升级是指把新的固件写入芯片中，代替原有的固件的过程。随着市场变化、开发方案升级等原因，涂鸦会定期进行固件更新。同时，涂鸦会根据原厂芯片迭代等情况，对部分旧版本进行停用。另外，设备本身也可以进行功能更新迭代，从而升级固件。

升级流程

查询升级信息

使用查询设备升级信息接口，可以查询到 ThingSmartFirmwareUpgradeModel 固件升级模型。其中：

upgradeMode 属性表示固件类别。
type 属性表示固件通道类型。
typeDesc 属性表示固件类型的描述。

固件类别

查询固件列表时，ThingSmartFirmwareUpgradeModel 中有 upgradeMode 字段：

普通固件：字段取值为 0。传统意义上的固件，用于升级设备内固件。
PID 版本升级固件：字段取值为 1。引入产品版本的概念，不同版本间的数据能在指定功能模组范围内（即产品 schema 配置、面板配置、多语言配置、快捷控制配置）进行隔离配置。

注意需要使用新接口获取固件列表、发起升级。

固件通道类型

作为标识 普通固件 的固件通道，在查询固件列表时，ThingSmartFirmwareUpgradeModel 中 type 字段为固件通道类型，可以通过typeDesc 来获取到具体的描述。

通常通道 type 含义如下表所示，推荐根据实际情况使用模型返回的 typeDesc 来标识实际固件描述。

普通固件通道 type	固件通道含义
0	主联网模组、Wi-Fi 模组、蓝牙模组
1	蓝牙模组
2	GPRS 模组
3	Zigbee 模组
5	433 模组
6	NB-IoT 模组
9	MCU 模组
10 ~ 19	扩展通道

接口说明

export class TSmartDevice {
  // 获取普通固件及 PID 版本升级固件
  public async checkFirmwareUpgrade(): Promise<ThingSmartFirmwareUpgradeModel[] | undefined>
  // 仅获取普通固件
  public async getFirmwareUpgradeInfo(): Promise<ThingSmartFirmwareUpgradeModel[] | void>
}

ThingSmartFirmwareUpgradeModel** **数据模型

字段	类型	说明
desc	string	升级文案
type	number	固件通道类型，普通固件使用
typeDesc	string	固件通道描述
upgradeStatus	ThingSmartDeviceUpgradeStatus	`0`：无新版本`1`：有新版本`2`：在升级中`5`：等待设备唤醒
version	string	新版本使用的固件版本
currentVersion	string	当前的固件版本
devType	number	`0`：普通设备`1`：低功耗类型设备
upgradeType	number	`0`：App 提醒升级`2`：App 强制升级`3`：检测升级
url	string	蓝牙设备的升级固件包下载 URL
fileSize	string	固件包的大小，单位为字节 (byte)，fileSize 仅支持蓝牙设备
md5	string	固件的 MD5
controlType	boolean	`YES`：升级中可控制`NO`：升级中不可控制
waitingDesc	string	固件等待设备唤醒的文案
upgradingDesc	string	固件升级中的提示文案
canUpgrade	boolean	true：有前置校验，可以升级false：有前置校验，不可升级，建议展示 `remind` 文案
remind	string	前置校验规则未通过的提示文案
upgradeMode	ThingSmartDeviceUpgradeMode	固件类别，从 3.35.5 版本开始支持0：普通固件1：PID 版本升级固件

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

async getFirmwareUpgradeInfo() {
    let res = await this.device?.checkFirmwareUpgrade()
}

查询设备正在升级的固件状态

这里只会返回正在升级的固件。

接口说明

export class TSmartDevice {
	public async getFirmwareUpgradingStatus(): Promise<ThingSmartFirmwareUpgradeStatusModel | undefined>
}

ThingSmartFirmwareUpgradeStatusModel** **数据模型

字段	类型	说明
upgradeStatus	ThingSmartDeviceUpgradeStatus	升级状态枚举：`2`：在升级中`3`：升级成功`4`：升级失败`5`：等待设备唤醒`6`：设备已下载固件`7`：升级超时`13`：云端排队中`14`：云端准备中`100`：App 正在准备中（例如：正在连接蓝牙设备、App 正在下载固件包）
statusText	string	状态描述
statusTitle	string	状态标题
progress	number	升级进度，部分情况下可能为 `-1`（通常是 `upgradeStatus` 变化时），请忽略并保持之前的进度，仍需处理 `upgradeStatus` 的变化
type	number	固件通道类型，在确认升级时需要使用到
upgradeMode	ThingSmartDeviceUpgradeMode	`0`：普通固件`1`：PID 版本升级，从 3.35.5 版本 SDK 开始支持
error	TSmartOTAError	失败信息

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

async getFirmwareUpgradeInfo() {
    let res = await this.device?.getFirmwareUpgradingStatus()
}

开始升级

接口说明

export class TSmartDevice {
	public startFirmwareUpgrade(firmwares: ThingSmartFirmwareUpgradeModel[])
}

参数说明

参数	说明
firmwares	从设备升级信息接口checkFirmwareUpgrade或`getFirmwareUpgradeInfo` 获取的固件列表

注意

通过设备升级信息接口 getFirmwareUpgradeInfo 获取的信息列表中会包含下列状态信息：
- 无新版本（upgradeStatus: 0）
- 有新版本（upgradeStatus: 1）
- 在升级中（upgradeStatus: 2）
- 等待设备唤醒（upgradeStatus: 5）
  
  上述状态信息用于展示升级相关状态。仅 有新版本（upgradeStatus: 1）状态时，可以发起升级。请在使用做好相关过滤和状态展示。

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

upgradeFirmware() {
    this.device?.startFirmwareUpgrade(firmwares)
}

继续升级

目前仅支持在升级中收到进度回调时，error.code 为 5005 的场景。

在升级 Wi-Fi 和双模类设备时，为保证升级通畅，通常会设置一个最低的信号强度。当发起升级时，会检查设备的信号强度是否符合。不符合，则会回调进度状态 error.code = 5005。此时，可以通过 UI 交互，让用户做选择。例如，弹窗提示 设备信号弱，升级可能失败，是否继续升级？ 等文案。

接口说明

export class TSmartDevice {
	public confirmWarningUpgradeTask(isContinue: boolean)
}

参数说明

参数	说明
isContinue	是否继续升级

注意

仅通过 -startFirmwareUpgrade: 发起的升级，才有此流程。

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

continueFirmware() {
    this.device?.confirmWarningUpgradeTask(isContinue)
}

取消升级

目前仅支持低功耗类型的设备。此类设备在发起升级后，可能处于 待唤醒状态（upgradeStatus = 5）。通过此方法，可以取消待唤醒的升级任务。

接口说明

export class TSmartDevice {
	public async cancelFirmwareUpgrade(): Promise<void>
}

注意

取消待唤醒的升级，仅适用于 upgradeStatus 为 5（等待设备唤醒）的设备。

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

async cancelFirmware() {
 cancelFirmwareUpgrade() {
    this.device?.cancelFirmwareUpgrade().then(() => {
      console.log("cancel success")
    }).catch((e:Error) => {
      console.log("cancel failure")
    })
  }
}

回调监听

接口说明

export interface TSmartDeviceOTAListener {
  onOTAUpdateStatusChanged: (device:TSmartDevice, status: ThingSmartFirmwareUpgradeStatusModel) => void;
}

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

this.device.registerOTAListener({
        onOTAUpdateStatusChanged: (device: TSmartDevice, status: ThingSmartFirmwareUpgradeStatusModel) => {
          const upgradeStatus = status.upgradeStatus
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Failure) {
            // OTA失败
            AlertDialog.show({ message: 'device ' + devId + ' OTA Fail' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Timeout) {
            AlertDialog.show({ message: 'device ' + devId + ' OTA Timeout' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Prepare || upgradeStatus === ThingSmartDeviceUpgradeStatus.LocalPrepare) {
            // AlertDialog.show({ message: 'device ' + devId + ' OTA Prepare' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.InQueue) {
            AlertDialog.show({ message: 'device ' + devId + ' OTA InQueue' })
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.WaitingExecute) {
            this.output = "准备开始OTA"
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Upgrading) {
            if (status && status.progress && status.progress >= 0) {
              this.output = "升级进度 - " + status.progress + "%"
            } else {
              this.output = "准备好了吗，OTA要开始了！"
            }
            return
          }
          if (upgradeStatus === ThingSmartDeviceUpgradeStatus.Success) {
            AlertDialog.show({ message: "真牛逼，居然让你升级成功了！" })
            this.output = "真牛逼，居然让你升级成功了！"
            return
          }
        }
      })

自动保持最新版本

部分设备支持自动保持最新版本。通过 TSmartDeviceModel - supportAuto 来判断设备是否支持该功能。

接口说明

export class TSmartDevice {
	// 获取开关状态
	public async getAutoUpgradeSwitchInfo(): Promise<Record<string, Object> | undefined>
    // 保存开关状态
	public async saveUpgradeInfoWithSwitchValue(switchValue: number): Promise<boolean | undefined>
}

参数说明

参数	说明
switchValue	功能状态：`0`：关闭`1`：开启

示例代码

public device: TSmartDevice = TSmartDevice.create(devId)

  async getAutoUpgradeSwitchInfo() {
     let flag = await this.device?.getAutoUpgradeSwitchInfo() as Record<string, Object>
     console.log("是否支持自动OTA: " + flag.value)
  }

  saveAutoUpgradeSwitchInfo() {
    const status = 0
    this.device?.saveUpgradeInfoWithSwitchValue(status).then(() => {
      console.log("save auto switch status success.")
    }).catch(() => {
      console.log("save auto switch status fail.")
    })
  }

错误码

ThingSmartFirmwareUpgradeStatusModel 中的 error 属性的 code，仅在通过新升级接口时可用。

错误码	说明	备注
5000	设备所有固件已是最新，无需升级	-
5001	未检查到固件	-
5002	蓝牙类设备同时只能有一个设备在升级	通常为蓝牙单点、涂鸦 Mesh 子设备、蓝牙 Mesh 子设备
5003	App 下载固件包失败	-
5004	获取是否需要信号强度检测失败	-
5005	设备信号强度不满足升级条件	建议询问用户是否继续，继续可能会失败，可通过接口 `- confirmWarningUpgradeTask:` 继续或者取消
5006	连接设备失败	通常为蓝牙单点、涂鸦 Mesh 子设备、蓝牙 Mesh 子设备
5007	将蓝牙单点设备从网关下解绑超时	-
5009	App 下载固件 MD5 校验不通过	-
5010	App 发送固件失败	通常为蓝牙单点、涂鸦 Mesh 子设备、蓝牙 Mesh 子设备
5012	设备不在线	-
5013	升级前置校验不通过	-
5014	手机蓝牙未打开	-
5015	可升级固件列表接口请求失败	-
5016	设备升级超时	-
5017	调用发起 OTA 升级接口失败	服务端返回接口调用错误，详细错误码通过 `error.localizedFailureReason` 获取，详细描述通过 `error.localizedDescription` 获取
5018	设备升级中失败，设备上报失败原因	详细描述通过 `error.localizedDescription` 获取
5019	批量升级检测超时	调用接口 `-batchCheckFirmwareWithDevId:success:failure:` 时失败返回
5020	双模设备云端不在线	-
5021	BLE单点蓝牙设备仅能通过网关升级	部分打标的单点蓝牙 BLE 设备，不允许通过手机直连升级
5099	通用错误码	-