CircuitPython ESP32网络编程实战：从Wi-Fi连接到IPv6通信

1. 项目概述

如果你正在用ESP32这类物联网开发板做项目，大概率绕不开网络连接。无论是从云端拉取数据，还是给设备推送指令，网络都是现代嵌入式应用的“血管”。过去几年，我经手过不少基于MicroPython和Arduino框架的项目，直到深度使用CircuitPython后，才发现它在简化网络编程，尤其是处理现代网络协议方面，确实有一套独特的哲学。它把很多底层复杂的操作，比如Wi-Fi连接管理、套接字创建、甚至是IPv6的支持，都封装成了几句直观的Python代码。这听起来很美好，但真要把一个ESP32设备稳定地接入网络，并玩转像IPv6这样的“新”特性，里面有不少细节和坑需要提前了解。这篇文章，我就结合一个从获取网络时间到探索IPv6通信的完整案例，拆解一下在CircuitPython环境下进行ESP32网络配置与编程的核心要点和实战经验。

2. 环境准备与基础配置

在开始写任何网络代码之前，确保你的开发环境是就绪的。这不仅仅是把板子插上USB那么简单，它涉及到固件、驱动、编辑器和项目文件结构等一系列基础工作。很多新手卡在第一步，往往是因为某个环节的疏忽。

2.1 硬件与固件准备

首先，你需要一块支持CircuitPython的ESP32开发板。Adafruit、SparkFun等厂商的很多型号都支持，核心是板载了Espressif的ESP32系列芯片。拿到板子后，第一件事是刷入最新的CircuitPython固件。去CircuitPython官网找到对应你板子型号的.uf2或.bin文件，通过Bootloader模式刷入。这一步至关重要，因为网络栈的功能，特别是像IPv6支持（从9.2版本开始引入），是依赖特定版本的固件的。我习惯在项目开始前，去GitHub的CircuitPython发布页看一眼最新版本，确保用的是稳定版而非开发版，避免遇到一些未修复的边界问题。

固件刷好后，电脑上会出现一个名为CIRCUITPY的U盘。这就是你的板子的文件系统，你的代码和配置文件都将存放在这里。如果没出现，检查一下是否进入了Bootloader模式，或者尝试换条质量好的USB数据线——劣质线缆只能供电不能传输数据的情况我见过不少。

2.2 核心配置文件：settings.toml

网络配置的起点，是一个名为settings.toml的文件。这个文件必须放在CIRCUITPY驱动器的根目录下。它采用TOML格式，本质是一个文本文件，用来安全地存储你的Wi-Fi凭证、API密钥等敏感信息。绝对不要把这些信息直接硬编码在code.py里，否则一旦代码分享出去，你的网络密码也就泄露了。

一个最基本的、用于连接Wi-Fi的settings.toml内容如下：

CIRCUITPY_WIFI_SSID = "你的Wi-Fi名称" CIRCUITPY_WIFI_PASSWORD = "你的Wi-Fi密码"

这里的变量名是固定的，CircuitPython的Wi-Fi库会主动寻找这两个键值对。请注意，Wi-Fi名称（SSID）最好避免使用特殊字符或中文，有些ESP32的驱动对非ASCII字符的支持并不完美，可能导致连接失败。

创建这个文件，你可以用任何纯文本编辑器，比如VS Code、Notepad++，或者CircuitPython社区推荐的Mu编辑器。在Windows上，注意文件扩展名必须是.toml，而不是.toml.txt（需要取消“隐藏已知文件类型的扩展名”选项）。在Mac或Linux上，用touch settings.toml命令创建后再编辑即可。

2.3 编辑器选择与串口连接

我强烈推荐初学者使用Mu编辑器。它专为教育和小型嵌入式开发设计，集成了代码编辑、文件管理和串口监视器于一体。对于网络调试来说，串口监视器是不可或缺的“眼睛”。当你运行网络代码时，所有的print()输出、连接状态、乃至错误信息（Traceback），都会在这里显示。Mu能自动检测并连接到你的CircuitPython板，点击底部的“串口”按钮即可打开控制台。

