WLAN - wifi 操作
作者：魏健强
一、概述
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、信号强度、加密方式、频段等）的过程。它是无线通信领域中一项基础且重要的功能，广泛应用于网络配置、设备连接、信号优化及安全检测等场景；
二、核心示例
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 1 do
wlan.scan()
sys.wait(15000) -- 注意, 尤其是Air780系列, 这个时间只能更长不能短
end
end
sys.taskInit(start_scan)
三、常量详解
核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；
如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；
3.1 wlan.ESPTOUCH
常量含义：ESPTOUCH配网；
数据类型：number；
常量取值：1；
示例代码: wlan.smartconfig(wlan.ESPTOUCH)；
3.2 wlan.AIRKISS
常量含义：AIRKISS配网；
数据类型：number；
常量取值：2；
示例代码: wlan.smartconfig(wlan.AIRKISS)；
3.3 wlan.ESPTOUCH_V2
常量含义：ESPTOUCH_V2配网；
数据类型：number；
常量取值：4；
示例代码: wlan.smartconfig(wlan.ESPTOUCH_V2)；
3.4 wlan.AP
常量含义：AP模式；
数据类型：number；
常量取值：2；
示例代码: wlan.setMode(wlan.AP)；
3.5 wlan.STATION
常量含义：STA模式；
数据类型：number；
常量取值：1；
示例代码: wlan.setMode(wlan.STATION)；
3.6 wlan.STATIONAP
常量含义：AP和STA同时使用；
数据类型：number；
常量取值：3；
示例代码: wlan.setMode(wlan.STATIONAP)；
四、函数详解
4.1 wlan.init()
功能
初始化 wlan；
参数
无
返回值
local res = wlan.init()
log.info("wlan", res)
res
含义说明：初始化wlan的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.init()
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)
log.info("wlan", res)
res
含义说明：设置wifi模式的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.setMode(wlan.STATIONAP)
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())
4.4 wlan.connect(ssid, password, auto_reconnect, bssid)
功能
作为 STATION 时,连接到指定 wifi；
参数
ssid
参数含义：wifi名称；
数据类型：string；
取值范围：暂无；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.connect("myap", "12345678")
password
参数含义：wifi密码；
数据类型：string；
取值范围：暂无；
是否必选：可选；
注意事项：暂无；
参数示例：wlan.connect("myap", "12345678")
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)
log.info("wlan", res)
res
含义说明：发起连接的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表发起成功,不代表连接AP成功!!，false代表失败；
返回示例：true；
示例
wlan.connect("myap", "12345678")
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)
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 1 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
含义说明：信号强度；
数据类型：number；
取值范围：无；
注意事项：无；
返回示例：-89；
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)
for k,v in pairs(results) do
log.info("scan", v["ssid"], v["rssi"], (v["bssid"]:toHex()))
end
end)
-- 下面演示的是初始化wifi后定时扫描,请按实际业务需求修改
sys.taskInit(function()
sys.wait(1000)
wlan.init()
while 1 do
wlan.scan()
sys.wait(15000)
end
end)
4.8 wlan.smartconfig(mode)
功能
开启配网功能；
参数
mode
参数含义：配网方式；
数据类型：number；
取值范围：wlan.ESPTOUCH/wlan.AIRKISS/wlan.ESPTOUCH_V2；
是否必选：可选，默认esptouch；
注意事项：详见第三部分常量说明；
参数示例：wlan.smartconfig(wlan.AIRKISS)；
返回值
local res = wlan.smartconfig(mode)
log.info("wlan", res)
res
含义说明：发起配网的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表发起成功，false代表失败；
返回示例：true；
示例
wlan.smartconfig()
4.9 wlan.getMac(mode, hexstr)
功能
获取 mac；
参数
mode
参数含义：获取什么类型的mac,AP或STA；
数据类型：number；
取值范围：wlan.AP/wlan.STATION；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.getMac(wlan.STATION)；
hexstr
参数含义：是否转HEX字符, 默认是true,即输出hex字符串；
数据类型：boolean；
取值范围：true/false；
是否必选：可选；
注意事项：无；
参数示例：wlan.getMac(wlan.STATION,true)
返回值
local mac = wlan.getMac()
log.info("wlan", mac)
mac
含义说明：mac地址；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例："F01122334455"；
示例
wlan.getMac(wlan.STATION)
wlan.getMac(wlan.AP)
4.10 wlan.setMac(mode, mac)
功能
设置 mac；
参数
mode
参数含义：设置什么类型的mac,AP或STA；
数据类型：number；
取值范围：wlan.AP/wlan.STATION；
是否必选：必选；
注意事项：暂无；
参数示例：wlan.setMac(tp, mac)；
mac
参数含义：mac地址；
数据类型：string；
取值范围：无；
是否必选：必选；
注意事项：无；
参数示例：wlan.setMac(tp, mac)
返回值
local res = setMac(mode, mac)
log.info("wlan", res)
res
含义说明：设置的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.setMac(wlan.AP, (string.fromHex("C81234567890")))
4.11 wlan.getIP()
功能
获取做为 station 使用时的 ip,仅 STATION 或 APSTA 模式下有意义；
参数
无
返回值
local ipv4 = wlan.getIP()
log.info("wlan", ipv4)
ipv4
含义说明：ip地址；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例： "192.168.1.25"；
示例
wlan.getIP()
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；
-- 是否必选：可选；
-- 注意事项：暂无；
-- 参数示例：
hidden = false,
-- 参数含义：AP最大客户端数量；
-- 数据类型：number；
-- 取值范围：1-4；
-- 是否必选：可选；
-- 注意事项：暂无；
-- 参数示例:
max_conn = 4
}
数据类型：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)
log.info("wlan", res)
res
含义说明：开启的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.createAP("luatos1234", "12341234")
4.13 wlan.stopAP()
功能
关闭 AP 热点；
参数
无
返回值
local res = wlan.stopAP()
log.info("wlan", res)
res
含义说明：关闭的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.stopAP()
4.14 wlan.getInfo()
功能
获取 wifi 热点的信息，连接 wifi 热点后获取；
参数
无
返回值
local res = wlan.getInfo()
log.info("wlan", "info", json.encode(res))
res
含义说明：wifi信息；
数据类型：table；
取值范围：无；
注意事项：连接wifi后获取；
返回示例：{
bssid = "F01122334455",
rssi = -89,
gw = "192.168.1.1"
}；
示例
log.info("wlan", "info", json.encode(wlan.getInfo()))
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)
log.info("wlan", hostname)
hostname
含义说明：名字；
数据类型：string；
取值范围：无；
注意事项：无；
返回示例："myhost"；
示例
wlan.hostname(1, "myhost") --设置AP的hostname
wlan.hostname(0) -- 获取STA的hostname
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)
log.info("wlan", res)
res
含义说明：设置的结果；
数据类型：boolean；
取值范围：true/false；
注意事项：返回值为true代表成功，false代表失败；
返回示例：true；
示例
wlan.staIp(true)
五、产品支持说明
支持 LuatOS 开发的所有产品都支持 wlan 核心库。