更新记录
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
EsptouchForOhosv1 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 协议不兼容。
安装
- 将本目录放入项目
uni_modules/acupday-esptouch - 使用 自定义调试基座 / 云打包(含原生代码,标准基座不可用)
- iOS:开发者账号需勾选 Access WiFi Information(插件已声明
wifi-info) - iOS 14+ EspTouch 广播/组播:需向 Apple 申请 Multicast Networking,审批通过后在 App ID / 描述文件勾选;插件默认不写入该 entitlement(未审批会导致云打包失败)
- Android / iOS / 鸿蒙均需授予定位权限后才能稳定读到 SSID/BSSID;手机请连接 2.4GHz Wi‑Fi
- 鸿蒙: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 示例工程与市场完善资料。

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 7
赞赏 0
下载 12779274
赞赏 1960
赞赏
京公网安备:11010802035340号