如果你是有经验的开发者，习惯使用VS Code、PyCharm等专业IDE，也完全没问题。但你需要额外处理两件事：一是文件保存后的“安全弹出”问题，二是需要一个独立的串口终端工具（如PuTTY、screen、minicom）。在非Mu编辑器下，当你保存code.py后，必须手动在操作系统层面“弹出”或“同步”CIRCUITPY驱动器，以确保文件被完全写入，否则极易导致文件系统损坏，严重时驱动器会无法识别，需要重新刷写固件来修复。

注意：在macOS Sonoma 14.1至14.3版本中，存在一个系统Bug，会导致向CIRCUITPY这类小容量驱动器写入文件时出现延迟和错误。解决方法是升级到14.4或更高版本。在Linux上，如果串口连接延迟数秒或出现乱码，可能是modemmanager服务在干扰，可以通过sudo apt purge modemmanager命令将其移除。

3. 基础网络连接与测试

配置好settings.toml后，我们就可以编写第一个网络测试脚本了。这个脚本的目标很简单：连接Wi-Fi，获取一个IP地址，并尝试访问一个外部网站来验证连通性。

3.1 编写网络测试脚本

在你的CIRCUITPY驱动器根目录下，找到或创建一个code.py文件，输入以下代码：

import os import wifi import socketpool import adafruit_requests import ssl # 1. 从settings.toml中读取Wi-Fi配置 ssid = os.getenv("CIRCUITPY_WIFI_SSID") password = os.getenv("CIRCUITPY_WIFI_PASSWORD") # 2. 打印本机MAC地址和可用的Wi-Fi网络（扫描） print("我的MAC地址:", [hex(i) for i in wifi.radio.mac_address]) print("正在扫描附近的Wi-Fi网络...") for network in wifi.radio.start_scanning_networks(): # 网络信息包括SSID、信号强度(RSSI)和信道 print(f"\t{str(network.ssid, 'utf-8')}\t信号强度: {network.rssi} dBm\t信道: {network.channel}") wifi.radio.stop_scanning_networks() # 扫描完成后务必停止 # 3. 连接Wi-Fi print(f"正在连接至: {ssid}") wifi.radio.connect(ssid, password) print("连接成功！") # 4. 打印获取到的IP地址（IPv4） ipv4_address = wifi.radio.ipv4_address print(f"本机IPv4地址: {ipv4_address}") # 5. 测试网络连通性：Ping一个公共DNS服务器 import ipaddress ping_target = ipaddress.ip_address("8.8.8.8") # Google DNS ping_time = wifi.radio.ping(ping_target) if ping_time is not None: print(f"Ping {ping_target}: {ping_time * 1000:.2f} ms") else: print(f"无法Ping通 {ping_target}") # 6. 发起一个HTTP GET请求作为终极测试 print("\n--- 发起HTTP请求测试 ---") pool = socketpool.SocketPool(wifi.radio) requests = adafruit_requests.Session(pool, ssl.create_default_context()) test_url = "http://httpbin.org/get" try: response = requests.get(test_url) print(f"HTTP状态码: {response.status_code}") print("响应头:", response.headers) # 打印部分响应体 print("响应内容（前200字符）:", response.text[:200]) response.close() except Exception as e: print(f"HTTP请求失败: {e}") print("\n网络测试完成。")

3.2 代码逐行解析与常见问题

1. 环境变量读取：os.getenv()是读取settings.toml中配置的标准方法。确保变量名拼写完全一致，包括大小写。
2. 网络扫描：start_scanning_networks()会返回一个可迭代对象。这是一个很好的诊断工具，如果看不到你自己的Wi-Fi SSID，说明信号太弱、SSID被隐藏，或者板子的Wi-Fi天线有问题。切记，扫描完成后调用stop_scanning_networks()，否则会持续占用射频资源。
3. 连接过程：wifi.radio.connect()是阻塞式的，它会一直尝试直到成功或超时。默认超时时间可能较长，如果网络环境复杂（如需要网页认证的公共Wi-Fi），这里可能会卡住。
4. IP地址获取：连接成功后，DHCP客户端会自动运行，为设备分配一个IPv4地址。wifi.radio.ipv4_address是一个ipaddress.IPv4Address对象，可以直接打印。
5. Ping测试：wifi.radio.ping()接受一个IP地址对象或域名，返回延迟（秒）。返回None意味着超时或网络不可达。这是检查三层（网络层）连通性的好方法。
6. HTTP请求：这是七层（应用层）测试。我们创建了一个socketpool和一个requests会话。ssl.create_default_context()即使对于HTTP连接也是推荐的，它为可能的HTTPS重定向做准备。我们选择httpbin.org这个测试网站，因为它稳定且会原样返回你的请求信息。

