更新记录

0.2.1（2026-10-08）

0.2.1

0.2.0（2026-10-08）

初版

平台兼容性

uni-app(3.8.5)

Zql Nordic DFU 蓝牙固件升级

面向 uni-app 的 UTS API 插件，封装 Nordic 官方原生 DFU 库，提供 ZIP 固件升级、原生进度、完成通知和取消接口。本插件并非 Nordic 官方出品或认证产品。

购买前确认

• 适用于匹配 Nordic nRF5 SDK Secure/Legacy Bootloader 的设备，不支持 nRF Connect SDK / MCUmgr 固件。底层库支持范围不等于本插件已验证所有设备，请先用目标设备试用。
• Android 依赖 no.nordicsemi.android:dfu:2.11.0，iOS 依赖 NordicDFU 4.17.0。
• 当前示例为传统 uni-app + Vue 3；uni-app x、Vue 2 未纳入当前实测承诺。Web、小程序、鸿蒙没有实现。
• 原生配置下限为 Android API 21、iOS 12.0，实际要求还受宿主、依赖和 HBuilderX 限制。package.json 声明的 HBuilderX 4.27 下限尚需补充实测，不表示全版本兼容保证。
• 不提供固件制作、签名密钥或固件托管。ZIP 必须匹配目标硬件、Bootloader 和签名配置。

安装与运行

1. 导入插件到 uni_modules/zql-nordic-dfu，保持目录名不变。
2. 为宿主配置蓝牙能力及权限。插件不接管扫描界面或自定义授权弹窗。
3. 插件含 Maven / CocoaPods 原生依赖，按 HBuilderX 提示配置 UTS 原生运行环境或云打包自定义基座，安装到真机。普通标准基座不能代替此步骤。
4. 修改原生依赖、权限或服务声明后，重新打包并安装基座 / APK。仅同步代码不会更新已安装包的 Manifest。
5. 宿主扫描选定设备后停止扫描，避免自己的 BLE 连接与 DFU 争用设备。厂商自定义的进入 Bootloader 指令需由宿主处理。

Android 的蓝牙、附近设备、定位授权要求取决于系统和宿主 targetSdk。插件 Manifest 声明了蓝牙、定位、FOREGROUND_SERVICE 和 FOREGROUND_SERVICE_CONNECTED_DEVICE，声明不等于已获用户授权。iOS 宿主应配置蓝牙用途说明（如 NSBluetoothAlwaysUsageDescription，兼容旧系统时配置对应说明），并在真机授权。

接入示例

以下代码放在传统 uni-app 页面脚本中，设备和路径由宿主选择后传入；不包含自动扫描、下载或权限申请。

// #ifdef APP-PLUS
import { startDfu, cancelDfu, isDfuRunning } from '@/uni_modules/zql-nordic-dfu'
// #endif

export default {
  data() {
    return { upgrading: false, percent: 0, status: '待机' }
  },
  methods: {
    upgrade(deviceId, firmwarePath) {
      // #ifdef APP-PLUS
      if (this.upgrading || isDfuRunning()) return
      this.upgrading = true
      this.percent = 0
      this.status = '准备升级'
      try {
        startDfu({
          deviceId,
          firmwarePath,
          progress: (event) => {
            this.percent = event.percent
            this.status = event.percent >= 100 ? '等待设备确认' : '正在传输'
          },
          log: (entry) => console.log('[DFU]', entry.level, entry.message),
          success: () => {
            this.upgrading = false
            this.percent = 100
            this.status = '升级完成'
          },
          fail: (error) => {
            this.upgrading = false
            this.status = error.errCode === 9011003 ? '已取消' : '升级失败'
            console.error('[DFU]', error.errCode, error.errMsg)
          }
        })
      } catch (error) {
        this.upgrading = false
        this.status = '插件启动失败'
        console.error(error)
      }
      // #endif
    },
    cancelUpgrade() {
      // #ifdef APP-PLUS
      cancelDfu()
      // iOS 当前主动取消不保证发送 fail，宿主自行更新取消界面。
      this.upgrading = isDfuRunning()
      this.status = this.upgrading ? '正在取消' : '已请求取消'
      // #endif
    }
  }
}

升级期间保持页面和回调所有者存活，页面退出不等于取消。iOS 取消后不要立即重启会话，先确认设备退出前次连接；也不要在 success 回调内部立即启动下一次 iOS 升级。

设备和文件

• Android deviceId：扫描返回的 BLE MAC 地址，例如 AA:BB:CC:DD:EE:FF。
• iOS deviceId：扫描返回的 UUID，不能传 MAC 地址。
• firmwarePath：App 可读取的本地路径，不是单独的 ZIP 名称或 HTTP 地址。网络固件须先下载。
• 打包资源路径示例：_www/static/firmware/device.zip，需自行提供合法固件并确认已打入当前安装包。
• 必须为 Nordic DFU 格式 ZIP，不能随意压缩 BIN 或修改扩展名。当前不提供 Android content:// 文档 URI 接入。

API

startDfu 必填 deviceId: string、firmwarePath: string，回调均可选。避免同时用全局监听与 progress 回调重复更新同一份状态。

真实进度来自 Nordic SDK，simulated 为 false。真实升级的 currentBytes、totalBytes 目前固定为 0，不能用于计算速度或文件大小。Android 合并多部分百分比；iOS 当前为单部分百分比，切换部分时可能回落。

100% 仅代表传输进度，只有 success 表示原生 DFU 流程完成。 宿主需要确认新固件正常运行时，应等待重启、重新连接并读取设备版本。

模拟模式约 3 秒完成，通过 onDfuProgress 发送进度，不使用 options.progress；不要与真实升级并行。Android 取消完成后 fail 返回 9011003；iOS 当前主动取消会清理回调，不保证发送该事件。

错误排查

隐私和支持

插件处理设备标识、本地 ZIP 及诊断信息，不包含自建服务上传、广告、账户或统计代码。Android 日志写入控制台，可能含设备地址和协议数据，请勿直接公开。

开发示例将每台设备最近 200 条日志保存于宿主本地存储，可在升级页清空；插件核心不执行此持久化。宿主应单独披露实际权限、日志保留及其他 SDK 行为，此说明不是整个 App 的隐私政策。

第三方依赖见 THIRD_PARTY_NOTICES.md。售价、是否出售源码、售后联系方式以最终商品页为准；购买前核对 DCloud 授权与打包规则、AppID、包名及所用打包方式。

反馈请附插件与 HBuilderX 版本、手机系统、基座生成时间、Bootloader 类型及脱敏日志，不要发送私钥、证书或未授权固件。