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

前言

上一篇实战教程，我们完成了W55RP20芯片HTTP 协议与 OneNET 平台数据上云。本篇内容我们聚焦轻量级物联网场景，实现W55RP20通过MQTT协议与MQTTX服务器对接，完成消息双向收发（订阅接收+发布反馈），掌握MQTTX服务器配置、MQTT连接配置、回调函数编写等核心技能，适配快速原型开发、本地调试、数据交互等各类轻量级物联网场景。

W55RP20集成硬件 TCP/IP 协议栈，搭配CircuitPython专属MQTT客户端（adafruit_minimqtt），通过CircuitPython编程即可实现与MQTTX服务器的稳定通信，无需关心底层Socket细节，依托WIZnet官方驱动库和MQTTX服务器规范，大幅降低嵌入式设备本地联网开发门槛，适用于环境监测、数据采集、原型验证、本地物联网调试等各类轻量级场景。

学完本文，你将掌握：

• W55RP20在CircuitPython环境下的引脚配置（CS、RST、SPI引脚）；

• MQTTX服务器的安装、配置与启动方法，获取MQTT连接核心参数；

• CircuitPython环境下adafruit_wiznet5k驱动库、adafruit_minimqtt库的安装与配置；

• W55RP20以太网初始化（DHCP自动获取IP）、MQTT客户端初始化与连接；

• MQTT回调函数（连接、断开、接收消息）的编写与调试；

• 消息双向收发逻辑实现，掌握“收到什么、发布什么”的回声功能；

• 串口调试与MQTTX客户端调试方法，快速定位连接失败、消息收发异常等问题。

传统MQTTX本地服务器IoT开发的3大痛点，W55RP20一键解决：

• 痛点1：底层网络编程复杂，新手难以上手——W55RP20集成硬件TCP/IP协议栈，CircuitPython驱动库已封装所有底层操作，无需编写Socket代码，一行代码即可完成以太网初始化；

• 痛点2：驱动库适配性差，频繁出现连接失败——使用WIZnet官方适配的adafruit_wiznet5k库，完美兼容W55RP20和CircuitPython环境，稳定性拉满，无需手动移植适配；

• 痛点3：调试繁琐，消息收发异常难以定位——代码自带详细打印日志，结合串口调试和MQTTX客户端，可一键排查连接、订阅、发布全流程问题，新手也能快速定位故障。

本节课核心目标：

1. 完成CircuitPython开发环境搭建，安装W55RP20所需依赖库（adafruit_wiznet5k、adafruit_minimqtt）；

2. 掌握W55RP20的引脚配置（CS、RST、SPI），完成以太网初始化与IP获取；

3. 实现与MQTTX服务器的连接、自动重连，掌握MQTT连接参数配置方法；

4. 编写MQTT回调函数，实现消息订阅接收，并完成“收到什么、发布什么”的回声功能；

5. 掌握串口调试与MQTTX客户端使用方法，排查各类常见问题，确保消息双向收发稳定。

系列教程学习路径

本专栏共 16 篇，循序渐进覆盖 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 硬件准备

1.3 MQTTX服务器准备（关键步骤）

2、W55RP20 CircuitPython开发环境搭建

2.1 驱动库与依赖库配置

2.2 固件烧录

3、硬件连接与串口配置

3.1 硬件连接

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

3.1.2 以太网连接

3.1.3 模块与开发板接线（分离式模块适用）

3.2 串口调试配置

4、MQTTX MQTT协议规范解析

4.1 核心连接规范

4.2 数据格式规范

4.3 标准主题格式

4.4 极简工作流程

5、核心CircuitPython代码复制与烧录

5.1 依赖库说明

5.2 完整CircuitPython代码（主程序）

5.3 代码关键配置说明（必看，否则连接失败）

5.4 编译与烧录步骤

6、运行结果与MQTTX服务器验证

6.1 串口输出结果

6.2 MQTTX服务器数据验证

7、常见问题一站式排查

8、W55RP20 核心优势对比

9、典型应用场景

10、系列预告与资源获取

