通过 Wi-Fi Developer Board 调试 Flipper Zero 固件：VS Code 全流程实战指南-育师

通过 Wi-Fi Developer Board 调试 Flipper Zero 固件：VS Code 全流程实战指南

【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware

Flipper Zero 的 Wi-Fi Developer Board（开发者板）本质上是一个调试探针，它在主机电脑上的 IDE/调试器与 Flipper Zero 内部的目标微控制器之间架起一座桥，让你可以在 VS Code 中像调试普通嵌入式程序一样，对 Flipper Zero 固件进行断点、单步、变量查看等操作。本文将基于仓库中的官方调试文档 Debugging via the Devboard，从环境准备、连接方式、调试模式切换，到 VS Code 调试会话的启动与源码级配置解析，完整讲解整套调试流程，并延伸覆盖日志读取与开发者板固件更新等配套操作。

调试架构概览：Developer Board 如何桥接 IDE 与 MCU

按官方文档的定位，Developer Board 扮演**调试探针（debug probe）**的角色，负责在两端之间转发调试协议：

主机侧：用户在连接到 Developer Board 的电脑上运行调试器（IDE），通过Wi-Fi或USB 线缆控制整个调试过程；
目标侧：Developer Board 与 Flipper Zero 之间通过Serial Wire Debug（SWD）接口交换数据，使用到 GPIO 排针上的两个引脚：
- Pin 10：Serial Wire Clock（SWCLK）——SWD 时钟线；
- Pin 12：Serial Wire Debug Data I/O（SWDIO）——SWD 双向数据线。

从源码结构看，仓库在 scripts/fbt_tools/blackmagic.py 中封装了 Black Magic 探针的配套构建/烧录逻辑，在 scripts/fwflash.py 与 scripts/wifi_board.py 中提供了固件烧录与开发者板相关的工具脚本；而 VS Code 调试依赖的 cortex-debug 配置模板位于 scripts/ufbt/project_template/.vscode/launch.json。下文会结合这些文件逐层展开。

开始前的准备

1. 在 Flipper Zero 上启用 Debug 模式

调试应用之前，需要先在 Flipper Zero 本机上开启 Debug 模式：进入Settings → System，将Debug设置为ON（详见 Get started with the Dev Board）。

[!note]每次更新 Flipper Zero 固件后，Debug 模式都需要重新开启。

Debug 模式开启后，你才能通过调试器访问应用的调试符号，并在应用 UI 与 CLI 中使用调试相关选项。

2. 安装 Git 并克隆固件仓库

调试面向的是固件源码，因此电脑上需要先安装 Git。然后打开Terminal（Linux/macOS）或PowerShell（Windows），在希望存放源码的目录中执行：

git clone --recursive https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware.git cd flipperzero-firmware

--recursive会一并拉取仓库依赖的 submodule（包括 FreeRTOS-Kernel、mbedtls、fatfs 等位于 lib 目录下的第三方库）。

3. 构建固件

在克隆得到的flipperzero-firmware目录下，使用Flipper Build Tool（FBT）构建固件：

./fbt

FBT 是仓库根目录下 fbt 入口脚本对应的构建系统（构建规则见 SConstruct 与 firmware.scons），首次运行会自动下载并校验 toolchain。构建产物中与调试直接相关的.elf文件（含完整调试符号）会被后续 VS Code 调试配置引用。

4. 更新开发者板固件（推荐）

开发者板出厂固件可能不含全部最新特性与修复，官方建议在首次使用前按 Firmware update on Developer Board 的步骤升级到最新版本，以确保调试功能的稳定性。

建立开发者板与电脑的连接

Developer Board 支持Wi-Fi与USB两种连接方式，两种方式的调试能力略有差异（详见下文“选择与切换调试模式”一节）。

Wi-Fi 连接：接入点（AP）模式（默认）

出厂状态下开发者板工作为 Wi-Fi 接入点。连接步骤如下（见 Wi-Fi connection to the Devboard）：

先关闭 Flipper Zero 电源，插上开发者板，再重新开机；
在手机/笔记本等客户端设备的 Wi-Fi 设置中连接开发者板创建的无线网络：
- 网络名（SSID）：blackmagic
- 密码：iamwitcher
浏览器访问开发者板 Web 管理界面：http://192.168.4.1 或 http://blackmagic.local。

找不到blackmagic网络怎么办？

尝试重置电脑的 Wi-Fi 连接；
开发者板很可能已被配置为 Wi-Fi 客户端（STA）模式——按住BOOT键10 秒重置为出厂设置，等待重启后即恢复 AP 模式。

AP 模式的缺点是：连接开发者板的 Wi-Fi 后，你的设备会暂时失去原有网络带来的互联网连接。

Wi-Fi 连接：客户端（STA）模式

如果你不希望断开互联网，可以让开发者板接入你现有的 2.4 GHz Wi-Fi 网络：

