更新记录

1.0.0（2023-02-20）

支持乐鑫 Wi-Fi Provisioning-wifi_prov_scheme_ble 版协议的蓝牙配网。

平台兼容性

Android	Android CPU类型	iOS
适用版本区间：6.0 - 12.0	armeabi-v7a：未测试，arm64-v8a：未测试，x86：未测试	适用版本区间：13 - 16

原生插件通用使用流程：

购买插件，选择该插件绑定的项目。
在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

- 乐鑫(esp芯片)蓝牙配网插件使用说明

简介

本插件主要为使用 乐鑫(esp芯片) 的嵌入式产品 提供手机端的蓝牙配网API。需要注意嵌入式产品需遵循乐鑫SDK Wi-Fi Provisioning 对应的wifi_prov_scheme_ble蓝牙配网方案才可正常使用。嵌入式产品SDK，Wi-Fi Provisioning 说明详见官方文档。

功能特性

支持最低 安卓-6.0 和 IOS-13.0（注意IOS系统最低支持为13.0）。
支持安卓和IOS插件运行所需权限，申请弹窗逻辑功能。
支持乐鑫 Wi-Fi Provisioning-wifi_prov_scheme_ble 版协议的蓝牙配网。
支持自定义 securityType， POP，需要与嵌入式产品保持一致。
支持搜索蓝牙设备时根据嵌入式设备蓝牙名称的前缀进行过滤。
提供测试工程项目示例，支持vue页面和nvue页面，可直接复制对应页面代码到自己的工程中，简单修改，即可正常测试使用。或者直接下载测试工程项目（若您当前在uni插件市场对应的插件说明页面，可直接在页面右上角点击 使用HBuiderX 导入示例项目），简单配置，即可测试运行。具体使用说明，详见工程代码示例中的 README.md 文件。

示例工程项目源码地址

点击跳转示例项目源码地址

插件示例工程配网页面流程

graph LR
初始化配网环境--> 配网使用说明 --> 搜索蓝牙设备-->连接配网蓝牙设备-->搜索可用的WIFI列表-->选择WIFI开始配网-->配网环境清理

初始化配网环境: 主要检查配网所需手机权限是否正常。若不正常，则弹窗申请。
配网使用说明：页面文本展示，主要告知用户配网操作流程和注意事项。
搜索蓝牙设备：搜索手机附近可以连接的蓝牙设备。
连接蓝牙设备: 选择待配网的蓝牙设备与手机建立蓝牙通讯连接。
搜索可用的wifi列表：手机端获取到可用的wifi列表。
选择WIFI开始配网：根据wifi列表，选择待接入的wifi，对嵌入式产品进行配网。
环境清理：主要用来清理配网插件运行时申请的内存或未完成的任务。

API使用说明

引入--使用API之前需要先引入原生插件

var espModule = uni.requireNativePlugin("nw-ble-esp-provisioning_module")

使用

API-初始化配网环境:

var code = espModule.bleEnvironmentOnLoad(objectData);

入参： let objectData= {"isRequestPermissions":true,"securityType":0, "pop":""} isRequestPermissions : Bool值，为true或false。 true：使用插件内的位置权限弹窗申请。 fasle：不使用插件内的位置权限弹窗申请。（鉴于安卓系统位置权限申请的逻辑问题，此值的抉择，可参考如下：若APP的其他功能模块也需要位置权限，则选择false，并在APP使用本模块之前，引导用户完成申请位置权限的功能。若APP其他模块没有使用位置权限，建议为true。） securityType: 值0 或者值1 ，安全通讯级别，由对应嵌入式设备得到此值。后续连接蓝牙设备API，还可再修改。 pop：字符串值，通讯凭证由对应嵌入式设备得到。securityType=1的时候 pop有效， securityType=0的时候 pop无效，传""即可。后续连接蓝牙设备API，还可再修改。

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-搜索蓝牙设备:

var code =espModule.bleStartSearchDevice(deviceNamePrefix)

入参： deviceNamePrefix：字符串值，名称前缀过滤字符串，根据搜索到的蓝牙名称匹配过滤返回对应设备。值为 "" 返回所有设备。

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-停止搜索蓝牙设备:

var code =espModule.bleStopSearchDevice()

入参：无

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-连接蓝牙设备:

var code =  espModule.bleConnectDevice(objectData);