10.1 系列预告

10.2 资源获取

1、准备工作

1.1 软件准备

所需软件均为免费版本，按要求下载安装即可，无需额外付费，适配CircuitPython开发需求，新增MQTTX服务器及调试相关工具。

1.2 硬件准备

所需硬件均为W55RP20开发常用配件，无需复杂器件，新手可直接采购套装，具体清单如下：

• W55RP20-EVB-Pico 开发板 1块（核心器件，集成W5500芯片和RP2040主控）；

• Micro USB 数据线 1根（用于供电、固件烧录和串口调试）；

• 网线 1根（用于连接开发板与路由器，实现以太网通信）；

• 电脑 1台（用于代码编写、固件烧录、串口调试和MQTTX服务器部署）；

• 路由器 1台（用于开发板与电脑、MQTTX服务器的局域网通信，确保设备在同一网段）。

1.3 MQTTX服务器准备（关键步骤）

在进行代码开发前，需先在电脑上完成MQTTX服务器的安装、启动和配置，获取MQTT连接所需的核心参数（服务器IP、端口、主题），步骤如下：

1. 下载并安装MQTTX服务器，打开软件后，点击“新建连接”，选择“服务器”模式，设置服务器名称（自定义，如W55RP20_MQTTX）；

2. 配置服务器参数：协议选择“MQTT”，端口默认1883（无需修改，MQTT默认端口），服务器IP为电脑本机IP（可通过cmd输入ipconfig获取，如192.168.1.100）；

3. 无需设置用户名和密码（简化调试，新手可关闭身份验证），点击“连接”，确认MQTTX服务器启动成功；

4. 创建两个主题（用于消息收发）：订阅主题（SUB_TOPIC，如w5500RP20/sub）、发布主题（PUB_TOPIC，如w5500RP20/pub），记录主题名称，后续用于代码配置；

5. 启动MQTTX客户端，新建客户端连接，参数与服务器一致，订阅上述SUB_TOPIC，用于接收开发板发送的消息，同时可向开发板发送消息，测试双向通信。

2、W55RP20 CircuitPython开发环境搭建

2.1 驱动库与依赖库配置

1. 下载W55RP20官方CircuitPython驱动库、adafruit_wiznet5k库和adafruit_minimqtt库，解压后得到核心文件；

2. 打开Thonny（推荐），新建项目，将W55RP20驱动库中的核心文件、adafruit_wiznet5k库（.h、.py文件）和adafruit_minimqtt库（.h、.py文件）放入项目根目录；

3. 配置Thonny开发环境，选择“解释器”，设置为“CircuitPython”，选择对应的W55RP20开发板（如WIZnet W55RP20-EVB-Pico），确保开发板能被正常识别；

4. 验证库配置：在项目中导入adafruit_wiznet5k和adafruit_minimqtt库，无报错即配置成功，可正常调用相关函数。

2.2 固件烧录

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

1. 下载W55RP20 CircuitPython专属UF2固件（从WIZnet官方下载，对应开发板型号）；

2. 将W55RP20开发板通过Micro USB数据线连接电脑，长按开发板上的BOOT键，同时重启开发板，此时电脑会识别出一个名为“RPI-RP2”的U盘；

3. 将下载好的UF2固件拖拽到“RPI-RP2”U盘中，固件会自动烧录，烧录完成后开发板会自动重启，此时固件烧录成功；

4. 打开Thonny，选择对应的解释器和串口，若能正常识别开发板，即可开始代码编写和烧录。

3、硬件连接与串口配置

3.1 硬件连接

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

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

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

3.1.2 以太网连接

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

3.1.3 模块与开发板接线（分离式模块适用）

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

3.2 串口调试配置

打开串口调试助手，按以下参数配置，用于查看开发板运行日志和调试信息：

1. 波特率：115200

2. 数据位：8

3. 停止位：1

4. 校验位：无

5. 流控：无

6. 选择开发板对应的串口（通常显示为 COMx），点击打开串口。

​

4、MQTTX MQTT协议规范解析

