更新记录

0.2.0(2026-11-21)

0.2.0 (2026-11-21)

0.2.0(2026-11-21)

  • 新增鸿蒙(HarmonyOS NEXT / app-harmony)EspTouch V1 配网
  • 内嵌 OpenHarmony TPC EsptouchForOhos v1 ETS 源码;BSSID 优先 getCurrentWifiBssidForLocating
  • 统一 API 不变:prepareWifiAccess / getCurrentWifi / startProvisioning / stopProvisioning / isProvisioning

0.1.0(2026-11-18)

新增 UTS 插件骨架,支持 uni-app / uni-app x

  • Android / iOS 实现 EspTouch V1:getCurrentWifi / startProvisioning / stopProvisioning / isProvisioning
  • 内嵌官方 EspTouch V1 源码(Android Java)与编译产物(iOS EspTouchV1.xcframework)
  • 声明定位、本地网络、Wi‑Fi 信息等相关权限与 entitlements

    0.1.0(2026-11-18)

新增 UTS 插件骨架?cframework)

  • 声明定位、本地网络、Wi‑Fi 信息等?/Users/cham/Downloads/微信图片_2026-11-21_160841_645.png

平台兼容性

uni-app(5.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

uni-app x(5.0)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ √ √ ×

acupday-esptouch

乐鑫 EspTouch 配网 UTS 插件,同时支持 uni-app 与 uni-app x(App-Android / App-iOS / App-Harmony)。

当前版本(0.2.0)

能力 状态
EspTouch V1 ✅ Android / iOS / 鸿蒙
读取当前 Wi‑Fi ✅ prepareWifiAccess + getCurrentWifi
取消配网 ✅ stopProvisioning
EspTouch V2 ⏳ 后续
ESP-IDF SoftAP ⏳ 后续
BLE ⏳ 后续(需带蓝牙芯片)

固件侧需运行 smart_config(与官方 EsptouchForAndroid / EsptouchForIOS 一致)。V1 与 V2 协议不兼容。

安装

  1. 将本目录放入项目 uni_modules/acupday-esptouch
  2. 使用 自定义调试基座 / 云打包(含原生代码,标准基座不可用)
  3. iOS:开发者账号需勾选 Access WiFi Information(插件已声明 wifi-info)
  4. iOS 14+ EspTouch 广播/组播:需向 Apple 申请 Multicast Networking,审批通过后在 App ID / 描述文件勾选;插件默认不写入该 entitlement(未审批会导致云打包失败)
  5. Android / iOS / 鸿蒙均需授予定位权限后才能稳定读到 SSID/BSSID;手机请连接 2.4GHz Wi‑Fi
  6. 鸿蒙:BSSID 使用 getCurrentWifiBssidForLocating(需 LOCATION + APPROXIMATELY_LOCATION);请先调用 prepareWifiAccess

API

import {
  prepareWifiAccess,
  getCurrentWifi,
  startProvisioning,
  stopProvisioning,
  isProvisioning
} from '@/uni_modules/acupday-esptouch'

prepareWifiAccess(callback)

申请定位等权限并刷新 Wi‑Fi 缓存(iOS / 鸿蒙强烈建议;Android 也可用于探测是否可读)。

getCurrentWifi()

返回 { ssid, bssid } 或 null。鸿蒙端为缓存值,请先 prepareWifiAccess。

startProvisioning(options, callback)

prepareWifiAccess((ok, message) => {
  if (!ok) {
    console.log(message)
    return
  }
  const wifi = getCurrentWifi()
  startProvisioning({
    mode: 'esptouch_v1',
    ssid: wifi?.ssid ?? '',
    bssid: wifi?.bssid ?? '',
    password: 'your-wifi-password',
    deviceCount: 1,
    broadcast: true, // iOS 上请显式传 boolean,不要省略
    timeoutMs: 0,
    aesKey: '',
    reservedData: ''
  }, (event) => {
    // event.state: start | deviceFound | success | fail | cancelled
    // event.result / event.results: { success, cancelled, bssid, ip }
    // event.errCode / event.errMsg
    console.log(event)
  })
})

iOS UTS 会把「可选 boolean」编成非可选 Bool。因此 broadcast 等布尔字段为必填,调用时请显式传入。

stopProvisioning() / isProvisioning()

取消进行中的任务;查询是否正在配网。

权限说明

  • Android:INTERNET、ACCESS_WIFI_STATE、CHANGE_WIFI_STATE、CHANGE_WIFI_MULTICAST_STATE、定位;业务侧需自行 uni.requestPermissions / 引导开启定位服务
  • iOS:插件自带完整中文用途说明(定位、本地网络)作为缺省;描述文件需含 Access WiFi Information。Multicast 需 Apple 审批后由宿主自行加到描述文件 / entitlements(插件默认不声明,避免未审批时打包失败)
  • NSBonjourServices(_esptouch_ln._udp)由插件提供,用于触发本地网络权限,一般无需改
  • 鸿蒙:插件 module.json5 声明 INTERNET、GET_WIFI_INFO、GET_NETWORK_INFO、LOCATION、APPROXIMATELY_LOCATION;运行时通过 prepareWifiAccess 申请定位类权限

iOS 权限文案:宿主自定义与多语言(推荐)

插件 Info.plist 仅为兜底。正式产品请在宿主 manifest.json 覆盖,并按系统语言配置多语言(跟系统语言,不是 App 内切语言)。改完需重新打自定义基座 / 云打包。

默认语言(app-plus.distribute.ios.privacyDescription):

"app-plus": {
  "distribute": {
    "ios": {
      "privacyDescription": {
        "NSLocationWhenInUseUsageDescription": "用于读取当前 Wi-Fi,以便给设备配网",
        "NSLocationAlwaysAndWhenInUseUsageDescription": "用于读取当前 Wi-Fi,以便给设备配网",
        "NSLocalNetworkUsageDescription": "用于向局域网设备发送配网数据"
      }
    }
  }
}

多语言(app-plus.locales):

"app-plus": {
  "locales": {
    "zh": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "用于读取当前 Wi-Fi,以便给设备配网",
          "NSLocationAlwaysAndWhenInUseUsageDescription": "用于读取当前 Wi-Fi,以便给设备配网",
          "NSLocalNetworkUsageDescription": "用于向局域网设备发送配网数据"
        }
      }
    },
    "en": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "Needed to read the current Wi-Fi for device provisioning.",
          "NSLocationAlwaysAndWhenInUseUsageDescription": "Needed to read the current Wi-Fi for device provisioning.",
          "NSLocalNetworkUsageDescription": "Needed to send provisioning data to devices on the local network."
        }
      }
    }
  }
}