实操心得：

• 连接失败排查：如果连接失败，首先打开串口监视器看输出。常见错误包括：OSError: Wifi Internal Error（密码错误或SSID不存在）、长时间无响应（信号太差）。此时，可以尝试在代码中增加超时和重试逻辑，或者先注释掉连接部分，只运行扫描，确认是否能发现目标网络。
• 关于HTTPS：CircuitPython的adafruit_requests库支持HTTPS，但这依赖于板载的根证书库。某些特别新的或自定义CA签名的网站可能无法连接。对于重要的生产环境，可以考虑在代码中指定自定义证书，或者使用预缓存的指纹验证。
• 内存管理：网络缓冲区和SSL上下文会消耗RAM。ESP32的RAM有限（通常约500KB），在处理大响应体时，注意使用response.content进行流式读取，而非一次性将response.text全部加载到内存。

运行这个脚本，如果一切顺利，你将在串口监视器中看到从扫描、连接到成功发起HTTP请求的全过程日志。这是你设备网络能力的“健康证明”。

4. 深入IPv6网络编程

在通过基础测试后，我们进入更现代的IPv6领域。IPv6并非遥不可及，很多家庭宽带和移动网络已经支持。对于物联网设备，IPv6的巨大地址空间意味着每个传感器、每个灯泡都可以拥有一个公网可达的地址，这为点对点通信和端到端安全提供了新的可能。

4.1 IPv6基础与CircuitPython支持

IPv6地址长达128位，通常表示为8组4位十六进制数，例如2001:db8::1。在CircuitPython中，从9.2版本开始，大多数基于Espressif芯片的开发板都获得了IPv6支持。但需要注意的是，IPv6在默认情况下是禁用的。这主要是出于隐私考虑，我们稍后会详细解释。

启用IPv6非常简单，只需要在连接Wi-Fi后，额外启动一个DHCPv6客户端：

# 在连接Wi-Fi之后... wifi.radio.connect(ssid, password) # 启用IPv6 DHCP客户端 wifi.radio.start_dhcp_client(ipv6=True) print("IPv6 DHCP客户端已启动。")

这行代码会触发设备向网络中的DHCPv6服务器（或通过无状态地址自动配置SLAAC）请求一个或多个IPv6地址。

4.2 查看与理解IPv6地址

启用后，我们可以通过wifi.radio.addresses属性查看所有网络地址：

>>> wifi.radio.addresses ('FE80::7EDF:A1FF:FE00:518C', 'FD5F:3F5C:FE50:0:7EDF:A1FF:FE00:518C', '10.0.3.96')

你会看到一个包含多个地址的元组。我们来拆解一下：

1. FE80::7EDF:A1FF:FE00:518C：这是一个链路本地地址（Link-Local Address）。它以FE80::/10开头，仅在同一个物理网络链路（比如你的本地Wi-Fi子网）内有效，路由器不会转发此类地址的数据包。每个启用IPv6的接口都会自动生成一个链路本地地址，用于邻居发现等协议。
2. FD5F:3F5C:FE50:0:7EDF:A1FF:FE00:518C：这是一个唯一本地地址（Unique Local Address, ULA），相当于IPv4中的私有地址（如10.0.0.0/8）。它以FD00::/8开头，用于本地站点通信，不会在公网被路由。
3. 10.0.3.96：这就是我们熟悉的IPv4私有地址。

关键点：隐私地址与EUI-64细心的你可能发现，后两个地址的后半部分（7EDF:A1FF:FE00:518C）看起来非常相似。这不是巧合。在默认情况下，Espressif的IPv6实现使用了一种基于设备MAC地址的算法（EUI-64）来生成接口标识符（IID）。这带来了严重的隐私问题：你的设备无论连接到哪个Wi-Fi网络，其IPv6地址的后64位都可能是相同的，这使得跨网络跟踪设备成为可能。