MQTTX服务器采用MQTT 5.0协议（与代码中adafruit_minimqtt库默认配置一致），基于发布/订阅模式实现设备与服务器的双向通信，与公共MQTT服务器相比，核心优势在于本地部署、延迟低、调试便捷，无上传间隔限制，适配本地物联网调试场景。

4.1 核心连接规范

• 协议版本：MQTT 5.0（adafruit_minimqtt库默认支持，无需手动配置）；

• 连接端口：默认1883（无加密端口，适合本地调试，无需额外配置SSL）；

• 服务器IP：电脑本机IP（局域网IP，如192.168.1.100，需与开发板在同一网段）；

• 身份验证：可关闭（简化调试），也可手动设置用户名和密码（代码中需对应配置）；

• 保活机制：代码中通过mqtt_client.loop()实现心跳保活，确保连接稳定，无需手动维护。

4.2 数据格式规范

MQTTX服务器对消息数据格式无严格限制，支持字符串、键值对、JSON等多种格式，本实战采用字符串格式，实现“收到什么、发布什么”的回声功能，示例如下：

接收消息："hello W55RP20" → 发布消息："hello W55RP20"

说明：代码中通过message回调函数接收订阅主题的消息，直接将消息原样发布到发布主题，无需复杂数据封装，适配快速调试需求。

4.3 标准主题格式

MQTTX MQTT通信的主题可自定义，无需遵循固定格式，只需确保开发板订阅的主题（SUB_TOPIC）与MQTTX客户端发布的主题一致，开发板发布的主题（PUB_TOPIC）与MQTTX客户端订阅的主题一致，示例如下：

​​

​​

• 订阅主题（SUB_TOPIC）：w5500RP20/sub（开发板订阅此主题，接收MQTTX客户端发送的消息）；

• 发布主题（PUB_TOPIC）：w5500RP20/pub（开发板发布消息到该主题，MQTTX客户端订阅此主题接收消息）。

代码中已封装好主题格式，只需替换为自己在MQTTX服务器中创建的主题名称，无需手动拼接，注意主题中无多余符号，自定义即可。

4.4 极简工作流程

1. 开发板初始化：完成W55RP20硬件初始化、SPI配置、以太网初始化，获取局域网IP；

2. MQTT连接：通过adafruit_minimqtt库初始化MQTT客户端，配置服务器IP、端口、主题，与MQTTX服务器建立连接；

3. 消息接收：开发板订阅指定主题，当MQTTX客户端发送消息到该主题时，通过回调函数接收消息并打印；

4. 消息发布：开发板将接收的消息原样发布到指定主题，MQTTX客户端订阅该主题，接收开发板反馈的消息，完成双向通信。

5、核心CircuitPython代码复制与烧录

5.1 依赖库说明

核心依赖3类库，无需额外添加MQTTX专用库，代码中已集成连接配置、回调函数和异常处理逻辑，直接关联到项目中即可使用：

• 基础库（time、board、bitbangio、digitalio）：CircuitPython自带，用于时间控制、引脚配置、SPI通信；

• adafruit_wiznet5k库：用于实现W55RP20硬件初始化、以太网连接、IP获取等功能；

• adafruit_minimqtt库：用于实现MQTT客户端的初始化、连接、订阅、发布、回调等功能，适配MQTT 5.0协议。

5.2 完整CircuitPython代码（主程序）

将以下代码复制到Thonny项目的主文件（如code.py）中，重点替换MQTTX服务器IP和主题名称，烧录到开发板后即可运行，代码注释清晰，关键配置部分已标注，可直接修改。

import time
import board
import bitbangio
import digitalio

from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K
from adafruit_wiznet5k.adafruit_wiznet5k_socketpool import SocketPool

import adafruit_minimqtt.adafruit_minimqtt as MQTT


print("===================================")
print(" W5500RP20 MQTT SUB/PUB Demo")
print("===================================")

# ------------------------------------------------
# W5500 Pins
# ------------------------------------------------
cs = digitalio.DigitalInOut(board.GP20)

