跳到主要内容

Wi-Fi 基础用法

本节课介绍了 ESP32 MicroPython 的 Wi-Fi 基础用法，包括扫描 WiFi、连接指定 WiFi、创建热点和配置静态 IP 等功能。

ESP32 系列芯片内置了强大的无线连接功能。多数 ESP32 芯片集成了 Wi-Fi, 这使其非常适用于物联网 (IoT) 项目。部分型号为满足成本或特定应用场景的需求，未集成 Wi-Fi 功能。各型号具体的支持情况可查阅官方的 ESP32 产品概览 文档。

ESP32 可以工作在多种 Wi-Fi 模式下：

  • STA 模式 (Station):ESP32 作为客户端连接到路由器或热点。
  • AP 模式 (Access Point):ESP32 创建热点，其他设备可以连接到它。
  • AP+STA 模式: 同时作为客户端连接网络，并为其他设备提供热点。

本教程将通过以下示例介绍 MicroPython 环境下 ESP32 的 Wi-Fi 基本用法：

1. 示例 1: 扫描 WiFi​

这个示例展示如何扫描周围的 Wi-Fi 网络并显示其详细信息，包括网络名称、信号强度、信道和加密类型。

1.1 代码​

import time
import network

def get_security_name(security_type):
    """将安全类型转换为可读字符串"""
    if security_type == 0:
        return "open"
    elif security_type == 1:
        return "WEP"
    elif security_type == 2:
        return "WPA-PSK"
    elif security_type == 3:
        return "WPA2-PSK"
    elif security_type == 4:
        return "WPA/WPA2-PSK"
    else:
        return "unknown"

# 创建 WLAN 对象，设置为 STA 模式
wlan = network.WLAN(network.STA_IF)
# 激活 WLAN 接口
wlan.active(True)

print("Setup done")

while True:
    print("Scan start")
    # 扫描可用的 Wi-Fi 网络
    networks = wlan.scan()
    print("Scan done")

    if len(networks) == 0:
        print("no networks found")
    else:
        print(f"{len(networks)} networks found")
        print("Nr | SSID                             | RSSI | CH | Encryption")

        for i, net in enumerate(networks):
            # 网络信息格式：(ssid, bssid, channel, RSSI, security, hidden)
            ssid = net[0].decode('utf-8') if net[0] else "Hidden"
            rssi = net[3]
            channel = net[2]
            security = net[4]

            # 格式化输出
            print(f"{i+1:2d} | {ssid:32.32s} | {rssi:4d} | {channel:2d} | {get_security_name(security)}")

    print("")

    # 等待 10 秒后再次扫描
    time.sleep(10)

1.2 代码解释​

  • network.WLAN(network.STA_IF): 创建一个 WLAN 网络接口对象，参数 network.STA_IF 表示站点 (Station) 模式。
  • wlan.active(True): 激活 WLAN 接口。在执行任何 Wi-Fi 操作之前，必须先激活接口。
  • wlan.scan(): 执行网络扫描。该方法会阻塞执行，直到扫描完成，返回一个包含所有发现网络信息的列表。每个网络信息是一个元组，格式为 (ssid, bssid, channel, RSSI, security, hidden)。
  • 元组元素说明:
    • ssid: 网络名称，字节类型，需要使用 .decode('utf-8') 解码为字符串。
    • bssid: 路由器的 MAC 地址，字节类型。
    • channel:Wi-Fi 信道号。
    • RSSI: 接收信号强度指示，单位为 dBm。该值为负数，越接近 0 表示信号越强。
    • security: 加密类型，整数值。
    • hidden: 是否为隐藏网络，布尔值。
  • get_security_name(): 辅助函数，将数字形式的安全类型转换为易读的字符串。
提示

软重启（Soft Reset）通常不会重置 Wi-Fi 硬件的状态。如果需要完全重置 Wi-Fi，建议在代码中显式调用 wlan.active(False) 或进行硬重启。

1.3 运行结果​

运行代码后，Shell 将显示检测到的可用 Wi-Fi 网络列表，输出类似如下：

示例 1: 扫描 WiFi 运行结果