因此，CircuitPython默认禁用IPv6，将启用权交给开发者。如果你的设备需要接入公网IPv6（获得一个2001:或2002:开头的全局单播地址），并且关心隐私，你需要关注网络是否支持隐私扩展（Privacy Extensions, RFC 4941），它会定期生成随机的临时地址。目前，CircuitPython的底层驱动可能还未完全支持此特性，这是在实际部署中需要考虑的风险点。

4.3 配置DNS与IPv6连通性测试

IPv6网络中的DNS同样重要。你可以查看和设置DNS服务器：

# 查看当前DNS服务器（可能是路由器下发的IPv6地址） print("当前DNS服务器:", wifi.radio.dns) # 手动设置为公共DNS（支持IPv6的） wifi.radio.dns = ("2001:4860:4860::8888", "2001:4860:4860::8844") # Google IPv6 DNS # 或者使用IPv4地址，系统会自动处理 # wifi.radio.dns = ("8.8.8.8", "8.8.4.4") print("设置后DNS服务器:", wifi.radio.dns)

测试IPv6连通性可以使用ping方法，它同时支持域名和IPv6地址：

# Ping一个支持IPv6的域名 target = "ipv6.google.com" latency = wifi.radio.ping(target) if latency is not None: print(f"Ping {target}: {latency*1000:.2f} ms") else: print(f"无法Ping通 {target}，可能网络不支持IPv6或域名解析失败。")

如果对ipv6.google.com的ping测试失败，而普通的google.com（IPv4）成功，那很可能意味着你的本地路由器或运营商没有提供IPv6接入。你需要登录路由器管理界面查看IPv6设置，或者咨询你的网络服务提供商。

4.4 创建IPv6套接字进行通信

最核心的部分来了：如何使用IPv6进行套接字编程。CircuitPython的socket库提供了与标准Python类似的接口，关键是指定地址族为socket.AF_INET6。

下面是一个向IPv6 NTP服务器请求时间的UDP客户端示例：

import socket import struct import time def get_time_via_ntp_v6(server_host="time.google.com", port=123): """ 通过IPv6从NTP服务器获取时间。 注意：此例需要你的网络具有IPv6互联网连接，且能解析服务器的IPv6地址。 """ # 创建一个IPv6 UDP套接字 with socket.socket(socket.AF_INET6, socket.SOCK_DGRAM) as sock: sock.settimeout(5.0) # 设置超时，避免无限等待 # 构建一个简单的NTP协议数据包（RFC 5905简化版） # 第一个字节：LI=0, VN=3 (NTPv3), Mode=3 (Client) ntp_packet = bytearray(48) ntp_packet[0] = 0b00100011 # LI=00, VN=011, Mode=011 # 发送请求 server_address = (server_host, port) sock.sendto(ntp_packet, server_address) print(f"已向 {server_address} 发送NTP请求") # 接收响应 data, address = sock.recvfrom(48) print(f"从 {address} 收到响应") # 解析NTP响应（简化解析，提取传输时间戳） # NTP时间戳从1900年1月1日开始，位于第40-47字节 if len(data) >= 48: transmit_timestamp = struct.unpack('!Q', data[40:48])[0] # 转换为Unix时间戳（从1970年开始的秒数） ntp_epoch = 2208988800 # 1900到1970的秒数差 unix_time = transmit_timestamp / 2**32 - ntp_epoch return unix_time else: raise ValueError("收到的NTP响应数据包长度不足") # 使用示例 try: current_ntp_time = get_time_via_ntp_v6() local_time = time.localtime(current_ntp_time) print(f"NTP服务器返回的UTC时间: {time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(current_ntp_time))}") print(f"转换为本地时间: {time.strftime('%Y-%m-%d %H:%M:%S', local_time)}") except socket.timeout: print("错误：连接NTP服务器超时，请检查IPv6网络连接。") except socket.gaierror: print("错误：无法解析服务器的主机名，请检查DNS或主机名拼写。") except Exception as e: print(f"发生未知错误: {e}")

代码要点解析：

