更新记录

1.0.0（2023-02-20）

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

平台兼容性

原生插件通用使用流程：

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

付费原生插件目前不支持离线打包。
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打包时必要的权限配置

1. 打开项目 manifest.json 文件，点击源码视图。
2. 检查，并增加 如下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 版协议配网插件的，可在评论区留言或联系QQ：370293265。 若需要的朋友较多，可在本插件中免费增加。
• 本插件目前暂未支持扫设备码联网的能力，若有需要的朋友可联系本人，若需求较多，一样可在本插件中免费增加。
• 有问题或需求时，可加我QQ：370293265 ，一起探讨解决。
• 添加QQ时， 请备注 uni插件咨询 。