本文为 W55RP20-EVB-Pico 模块 CircuitPython 教程专项篇，基于官方最新固件编写，代码均经过实际验证，可直接烧录运行。 版权声明：本文为 WIZnet 官方原创技术文章，转载请注明出处。

前言

上一篇教程中，我们已经完成了 UDP 组播 / 广播 开发，实现了局域网多设备批量通信。而在实际物联网项目中，设备除了需要局域网通信，还必须具备访问公网服务器的能力，这就离不开 DNS 域名解析功能。

当我们结合 WIZnet W5500 网络模块，CircuitPython 和树莓派 PICO 的开发潜力被进一步放大。这款模块内置了硬件 TCP/IP 协议栈，使得在嵌入式设备上实现网络连接、域名解析变得更加容易。无论是进行数据传输、远程控制，还是构建物联网应用，它们都提供了强大的支持。

本文将带你快速上手 W55RP20-EVB-Pico 模块的 CircuitPython 开发，重点实现 DNS 域名解析功能，学完本文，你将掌握：

• DNS 协议的核心原理与工作流程
• W55RP20-EVB-Pico 模块开发环境搭建与固件烧录
• 极简代码实现域名解析，将域名转换为 IP 地址
• DNS 解析的测试验证与常见故障排查
• WIZnet 硬件协议栈芯片的核心优势

系列教程学习路径

本专栏共 15 篇，循序渐进覆盖 W55RP20-EVB-Pico 模块 CircuitPython 开发全流程：

1.第 1 篇：静态 IP 配置与网络基础

2.第 2 篇：DHCP 自动联网与网络诊断

3.第 3 篇：TCP Client 客户端通信

4.第 4 篇：TCP Server 服务端通信

5.第 5 篇：UDP 单播数据通信

6.第 6 篇：UDP 组播/广播数据通信

7.第 7 篇：DNS 域名解析（本文）

8.第 8 篇：NTP 从网络获取时间

9.第 9 篇：HTTP Client 客户端请求

10.第 10 篇：HTTP Server 服务端搭建

11.第 11 篇：HTTP 协议与 OneNET 平台数据上云

12.第 12 篇：MQTT 协议基础通信验证

13.第 13 篇：MQTT 协议与阿里云平台对接

14.第 14 篇：MQTT 协议与 OneNET 平台对接

15.第 15 篇：MQTT 协议与 ThingSpeak 平台对接

16.第 16 篇：Modbus 工业协议通信

建议收藏本专栏，跟随教程逐步学习，所有代码均会同步更新至官方 Gitee 仓库。

目录

1. 准备工作

1.1 软件准备

1.2 硬件准备

2. 烧录 W55RP20-EVB-Pico 模块专属 CircuitPython 固件

3. 硬件连接与开发环境配置

3.1 硬件连接

3.1.1 基础连接（供电+调试）

3.1.2 以太网连接

3.1.3 模块与开发板接线

3.2 Thonny 开发环境配置

4. DNS 域名解析原理

4.1 DNS 协议简介

4.2 DNS 工作流程

4.3 DNS 核心优势

4.4 DNS 典型应用场景

5. 核心代码解析

5.1 完整代码        

5.2 代码关键步骤说明

6. 运行结果与测试验证

6.1 串口输出结果

6.2 DNS 解析验证方法

方法① 电脑 ping 解析后的 IP 地址

方法② 更换域名重新解析

7. 常见问题一站式排查指南

7.1 烧录相关问题

7.2 端口识别问题

7.3 网络连接与 DNS 解析问题

8. WIZnet 硬件协议栈核心优势对比

9. 典型应用场景

10. 系列预告与资源获取

10.1 系列预告

10.2 资源获取

1. 准备工作

1.1 软件准备

所需软件均为免费版本，按要求下载安装即可，无需额外付费。

软件名称	版本要求	下载地址	说明
Thonny	4.0 及以上	Thonny 官方下载	轻量级 CircuitPython IDE，支持代码编辑、烧录与串口调试，新手友好
W55RP20-EVB-Pico 模块 CircuitPython 固件	最新稳定版	WIZnet 官方固件下载	专为 W55RP20-EVB-Pico 模块 编写，已集成 WIZnet 硬件驱动与协议栈