入参： let objectData= {"mBleDevice":mBleDevice,"securityType":0,"pop":"" } mBleDevice：通过搜索蓝牙设备API返回的某一个蓝牙对象。 securityType: 值0 或者值1 ，安全通讯级别，由对应嵌入式设备得到此值。（此值与前面的初始化环境API入参重复，但实际以此API传入的值为准。） pop：字符串值，通讯凭证，由对应嵌入式设备得到。（此值与前面的初始化环境API入参重复，但实际以此API传入的值为准。）

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-停止正在连接或断开已经连接的蓝牙设备:

var code =  espModule.bleStopDisconnectDevice();

入参：无

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-获取WIFI列表:

var code =  espModule.bleScanNetworks();

入参：无

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-开始蓝牙配网:

var code =espModule.bleStartProvisioning(objectData);

入参：let objectData= {"wifiName":mWifi.wifiName,"security":mWifi.security,"passWord":passWord} wifiName：通过获取WIFI列表API返回的对应单个WIFI的名称。 security：通过获取WIFI列表API返回的对应单个WIFI的加密安全级别，规定级别为0时，不需要wifi密码，传""即可。 passWord：用户输入的当前WIFI的密码。

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-停止蓝牙配网:
var code = espModule.bleStopProvisioning();
入参：无

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API-环境清理:

var code = espModule.bleEnvironmentOnUnload();

入参：无

出参： var code： Number值，具体参见 同步API返回code码含义 。

异步回调：有具体参见 API异步返回值含义 。

API同步返回code码含义

let codeState = [
    {
        code:0,
        message:"执行成功!"

    },
    {
        code:1,
        message:"环境已存在,不需要重复初始化!"

    },
    {
        code:2,
        message:"配网环境未得到初始化,请先执行环境初始化!"

    },
    {
        code:3,
        message:"搜索蓝牙任务,已经停止运行,无需重复停止!"

    },
    {
        code:4,
        message:"搜索蓝牙任务,已经在运行,无需重复运行!"

    },
    {
        code:5,
        message:"蓝牙设备不具备扫描WIFI列表的能力!"

    },
    {
        code:6,
        message:"蓝牙设备未连接,请先连接设备!"

    },
    {
        code:7,
        message:"传递参数错误!"

    },
    {
        code:8,
        message:"初始化会话失败,请重新初始化!"

    },
    {
        code:9,
        message:"预留!"

    },
    {
        code:10,
        message:"环境检查OK!"  //插件使用者无需关注

    },
    {
        code:11,
        message:"位置权限未打开!" //参数isRequestPermissions 为false有效

    },
    {
        code:12,
        message:"GPS未打开!"

    },
    {
        code:13,
        message:"此设备不支持蓝牙!"

    },
    {
        code:14,
        message:"需要打开蓝牙开关,才能继续!"  //检测到蓝牙未开启,已经向用户请求弹窗

    },
    /* 需要注意 若参数isRequestPermissions为true, 请保证不要在系统的其他地方调用 申请位置权限弹窗的操作,否则回应码将是不准确的! */
    {
        code:15,
        message:"需要位置权限,才能继续!" //参数isRequestPermissions 为true有效  (第一次弹出的位置权限弹窗,被用户手动拒绝了,需要手动引导用户)

    },
    {
        code:16,
        message:"请允许位置权限,才能继续!" //参数isRequestPermissions 为true有效 ( 位置权限第一次弹窗成功,需要监听用户操作后的回调locationPermissions)

    },
    {
        code:17,
        message:"需要位置权限,才能继续!" //  不准确的!--理论上不会出现这个回应码,若出现则说明系统在其他位置也调用了申请位置权限弹窗的操作! 参数isRequestPermissions 为true有效

    },
    {
        code:18,
        message:"正在连接蓝牙设备,请允许配对或稍后重试!!"

    },
    {
        code:19,
        message:"已经连接蓝牙设备,请断开蓝牙后重新尝试!" 

    },
    {
        code:20,
        message:"正在供应配网数据,稍后重试!" 

    },
    {
        code:21,
        message:"需要蓝牙权限,才能继续!" //蓝牙权限被用户拒绝,需要手动引导用户!--IOS有效

    },
    {
        code:22,
        message:"需要蓝牙权限,才能继续!"  //蓝牙权限申请已弹窗,监听回调!--目前IOS有效

    }

]

API异步返回值含义

注册回调事件

注册回调事件，才能收到异步返回值。建议直接参考示例项目页面代码。