1. socket.AF_INET6：这是创建IPv6套接字的关键参数。
2. sock.sendto()和sock.recvfrom()：用于无连接的UDP通信。对于TCP通信，你需要使用sock.connect()、sock.send()和sock.recv()。
3. 地址格式：在IPv6中，sendto和connect的目标地址是一个元组(host, port)，其中host可以是字符串形式的IPv6地址（如"2001:4860:4806::"）或域名。如果是字面量IPv6地址，通常需要用方括号括起来，但在Python的socket模块中，直接传递字符串即可，库函数会自行处理。
4. 错误处理：IPv6网络可能不如IPv4稳定，因此健壮的错误处理（超时、地址解析失败）尤为重要。

重要提示：如果你的设备只拥有链路本地（FE80::）或唯一本地地址（FD00::），那么它无法直接连接互联网上的IPv6服务（如time.google.com）。要测试公网IPv6通信，你的设备必须从路由器获取到一个全局单播地址（GUA，通常以2001:、2002:、2xxx:开头）。这需要你的家庭宽带和路由器支持并正确配置了IPv6。

5. 集成Adafruit IO获取网络时间

对于许多物联网项目，获取准确的网络时间（NTP）是必要功能，用于数据打时间戳、定时触发任务等。由于在微控制器上实现完整的时区、夏令时计算非常复杂，Adafruit提供了一个简便的替代方案：通过Adafruit IO的Web API来获取已转换好的本地时间。

5.1 配置Adafruit IO凭证

首先，你需要一个免费的Adafruit IO账户。访问io.adafruit.com注册。登录后，点击右上角的“My Key”获取你的用户名（AIO_USERNAME）和密钥（AIO_KEY）。

然后，将这些信息添加到你的settings.toml文件中：

CIRCUITPY_WIFI_SSID = "你的Wi-Fi名称" CIRCUITPY_WIFI_PASSWORD = "你的Wi-Fi密码" ADAFRUIT_AIO_USERNAME = "你的Adafruit IO用户名" ADAFRUIT_AIO_KEY = "你的Adafruit IO活跃密钥" # 时区可选，不设置则Adafruit IO会根据你的IP猜测 TIMEZONE="Asia/Shanghai"

时区字符串需要遵循IANA时区数据库的格式（如America/New_York,Europe/London）。你可以在worldtimeapi.org/timezones找到完整的列表。

5.2 编写时间获取脚本

以下脚本演示了如何连接Adafruit IO并获取格式化的本地时间：

import os import wifi import socketpool import adafruit_requests import ssl # 加载配置 ssid = os.getenv("CIRCUITPY_WIFI_SSID") password = os.getenv("CIRCUITPY_WIFI_PASSWORD") aio_username = os.getenv("ADAFRUIT_AIO_USERNAME") aio_key = os.getenv("ADAFRUIT_AIO_KEY") timezone = os.getenv("TIMEZONE", "UTC") # 默认使用UTC # 构建Adafruit IO时间API URL # fmt参数指定返回的时间格式：%Y年-%m月-%d日 %H时:%M分:%S秒.%L毫秒 %j年中日 %u周中日 %z时区偏移 %Z时区名 TIME_URL = f"https://io.adafruit.com/api/v2/{aio_username}/integrations/time/strftime" params = { "x-aio-key": aio_key, "tz": timezone, "fmt": "%Y-%m-%d %H:%M:%S.%L %j %u %z %Z" } # 简单拼接查询字符串（对于更复杂的参数，建议使用urequests的params功能，但adafruit_requests可能不支持） query_string = "&".join([f"{k}={v}" for k, v in params.items()]) full_url = f"{TIME_URL}?{query_string}" print("Adafruit IO 网络时间测试") print("="*40) # 连接Wi-Fi print(f"连接至网络: {ssid}") wifi.radio.connect(ssid, password) print(f"连接成功！IPv4地址: {wifi.radio.ipv4_address}") # 启用IPv6（可选） try: wifi.radio.start_dhcp_client(ipv6=True) print("IPv6已启用。地址列表:", wifi.radio.addresses) except Exception as e: print(f"启用IPv6时出错（可能不支持）: {e}") # 创建HTTP会话 pool = socketpool.SocketPool(wifi.radio) requests = adafruit_requests.Session(pool, ssl.create_default_context()) print(f"\n请求时间数据从: {TIME_URL}") try: response = requests.get(full_url) if response.status_code == 200: time_data = response.text.strip() print("="*40) print("Adafruit IO 返回的原始时间字符串:") print(time_data) print("="*40) # 简单解析示例 parts = time_data.split(' ') if len(parts) >= 1: date_time = parts[0] + ' ' + parts[1] day_of_year = parts[2] day_of_week = parts[3] # 1=周一, 7=周日 timezone_offset = parts[4] timezone_name = parts[5] if len(parts) > 5 else '' print(f"解析结果 -> 本地日期时间: {date_time}") print(f" 年中的第几天: {day_of_year}") print(f" 星期几 (1-7): {day_of_week}") print(f" 时区偏移: {timezone_offset}") print(f" 时区名称: {timezone_name}") else: print(f"错误: HTTP状态码 {response.status_code}") response.close() except Exception as e: print(f"获取时间失败: {e}") finally: print("\n测试结束。")