1.2 硬件准备

• W55RP20-EVB-Pico × 1

• Circuit USB 数据线（必须支持数据传输，不能使用纯充电线）× 1

• 标准网线 × 1

• 开启 DHCP 功能的路由器 / 交换机 × 1（用于获取网络参数，实现 DNS 解析）

W55RP20-EVB-Pico 模块已集成以太网相关器件，无需额外焊接飞线，配合 RP2040 开发板可快速搭建开发环境，大幅降低接线错误和硬件故障概率。

2. 烧录 W55RP20-EVB-Pico 模块专属 CircuitPython 固件

W55RP20-EVB-Pico 模块 完全兼容树莓派 Pico 的 UF2 固件烧录方式，操作简单无需额外烧录器，新手可快速上手：

1. 按住 RP2040 开发板上的 BOOTSEL 按键不放；
2. 使用 USB 数据线连接开发板与电脑；
3. 待电脑识别出名为 RPI-RP2 的 U 盘后，松开 BOOTSEL 按键；
4. 将下载好的 W5500_RP2040_firmware.uf2 固件文件拖拽到 U 盘中；
5. 开发板会自动重启，固件烧录完成。

注意：如果电脑没有识别出 RPI-RP2 U 盘，请尝试更换 USB 数据线、重新插拔开发板，或更换电脑 USB 接口（优先使用 USB 2.0 接口）。

3. 硬件连接与开发环境配置

3.1 硬件连接

W55RP20-EVB-Pico 模块连接分为两步，分别实现供电/调试和以太网连接，操作简单，无需复杂接线：

3.1.1 基础连接（供电+调试）

使用 USB 数据线连接 RP2040 开发板与电脑，用于开发板供电、代码烧录和串口调试。

3.1.2 以太网连接

使用网线连接 W55RP20-EVB-Pico 模块的以太网接口与路由器的 LAN 口（或直接连接电脑网口，需手动配置电脑 IP 与开发板同网段）。

3.1.3 模块与开发板接线

若使用分离式模块与开发板，需按以下引脚对应连接（SPI 通信）：

【硬件预留】此处插入硬件连接示意图

3.2 Thonny 开发环境配置

打开 Thonny 软件，按以下步骤配置开发环境，确保代码能正常烧录和运行：

1. 点击顶部菜单栏「运行」→「配置解释器」；
2. 切换到「解释器」选项卡；
3. 在「解释器」下拉列表中选择 CircuitPython (通用)；
4. 在「端口」下拉列表中选择开发板对应的串口（通常显示为 Board CDC @ COMx）；
5. 勾选「运行代码前先重启解释器」和「同步设备的实时时钟」；
6. 点击「确定」完成配置。

如果端口列表中没有出现开发板，请尝试：

• 重新插拔 USB 数据线；

• 更换支持数据传输的 USB 数据线；

• 关闭其他占用串口的软件（如串口助手、Arduino IDE 等）；

• 重新烧录 CircuitPython 固件；

• 安装树莓派 Pico USB 驱动。

4. DNS 域名解析原理

4.1 DNS 协议简介

DNS，即域名系统，是因特网中的一项核心服务。它是用于实现域名和 IP 地址相互映射的一个分布式数据库，能够使用户更方便地访问互联网，而不用去记住能够被机器直接读取的 IP 数字串。

在互联网中，每台计算机都有一个唯一的标识，称为 IP 地址。然而，IP 地址是由数字组成的，不便于人们记忆。因此，我们通常使用域名来访问网站。

简单来说，DNS 协议的核心作用就是「将域名转换为 IP 地址」，相当于互联网中的「地址簿」，让人们通过易于记忆的域名，快速找到对应的网络设备。

4.2 DNS 工作流程