先按 AP 模式步骤连接开发者板并进入 Web 界面；
选择STA模式，输入你家网络的SSID与密码（可点+号扫描附近 2.4 GHz 网络，不支持 5 GHz）；
保存配置并重启开发者板；
此后即可通过现有 Wi-Fi 网络访问 http://blackmagic.local，同时保留互联网连接。

USB 连接

USB 连接用于 DAPLink 调试模式以及读取日志，步骤（见 USB connection to the Devboard）：

若开发者板尚未插在 Flipper Zero 上：先关机 → 插入 → 再开机；
在电脑上查看串口设备列表：macOS 执行ls /dev/cu.*，Linux 执行ls /dev/tty*，Windows 打开设备管理器 → 端口（COM 和 LPT）；
用 USB-C 线缆把开发者板连到电脑；
再次查看设备列表，出现两个新设备即代表开发者板已被识别。

[!warning] 若列表中看不到开发者板，请更换线缆、USB 口或电脑尝试。

选择与切换调试模式

开发者板支持Black Magic与DAPLink两种调试模式（详见 Devboard debug modes），可用模式取决于连接方式：

连接方式	可用调试模式	说明
Wi-Fi	仅 Black Magic	无线调试仅支持 Black Magic
USB	Black Magic（默认）/ DAPLink	可在 Web 界面中切换

[!note] Black Magic 模式不支持查看 RTOS 线程，但其他调试操作不受影响。

切换 USB 调试模式需要无线完成（你没看错），且要区分开发者板当前的 Wi-Fi 工作模式：

若开发者板未连接 Flipper Zero：先关机 → 插入 → 再开机；
按上文的 AP 或 STA 方式进入 Web 界面；
在WiFi标签页点击USB mode，选择BlackMagicProbe或DapLink；
点击SAVE保存，再点击REBOOT重启生效。

[!note] 切换后，记得在 VS Code 的Run and Debug面板中选择与之匹配的调试器，再点击 ▷Start Debugging。

在 VS Code 中调试固件

以下流程以核心文档 Debugging via the Devboard 为骨架，并结合仓库内真实的 launch.json 模板展开。

1. 安装推荐扩展

在 VS Code 中打开flipperzero-firmware目录后，通常会弹出推荐扩展通知，直接安装即可；若未弹出，可在Extensions标签页搜索栏输入@recommended，安装工作区推荐的扩展（调试依赖其中的 Cortex-Debug 扩展）。

2. 生成 VS Code 调试配置

运行 FBT 的配置生成命令：

./fbt vscode_dist

该命令会生成.vscode下的调试配置文件。仓库中同时提供了一份完整的参考模板 scripts/ufbt/project_template/.vscode/launch.json（由 ufbt 的vscode_dist按同样机制生成），其中预置了四种调试配置：Attach FW (ST-Link)、Attach FW (DAP)、Attach FW (blackmagic)与Attach FW (JLink)。

3. 选择调试器

打开Run and Debug标签页，从下拉菜单中按连接方式选择：

Attach FW (blackmagic)：支持Wi-Fi与USB两种连接；
Attach FW (DAP)：仅 USB连接可用。

通过 USB 调试时，必须确保所选的调试器与开发者板当前的 USB 调试模式一致：在开发者板 Web 界面（进入方式见上文 Wi-Fi 连接一节）查看USB mode字段即可确认当前模式；如需切换，按“选择与切换调试模式”一节操作。

4. 烧录固件并启动调试会话

必要时先用./fbt flash把刚构建的固件通过开发者板烧入 Flipper Zero；
点击调试侧边栏的 ▷Start Debugging启动调试会话；
注意：启动调试会立即暂停固件执行，需要点击顶部工具栏的 I▷Continue按钮让固件继续运行，随后即可在 VS Code 中设置断点、单步调试。

5. launch.json 源码级解析：Black Magic 配置做了什么

以仓库模板中的Attach FW (blackmagic)配置为例，其核心字段与启动命令说明了 Wi-Fi/USB 调试的底层机制（见 launch.json）：

