MicroPython 固件烧录指南：WeAct Studio RP2040 开发板的 UF2 Bootloader 部署全流程
  • 嵌入式
  • 语言运行时
  • 编程语言
  • 解释器
  • 编译器
  • 物联网
  • 系统编程

本文围绕 ports/rp2/boards/WEACTSTUDIO/deploy.md 这一部署文档展开，系统讲解如何将 MicroPython 固件烧录到 WeAct Studio RP2040 开发板：从 REPL 内执行machine.bootloader()与硬件 BOOTSEL 两种进入 bootloader 模式的方式，到 UF2 文件的获取、拷贝与自动复位机制，再到machine.bootloader()

的源码级实现原理。读完本文，你将掌握该开发板固件升级的完整闭环，并能根据板载 Flash 容量正确构建与部署对应版本的固件。

一、部署方式概览：为什么选择 UF2 Bootloader

WeAct Studio RP2040（常以 "Pico Board RP2040" 之名出现在各渠道）是基于树莓派 RP2040 双核 MCU 的开发板，板载 2/4/8/16 MiB 外部 Flash 与 USB-C 接口（见 board.json 中的 features 字段）。其固件部署采用 RP2040 原生 ROM bootloader 提供的UF2 协议：开发板无需任何专用烧录器或 SWD 调试线，只要通过 USB 连接主机，将编译产物firmware.uf2

拖拽到弹出的 U 盘即可完成烧录。这与树莓派 Pico 生态的部署方式完全一致，是 RP2040 平台最便捷的固件更新途径。

二、进入 Bootloader 模式的两种方式

要让板子进入等待固件更新的 bootloader 模式，原文档提供了两种等价手段：

方式一：REPL 内执行machine.bootloader()

如果板子上已经运行着 MicroPython（或任何可用 REPL 的固件），无需触碰任何按键，直接在 REPL 中执行：

import machine machine.bootloader()

该命令会立即使芯片重启并进入 UF2 引导模式。这是最干净的软件触发方式，适合远程操作或板卡被封装在机壳内、不便按键的场景。

方式二：硬件按键组合（BOOTSEL + NRST）

若板子上尚未烧录任何固件（或固件已损坏无法进入 REPL），则需要使用硬件方式：

  1. 按住 BOOTSEL 按钮；
  2. 同时按下复位按键（NRST）；
  3. 松开按键。

需要注意原文档在此处的细节描述——在 WEACTSTUDIO 板上是"按住 BOOTSEL 的同时按复位键（NRST）"，这与树莓派官方 Pico 的"按住 BOOTSEL 插入 USB"略有区别，原因在于该开发板的 BOOTSEL 与 USB 供电链路设计。两者本质都是让 RP2040 在启动阶段检测到 BOOTSEL 引脚被拉低，从而跳过 Flash 中的用户程序，直接运行 ROM 中的 USB bootloader。

验证是否进入 bootloader 模式

成功进入后，主机上会出现一个名为RPI-RP2的 USB 大容量存储设备（U 盘），其中包含INFO_UF2.TXT

等引导文件。看到这个盘符即代表板子已就绪，可以开始烧写固件。

三、UF2 固件文件的获取与构建

烧录所需的.uf2

文件来自 MicroPython 源码的 rp2 移植目录。通用构建流程见 ports/rp2/README.md：

cd ports/rp2 make submodules make clean make

构建完成后，固件位于 CMake 构建目录顶层（默认build目录），文件名为firmware.uf2

。

针对 WEACTSTUDIO 的板级构建

由于 WeAct Studio RP2040 存在 2/4/8/16 MiB 四种 Flash 容量版本，默认固件按 16 MiB 编译，其他容量需通过BOARD_VARIANT

参数指定（见 board.md）：

cd ports/rp2 make BOARD=WEACTSTUDIO BOARD_VARIANT=FLASH_8M submodules all # 构建 8 MiB 版本

BOARD_VARIANT的合法取值为FLASH_2M、FLASH_4M、FLASH_8M

，分别对应 mpconfigvariant_FLASH_2M.cmake、mpconfigvariant_FLASH_4M.cmake、mpconfigvariant_FLASH_8M.cmake 三个变体配置；不指定时使用默认的 mpconfigvariant.cmake（16 MiB）。

从这些 CMake 变体文件可以看出，不同变体不仅切换了 PICO SDK 的板级定义（如PICO_BOARD "weact_studio_rp2040_2mb"），还同步调整了 MicroPython 文件系统可用的 Flash 存储区大小MICROPY_HW_FLASH_STORAGE_BYTES

：

变体PICO_BOARD 定义文件系统存储区（字节）计算说明
默认（16 MiB）weact_studio_rp2040_16mb1572864016 MiB − 1 MiB
FLASH_2Mweact_studio_rp2040_2mb10485762 MiB − 1 MiB
FLASH_8Mweact_studio_rp2040_8mb73400328 MiB − 1 MiB

因此，务必选择与你的板卡实际 Flash 容量匹配的变体

进行构建，否则固件布局可能与硬件不符。

四、烧写流程与自动复位机制

拿到匹配的firmware.uf2