脚本工作流程：

1. 从settings.toml读取所有配置。
2. 连接Wi-Fi并可选启用IPv6。
3. 构建指向Adafruit IO时间服务的特定URL，其中包含了你的密钥、所需时区和时间格式。
4. 发起HTTPS GET请求。
5. 解析返回的文本响应。返回的格式如2023-10-27 14:30:15.123 300 5 +0800 CST，分别对应日期时间、毫秒、年中日、周中日、时区偏移和时区名。

优势与局限：

• 优势：极其简单，无需在设备端处理复杂的NTP协议和时区转换，所有计算由Adafruit IO服务器完成。
• 局限：依赖Adafruit IO服务可用性和网络连接。对于离线或高可靠性应用，仍需考虑在本地实现NTP客户端，并硬编码时区规则。

6. 常见问题排查与实战技巧

在实际开发中，你几乎一定会遇到网络连接问题。下面是我总结的一些常见错误场景和排查思路，以及几个提升稳定性的实战技巧。

6.1 连接类问题排查表

6.2 提升稳定性的编程技巧

1. 增加重试与退避机制：网络是不稳定的，一次连接失败不代表永远失败。

   import time max_retries = 5 retry_delay = 2 # 秒 for attempt in range(max_retries): try: wifi.radio.connect(ssid, password) print("Wi-Fi连接成功") break except Exception as e: print(f"连接尝试 {attempt + 1} 失败: {e}") if attempt < max_retries - 1: time.sleep(retry_delay * (attempt + 1)) # 指数退避 else: print("达到最大重试次数，连接失败。") # 进入深度睡眠或错误状态

2. 优雅的资源管理：使用with语句或try...finally确保网络套接字和响应对象被正确关闭，防止内存泄漏。

   # 使用 with 语句自动管理socket with socket.socket(socket.AF_INET6, socket.SOCK_DGRAM) as s: s.settimeout(5) # ... 使用 s ... # 离开with块后，s会自动关闭 # 对于requests响应，手动关闭 response = requests.get(url) try: # 处理响应 data = response.json() finally: response.close() # 重要！

3. 心跳与看门狗：对于需要长期运行的项目，实现一个简单的心跳机制，定期检查网络连接，并在连接丢失时尝试恢复。结合硬件看门狗定时器（如果ESP32固件支持），可以防止软件死锁导致的永久离线。

4. 优化内存使用：

   • 避免在内存中累积大量数据。对于大文件，考虑流式处理。
   • 及时使用del语句释放不再需要的大对象（如大的字节数组、字符串）。
   • 谨慎使用全局变量，尽量使用局部变量。

5. 安全存储敏感信息：重申settings.toml的重要性。对于生产环境，可以考虑对文件内容进行简单的混淆，或使用支持加密文件系统的更高端芯片。

网络编程是物联网项目的基石，从基础的Wi-Fi连接到IPv6这样的进阶特性，每一步都充满了细节。从配置一个正确的settings.toml文件开始，逐步测试连通性，再到谨慎地启用和测试IPv6，最后集成实用的网络服务，这个过程需要耐心和系统的排查。我个人的体会是，在嵌入式开发中，网络部分的调试时间往往比核心业务逻辑还长，因此建立一套清晰的诊断流程和健壮的错误处理机制，是项目成功的关键。当你看到设备第一次成功从云端获取到时间，或者通过IPv6与另一个设备直接通信时，那种成就感会让人觉得所有的折腾都是值得的。