rst = digitalio.DigitalInOut(board.GP25)
rst.direction = digitalio.Direction.OUTPUT

print("Reset W5500RP20...")

rst.value = False
time.sleep(0.2)

rst.value = True
time.sleep(2)

# ------------------------------------------------
# SPI
# ------------------------------------------------
print("Init SPI...")

spi_bus = bitbangio.SPI(
    board.GP21,
    MOSI=board.GP23,
    MISO=board.GP22
)

# ------------------------------------------------
# Ethernet DHCP
# ------------------------------------------------
print("Start DHCP...")

eth = WIZNET5K(spi_bus, cs)

print("DHCP Success")
print("IP Address:", eth.pretty_ip(eth.ip_address))

# ------------------------------------------------
# Socket Pool
# ------------------------------------------------
pool = SocketPool(eth)

# ------------------------------------------------
# MQTT Config
# ------------------------------------------------
MQTT_BROKER = "broker.emqx.io"
MQTT_PORT = 1883

SUB_TOPIC = "w5500PR20/sub"
PUB_TOPIC = "w5500RP20/pub"

# ------------------------------------------------
# MQTT Callback
# ------------------------------------------------
def connected(client, userdata, flags, rc):

    print("\n[ MQTT Connected ]")

    client.subscribe(SUB_TOPIC)

    print("SUB Topic:", SUB_TOPIC)
    print("PUB Topic:", PUB_TOPIC)


def disconnected(client, userdata, rc):

    print("[ MQTT Disconnected ]")


def message(client, topic, msg):

    print("\n========== SUB ==========")
    print("TOPIC :", topic)
    print("DATA  :", msg)

    # 收到什么 回什么
    client.publish(PUB_TOPIC, msg)

    print("========== PUB ==========")
    print("TOPIC :", PUB_TOPIC)
    print("DATA  :", msg)
    print("=========================")


# ------------------------------------------------
# MQTT Client
# ------------------------------------------------
mqtt_client = MQTT.MQTT(
    broker=MQTT_BROKER,
    port=MQTT_PORT,
    socket_pool=pool,
)

mqtt_client.on_connect = connected
mqtt_client.on_disconnect = disconnected
mqtt_client.on_message = message

# ------------------------------------------------
# Connect MQTT
# ------------------------------------------------
print("Connecting MQTT...")

try:

    mqtt_client.connect()

    print("MQTT Connected OK")

except Exception as e:

    print("MQTT Connect Failed:", repr(e))

    while True:
        time.sleep(1)

# ------------------------------------------------
# Main Loop
# ------------------------------------------------
print("MQTT Running...\n")

while True:

    try:

        mqtt_client.loop()

    except Exception as e:

        print("Loop Error:", repr(e))

    time.sleep(0.1)

5.3 代码关键配置说明（必看，否则连接失败）

• MQTTX服务器IP配置：必须替换为电脑本机的局域网IP（如192.168.1.100），确保开发板与电脑在同一网段（可通过路由器查看设备IP）；

• 主题配置：SUB_TOPIC和PUB_TOPIC需与MQTTX服务器中创建的主题完全一致，大小写、符号不可出错，否则无法接收或发布消息；

• 引脚配置：CS、RST、SPI引脚（GP20、GP25、GP21、GP23、GP22）需与硬件连接一致，若修改硬件接线，需同步修改代码中的引脚定义；

• DHCP配置：代码中默认使用DHCP自动获取IP，无需手动配置，若局域网未开启DHCP，需手动配置开发板IP（参考W55RP20官方文档）；

• 自动重连：代码中集成异常处理逻辑，当MQTT连接断开、循环出错时，会自动尝试重新连接，无需手动重启开发板；

• 回声功能：message回调函数中实现“收到什么、发布什么”，若需修改消息格式（如添加时间戳），可在client.publish()前修改msg内容。

5.4 编译与烧录步骤

1. 打开Thonny，将上述代码复制到code.py文件中，修改MQTT_BROKER（服务器IP）、SUB_TOPIC和PUB_TOPIC（主题）；​​​​

