69 wlan-WiFi网络控制

作者：魏健强　|　最后修改：2026-06-08

一、概述

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.AIRKISS

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

3.2 wlan.AP

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

3.3 wlan.STATION

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

3.4 wlan.STATIONAP

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

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

3.5.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.5.1 "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.5.1 "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

```lua
参数含义：是否使用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

五、产品支持说明

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

69 wlan-WiFi网络控制

一、概述

二、核心示例

三、常量详解

3.1 wlan.AIRKISS

3.2 wlan.AP

3.3 wlan.STATION

3.4 wlan.STATIONAP

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

3.5.1 "WLAN_AP_INC"

3.5.1 "WLAN_STA_INC"

3.5.1 "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)

五、产品支持说明

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