WiFi

目前柿饼模组支持使用JS连接 WiFi ,简单几步即可实现联网的功能。本文档介绍 WiFi 相关的API并提供一键联网的实例代码。

注:因为 WiFi 属于硬件设备,因此在使用 WiFi 对象时,设计器的模拟器是无法获取到硬件板载的 WiFi 设备的,也就无法使用模拟器进行仿真操作 WiFi 设备。同样的道理,类似于 AudioPlayer、 videoPlayer、uart 等 API 接口,都是与硬件交互紧密相联的,同样不能使用模拟器仿真操作。

WiFi()

获取 WiFi 对象。

var wifi = pm.createWifi();  // WiFi 对象实例化

scan()

扫描获取周围的 WiFi 热点信息。扫描操作成功返回值为 true,否则为 false

注:扫描操作返回值为 true 代表 wifi.scan() 函数的调用执行成功,属于同步返回结果。而扫描操作的执行过程是需要 WiFi 设备阻塞式的等待扫描并返回其结果,属于异步返回,因此真正扫描成功的标志是扫描回调函数 onScanEvent 的返回值为 true

//该例子也可简写为wifi.scan(), 然后扫描成功的标志依据回调函数 onScanEvent 进行判断。
if (wifi.scan()) {
    console.log("scan WiFi success");
} else {
    console.log("scan wifi fail");
}

onScanEvent(func)

监听扫描 WiFi 结束事件,并配置事件回调函数。该函数用于 wifi.scan() 执行成功后的消息回调,回调函数 func 内包含了 WiFi 扫描到的热点信息。

参数说明:

参数 类型 必填 说明
func function 当扫描周围 WiFi 信息结束后,将执行回调函数

事件回调函数 func 的入参说明:当扫描到的 WiFi 设备信息存放到 Array 对象内,如果没有扫描到则为 null

Array 数组中单个对象属性说明:

属性 类型 说明
ssid string WiFi 设备的SSID
bssid string WiFi 设备的BSSID
strength number WiFi 设备的信号强度
secure bool WiFi 设备是否有安全性(加密)
wifi.onScanEvent(function (res) {
    if (res) {
        console.log("WiFi scanned success.");
        for (var i = 0; i < res.length; i++) {
            var item = res[i];
            console.log("ssid : " + item.ssid);
            console.log("bssid : " + item.bssid);
            console.log("strength " + item.strength);
            console.log("secure " + item.secure);
        }
    } else {
        console.log("WiFi cannot be scanned.");
    }
}

connect(object)

连接指定的 WiFi 网络。连接操作成功返回值为 true,否则为 false

注:连接操作返回值为 true 代表 wifi.connect() 函数的调用执行成功,属于同步返回结果,而连接操作的执行过程是需要WiFi设备阻塞式的请求连接并等待连接返回的结果,属于异步返回。因此真正连接成功的标志是连接回调函数 onConnectEvent 的返回值为 true

object 参数属性说明。

属性 类型 必填 说明
ssid string 指定 WiFi 设备的SSID
bssid string 指定 WiFi 设备的BSSID
password string 指定 WiFi 设备的密码
/* 该例子也可以写为如下代码段, 然后连接成功的标志依据回调函数 onConnectEvent 进行判断。
wifi.connect({ ssid: "aptest", bssid: "c0:3d:46:00:43:0a",password: "123456789"}
*/
if (wifi.connect({
    ssid: "aptest",
    bssid: "c0:3d:46:00:43:0a",
    password: "123456789"
})) {
    console.log("connect success")
} else {
    console.log("connect fail")
}

onConnectEvent(func)

监听连接 WiFi 事件,并配置事件回调函数。

参数 类型 必填 说明
func function 当连接 Wifi 结束后,将执行回调函数

事件回调函数入参说明

连接到的 Wifi 设备信息为 object,如果连接失败则为 null

object 属性说明

属性 类型 说明
ssid string wifi 设备的SSID
bssid string wifi 设备的BSSID
strength number wifi 设备的信号强度
secure bool wifi 设备的是否安全
wifi.onConnectEvent(function(res) {
    if (res) {
        console.log("wifi is connected");
        console.dir(res);
    } else {
        console.log("wifi is connected fail");
    }
});

onNetworkEvent(func)

监听网络连接事件,并配置事件回调函数。网络连接成功返回值为 true,否则为 false

注:当 onConnectEvent 返回为 true 时,意味着只是 WiFi 连接成功,此时设备还需等待连接 Network, 该连接网络的过程是自动完成的,当网络连接回调函数 onNetworkEvent 返回为 true,此时才代表网络连接成功,并且也能够获取到分配的IP地址了。

回调函数说明:

属性 类型 说明
func function 当网络连接状态变化时将执行回调函数
wifi.onNetworkEvent(function(res) {
    if (res)
        console.log("Network is connected");
    else
        console.log("Network is connected fail");
});

disconnect()

断开WiFi连接。断开操作成功返回值为 true,否则为 false

if (wifi.disconnect()) {
    console.log("disconnect success")
} else {
    console.log("disconnect fail")
}

getConnected()

获取已连接 WiFi 信息。获取操作成功返回值为 object,否则为 null

返回值 object 属性说明:

属性 类型 必填
ssid string WiFi 设备的SSID
bssid string wifi 设备的BSSID
strength number wifi 设备的信号强度
secure bool wifi 设备的是否安全(加密)
//此处需要先连接WiFi再进行获取。
var res = wifi.getConnected();
if (res) {
    console.log("getConnected success")
    console.log(res);
} else {
    console.log("getConnected fail")
}

destroy()

销毁 WiFi 对象。

wifi.destroy();

调用流程

  1. 实例化 WiFi 对象 pm.createWifi()
  2. 扫描 WiFi 热点信息 scan() (如果直接连接特定 WiFi ,则可以不用扫描,此步骤可省略)。
  3. 连接 WiFi 热点 connect() 连接特定网络。
  4. 监听连接事件,回调 onConnectEvent 判断连接结果。
  5. 监听 WiFi 连接网络,回调 onNetworkEvent 判断连接结果,当返回为 true,则连接网络成功。

实例代码

实例代码一:完整调用过程,每一步的调用过程都进行返回值判断

/*
该实例为一键联网的简单demo:
新建一个 button,绑定回调为 onbtn, 当点击button时,扫描 WiFi 热点信息,并连接特定的网络。
*/
var page = {

    wifi: 0,
    /* 此方法在第一次显示窗体前发生 */
    onLoad: function (event) {
        wifi = pm.createWifi();

        wifi.onNetworkEvent(function (res) {
            if (res) {//此时意味着wifi成功连接到网络
                console.log("Network is connected");
                console.log(wifi.getConnected()); //获取连接的wifi信息
            } else
                console.log("Network is connected fail");
        });

        wifi.onConnectEvent(function (res) {
            if (res) {
                // 此处代表wifi连接成功,然后wifi会自动连接网络,真正连接到网络会在onNetworkEvent函数内返回结果
                console.log("wifi connect success by Callback ");
                console.log(res); // 打印连接到的wifi的信息值
            } else {
                console.log("wifi is connected fail by Callback ");
            }
        });
    },

    /* 此方法展示窗体前发生 */
    onShow: function (event) {
        wifi.onScanEvent(function (res) {
            if (res) {
                //打印出扫描的 WiFi 信息
                for (var i = 0; i < res.length; i++) 
                {
                    var item = res[i];
                    console.log("ssid : " + item.ssid);
                    console.log("bssid : " + item.bssid);
                    console.log("strength " + item.strength);
                    console.log("secure " + item.secure);
                }
                if (wifi.connect({ssid: "realthread",password: "02158995663"})) {
                    //此处代表wifi.connect调用成功,然后等待wifi连接,真正的wifi连接成功会在                             onConnectEvent函数内返回结果
                    console.log("wifi.connect success")
                } else {
                    console.log("wifi.connect failed")
                }
            } else {
                console.log("WiFi cannot be scanned.");
            }
        });
    },

    /* 此方法展示窗体后发生 */
    onResume: function (event) {

    },

    /* 此方法关闭窗体前发生 */
    onExit: function (event) {

    },

    /* 点击 button,调用 wifi.scan() 进行扫描 */
    onbtn: function (event) {
        if (wifi.scan()) {
            console.log("scan WiFi success");
        } else {
            console.log("scan wifi fail");
        }
    },
};

Page(page);

page = 0;

实例代码二:简写执行流程,仅通过回调进行判断。

/*
该实例为一键联网的简单demo:
新建一个 button,绑定回调为 onbtn, 当点击button时,扫描 WiFi 热点信息,并连接特定的网络。
*/
var page = {

    wifi: 0,
    /* 此方法在第一次显示窗体前发生 */
    onLoad: function (event) {
        wifi = pm.createWifi();

        wifi.onNetworkEvent(function (res) {
            if (res) {
                console.log("Network is connected");    //此时意味着wifi成功连接到网络
                console.log(wifi.getConnected());       //获取连接的wifi信息
            } else
                console.log("Network is connected fail");
        });
    },

    /* 此方法展示窗体前发生 */
    onShow: function (event) {
        wifi.onScanEvent(function (res) {
            if (res) {
                wifi.connect({ssid: "realthread",password: "02158995663"})
            } else {
                console.log("WiFi cannot be scanned.");
            }
        });
    },

    /* 此方法展示窗体后发生 */
    onResume: function (event) {

    },

    /* 此方法关闭窗体前发生 */
    onExit: function (event) {

    },

    /* 点击 button,调用 wifi.scan() 进行扫描 */
    onbtn: function (event) {
        wifi.scan();
    },
};

Page(page);

page = 0;