1. W55RP20-EVB-Pico 模块 实现 DNS 解析的完整工作流程如下：
2. 开发板上电 → 初始化 SPI 接口 → 激活 W55RP20-EVB-Pico 模块 网络模块；
3. 通过 DHCP 自动获取网络参数（IP 地址、子网掩码、网关、DNS 服务器地址）；
4. 用户输入目标域名，程序调用 DNS 解析函数；
5. 开发板向 DNS 服务器发送域名解析请求；
6. DNS 服务器查询域名对应的 IP 地址，返回解析结果；
7. 开发板接收解析结果，提取 IP 地址并打印，完成 DNS 解析；
8. 后续可通过解析得到的 IP 地址，实现 TCP/UDP 通信、网页访问等功能。

4.3 DNS 核心优势

• 易于记忆：人们通常更容易记住单词和短语组成的域名，而非复杂的数字 IP 地址；
• 灵活性高：网站可在不通知用户的情况下更换服务器 IP 地址，只需更新 DNS 服务器记录，用户仍可通过原域名访问；
• 负载均衡：DNS 可将一个域名解析为多个 IP 地址，实现多服务器负载分担，提升网站可用性和性能；
• 安全性强：通过 DNSSEC（域名系统安全扩展），可防止 DNS 欺骗攻击，保障解析结果的真实性。

4.4 DNS 典型应用场景

DNS 协议在物联网、嵌入式开发中应用广泛，主要包括：

• 网页浏览：通过域名访问网站，无需记忆 IP 地址；
• 电子邮件：邮件服务器通过 DNS 查询收件人邮箱服务器的 IP 地址；
• 网络通信：嵌入式设备通过域名解析，连接远程服务器（如物联网平台）；
• 在线游戏/网络电话：通过 DNS 解析游戏服务器、通话对方设备的 IP 地址；
• 云服务访问：通过域名访问 AWS、Azure 等云服务，无需关注云服务器 IP 变化。

5. 核心代码解析

W55RP20-EVB-Pico 模块 的 CircuitPython 库已经封装了所有底层细节，实现 DNS 域名解析仅需 X 行核心代码，无需编写复杂的底层驱动和协议解析逻辑。

5.1 完整代码        

以下代码可直接复制到 Thonny 中，烧录后即可运行，实现 DNS 域名解析功能：

import board
import bitbangio
import digitalio
import time
from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K

# 硬件配置
cs = digitalio.DigitalInOut(board.GP20)
rst = digitalio.DigitalInOut(board.GP25)

# 复位 W5500
rst.direction = digitalio.Direction.OUTPUT
rst.value = False
time.sleep(0.2)
rst.value = True
time.sleep(2)

# 软件 SPI
spi_bus = bitbangio.SPI(
    board.GP21,        # SCK
    MOSI=board.GP23,   # MOSI
    MISO=board.GP22,   # MISO
)

# 初始化网口（用DHCP自动获取IP）
print("初始化以太网...")
eth = WIZNET5K(spi_bus, cs)

print("本机 IP:", eth.pretty_ip(eth.ip_address))

# DNS 解析部分
domain = "www.baidu.com"
print(f"\n正在解析域名: {domain}")

try:
    ip_bytes = eth.get_host_by_name(domain)
    ip_str = eth.pretty_ip(ip_bytes)
    print("✅ 解析成功:", ip_str)

except Exception as e:
    print("❌ 解析失败:", e)

# 保持 DHCP 连接
while True:
    if hasattr(eth, "maintain_dhcp_lease"):
        eth.maintain_dhcp_lease()
    time.sleep(1)

以下是实现 DNS 域名解析功能过程：

5.2 代码关键步骤说明

网络初始化：

1. 初始化 SPI 接口，指定波特率和对应引脚，与硬件接线保持一致；
2. 创建 WIZNET5K 网络对象，绑定 SPI、CS、RST 引脚；
3. 优先尝试 DHCP 自动获取网络参数，失败则切换为静态 IP，提升兼容性；
4. 打印网络参数，便于调试；若未联网，打印寄存器信息辅助排查问题。

DNS 解析：

1. 调用 usocket.getaddrinfo 函数，传入域名和端口；
2. 提取解析结果中的 IP 地址，返回字符串格式，便于后续使用。

主函数：

1. 定义待解析的域名，可根据需求修改；
2. 调用网络初始化和 DNS 解析函数，打印解析结果；

6. 运行结果与测试验证

6.1 串口输出结果