var globalEvent = uni.requireNativePlugin('globalEvent'); //插件全局监听

/* 注册插件监听事件,页面内有效 */
globalEvent.addEventListener('espEvent', function(event) {
        console.log('收到插件espEvent事件:'+JSON.stringify(event));
     });

返回值含义

返回值含义及使用 建议直接参考示例项目页面代码。

//返回值 event：是一个JSON对象。
//event.tag : 返回值对应的含义,具体如下
switch (event.tag){
    case "locationPermissions":{
            /* 位置权限弹窗后,用户操作的回调- 允许了位置权限 或者拒绝了位置权限!
        环境初始化时,传入的参数isRequestPermissions为true 有效*/  
            break;
        }
    case "blePermissions":{
            /* 蓝牙关闭的情况下,会向用户弹窗请求打开蓝牙, 这里是用户操作后的回调! */
            break;  
    }
    case "blePermissionsState" :{
        // 蓝牙权限用户操作后的 回调---只IOS有效

        break;  
    }
    case "mBleDevice":{
        /* 扫描蓝牙设备,返回的蓝牙设备 */

            break;  
    }
    case "wifiList":{   
        /* 搜索wifi列表获取到的WIFI列表 */
        break;  
    }
    case "bleScanListenerCodeState":{
        /* 蓝牙设备扫描监听 回调状态 */
        break;  
    }
    case "bleConnectCodeState":{
        /* 蓝牙设备首次连接 回调状态 */
        break;  
    }
    case "initSessionCodeState":{   
        /* 蓝牙设备首次建立会话 回调状态 */
            break;  
    }
    case "provisioningCodeState":{
        /* 配网API调用后,成功或失败后的回调码 */
            break;  
    }
    default:
        console.log(event); 
        break;
}

所需权限

安卓：

"android.permission.BLUETOOTH",
"android.permission.BLUETOOTH_ADMIN",
"android.permission.INTERNET",
"android.permission.ACCESS_WIFI_STATE",
"android.permission.ACCESS_NETWORK_STATE",
"android.permission.CHANGE_WIFI_MULTICAST_STATE",
"android.permission.CHANGE_WIFI_STATE",
"android.permission.ACCESS_FINE_LOCATION"
"android.permission.CAMERA"

IOS：

"NSLocationWhenInUseUsageDescription",
"NSLocationAlwaysUsageDescription",
"NSLocationAlwaysAndWhenInUseUsageDescription",
"NSBluetoothAlwaysUsageDescription",
"NSCameraUsageDescription" //需要说明：相机权限，本插件API暂未使用相机权限，但插件中引用的三方SDK中使用相机API，用于扫码联网功能。所以在uniAPP打包时必须配置使用描述语，否则APP将审核不通过，具体配置见下节 uniAPP打包时必要的权限配置

uniAPP打包时必要的权限配置

打开项目 manifest.json 文件，点击源码视图。

检查，并增加如下distribute 节点下的信息。

    "distribute" : {
        /* android打包配置 */
        "android" : {
            "permissions" : [
                "<uses-permission android:name=\"android.permission.INTERNET\"/>",
                "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>",
                "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
                "<uses-permission android:name=\"android.permission.CHANGE_WIFI_MULTICAST_STATE\"/>",
                "<uses-permission android:name=\"android.permission.CHANGE_WIFI_STATE\"/>",
                "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
                "<uses-permission android:name=\"android.permission.BLUETOOTH\"/>",
                "<uses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\"/>",
                "<uses-permission android:name=\"android.permission.CAMERA\"/>"
            ],
            "minSdkVersion" : 23
        },
        /* ios打包配置 */
        "ios" : {
            "privacyDescription" : {
                "NSBluetoothAlwaysUsageDescription" : "APP需要蓝牙权限，才能进行蓝牙通讯,用于设备配网。",
                "NSLocationWhenInUseUsageDescription" : "APP需要您同意访问位置信息，才能获取WI-FI信息，用于设备配网。",
                "NSLocationAlwaysUsageDescription" : "APP需要您同意访问位置信息，才能获取WI-FI信息，用于设备配网。",
                "NSLocationAlwaysAndWhenInUseUsageDescription" : "APP需要您同意访问位置信息，才能获取WI-FI信息，用于设备配网。"
                "NSCameraUsageDescription" : "APP需要访问您的相机以便拍照或录制视频，用于在应用中分享或扫描设备。我们不会在您未经授权的情况下访问您的相机。"
            },
            "capabilities" : {
                "entitlements" : {
                    "com.apple.developer.networking.wifi-info" : true
                }
            }
        }
    }

