80 wlan-WiFi网络控制

作者：魏健强　|　最后修改：2026-10-27

一、概述

wifi 操作：主要介绍模组支持的 wifi 相关功能(对于仅支持 wifiscan 的模块, 仅 init/scan/scanResult 函数是可用的。例如: Air780EXXX 等仅支持 wifiscan)。

AP 应用：AP 是 Access Point 的缩写，即无线接入点，它是一个无线网络的中心节点，可以看成是一个服务器。它作为一个网络的中心节点，提供无线接入服务，其他的无线设备允许接入该节点，所有接入该节点设备的无线信号数据都要通过它才能进行交换和互相访问。一般的无线路由器、网关、热点就是工作在 AP 模式下，AP 节点和 AP 节点之间允许相互连接；

STA 应用：STA 是 Station 的缩写，它是无线网络中的一个终端站点设备，可以看成是一个客户端，一般来说，处在 STA 模式下的设备本身不接受无线的接入，该设备连接到 AP 节点进行网络访问，STA 模式下的设备之间的通信可以通过 AP 进行转发实现；

扫描应用：WiFiSCAN 是指通过无线设备（如智能手机、路由器、物联网设备等）主动扫描周围可用的 WiFi 网络，以获取其基本信息（如 SSID、信号强度、加密方式、频段等）的过程。它是无线通信领域中一项基础且重要的功能，广泛应用于网络配置、设备连接、信号优化及安全检测等场景；

手机可以安装cellular_z软件查看附近wifi信息:

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库中各个产品目录下的 demo/wlan；