2. 示例 2: 连接指定 Wi-Fi (STA 模式）​

ESP32 连接到指定的 Wi-Fi 网络，获取 IP 地址并保持连接。

2.1 代码​

import time
import network

# 请替换为实际的 Wi-Fi 网络信息
SSID = "Maker"        # 替换为 Wi-Fi 名称
PASSWORD = "12345678"  # 替换为 Wi-Fi 密码

# 创建 WLAN 对象，设置为 STA 模式
wlan = network.WLAN(network.STA_IF)
# 激活 WLAN 接口
wlan.active(True)

print(f"Connecting to {SSID}")

# 连接到指定的 Wi-Fi 网络
wlan.connect(SSID, PASSWORD)

# 等待连接建立
while not wlan.isconnected():
    time.sleep(0.5)
    print(".", end="")

print("")
print("WiFi connected.")
print("IP config:", wlan.ifconfig())

2.2 代码解释​

  • wlan.connect(ssid, password): 启动连接过程。这是一个异步函数，它会立即返回，而连接在后台进行。
  • wlan.isconnected(): 返回当前的 Wi-Fi 连接状态。返回 True 表示已成功连接，False 表示未连接。while 循环通过轮询此状态来等待连接完成。
  • wlan.ifconfig(): 获取网络接口配置信息，返回一个包含 4 个元素的元组：(ip, subnet_mask, gateway, dns_server)。
    • wlan.ifconfig()[0]: 获取分配到的 IP 地址。

2.3 运行结果​

将代码中的 SSID 和 PASSWORD 修改为实际的 Wi-Fi 信息后运行。Shell 将显示连接过程，成功后打印出获取到的 IP 地址： 示例 2: 连接 WiFi 运行结果

3. 示例 3: 创建 Wi-Fi 热点 (AP 模式）​

ESP32 创建一个 Wi-Fi 热点，其他设备可以连接到它。

3.1 代码​

import network

SSID = "ESP32-S3-TEST"  # 设置热点名称
PASSWORD = "12345678"   # 设置热点密码（至少 8 位）

# 创建 WLAN 对象，设置为 AP 模式
ap = network.WLAN(network.AP_IF)
# 激活 AP 接口
ap.active(True)

print("Configuring access point...")

# 配置并创建热点
ap.config(essid=SSID, password=PASSWORD, authmode=network.AUTH_WPA_WPA2_PSK)

# 获取 AP 的 IP 地址
ip = ap.ifconfig()[0]
print(f"AP IP address: {ip}")
print("AP started")

3.2 代码解释​

  • network.WLAN(network.AP_IF): 创建一个 WLAN 网络接口对象，参数 network.AP_IF 表示接入点 (AP) 模式。
  • ap.config(essid=ssid, password=password): 配置 AP 的参数。essid 参数设置热点名称，password 参数设置密码（至少 8 位）。

3.3 运行结果​

程序运行后，ESP32 会创建一个名为 "ESP32-S3-TEST" 的 Wi-Fi 热点。Shell 会打印出 AP 的 IP 地址： 示例 3: 创建 WiFi 热点运行结果

4. 示例 4: 配置静态 IP​

在特定应用场景下，为 ESP32 设置一个固定的 IP 地址（而非通过 DHCP 动态获取）是一种常见需求，便于设备被稳定访问。

4.1 STA 模式：配置静态 IP​

基于示例 2, 添加静态 IP 配置：

import time
import network

SSID = "Maker"         # Wi-Fi 名称
PASSWORD = "12345678"  # Wi-Fi 密码

# 设置静态 IP 地址、子网掩码、网关和 DNS 服务器
# 根据实际局域网配置进行修改
STATIC_IP = "192.168.137.100"     # 设定静态 IP 地址
SUBNET = "255.255.255.0"   # 设定子网掩码
GATEWAY = "192.168.137.1"  # 设定网关
DNS = "192.168.137.1"      # 设定 DNS 服务器

# 创建 WLAN 对象，设置为 STA 模式
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
# 配置静态 IP
wlan.ifconfig((STATIC_IP, SUBNET, GATEWAY, DNS))

print(f"Connecting to {SSID}")

# 连接到指定的 Wi-Fi 网络
wlan.connect(SSID, PASSWORD)

# 等待连接建立
while not wlan.isconnected():
    time.sleep(0.5)
    print(".", end="")

print("")
print("WiFi connected.")
print(f"IP address: {wlan.ifconfig()[0]}")

代码解释

  • wlan.ifconfig((STATIC_IP, SUBNET, GATEWAY, DNS)): 配置网络接口的静态 IP。参数是一个包含 4 个字符串的元组，分别表示 IP 地址、子网掩码、网关和 DNS 服务器。

    注意

    请确保设置的 IP 地址、网关和子网掩码与所在的局域网环境相匹配，且该 IP 未被其他设备占用。

    提示

    建议在连接 Wi-Fi 之前配置静态 IP，以确保设备使用指定的网络配置建立连接。

4.2 AP 模式：配置静态 IP​

基于示例 3, 为热点设置自定义 IP 地址：

import network

SSID = "ESP32-S3-TEST"  # 设置热点名称
PASSWORD = "12345678"   # 设置热点密码（至少 8 位）

STATIC_IP = "192.168.5.1"       # 设定静态 IP 地址
SUBNET = "255.255.255.0" # 设定子网掩码
GATEWAY = "192.168.5.1"  # 设定网关
DNS = "192.168.5.1"      # 设定 DNS 服务器

# 创建 WLAN 对象，设置为 AP 模式
ap = network.WLAN(network.AP_IF)
ap.active(True)

print("Configuring access point...")

# 在激活接口后配置静态 IP
ap.ifconfig((STATIC_IP, SUBNET, GATEWAY, DNS))

# 配置并创建热点
ap.config(essid=SSID, password=PASSWORD)

print(f"AP IP address: {ap.ifconfig()[0]}")
print("AP started")

代码解释

  • ap.ifconfig((STATIC_IP, SUBNET, GATEWAY, DNS)): 在激活 AP 接口后，使用此方法配置自定义的 IP 地址、子网掩码、网关和 DNS 服务器。

6. 相关链接​

最后由 Wulu 于 更新