在 Thonny 中点击运行按钮（或按 F5 键），Shell 窗口会输出类似以下内容，说明 DNS 解析成功：

初始化以太网...
本机 IP: 192.168.1.140

正在解析域名: www.baidu.com
✅ 解析成功: 183.2.172.177

说明：

• 若显示「Configuring DHCP」后长时间无反应，说明 DHCP 配置失败，会自动切换为静态 IP 配置；

• 解析后的 IP 地址可能因网络环境、DNS 服务器不同而略有差异，属于正常现象；

6.2 DNS 解析验证方法

解析完成后，可通过以下两种方式验证解析结果的正确性：

方法① 电脑 ping 解析后的 IP 地址

1. 打开电脑的命令提示符（Windows）或终端（Mac/Linux）；
2. 输入命令：ping 你的目标域名（如 ping www.w5500.com）； - 观察命令返回的IP地址是否与你预期的解析结果一致，同时看是否能收到正常回复。
3. 若收到类似以下回复，说明解析结果正确，网络连通正常：

来自 203.253.128.164 的回复: 字节=32 时间=50ms TTL=64 
来自 203.253.128.164 的回复: 字节=32 时间=48ms TTL=64 
来自 203.253.128.164 的回复: 字节=32 时间=52ms TTL=64

在实际测试中， ping 同一个域名时，收到的回复 IP 可能会出现变化，这是正常现象，并非解析错误：

1. 同一域名对应多个服务器地址大型网站 / 服务通常会部署多台服务器，并通过 DNS 轮询、CDN 或智能解析，将用户导向延迟最低、距离最近的节点，因此不同时间 ping 域名，返回的 IP 可能不同。

2. 域名解析的本质是 “域名→IP 映射”无论返回的 IP 如何变化，它们最终都指向同一个服务，所以你 ping 得到的 IP 不同，不代表解析结果错误，也不影响最终访问。

方法② 更换域名重新解析

修改 main 函数中的 domain 变量（如改为 "www.baidu.com"），重新运行程序，查看是否能正常解析出百度的 IP 地址，验证 DNS 解析功能的稳定性。

7. 常见问题一站式排查指南

开发过程中遇到问题，可按以下分类排查，快速解决问题。

7.1 烧录相关问题

问题现象	排查步骤
电脑无法识别 RPI-RP2 U 盘	1. 确认按住 BOOTSEL 按键再插入 USB 数据线； 2. 更换支持数据传输的 USB 数据线； 3. 更换电脑 USB 接口（优先使用 USB 2.0 接口）； 4. 尝试使用另一台电脑。
固件拖拽后开发板无反应	1. 确认下载的是 W55RP20-EVB-Pico 模块 专属固件，不是通用树莓派 Pico 固件； 2. 重新烧录固件，确保拖拽过程中数据线未断开； 3. 检查 USB 供电是否稳定，避免供电不足。

7.2 端口识别问题

问题现象	排查步骤
Thonny 中找不到开发板端口	1. 重新插拔 USB 数据线，确保连接牢固； 2. 关闭其他占用串口的软件（如串口助手、Arduino IDE 等）； 3. 在设备管理器中查看是否有 Board CDC 设备，若无则安装树莓派 Pico USB 驱动； 4. 重新烧录 CircuitPython 固件；5. 更换 USB 数据线或电脑 USB 接口。

7.3 网络连接与 DNS 解析问题

问题现象	排查步骤
长时间显示 "Configuring DHCP"，无法获取 IP	1. 检查网线是否插紧，网口指示灯是否闪烁； 2. 确认网线连接到路由器的 LAN 口，不是 WAN 口； 3. 确认路由器已开启 DHCP 功能； 4. 更换路由器 LAN 口或网线； 5. 重启路由器和开发板； 6. 切换为静态 IP 配置，手动设置网络参数。
IP 地址显示为 0.0.0.0	1. 执行上述网络连接排查步骤； 2. 确认代码中 SPI 引脚、CS 引脚、RST 引脚配置与硬件接线一致； 3. 确认使用的是 W55RP20-EVB-Pico 模块 专属固件； 4. 重新烧录固件，重启开发板。
DNS 解析失败，提示报错	1. 确认 DNS 服务器地址配置正确（DHCP 自动获取或静态配置）； 2. 检查开发板与 DNS 服务器的网络连通性（可 ping DNS 服务器地址）； 3. 确认域名输入正确（如无拼写错误、无多余空格）； 4. 更换公共 DNS 服务器地址（如 8.8.8.8、114.114.114.114）； 5. 检查网络是否正常，路由器是否能正常访问互联网。
电脑 ping 不通解析后的 IP 地址	1. 确认电脑和开发板连接到同一个路由器（同一网段）； 2. 关闭电脑的防火墙和杀毒软件； 3. 检查解析后的 IP 地址是否正确，是否与开发板打印的 IP 一致； 4. 重启开发板和电脑； 5. 检查网线连接是否正常，网口是否有故障。