uni-app x 云打包对权限文案 i18n 支持较弱时,可用离线工程配置 *.lproj/InfoPlist.strings 覆盖同名 Key。

第三方说明

  • Android / iOS EspTouch V1 核心实现来自 Espressif 官方 SDK(MIT License)
  • 鸿蒙 EspTouch V1 来自 EsptouchForOhos(OpenHarmony TPC)

详见 THIRD_PARTY_NOTICES.md。

插件作者:本地源码 / 市场上架

  • 纯源码在 native-src/(.npmignore 排除,不会进市场包)
  • 日常开发:scripts/use-source.sh(默认;utssdk 含 Android Java)
  • 发布市场前:scripts/use-binary.sh(打 libs/esptouch-v1.aar 并移除 utssdk/app-android/com)
  • 发布后建议再执行 use-source.sh 切回本地源码
  • 付费上架时,市场还会加密 .uts / .kt / .swift 等(interface.uts 仍可见)

详见 native-src/README.md。

路线图

P1 EspTouch V2 → P2 ESP-IDF SoftAP → P3 BLE → P5 示例工程与市场完善资料。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:INTERNET、ACCESS_WIFI_STATE、CHANGE_WIFI_STATE、CHANGE_WIFI_MULTICAST_STATE、定位(读 SSID);iOS:定位(读 SSID)、本地网络、Access WiFi Information;鸿蒙:INTERNET、GET_WIFI_INFO、GET_NETWORK_INFO、LOCATION、APPROXIMATELY_LOCATION(读真实 BSSID)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集、不上传用户数据;Wi-Fi SSID/密码仅用于本地配网过程

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。