2. 确认开发板通过Micro USB数据线连接电脑，Thonny已识别开发板（解释器选择正确）；​​

3. 点击Thonny工具栏中的“保存”按钮，将代码保存到开发板（选择“W55RP20”对应的存储设备）；

4. 保存完成后，开发板会自动运行代码，打开串口调试助手，即可查看运行日志；​​

5. 若代码有修改，重复步骤1-3，重新保存即可完成烧录，无需额外操作。

6、运行结果与MQTTX服务器验证

6.1 串口输出结果

烧录完成后，开发板自动重启，打开串口调试助手，会输出以下内容，说明以太网初始化、MQTT连接及消息收发功能正常：

===================================
 W5500RP20 MQTT SUB/PUB Demo
===================================
Reset W5500RP20...
Init SPI...
Start DHCP...
DHCP Success
IP Address: 192.168.1.140
Connecting MQTT...

[ MQTT Connected ]
SUB Topic: w5500PR20/sub
PUB Topic: w5500RP20/pub
MQTT Connected OK
MQTT Running...


========== SUB ==========
TOPIC : w5500PR20/sub
DATA  : {"msg":"Hello"}
========== PUB ==========
TOPIC : w5500RP20/pub
DATA  : {"msg":"Hello"}
=========================

说明：若打印“MQTT Connect Failed”，属于正常现象，检查服务器IP、主题配置后，开发板会自动重试；若一直无法连接，参考“常见问题排查”部分。

6.2 MQTTX服务器数据验证

打开MQTTX客户端，连接到本地MQTTX服务器，订阅PUB_TOPIC（如w5500RP20/pub），同时向SUB_TOPIC（如w5500RP20/sub）发送消息，步骤如下：

1. 打开MQTTX客户端，新建连接，配置服务器IP（与代码中一致）、端口1883，点击“连接”；

2. 在客户端中，订阅主题w5500RP20/pub，用于接收开发板发布的消息；

3. 向主题w5500RP20/sub发送消息（如“hello W55RP20”）；

4. 观察串口调试助手，会打印接收的消息和发布的消息；同时观察MQTTX客户端，会收到开发板反馈的相同消息，说明双向通信成功。

至此，W55RP20的CircuitPython版MQTT协议与MQTTX服务器对接实战完成！

7、常见问题一站式排查

结合MQTTX本地服务器对接的特殊性（局域网连接、IP配置、主题匹配），以下是高频问题及排查步骤，优先排查连接参数和网络配置问题：

8、W55RP20 核心优势对比

为了让你更直观地了解 W55RP20 的价值，我们对比了目前主流的三种嵌入式以太网方案，适配CircuitPython开发场景：

9、典型应用场景

W55RP20 芯片集成以太网功能，结合CircuitPython的便捷开发特性和工业级稳定性，非常适合以下应用场景：

1. 本地物联网调试终端：用于MQTT协议验证、设备通信测试，快速原型开发，降低调试成本；

2. 工业数据采集网关：简化现场部署，实现传感器数据的本地存储和双向通信，适配工厂、机房场景；

3. 串口转网口设备：将传统 RS232/RS485 串口设备快速升级为以太网设备，实现本地网络通信；

4. 智能楼宇节点：用于照明、空调、门禁等楼宇设备的本地网络控制，响应速度快，延迟低；

5. 教育实训设备：适配CircuitPython新手入门，用于物联网、网络通信相关实训教学，操作简单、易上手。

10. 系列预告与资源获取

10.1系列预告

下一篇教程我们将讲解 W55RP20 CircuitPython开发下的 MQTT+阿里云实现上传数据，带你了解云平台连接建立、心跳包维护、异常重连等关键机制，掌握嵌入式以太网设备上云的基础能力，实现温湿度数据远程可视化。

10.2 资源获取

本文完整代码：WIZnet 官方 Gitee 仓库
W55RP20 芯片手册：WIZnet 官方资料网址

如果本文对你有帮助，欢迎点赞、收藏、关注，你的支持是我们持续更新的动力！如有任何问题，欢迎在评论区留言，我们会第一时间回复。