8. WIZnet 硬件协议栈核心优势对比

为了让你更直观地了解 W5500 硬件协议栈芯片的价值，我们对比了目前主流的三种嵌入式以太网方案：

对比维度	W5500 硬件协议栈方案	外接 PHY 芯片方案	外接串口转以太网模块方案
BOM 成本	中（MCU + 网络模块，无需额外器件）	中高（MCU + PHY 芯片 + 外围器件）	高（MCU + 串口转网口模块）
PCB 面积	小（模块集成度高，仅需预留模块安装空间）	大（需预留芯片、布线空间及外围电路）	中（需预留模块安装空间）
开发难度	低（CircuitPython 固件已封装底层，一行代码实现联网）	中高（需调试协议栈、编写底层驱动，对研发能力要求高）	低（模块已集成驱动，仅需串口通信）
网络稳定性	极高（WIZnet 专注硬件 TCP/IP 协议栈 25 年，抗干扰能力强）	不定（依赖研发人员对协议栈和网络开发的掌握程度）	不定（视模块厂商研发能力和产品质量）
CPU 资源占用	0%（协议栈完全由硬件处理，不占用 MCU 资源）	50%以上（协议栈运行在 MCU 上，占用大量 CPU 和内存）	0%（模块独立处理网络逻辑）
硬件 Socket 数量	W5500 8个独立硬件 Socket	视 MCU 能力而定，理论支持多路拓展	一般为单路透传，多连接需额外配置
网络吞吐量	W5500 最高 15Mbps	视 MCU 能力而定，普遍低于硬件协议栈方案	约 3-5Mbps，速率较低
接口易用性	SPI 接口，接线简单，适配大多数 MCU	需 MCU 带有 MII/RMII 等专用接口，适配性有限	TTL 串口接口，适配性强，但速率受限
部署难度	低（CircuitPython 成熟固件，应用层协议均有库文件，可灵活部署）	高（应用层协议需要手动移植开源库适配，调试成本高）	中（无集成功能需自行封包拆包，灵活性不足）

9. 典型应用场景

W55RP20-EVB-Pico 模块，结合 CircuitPython 快速开发优势和 WIZnet 硬件协议栈的稳定性，非常适合以下嵌入式、物联网应用场景：

• 工业数据采集网关：简化现场部署，实现传感器、PLC 等设备数据的稳定上传；
• 远程监控终端：用于工厂、机房、变电站等环境的设备状态远程监控和数据传输；
• 串口转网口设备：将传统 RS232/RS485 串口设备（如仪表、传感器）快速升级为以太网设备；
• 物联网节点：用于智能家电、智能楼宇等设备的网络连接，实现远程控制和数据上云；
• 嵌入式学习开发：适合新手入门嵌入式网络开发，快速掌握 DNS、TCP/UDP、HTTP 等网络协议；
• 小型服务器：搭建简易 HTTP Server、TCP Server，实现设备间的局域网通信。

10. 系列预告与资源获取

10.1 系列预告

下一篇教程我们将讲解 W55RP20-EVB-Pico 模块 CircuitPython 开发下的 NTP 从网络获取时间实现，带你了解 NTP 协议原理、网络时间同步流程、本地时间校准、定时同步等关键机制，掌握嵌入式设备精准获取网络时间的核心能力，为后续日志打时间戳、定时任务执行、物联网设备时序控制打下基础。

10.2 资源获取