-- 初始化wlan
wlan.init()
-- 设置wifi模式，支持同时使用AP和STA功能
wlan.setMode(wlan.STATIONAP)
-- 连接wifi
wlan.connect("test", "HZ88888888")
-- 开启ap热点
wlan.createAP("test2", "HZ88888888")
-- 设置ap网卡的ip子网掩码和网关
netdrv.ipv4(socket.LWIP_AP, "192.168.4.1", "255.255.255.0", "0.0.0.0")
-- wifi扫描成功后, 会有WLAN_SCAN_DONE消息, 读取即可
local function scan_cb()
    local results = wlan.scanResult()
    log.info("scan", "results", #results)
    for k,v in pairs(results) do
        log.info("scan", v["ssid"], v["rssi"], (v["bssid"]:toHex()))
    end
end
sys.subscribe("WLAN_SCAN_DONE", scan_cb)

-- 开启wifi扫描
local function start_scan()
    wlan.init()
    while true do
        wlan.scan()
        sys.wait(15000) -- 注意, 尤其是Air780系列, 这个时间只能更长不能短
    end
end
sys.taskInit(start_scan)

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 wlan.NONE

常量含义：WLAN 功能停用（关掉 WiFi 收发），对应源码里的 LUAT_WLAN_MODE_NULL；
          一般用于需要彻底关闭 WiFi 省电的场景，关闭后再用 wlan.setMode(wlan.STATION) 重新开启；
数据类型：number；
示例代码: wlan.setMode(wlan.NONE)；
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.2 wlan.AIRKISS

常量含义：AIRKISS配网(仅Air8101支持)；
数据类型：number；
示例代码: wlan.smartconfig(wlan.AIRKISS)；

3.3 wlan.AP

常量含义：AP模式；
数据类型：number；
示例代码: wlan.setMode(wlan.AP)；

3.4 wlan.STATION

常量含义：STA模式；
数据类型：number；
示例代码: wlan.setMode(wlan.STATION)；

3.5 wlan.STATIONAP

常量含义：AP和STA同时使用；
数据类型：number；
示例代码: wlan.setMode(wlan.STATIONAP)；

3.6 wlan.STOP

常量含义：停止配网，对应源码里的 LUAT_SC_TYPE_STOP；
          配网成功或者用户主动取消配网时，用它传给 wlan.smartconfig() 结束配网流程；
数据类型：number；
示例代码: wlan.smartconfig(wlan.STOP)；
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.7 wlan.ESPTOUCH

常量含义：ESP-TOUCH 配网（V1 版本）；
数据类型：number；
示例代码: wlan.smartconfig(wlan.ESPTOUCH)；
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.8 wlan.ESPTOUCH_AIRKISS

常量含义：ESP-TOUCH 和 AIRKISS 混合配网，两种手机 App 都能配；
          不知道用户手里装的是哪家的配网 App 时用这个模式最稳妥；
数据类型：number；
示例代码: wlan.smartconfig(wlan.ESPTOUCH_AIRKISS)；
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.9 wlan.ESPTOUCH_V2

常量含义：ESP-TOUCH 配网（V2 版本）；
          源码注释明确写着“未测试”，量产项目不要优先选它，建议用 V1 或混合模式；
数据类型：number；
示例代码: wlan.smartconfig(wlan.ESPTOUCH_V2)；
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.10 wlan.PS_NONE

常量含义：关闭省电模式，WiFi 一直保持唤醒，功耗最高、响应最快；
          取值为 0，作为 wlan.powerSave(mode) 的入参使用；
数据类型：number；
示例代码:
          -- 设置省电模式为“关闭”
          wlan.powerSave(wlan.PS_NONE)
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.11 wlan.PS_MIN_MODEM

常量含义：最小 Modem 省电模式，功耗与响应速度的折中；
          取值为 1，作为 wlan.powerSave(mode) 的入参使用；
数据类型：number；
示例代码:
          wlan.powerSave(wlan.PS_MIN_MODEM)
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.12 wlan.PS_MAX_MODEM

常量含义：最大 Modem 省电模式，省电效果最好，但唤醒延迟最大、吞吐最低；
          取值为 2，作为 wlan.powerSave(mode) 的入参使用；
数据类型：number；
示例代码:
          wlan.powerSave(wlan.PS_MAX_MODEM)
适用产品型号：Air8101、Air6201 等带 WiFi 能力的平台；

3.13 相关系统消息在代码中通过sys.subscribe("消息名称", 回调函数)订阅使用或sys.waitUntil("消息名称")阻塞等待对应消息

3.13.1 "WLAN_AP_INC"

发布条件: 其他设备连接模块ap热点或断开时发布
示例代码:
local function ap_event(evt, data)
    -- evt 可能的值有: "CONNECTED", "DISCONNECTED"
    -- 当evt=CONNECTED, data是连接的AP的新STA的MAC地址
    -- 当evt=DISCONNECTED, data是断开与AP连接的STA的MAC地址
    log.info("收到AP事件", evt, data and data:toHex())
end
sys.subscribe("WLAN_AP_INC", ap_event)

3.13.2 "WLAN_STA_INC"

发布条件: 模块连接wifi或断开wifi时发布
示例代码:
local function sta_event(evt, data)
    -- evt 可能的值有: "CONNECTED", "DISCONNECTED"
    -- 当evt=CONNECTED, data是连接的AP的ssid, 字符串类型
    -- 当evt=DISCONNECTED, data断开的原因, 整数类型:260是dhcp超时,259是程序主动断开,258是密码错误,257是找不到对应ssid(wifi名称),256是信号丢失
    log.info("收到STA事件", evt, data)
end
sys.subscribe("WLAN_STA_INC", sta_event)

3.13.3 "WLAN_SCAN_DONE"

发布条件: wifi扫描结束时发布
示例代码:
function scan_done_handle()
    local result = wlan.scanResult()
    for k, v in pairs(result) do
        log.info("scan", (v["ssid"] and #v["ssid"] > 0) and v["ssid"] or "[隐藏SSID]", v["rssi"], (v["bssid"]:toHex()))
        if v["ssid"] and #v["ssid"] > 0 then
            table.insert(scan_result, v["ssid"])
        end
    end
    log.info("scan", "aplist", json.encode(scan_result))
end
sys.subscribe("WLAN_SCAN_DONE", scan_done_handle)

四、函数详解

4.1 wlan.init()

功能

初始化 wlan；

参数

无

返回值

local res = wlan.init()

res

含义说明：初始化wlan的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = wlan.init()

log.info("wlan", res) --预期打印 I/user.wlan true

4.2 wlan.setMode(mode)

功能

设置 wifi 模式、单 STA、单 AP、STATIONAP（混合模式）；

参数

mode

参数含义：wifi模式；
数据类型：number；
取值范围：wlan.AP/wlan.STATION/wlan.STATIONAP；
是否必选：是；
注意事项：参考第三节常量详解；
参数示例：wlan.setMode(wlan.STATIONAP)；

返回值

local res = wlan.setMode(mode)

res

含义说明：设置wifi模式的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = wlan.setMode(mode)
log.info("wlan", res) --预期打印 I/user.wlan true

4.3 wlan.ready()

功能

作为 STATION 时,是否已经连接上 AP,且获取 IP 成功；

参数

无

返回值

local res = wlan.ready()

log.info("wlan", res)

res

含义说明：连接wifi的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

log.info("wlan", wlan.ready()) --预期打印 连接成功前I/user.wlan false,连接成功后I/user.wlan true

4.4 wlan.connect(ssid, password, auto_reconnect, bssid)

功能

作为 STATION 时,连接到指定 wifi；

参数

ssid

参数含义：wifi名称；
数据类型：string；
取值范围：支持中英文和特殊字符，长度32字节内；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.connect("myap", "12345678")
         wlan.connect("茶室-降功耗,找合宙!", "Air123456")
         wlan.connect("合宙-test!", "Air123456")

password

参数含义：wifi密码；
数据类型：string；
取值范围：长度限制64以内；
是否必选：可选；
注意事项：暂无；
参数示例：wlan.connect("myap", "1234567890")

auto_reconnect

参数含义：是否自动重连；
数据类型：number；
取值范围：0/1；
是否必选：可选,默认开启；
注意事项：0关闭自动重连,1开启自动重连,当前强制开启自动重连,配置为0，实际上也是自动重连；
参数示例：wlan.connect("myap", "12345678", 1)

bssid

参数含义：mac地址；
数据类型：string；
取值范围：暂无；
是否必选：可选；
注意事项：接入点（AP）或无线路由器的MAC地址（或虚拟MAC地址）,一般用于区分同名Wi-Fi；
参数示例：local bssid = string.fromHex("00182946365f")
         wlan.connect("myap", "12345678", 1, bssid)

返回值

local res = wlan.connect(ssid, password)

res

含义说明：发起连接的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表发起成功,不代表连接AP成功!!，false代表失败；
返回示例：true；

示例

local res = wlan.connect(ssid, password)

log.info("wlan", res) --预期打印 I/user.wlan true

4.5 wlan.disconnect()

功能

作为 STATION 时,断开 wifi 连接。主动断开连接后不会再自动重连，wlan.connect 重新连接后自动重连生效。

参数

无

返回值

无

示例

wlan.disconnect()

4.6 wlan.scan()

功能

扫描附近 wifi 信息；

参数

无

返回值

无

示例

-- 注意, wlan.scan()是异步API,启动扫描后会马上返回
-- wifi扫描成功后, 会有WLAN_SCAN_DONE消息, 读取即可
local function scan_cb()
    local results = wlan.scanResult()
    log.info("scan", "results", #results) --预期打印 I/user.scan results xxx
    for k,v in pairs(results) do
        log.info("scan", v["ssid"], v["rssi"], (v["bssid"]:toHex())) --预期打印 I/user.scan test -63 XXXXXXXXXXXX
    end
end
sys.subscribe("WLAN_SCAN_DONE", scan_cb)

-- 开启wifi扫描
local function start_scan()
    wlan.init()
    while true do
        wlan.scan()
        sys.wait(15000) -- 注意, 尤其是Air780系列, 这个时间只能更长不能短
    end
end
sys.taskInit(start_scan)

4.7 wlan.scanResult()

功能

获取 wifi 扫描结果（异步）；

参数

无

返回值

local results = wlan.scanResult()

log.info("scan", "results", #results)

for k,v in pairs(results) do

log.info("scan", v["ssid"], v["rssi"], (v["bssid"]:toHex()))

end

results

含义说明：存储wifi信息的table，包含有一个或者多个这样的子table；
        {{
         含义说明：wifi名称；
         数据类型：string；
         取值范围：无；
         注意事项：无；
         返回示例："test"；
         ssid

         含义说明：信号强度(大于-60为信号强,-60至-80为信号中等,小于-80为信号差)；
         数据类型：number；
         取值范围：无；
         注意事项：无；
         返回示例：-69；
         rssi

         含义说明：mac地址；
         数据类型：string；
         取值范围：无；
         注意事项：无；
         返回示例：0xF01122334455。hex字符串，直接打印的话会是乱码，需要tohex()；
         bssid
        }}

数据类型：table；
取值范围：无；
注意事项：无；
返回示例：无；

示例

-- 注意, wlan.scan()是异步API,启动扫描后会马上返回

-- wifi扫描成功后, 会有WLAN_SCAN_DONE消息, 读取即可
sys.subscribe("WLAN_SCAN_DONE", function ()
    local results = wlan.scanResult()
    log.info("scan", "results", #results) --预期打印 I/user.scan results xxx
    for k,v in pairs(results) do
        log.info("scan", v["ssid"], v["rssi"], (v["bssid"]:toHex())) --预期打印 I/user.scan test -63 XXXXXXXXXXXX
    end
end)

-- 下面演示的是初始化wifi后定时扫描,请按实际业务需求修改
sys.taskInit(function()
    sys.wait(1000)
    wlan.init()
    while true do
        wlan.scan()
        sys.wait(15000)
    end
end)

4.8 wlan.smartconfig(mode)

功能

开启配网功能(仅Air8101支持AIRKISS配网)；

参数

mode

参数含义：配网方式；
数据类型：number；
取值范围：wlan.AIRKISS；
是否必选：必选；
注意事项：详见第三部分常量说明；
参数示例：wlan.smartconfig(wlan.AIRKISS)；

返回值

local res = wlan.smartconfig(mode)

res

含义说明：发起配网的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表发起成功，false代表失败；
返回示例：true；

示例

local res = wlan.smartconfig(mode)

log.info("wlan", res) --预期打印 I/user.wlan true

4.9 wlan.getMac(mode, hexstr)

功能

获取 mac；

参数

mode

参数含义：获取什么类型的mac,AP填1或STA填0；
数据类型：number；
取值范围：0/1；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.getMac(0)；

hexstr

参数含义：是否转HEX字符, 默认是true,即输出hex字符串；
数据类型：boolean；
取值范围：true/false；
是否必选：可选；
注意事项：无；
参数示例：wlan.getMac(0,true)

返回值

local mac = wlan.getMac()

log.info("wlan", mac)

mac

含义说明：mac地址；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例："F01122334455"；

示例

local mac = wlan.getMac(0)
log.info("wlan", mac) --预期打印 I/user.wlan C812345678CD
local mac = wlan.getMac(1)
log.info("wlan", mac) --预期打印 I/user.wlan C812345678CC

4.10 wlan.setMac(mode, mac)

功能

仅支持设置sta的mac,mac必须是偶数结尾，然后ap是sta的mac+1，如果是奇数结尾，那么ap就是-1；

参数

mode

参数含义：仅支持设置STA的mac,mac必须是偶数结尾，然后ap是sta的mac+1，
如果是奇数结尾，那么ap就是-1；
数据类型：number；
取值范围：0；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.setMac(0, (string.fromHex("C81234567890")))；

mac

参数含义：mac地址；
数据类型：string；
取值范围：无；
是否必选：必选；
注意事项：无；
参数示例：wlan.setMac(0, (string.fromHex("C81234567890")))

返回值

local res = setMac(mode, mac)

res

含义说明：设置的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = setMac(mode, mac)

log.info("wlan", res)  --预期打印 I/user.wlan true

4.11 wlan.getIP()

功能

获取做为 station 使用时的 ip,仅 STATION 或 APSTA 模式下有意义；

参数

无

返回值

local ipv4 = wlan.getIP()

ipv4

含义说明：ip地址；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例： "192.168.1.25"；

示例

local ipv4 = wlan.getIP()

log.info("wlan", ipv4) --预期打印 I/user.wlan XXX.XXX.XXX.XXX

4.12 wlan.createAP(ssid, passwd, gateway, netmask, channel, opts)

功能

开启 AP 热点；

参数

ssid

参数含义：AP热点名称；
数据类型：string；
取值范围：暂无；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.createAP("luatos1234")

password

参数含义：AP热点密码，无需密码时可以不填写当前参数；
数据类型：string；
取值范围：暂无；
是否必选：可选；
注意事项：暂无；
参数示例：wlan.createAP("luatos1234", "12341234")

gateway

参数含义：网关；
数据类型：string；
取值范围：0/1；
是否必选：可选；
注意事项：无；
参数示例：wlan.createAP("luatos1234", "12341234", "192.168.4.1")

netmask

参数含义：网关掩码；
数据类型：string；
取值范围：暂无；
是否必选：可选；
注意事项：无；
参数示例：wlan.createAP("luatos1234", "12341234", "192.168.4.1")

channel

参数含义：AP建立的通道；
数据类型：number；
取值范围：1-13；
是否必选：可选；
注意事项：默认值为6；
参数示例：wlan.createAP("luatos1234", "12341234", "192.168.4.1", "255.255.255.0", 6)

opts

参数含义：配置项；
{
-- 参数含义：AP是否隐藏SSID, 默认false,不隐藏；
-- 数据类型：boolean；
-- 取值范围：true/false；
-- 是否必选：可选；
-- 注意事项：暂无；
-- 参数示例：
参数名称： opts.hidden

-- 参数含义：AP最大客户端数量；
-- 数据类型：number；
-- 取值范围：1-4；
-- 是否必选：可选；
-- 注意事项：暂无；
-- 参数示例:
参数名称： opts.max_conn
}

数据类型：table；
取值范围：暂无；
是否必选：可选；
注意事项：无；
参数示例：wlan.createAP("luatos1234", "12341234", "192.168.4.1", "255.255.255.0", 6 ，{ hidden = false, max_conn = 4 })

返回值

local res = wlan.createAP(ssid, passwd, gateway, netmask, channel, opts)

res

含义说明：开启的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = wlan.createAP(ssid, passwd, gateway, netmask, channel, opts)

log.info("wlan", res) --预期打印 I/user.wlan true

4.13 wlan.stopAP()

功能

关闭 AP 热点；

参数

无

返回值

local res = wlan.stopAP()

res

含义说明：关闭的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = wlan.stopAP()

log.info("wlan", res) --预期打印 I/user.wlan true

4.14 wlan.getInfo()

功能

获取 wifi 热点的信息，连接 wifi 热点后获取；

参数

无

返回值

local res = wlan.getInfo()

res

含义说明：wifi信息；
         {
         含义说明：网关；
         数据类型：string；
         取值范围：无；
         注意事项：无；
         返回示例："192.168.1.1"；
         gw

         含义说明：信号强度(大于-60为信号强,-60至-80为信号中等,小于-80为信号差)；
         数据类型：number；
         取值范围：无；
         注意事项：无；
         返回示例：-69；
         rssi

         含义说明：mac地址；
         数据类型：string；
         取值范围：无；
         注意事项：无；
         返回示例："F01122334455"；
         bssid
        }
数据类型：table；
取值范围：无；
注意事项：连接wifi后获取；
返回示例：{
             bssid = "F01122334455",
             rssi  = -69,
             gw    = "192.168.1.1"
         }；

示例

log.info("wlan", "info", json.encode(wlan.getInfo())) --预期打印 I/user.wlan info {"gw":"XXX.XXX.XXX.XXX","rssi":-77,"bssid":"XXXXXXXXXXXX"}

4.15 wlan.hostname(id, new_name)

功能

读取或设置 Hostname；

不填写 new_name 参数时是读取；

参数

id

参数含义：STA填0, AP填1；
数据类型：number；
取值范围：0/1；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.hostname(1, "myhost")；

new_name

参数含义：新的hostname,可选, 传入就是设置，不传是读取；
数据类型：string；
取值范围：无；
是否必选：可选；
注意事项：无；
参数示例：wlan.hostname(1, "myhost")

返回值

local hostname = wlan.hostname(id)

hostname

含义说明：名字；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例："myhost"；

示例

wlan.hostname(1, "myhost") --设置AP的hostname
local hostname = wlan.hostname(id)

log.info("wlan", hostname) --预期打印  I/user.wlan XXX

4.16 wlan.staIp(dhcp_enable, ip, netmask, gateway)

功能

设置 Station 模式下的 IP 获取模式(dhcp 或静态 ip)；

参数

dhcp_enable

参数含义：是否使用dhcp；
数据类型：boolean；
取值范围：true/false；
是否必选：必选；
注意事项：无；
参数示例：wlan.staIp(true)；

addr

参数含义：静态ip地址；
数据类型：string；
取值范围：暂无；
是否必选：可选，如果是dhcp就不需要传此参数；
注意事项：需要填写正确的ipv4地址；
参数示例：wlan.staIp(false, "192.168.2.200", "255.255.255.0", "192.168.2.1")；

mark

参数含义：子网掩码；
数据类型：string；
取值范围：暂无；
是否必选：可选，如果是dhcp就不需要传此参数；
注意事项：需要填写正确的掩码；
参数示例：wlan.staIp(false, "192.168.2.200", "255.255.255.0", "192.168.2.1")；

gw

参数含义：网关；
数据类型：string；
取值范围：暂无；
是否必选：可选，如果是dhcp就不需要传此参数；
注意事项：需要填写正确的ipv4网关；
参数示例：wlan.staIp(false, "192.168.2.200", "255.255.255.0", "192.168.2.1")；

返回值

local res = wlan.staIp(dhcp_enable, ip, netmask, gateway)

res

含义说明：设置的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；

示例

local res = wlan.staIp(dhcp_enable, ip, netmask, gateway)

log.info("wlan", res) --预期打印  I/user.wlan true

4.17 wlan.powerSave(mode)

功能

读取或设置 WiFi 的省电模式。

参数

mode

参数含义：省电模式，可选；
          不传该参数时本接口只做“读取”，不做任何设置；
数据类型：number；
取值范围：wlan.PS_NONE（0，关闭省电）、wlan.PS_MIN_MODEM（1，最小 Modem 省电）、
          wlan.PS_MAX_MODEM（2，最大 Modem 省电）；
是否必选：可选，省略时为纯读取；
注意事项：传参即设置，不传即读取，两种用法共用同一个接口；
参数示例：wlan.PS_NONE，wlan.PS_MIN_MODEM，wlan.PS_MAX_MODEM；

返回值

local mode = wlan.powerSave(mode)

mode

含义说明：当前生效的省电模式；传参时返回的是设置之后重新读到的值，不是设置前的值；
数据类型：number；
取值范围：0/1/2，分别对应 wlan.PS_NONE / wlan.PS_MIN_MODEM / wlan.PS_MAX_MODEM；

示例

-- 设置为最小 Modem 省电，并打印实际生效的值
local mode = wlan.powerSave(wlan.PS_MIN_MODEM)
log.info("wlan", "省电模式", mode)

-- 只读取当前省电模式
local cur = wlan.powerSave()
log.info("wlan", "当前省电模式", cur)

注意事项

这个接口是“读写合一”：传了参数就设置，然后无论是否设置都会把当前值返回，所以不要拿它的返回值去判断“设置是否成功”；
省电模式与时延、吞吐直接相关：wlan.PS_MAX_MODEM 最省电但响应最慢，做实时性要求高的应用（如 TCP 长连接心跳、语音）建议用 wlan.PS_NONE；
源码里该函数没有任何 @api 注释，属于长期未写进文档的接口，这里按实际实现补全。

4.18 wlan.mode(mode)

功能

设置 WLAN 工作模式。功能与 wlan.setMode(mode) 相同，是同一套底层配置的另一个入口。

参数

mode
参数含义：WLAN 工作模式；
数据类型：number；
取值范围：wlan.NONE / wlan.STATION / wlan.AP / wlan.STATIONAP；
是否必选：可选，不传时按 STATION 处理；
注意事项：
        1. 传了非法值（小于等于 wlan.NONE 或不存在的值）会被强制改成 wlan.STATION；
        2. 兼容老写法时也接受把模式放在第二个参数；
参数示例：wlan.STATIONAP

返回值

无返回值（nil）。

示例

-- 与 wlan.setMode(wlan.STATIONAP) 等价
wlan.mode(wlan.STATIONAP)

注意事项

新代码统一用 wlan.setMode，这个别名只为兼容早期脚本保留；
模式要在 wlan.init() 之后、wlan.connect() 之前设置好。

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 wlan 核心库。

80 wlan-WiFi网络控制

一、概述

二、核心示例

三、常量详解

3.1 wlan.NONE

3.2 wlan.AIRKISS

3.3 wlan.AP

3.4 wlan.STATION

3.5 wlan.STATIONAP

3.6 wlan.STOP

3.7 wlan.ESPTOUCH

3.8 wlan.ESPTOUCH_AIRKISS

3.9 wlan.ESPTOUCH_V2

3.10 wlan.PS_NONE

3.11 wlan.PS_MIN_MODEM

3.12 wlan.PS_MAX_MODEM

3.13 相关系统消息 在代码中通过sys.subscribe("消息名称", 回调函数)订阅使用或sys.waitUntil("消息名称")阻塞等待对应消息

3.13.1 "WLAN_AP_INC"

3.13.2 "WLAN_STA_INC"

3.13.3 "WLAN_SCAN_DONE"

四、函数详解

4.1 wlan.init()

4.2 wlan.setMode(mode)

4.3 wlan.ready()

4.4 wlan.connect(ssid, password, auto_reconnect, bssid)

4.5 wlan.disconnect()

4.6 wlan.scan()

4.7 wlan.scanResult()

4.8 wlan.smartconfig(mode)

4.9 wlan.getMac(mode, hexstr)

4.10 wlan.setMac(mode, mac)

4.11 wlan.getIP()

4.12 wlan.createAP(ssid, passwd, gateway, netmask, channel, opts)

4.13 wlan.stopAP()

4.14 wlan.getInfo()

4.15 wlan.hostname(id, new_name)

4.16 wlan.staIp(dhcp_enable, ip, netmask, gateway)

4.17 wlan.powerSave(mode)

4.18 wlan.mode(mode)

五、产品支持说明

3.13 相关系统消息在代码中通过sys.subscribe("消息名称", 回调函数)订阅使用或sys.waitUntil("消息名称")阻塞等待对应消息