模块: WiFi
约 6411 字大约 21 分钟
2024-05-03
构建固件和导入到JS
在 C++ 里加入以下代码, 然后重新编译构建固件：
// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::WiFi>() ;在JS中导入 wifi module：
import * as wifi from 'wifi'import wifi简介
WiFi 模块的例子请参考：用 JavaScript 连接 WiFi
系统在初次 import WiFi 模块时，会自动初始化所有相关的硬件资源。
模块函数
函数 start
原型: start ()
启动 WiFi 硬件
所有 WiFi 模块里的 API 都需要在 start() 之后才能调用。 startAP 和 connect 会自动调用 start()，因此一般情况下可以直接使用。
异常:
- WiFi 初始化失败
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 stop
原型: stop ()
停止 WiFi 硬件
返回 0 表示成功，非 0 表示错误代码
异常:
- WiFi 未初始化
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 isReady
原型: isReady ()
返回是否已经调用过 start() 启动 WiFi
返回值:
类型bool
说明返回 true 表示 WiFi 已启动，false 表示未启动
函数 startAP
原型: startAP (ssid:string, password:string)
启动 WiFi 热点
该函数会自动调用
start()启动 WiFi 模块。
异步返回 Promise<bool> 表示成功或者失败
示例：
import { startAP } from "wifi"
await startAP("MyAP", "password123")
console.log("AP started!")参数:
ssid
类型string
参数说明WiFi 热点名称
password
类型string
参数说明WiFi 热点密码
返回值:
类型Promise<bool>
函数 stopAP
原型: stopAP ()
停止 WiFi 热点
异步返回 Promise<bool> 表示成功或者失败
返回值:
类型Promise<bool>
函数 connect
原型: connect (ssid:string, password:string, retry:number=3, retryDuration:number=2000)
做为 WiFi STA 连接到热点
该函数会自动调用
start()启动 WiFi 模块。
异步返回 Promise<bool> 表示成功或者失败
示例：
import { connect, waitIP } from "wifi"
const connected = await connect("MyWiFi", "password123")
if (connected) {
const ipInfo = await waitIP()
console.log("Connected! IP:", ipInfo.ip)
}参数:
ssid
类型string
参数说明WiFi 热点名称
password
类型string
参数说明WiFi 热点密码
retry
类型number
默认值3
参数说明连接失败重试次数
retryDuration
类型number
默认值2000
参数说明连接重试间隔时间，单位 ms
返回值:
类型Promise<bool>
函数 disconnect
原型: disconnect ()
断开 WiFi STA 的连接
异步返回 Promise<bool> 表示成功或者失败
未连接状态下，直接返回 Promise<true>
返回值:
类型Promise<bool>
函数 isConnecting
原型: isConnecting ()
返回是否正在连接中
返回值:
类型bool
说明返回 true 表示正在连接中，false 表示未连接
函数 status
原型: status (type:string="apsta")
返回 AP/STA 详细状态
返回对象的格式：
{
"ap": {
"ssid": string,
"password": string,
"started": bool,
"ip":string,
"netmask":string,
"gw":string
} ,
"sta": {
"ssid": string,
"password": string,
"started": bool,
"connected": bool,
"authmode":number,
"ip":string,
"netmask":string,
"gw":string
} ,
}"ap": {
"ssid": string,
"password": string,
"started": bool,
"ip":string,
"netmask":string,
"gw":string
} ,"sta": {
"ssid": string,
"password": string,
"started": bool,
"connected": bool,
"authmode":number,
"ip":string,
"netmask":string,
"gw":string
} ,示例：
import { status } from "wifi"
const info = status("sta")
console.log("Connected:", info.sta.connected)
console.log("IP:", info.sta.ip)参数:
type
类型string
默认值"apsta"
参数说明可选值："apsta"、"ap"、"sta"
返回值:
类型object
函数 waitIP
原型: waitIP ()
等待从 DHCP 获取 IP 地址
异步返回 Promise<object|false> ，如果失败返回 false，成功则返回包含 ip 的 sta status 对象。
参考 status() 函数的返回值。
返回值:
类型Promise<object, false>
函数 startStaDeamon
原型: startStaDeamon (dur:number=10000)
启动 STA 守护进程
当 WiFi 连接断开时，守护进程会自动尝试重新连接。 通常在 connect() 函数中设置 retry 为负数时会自动启动守护进程。
参数:
dur
类型number
默认值10000
参数说明检查间隔时间，单位毫秒，默认 10000ms
返回值:
undefined
函数 stopStaDeamon
原型: stopStaDeamon ()
停止 STA 守护进程
停止自动重连功能。disconnect() 函数会自动调用此函数。
返回值:
undefined
函数 isStaDeamonRunning
原型: isStaDeamonRunning ()
返回 STA 守护进程是否正在运行
返回值:
类型boolean
说明返回 true 表示守护进程正在运行，false 表示未运行
函数 setPS
原型: setPS (mode:number)
设置 WiFi 的节能模式 (Power Save)
参数 mode：
- 0: 关闭节能模式
- 1: 最小节能模式
- 2: 最大节能模式
关闭节能模式可以避免 WiFi 休眠，提高通信的效率和稳定性，但会增加功耗。
参数:
mode
类型number
参数说明节能模式，取值 0|1|2
异常:
- WiFi 未初始化
- 参数数量不足
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 setMode
原型: setMode (mode:number)
设置 WiFi 的工作模式
startAP 和 connect 会自动设置工作模式，因此通常不需要直接使用这个 API。
参数 mode：
- 0: 未启动
- 1: STA 模式
- 2: AP 模式
- 3: STA + AP 模式
参数:
mode
类型number
参数说明工作模式，取值 0|1|2|3
异常:
- WiFi 未初始化
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 getMode
原型: getMode ()
返回 WiFi 的工作模式
返回值：
- 0: 未启动
- 1: STA 模式
- 2: AP 模式
- 3: STA + AP 模式
异常:
- WiFi 未初始化
返回值:
类型number
说明当前工作模式
函数 setAPConfig
原型: setAPConfig (config:object)
设置 WiFi AP 模式的参数
startAP 会自动配置 AP 参数，需要对设备更详细的设置时，可以使用这个 API。
参数 config：
{
ssid: string, // 热点名称
password?: string, // 热点密码
"threshold.authmode"?: number, // 认证模式 0-8
channel?: number, // 信道 1-13
max_connection?: number, // 最大客户端连接数，默认 4
ssid_hidden?: boolean, // 是否隐藏热点，默认 false
beacon_interval?: number, // 信标间隔
pairwise_cipher?: number, // 加密方式
ftm_responder?: boolean, // 启用 FTM Responder 模式
}如果 password 为空，则 threshold.authmode 自动设置为 WIFI_AUTH_OPEN。
参数:
config
类型object
参数说明AP 配置对象
异常:
- WiFi 未初始化
- 参数数量不足
- 参数类型错误
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 setStaConfig
原型: setStaConfig (config:object)
设置 WiFi STA 模式的连接参数
connect 会自动配置连接参数，需要使用更详细的连接参数时使用此 API。
参数 config：
{
ssid: string, // 目标 AP 的 SSID
password?: string, // 目标 AP 的密码
"threshold.authmode"?: number, // 认证模式 0-8
scan_method?: number, // 扫描方法 0|1
channel?: number, // 目标信道 1-13
listen_interval?: number, // 监听间隔，默认 3
sort_method?: number, // 排序方法 0|1，默认 0
}如果 password 为空，则 threshold.authmode 自动设置为 WIFI_AUTH_OPEN。
参数:
config
类型object
参数说明STA 配置对象
异常:
- WiFi 未初始化
- 参数数量不足
- 参数类型错误
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 getConfig
原型: getConfig (mode:number)
返回 WiFi 的工作参数
返回的对象可参考 setStaConfig() 和 setAPConfig() 的参数说明。
参数:
mode
类型number
参数说明1 代表 STA，2 代表 AP
异常:
- WiFi 未初始化
- 参数数量不足
- 获取配置失败
- 未知的网络接口类型
返回值:
类型object
说明配置对象
函数 dhcpStaStart
原型: dhcpStaStart ()
启动 STA 模式的 DHCP 客户端
使用 setStaIP() 设置静态 IP 后，如需重新使用 DHCP，可调用此函数。
返回值:
类型undefined
函数 dhcpStaStop
原型: dhcpStaStop ()
停止 STA 模式的 DHCP 客户端
停止 DHCP 后，可以使用 setStaIP() 设置静态 IP 地址。
返回值:
类型undefined
函数 setStaIP
原型: setStaIP (ip:string, netmask:string, gw:string)
设置 WiFi STA 的静态 IP 地址
会先停止 DHCP 客户端，如果需要重新使用 DHCP，可调用 dhcpStaStart() 函数。
参数:
ip
类型string
参数说明IP 地址
netmask
类型string
参数说明子网掩码
gw
类型string
参数说明网关地址
异常:
- WiFi 未初始化
- 参数数量不足
- 设置 IP 失败
返回值:
类型undefined
函数 peripheralConnect
原型: peripheralConnect ()
执行 WiFi STA 连接操作
这是底层连接函数，通常在 JS 侧被 connect() 调用。
异常:
- WiFi 未初始化
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 peripheralDisconnect
原型: peripheralDisconnect ()
WiFi STA 断开连接
这是底层断开函数，通常在 JS 侧被 disconnect() 调用。
异常:
- WiFi 未初始化
返回值:
类型number
说明返回 0 表示成功，非 0 表示错误代码
函数 getIpInfo
原型: getIpInfo (type:number)
返回 AP/STA 的 IP 信息
返回一个对象，包含 ip、netmask、gw 信息。
{
ip: string,
netmask: string,
gw: string
}参数:
type
类型number
参数说明1 代表 STA，2 代表 AP
异常:
- WiFi 未初始化
- 参数数量不足
- 未知的网络接口类型
返回值:
类型object
说明IP 信息对象
函数 setHostname
原型: setHostname (name:string)
设置 WiFi 在局域网中显示的主机名
参数:
name
类型string
参数说明主机名
异常:
- WiFi 未初始化
- 参数数量不足
返回值:
类型undefined
函数 allSta
原型: allSta ()
返回所有连接到本机 AP 的客户端
返回对象数组，每个对象包含 mac 和 rssi 信息。
[
{mac: "xx:xx:xx:xx:xx:xx", rssi: -30},
]rssi 值范围 -100 ~ 0，单位为 dBm，表示信号强度，越大（绝对值越小）表示信号越强。
异常:
- WiFi 未初始化
- 获取客户端列表失败
返回值:
类型object[] 客户端列表，每个对象包含 mac 和 rssi 属性
函数 scan
原型: scan ()
扫描周围的 WiFi 热点，必须在 STA 模式下运行
异步返回 Promise<object[]>
返回对象数组的格式：
[
{
bssid:string ,
ssid:string ,
channel:number ,
rssi:number ,
authmode:number ,
} ,
...
]示例：
import { scan } from "wifi"
const aps = await scan()
aps.forEach(ap => {
console.log(ap.ssid, ap.rssi, "dBm")
})返回值:
类型Promise<object[]>
函数 scanStart
原型: scanStart ()
开始扫描附近的 AP
WiFi STA 模式必须已启动。
异常:
- WiFi 未初始化
返回值:
类型boolean
说明返回 true 表示开始扫描成功，false 表示失败
函数 scanStop
原型: scanStop ()
停止 AP 扫描
异常:
- WiFi 未初始化
返回值:
类型boolean
说明返回 true 表示停止成功，false 表示失败
函数 isScanning
原型: isScanning ()
返回 AP 扫描是否正在进行
异常:
- WiFi 未初始化
返回值:
类型boolean
说明返回 true 表示正在扫描中，false 表示未扫描
函数 scanRecords
原型: scanRecords ()
取回 AP 扫描的结果
返回的数组格式：
[
{
bssid: string,
ssid: string,
channel: number,
rssi: number,
authmode: number,
}
]异常:
- WiFi 未初始化
- 内存分配失败
返回值:
类型object[] AP 列表
函数 staStarted
原型: staStarted ()
返回 WiFi STA 模式是否已启动
返回值:
类型boolean
说明返回 true 表示 STA 已启动，false 表示未启动
函数 staConnected
原型: staConnected ()
返回 WiFi STA 是否已经连接到 AP
返回值:
类型boolean
说明返回 true 表示已连接，false 表示未连接
函数 apStarted
原型: apStarted ()
返回 WiFi AP 模式是否已启用
返回值:
类型boolean
说明返回 true 表示 AP 已启用，false 表示未启用
函数 setMAC
原型: setMAC (ifname:string, mac:string)
设置 WiFi 接口的 MAC 地址
必须在 WiFi 启动前设置 MAC 地址。
参数:
ifname
类型string
参数说明接口名称，可选值为 "sta"、"ap"、"nan"
mac
类型string
参数说明MAC 地址，格式为 "xx:xx:xx:xx:xx:xx"
异常:
- WiFi 已启动，无法设置 MAC 地址
- 参数数量不足
- 接口名称无效
- MAC 地址格式错误
- 设置 MAC 地址失败
返回值:
类型undefined
函数 getMAC
原型: getMAC (ifname:string)
获取 WiFi 接口的 MAC 地址
参数:
ifname
类型string
参数说明接口名称，可选值为 "sta"、"ap"、"nan"
异常:
- 参数数量不足
- 接口名称无效
- 获取 MAC 地址失败
返回值:
类型string
说明MAC 地址，格式为 "xx:xx:xx:xx:xx:xx" (字母小写)
函数 isReady
原型: isReady ()
返回 WiFi 是否已准备好
检查 WiFi 是否已经启动并处于可用状态。
示例：
import * as wifi from "wifi"
if (wifi.isReady()) {
console.log("WiFi is ready")
}返回值:
类型boolean
说明返回 true 表示 WiFi 已准备好，false 表示未准备好
函数 start
原型: start ()
启动 WiFi
异步启动 WiFi 硬件，返回 Promise。 startAP 和 connect 会自动调用此函数。
示例：
import * as wifi from "wifi"
await wifi.start()
console.log("WiFi started!")返回值:
类型Promise<undefined>
函数 stop
原型: stop ()
停止 WiFi
异步停止 WiFi 硬件，返回 Promise。
示例：
import * as wifi from "wifi"
await wifi.stop()
console.log("WiFi stopped!")返回值:
类型Promise<undefined>
函数 connect
原型: connect (ssid:string|object, password:string, retry:number=3, retryDur:number=5000)
连接到 WiFi 热点
作为 STA 模式连接到指定的 WiFi 热点。 如果 retry 为负数，则会启动守护进程自动重连。
示例：
import * as wifi from "wifi"
// 基本连接
const connected = await wifi.connect("MyWiFi", "password123")
if (connected) {
console.log("Connected!")
}
// 使用配置对象
await wifi.connect({
ssid: "MyWiFi",
password: "password123",
retry: 3,
retryDur: 5000
})
// 启动守护进程（retry < 0）
await wifi.connect("MyWiFi", "password123", -1)参数:
ssid
类型string, object
参数说明WiFi 热点名称或配置对象
password
类型string
参数说明WiFi 热点密码（当 ssid 为字符串时）
retry
类型number
默认值3
参数说明连接失败重试次数，负数表示启动守护进程
retryDur
类型number
默认值5000
参数说明连接重试间隔时间，单位毫秒
返回值:
类型Promise<boolean>
说明返回 true 表示连接成功，false 表示失败
函数 disconnect
原型: disconnect (dontStopDeamon:boolean=false)
断开 WiFi 连接
断开 STA 模式的 WiFi 连接，并停止守护进程（如果正在运行）。
示例：
import * as wifi from "wifi"
await wifi.disconnect()
console.log("Disconnected!")参数:
dontStopDeamon
类型boolean
默认值false
参数说明如果为 true，则不停止守护进程
返回值:
类型Promise<undefined>
函数 isConnecting
原型: isConnecting ()
返回是否正在连接中
返回值:
类型boolean
说明返回 true 表示正在连接中，false 表示未连接
函数 startAP
原型: startAP (ssid:string, password:string)
启动 WiFi 热点（AP 模式）
启动一个 WiFi 热点，供其他设备连接。
示例：
import * as wifi from "wifi"
const started = await wifi.startAP("MyAP", "password123")
if (started) {
console.log("AP started!")
}参数:
ssid
类型string
参数说明热点名称
password
类型string
参数说明热点密码
返回值:
类型Promise<boolean>
说明返回 true 表示启动成功，false 表示失败
函数 stopAP
原型: stopAP ()
停止 WiFi 热点
停止 AP 模式的 WiFi 热点。
示例：
import * as wifi from "wifi"
const stopped = await wifi.stopAP()
if (stopped) {
console.log("AP stopped!")
}返回值:
类型Promise<boolean>
说明返回 true 表示停止成功，false 表示失败
函数 status
原型: status (netif:string="apsta")
返回 WiFi 状态
返回 AP 和/或 STA 的详细状态信息。
示例：
import * as wifi from "wifi"
// 获取所有状态
const status = wifi.status()
console.log(status.sta)
console.log(status.ap)
// 仅获取 STA 状态
const staStatus = wifi.status("sta")
console.log(staStatus.ip)参数:
netif
类型string
默认值"apsta"
参数说明网络接口类型，可选值为 "apsta"、"sta"、"ap"
返回值:
类型object
说明状态对象
函数 startStaDeamon
原型: startStaDeamon (dur:number=10000)
启动 STA 守护进程
当 WiFi 连接断开时，守护进程会自动尝试重新连接。 通常在 connect() 函数中设置 retry 为负数时会自动启动守护进程。
参数:
dur
类型number
默认值10000
参数说明检查间隔时间，单位毫秒，默认 10000ms
返回值:
undefined
函数 stopStaDeamon
原型: stopStaDeamon ()
停止 STA 守护进程
停止自动重连功能。disconnect() 函数会自动调用此函数。
返回值:
undefined
函数 isStaDeamonRunning
原型: isStaDeamonRunning ()
返回 STA 守护进程是否正在运行
返回值:
类型boolean
说明返回 true 表示守护进程正在运行，false 表示未运行
函数 scan
原型: scan ()
扫描周围的 WiFi 热点
扫描并返回周围可用的 WiFi 热点列表。
示例：
import * as wifi from "wifi"
const aps = await wifi.scan()
aps.forEach(ap => {
console.log(ap.ssid, ap.rssi, "dBm")
})返回值:
类型Promise<object[]> AP 列表，每个对象包含 ssid、rssi、authmode 等属性
函数 waitIP
原型: waitIP ()
等待获取 IP 地址
等待分配 IP 地址，返回包含 IP 信息的状态对象，对象格式参考 wifi.status("apsta")
如果连接断开，返回 false。
如果已经获得IP，则直接返回，不需要等待。
连接到 WiFi 以后，还需要分配一个 IP 地址才能通讯。通常在
await connect()之后await waitIP()。
示例：
import * as wifi from "wifi"
await wifi.connect("MyWiFi", "password123")
const ipInfo = await wifi.waitIP()
if (ipInfo) {
console.log("IP:", ipInfo.ip)
}
// @todo
// 现在可以请求服务器了
// ... ...返回值:
类型Promise<object, false>
说明成功返回状态对象，失败返回 false