已知问题

在nvue页面的onUnload 生命周期函数中执行配网销毁函数 espModule.bleEnvironmentOnUnload() 时, 会出现无返回值的问题。但此问题已在插件内部解决。更为详细的原因和情况已在示例项目代码对应的NVUE页面中注释清楚。
在IOS手机，若第一次系统蓝牙权限弹窗被用户拒绝后，后续通过自定义弹窗跳转到手机的蓝牙权限设置页面后，用户操作蓝牙权限状态后，将会导致APP重启。-----此问题暂未找到原因，也找了几个需要蓝牙权限的其他APP测试，同样也会有此问题，所以可能是IOS系统自有问题。

常见问题

可以搜索到蓝牙设备,但是点击蓝牙设备进行连接时,提示连接失败. 这个问题可能是如下原因:
1. ESP支持两种蓝牙配网协议分别为ESP Blufi 协议和ESP BLE provisioning协议，本插件使用的是ESP BLE provisioning ，对应的嵌入式设备应保持一致。
2. ESP BLE provisioning协议支持V0，V1，V2三种加密方案，本插件只支持V0和V1，如果嵌入式设备生成的QRCODE码中包含有 username ，即为V2版本，本插件目前仅支持V0和V1版本的通讯，即QRCODE码不能包含username字段。

其他

本插件目前仅支持乐鑫 Wi-Fi Provisioning-wifi_prov_scheme_ble 版协议的蓝牙配网，若有需要 wifi_prov_scheme_softap 版协议配网插件的，可在评论区留言。若需要的朋友较多，可在本插件中免费增加。
本插件目前暂未支持扫设备码联网的能力，若有需要的朋友可在评论区留言。需求较多，可在本插件中免费增加。
联系
由于平台限制,不能使用除uni-im之外的其他联系方式,若急需联系,可先在评论区留言,我将会收到邮件通知. 收到邮件后,若具备条件我会第一时间登录uni-im查看并回复消息. 若不能及时回复,敬请见谅.
补充说明: 大部分情况下使用示例项目是最佳的快速食用方案.

示例项目使用大致流程如下:
1. 在插件说明页面右上角点击 "使用HBuilderX导入示例项目".
2. 在示例项目中找到 manifest.json 文件,并依次点击:APP原生插件配置->选择云端插件->列表选中所要试用的插件并保存.
3. 在菜单中找到 "制作自定义调试基座" ,完成本地基座的制作.
4. 使用自定义基座,运行到指定手机,即可正常运行和试用. 需要注意:本示例项目中提供了UDP配网和BLE蓝牙配网两种方案,分别对应了两个插件,只有在插件配置中选中了对应的插件后,才可正常运行对应的页面. 另外,本示例中还提供了VUE和NVUE两种UI方案的参考示例,请根据自己的项目选择性试用.

乐鑫(esp芯片)蓝牙配网插件 乐鑫配网 蓝牙配网 Provisioning 支持安卓IOS

更新记录

1.0.0（2023-02-20）

平台兼容性

原生插件通用使用流程：

- 乐鑫(esp芯片)蓝牙配网插件使用说明

简介

功能特性

示例工程项目源码地址

插件示例工程 配网页面 流程

API使用说明

引入--使用API之前需要先引入原生插件

使用

API-初始化配网环境:

API-搜索蓝牙设备:

API-停止搜索蓝牙设备:

API-连接蓝牙设备:

API-停止正在连接或断开已经连接的蓝牙设备:

API-获取WIFI列表:

API-开始蓝牙配网:

API-停止蓝牙配网:

API-环境清理:

API同步返回code码含义

API异步返回值含义

注册回调事件

返回值含义

所需权限

安卓：

IOS：

uniAPP打包时必要的权限配置

已知问题

常见问题

其他

联系

补充说明: 大部分情况下使用 示例项目 是最佳的快速食用方案.

示例项目使用大致流程如下:

隐私、权限声明

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

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

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

乐鑫(esp芯片)蓝牙配网插件

乐鑫(esp芯片)UDP配网插件

Modal title

乐鑫(esp芯片)蓝牙配网插件乐鑫配网蓝牙配网 Provisioning 支持安卓IOS

插件示例工程配网页面流程

补充说明: 大部分情况下使用示例项目是最佳的快速食用方案.