后，烧写本身只需三步：

  1. 按上文任一方式让板子进入 bootloader 模式，确认出现RPI-RP2USB 存储设备；
  2. 将firmware.uf2文件复制（拖拽）到该设备中；
  3. 等待拷贝完成。

整个流程中不需要任何额外烧录软件。RP2040 的 ROM bootloader 会解析 UF2 文件中的块（block）头信息，将固件逐块写入板载 Flash 的指定扇区，并在校验完成后自动复位芯片、重新启动。原文档特别强调了这一点："Once programming of the new firmware is complete the device will automatically reset and be ready for use."

——烧录完成即自动重启，无需手动断电，重启后便直接运行新固件，可通过串口 REPL 验证版本。

此外，ports/rp2/README.md 还给出了进阶部署路径：除拷贝 UF2 外，也可在 bootloader 模式下使用picotool load -x firmware.elf直接加载 ELF 固件，该命令可通过make deploy便捷触发；若板内已有 MicroPython，同样支持在 REPL 执行import machine; machine.bootloader()

进入引导模式。

五、源码级原理解析：machine.bootloader()

做了什么

理解烧录流程后，不妨深入 ports/rp2/modmachine.c 看一下machine.bootloader()

的真实实现，这能解释"为什么执行一条命令板子就变成了 U 盘"：

MP_NORETURN void mp_machine_bootloader(size_t n_args, const mp_obj_t *args) { MICROPY_BOARD_ENTER_BOOTLOADER(n_args, args); rosc_hw->ctrl = ROSC_CTRL_ENABLE_VALUE_ENABLE << ROSC_CTRL_ENABLE_LSB; reset_usb_boot(0, 0); for (;;) { } }

该函数的关键调用链分三步：

  1. 板级钩子：MICROPY_BOARD_ENTER_BOOTLOADER允许各板卡在进入引导模式前执行自定义动作（例如 WEACTSTUDIO 这类板卡若需要切换引脚状态或写标志位，可在此宏处扩展）；
  2. 时钟复位：直接操作 ROSC（环形振荡器）控制寄存器，将芯片时钟切回片上振荡器，为后续 USB 引导做准备；
  3. 进入 USB 引导：调用 Pico SDK 的reset_usb_boot(0, 0)，这是整个机制的落点——它把 RP2040 复位到 ROM 中的 USB bootloader，该 bootloader 随后枚举为RPI-RP2大容量存储设备并等待 UF2 文件。函数声明为MP_NORETURN并以死循环收尾，表明此调用不会返回，芯片已经完全切换到 bootloader 上下文。

从实现可以看出，"REPL 执行命令"与"按住 BOOTSEL 复位"殊途同归：前者通过软件调用reset_usb_boot()

重定向到 ROM 引导流程，后者通过硬件引脚状态让 ROM 在启动时直接进入同一流程。二者最终都落在 RP2040 的 USB UF2 引导程序上，这正是该平台部署机制高度统一的根源。

六、注意事项与排障建议

  • 识别 Flash 容量：WEACTSTUDIO 板卡外观相近但 Flash 容量可能不同，烧录前先确认变体选择。若误用 16 MiB 固件烧入小容量板卡，可能导致固件写入越界或文件系统空间异常。
  • 盘符未出现：进入 bootloader 后若无RPI-RP2盘符，请检查 USB 线是否为数据线（而非仅充电线），并确认 BOOTSEL 按键时机——务必在复位/上电之前保持按住。
  • 烧录完成自动重启：若拷贝完成后设备未自动复位，多为 UF2 文件损坏或固件与板型不匹配，可重新构建BOARD=WEACTSTUDIO的对应变体后再试。
  • 固件版本验证：重启后通过串口（默认 115200 波特率）连接 REPL，可立即验证新固件是否生效。

七、拓展：板载外设与board

模块

WEACTSTUDIO 板的固件还冻结了板级board

模块（见 modules/board.py 与 mpconfigboard.cmake），烧录完成后即可在 REPL 中直接驱动板载外设：

import board board.led.toggle() # 翻转板载 LED（GPIO25）状态 board.key.value() # 读取用户按键（GPIO23，内部上拉），返回 0 或 1

该模块与板级引脚映射 pins.csv（LED,GPIO25

）保持一致，可作为烧录成功后快速验证固件与板卡工作状态的第一手工具。

综上所述，WeAct Studio RP2040 的固件部署高度依赖 UF2 bootloader 的"拖拽即烧录"机制：进入引导模式有软件（machine.bootloader()）与硬件（BOOTSEL + NRST）两条路径，固件按 Flash 容量通过BOARD_VARIANT

精准构建，烧录完成后板卡自动复位即用。掌握这套流程，即可像升级普通 USB 设备一样完成 MicroPython 固件的迭代与维护。

赞分享
  • 嵌入式
  • 语言运行时
  • 编程语言
  • 解释器
  • 编译器
  • 物联网
  • 系统编程

相关推荐

上一篇：Linutil音频配置：从ALSA到PulseAudio的完美设置
下一篇：JavaScript原型链深入理解：Front-End-Interview-Notebook解析

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考