{ "name": "Attach FW (blackmagic)", "cwd": "${workspaceFolder}", "executable": "@UFBT_FIRMWARE_ELF@", // 固件 ELF（含调试符号） "request": "attach", // 附加到已运行的目标 "type": "cortex-debug", "servertype": "external", // 复用外部 GDB 服务器 "gdbTarget": "${input:BLACKMAGIC}", // 由 ufbt get_blackmagic 探测探针地址 "svdFile": "@UFBT_DEBUG_DIR@/STM32WB55_CM4.svd", // SVD 外设寄存器描述 "rtos": "FreeRTOS", // 通过 FreeRTOS 插件感知 RTOS "postAttachCommands": [ "monitor swdp_scan", // 扫描 SWD 端口上的目标 "attach 1", // 附加到扫描到的目标（Cortex-M4 核心） "set confirm off", "set mem inaccessible-by-default off", "source @UFBT_DEBUG_DIR@/flipperversion.py", "fw-version", "source @UFBT_DEBUG_DIR@/flipperapps.py", "fap-set-debug-elf-root @UFBT_DEBUG_ELF_DIR@" // 绑定 .fap 应用调试符号 ] }

其中inputs段的BLACKMAGIC输入通过shellCommand.execute执行ufbt -s get_blackmagic，自动解析出 Black Magic 探针的 GDB 目标地址——这正是 Wi-Fi 与 USB 两种连接都能被同一个配置覆盖的原因。flipperversion.py/flipperapps.py由构建系统生成（对应构建产物中的调试辅助脚本），用于把固件版本与应用（FAP）的 ELF 符号注入调试会话，从而实现对固件与应用的双重符号级调试。

对比Attach FW (DAP)配置（见 launch.json）：它使用servertype: "openocd"+device: "cmsis-dap"，通过 OpenOCD 连接 DAPLink 探针，因此只适用于 USB 连接。

通过开发者板读取日志（USB）

除了断点调试，开发者板还能经 UART 直接读取 Flipper Zero 的日志。与通过 CLI 读日志不同，这种方式独立于 Flipper Zero 的操作系统，在设备启动、升级或崩溃时也能看到日志，非常利于开发期排障（详见 Reading logs via the Dev Board）。

NOTE:目前只有 USB 连接支持日志查看，Wi-Fi 查看日志将在后续版本提供。

设置日志级别

按需进入主菜单 → 设置 → 日志级别（Log Level）调整日志输出详略，之后再按平台读取。

通用第一步：冷插拔（cold-plug）

三种平台一致：先关闭 Flipper Zero → 插上开发者板 → 重新开机，然后用 USB-C 线把开发者板连到电脑，并在串口设备列表中确认两个新设备出现。

macOS：使用 minicom

安装 Homebrew 后执行brew install minicom；
查看串口设备：ls /dev/cu.*，记录连接开发者板后新出现的设备，例如：
```
/dev/cu.usbmodemblackmagic1 /dev/cu.usbmodemblackmagic3
```
（具体名称可能不同。）
用编号较大的设备作为端口，以230400波特率连接：
```
minicom -D /dev/cu.usbmodemblackmagic3 -b 230400
```
在终端查看 Flipper Zero 日志；退出时关闭窗口或经 minicom 菜单退出。

Linux：使用 minicom

安装：Ubuntu 等发行版执行sudo apt install minicom；
查看串口设备：ls /dev/tty*，连接后通常出现/dev/ttyACM0、/dev/ttyACM1；
用编号较大的设备连接：
```
minicom -D /dev/ttyACM1 -b 230400
```
NOTE:若终端无日志输出，尝试换用另一个设备名重跑上一条命令。
查看日志；退出时关闭窗口或经 minicom 菜单退出。

Windows：使用 PuTTY

安装PuTTY；
在设备管理器 → 端口（COM 和 LPT）中找到连接开发者板后新增的 COM 口；
打开 PuTTY，连接类型选Serial，在Serial line填入该端口号，Speed设为230400，点击Open；
在 PuTTY 终端窗口查看日志；退出直接关闭窗口。

开发者板固件更新

如需更新开发者板固件，官方流程（见 Firmware update on Developer Board）如下：

1. 安装 micro Flipper Build Tool（uFBT）

uFBT 是官方提供的跨平台轻量构建工具，支持构建/调试应用、烧录固件、生成 VS Code 配置以及给开发者板烧录固件。

Linux/macOS：先按 pipx 官方说明安装pipx并重启终端，再执行pipx install ufbt；
Windows：安装 Python 后，在 PowerShell 中依次执行py -m pip install --user pipx、py -m pipx ensurepath，重启 PowerShell，再执行pipx install ufbt。

2. 将开发者板切换到 Bootloader 模式

先查看串口设备列表（macOS：ls /dev/cu.*；Linux：ls /dev/tty*；Windows：设备管理器）；
用 USB-C 线连接开发者板与电脑；
进入 Bootloader 模式：按住 BOOT 键不放 → 按住的同时按下并松开 RESET 键 → 松开 BOOT 键；
再次查看串口设备列表，记录新出现的开发者板设备名。

3. 烧录固件

# Linux / macOS python3 -m ufbt devboard_flash # Windows（PowerShell） py -m ufbt devboard_flash

成功后会输出WiFi board flashed successfully。

烧录失败的常见错误与处理：

A fatal error occurred: Serial data stream stopped: Possible serial noise or corruption. FileNotFoundError: [Errno 2] No such file or directory: '/dev/cu.usbmodem01'

可尝试：拔下并重插开发者板，再次按第 2 步进入 Bootloader 模式；或更换电脑的 USB 口、更换 USB-C 线缆。

4. 完成安装

按RESET键重启开发者板，拔下并重新插上 USB-C 线缆，固件更新即完成。

通过 Wi-Fi Developer Board 调试 Flipper Zero 固件：VS Code 全流程实战指南