Birdiebot WiFi DAP 快速上手

本页只走最短路径：让第一个变量出现在曲线上。UART、Wi-Fi、OTA、烧录细节和进阶采样都放在完整手册里，先跑通再深入。

“打开设备面板”需先连上设备热点（默认 192.168.1.1）；默认 S3 固件同时支持有线 USB-NCM（192.168.7.1）和 Wi-Fi；有线口已启用 DHCP。还没连接请先看 0 准备 与 1 上电并连接。

整页路线：连接设备 → 打开面板 → 检测目标 → 上传 ELF → 选变量采样 → 看曲线并停止。每一步都给出可核对的界面状态；卡住了直接跳到 常见问题。

0 准备

第一次跑通只需要四样东西：

• DAP：Birdiebot WiFi DAP（8 MB Flash 发布版），已烧录固件。
• 目标板：一块 STM32 开发板（F1/F4/G4/H7 等常见系列可识别，烧录支持范围见 常见问题）。
• SWD 4 线：3V3、GND、SWCLK（GPIO12）、SWDIO（GPIO11）；务必共地，GPIO 电压为 3.3 V，不要接 5 V。目标板建议自供电，nRESET（GPIO13）可选。目标板丝印可能是 SWDIO/SWCLK 或 DIO/CLK，以原理图为准；只跑 SWD 时 JTAG 的 TDO/TDI 可以不接。
• 网络：2.4 GHz Wi-Fi 连接设备热点或接入实验室路由器；或一根可传数据的 USB-C 线走有线 USB-NCM（默认 S3 固件已内置，和 Wi-Fi 同一固件）。

两条连接路径按接入方式选一条（默认 S3 固件同时支持两者）：

1 上电并连接

1. 上电：USB-C 给 DAP 供电（或按板卡设计由目标板供电），等几秒让 Wi-Fi 启动；首次使用建议先只接 DAP，确认热点出现。
2. 无线连接：电脑或手机连接 Birdiebot-DAP-XXXX，输入密码 12345678，浏览器访问 http://192.168.1.1/。如果设备已接入路由器，STA 连上 30 秒后 AP 会自动关闭，这是正常行为；此时请用 Wi-Fi 页显示的 STA IP 访问。
3. 接入实验室 WiFi（可选）：保持上面的 AP 连接，进入 Wi-Fi 页 → 扫描/选择实验室 2.4 GHz SSID → 输入密码 → 保存并连接。设备会作为 STA 加入实验室网络，约 30 秒后关闭自己的 AP；在 Wi-Fi 页查看 STA IP，之后同一实验室网络中的电脑可直接访问该 IP 或 http://birdiebot-dap-XXXX.local/。
4. 有线连接（USB-NCM）：USB-C 连接主机，等待主机出现 NCM 网卡并自动取得 192.168.7.x（设备 DHCP）；若没有自动地址，手工配 192.168.7.2/24、网关留空兜底。先 ping 192.168.7.1，通了打开 http://192.168.7.1/。设备端固定 .1，不要把主机也配成 .1。
5. 首次设置：进入 Wi-Fi 页修改 AP 密码，或把设备接入自己的 2.4 GHz 网络；之后按分配的 IP 访问。非可信网络不要接入，也不要把调试口暴露到公网。

小提示：设备热点本身没有互联网，手机有时会自动切回移动数据导致页面一直转圈；连上 AP 后临时关闭移动数据，或确认浏览器仍走 Wi-Fi。

1.1 发现设备：mDNS / SSDP

连上同一局域网后，不一定每次都要记 IP。设备注册了 mDNS 主机名 birdiebot-dap-XXXX.local 和 _http._tcp 服务，也响应 SSDP（1900/UDP）。其中 XXXX 是该设备 STA MAC 最后两个字节的 4 位十六进制（与默认 AP SSID 的后缀一致；例如 MAC 末两字节是 CA:60，主机名就是 birdiebot-dap-ca60.local）。两种方式只用于“发现设备”，都不提供鉴权；不要在不可信网络依赖它们。

mDNS（推荐）

直接浏览器打开 http://birdiebot-dap-XXXX.local/。命令行验证：

# Linux（avahi）
avahi-browse -rt _http._tcp
getent hosts birdiebot-dap-XXXX.local

# macOS（Bonjour）
dns-sd -B _http._tcp
dns-sd -L "Birdiebot WiFi DAP" _http._tcp local

# Windows（装了 Bonjour/支持 mDNS 时）
ping birdiebot-dap-XXXX.local
Resolve-DnsName birdiebot-dap-XXXX.local

若主机名解析失败，直接用 Wi-Fi 页显示的 STA IP 或 AP 模式的 192.168.1.1；Windows 未安装 mDNS 解析器时只能走 IP/SSDP。

SSDP（UPnP 发现）

SSDP 地址是 239.255.255.250:1900。在 Linux/macOS/Windows 的 Python 3 中发送 M-SEARCH：

python3 - <<'PY'
import socket
msg = ('M-SEARCH * HTTP/1.1\r\n'
       'HOST: 239.255.255.250:1900\r\n'
       'MAN: "ssdp:discover"\r\n'
       'MX: 1\r\n'
       'ST: upnp:rootdevice\r\n\r\n')
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
s.settimeout(3)
s.sendto(msg.encode(), ('239.255.255.250', 1900))
try:
    data, addr = s.recvfrom(4096)
    print(addr)
    print(data.decode(errors='replace'))
except socket.timeout:
    print('no SSDP response: same L2 network / firewall 1900 UDP?')
PY

响应里的 LOCATION: http://<设备IP>/SSDP.xml 就是设备描述地址；用 curl 或浏览器打开即可查看型号、序列号与厂商信息。设备也支持直接 GET /SSDP.xml。Windows 防火墙、跨 VLAN、访客网络隔离都会阻止 SSDP/mDNS；这时改用 IP。

2 打开 Web 面板

浏览器打开设备地址后进入内嵌单页面板，默认落在 目标烧录 页（/#/target）。顶部主导航有 目标烧录 / 变量曲线 / UART / Wi-Fi / 更新 五个入口；更新页默认可用，移动端抽屉里还有“关于”。右上角绿色 已连接 表示浏览器已通过 WebSocket 连上设备，可以开始操作。

五个入口的分工：目标烧录负责 SWD 检测、烧录与首页状态总览；变量曲线负责 ELF 解析、采样与调试；UART 看串口；Wi-Fi 配网络；更新负责本地 OTA。它们共享同一条 WebSocket 连接。

状态总览与首次引导：目标烧录页顶部现在有 Dashboard，集中显示 DAP 会话、Wi-Fi SSID/RSSI/IP、目标状态和当前链路。首次打开会自动出现“连接 → 检测 → 加载 ELF → 采样 → 烧录”的引导，可跳过，也可从页面重新打开。

命令面板：按 Ctrl K（macOS 为 ⌘ K）打开全局命令面板，可快速切换页面、执行常用动作；它不搜索文档内容。

3 目标检测

1. 按 0 准备 接好 SWD 4 线，并给目标板上电。
2. 进入 目标烧录 页，点 检测目标。检测按钮旁可手动选择 SWD 时钟：默认“自动”（2 MHz → 1 MHz → 500 kHz 探测），也可固定 500 kHz/1/2/4/10 MHz；H7 长线或低电压目标建议先 1 MHz 或自动。该设置同时用于目标检测、Web 烧录和本地变量采样。
3. 确认芯片系列、自动匹配型号、Flash 大小和 UID；检测成功后，变量曲线页的“目标检测 / ELF 匹配”也会带出目标信息。

UID0 / UID1 / UID2 是 STM32 96-bit 唯一 ID 的三个 32-bit 字，每颗芯片不同，可用来区分同型号的多块板子。页面按 DEV_ID（器件组）+ FSIZE（Flash 容量） 自动匹配一个内置代表型号；候选型号组只表示可能的器件组，不能据此确定完整 order code。

同一张卡片还会列出 DEV_ID、CPUID、DBGMCU IDCODE 与 Flash 地址（STM32 通常为 0x08000000），可用来核对芯片和调试链路是否正常；点“复制诊断 JSON”可以把这些只读信息复制给开发者排查。

型号匹配是只读的：不需要你选择或上传 profile，页面也不显示置信度/限制说明区域。

识别失败先查接线与供电：4 线是否接反、GND 是否共地、目标是否上电、是否一次只接一个 SWD 目标；换板后重新点一次“检测目标”。识别成功但 supported=false 时仍可做变量曲线，只是不支持 Web 目标烧录。检测只需几秒，失败时按提示检查即可，不要沿用上一块板的型号信息。

4 上传 ELF

进入 变量曲线 页，在“上传 ELF”卡片点 上传 ELF，选择与板上固件对应的 .elf 文件（不是 .bin）。页面会解析 DWARF 调试信息，列出可采样变量、类型和地址；上传 ELF 只用于解析变量，不会烧录目标。

ELF 应与板上固件来自同一次构建；不匹配时页面会提示 ELF/目标固件范围不符。若目标已连接，曲线页顶部会显示检测到的型号与自动匹配结果，可先在这里核对。ELF 解析成功后，变量区会显示名称、类型和地址，可以按名称搜索、按函数或对象路径展开；源码/对象标签页还能直接浏览工程中的变量（详见完整手册）。

5 选变量并开始采样

1. 在变量列表里搜索、展开，勾选想看的变量。第一次建议选 几个到几十个，例如一个系统节拍、两三个传感器轴、一个 PID 输出。
2. 保持默认采样来源 设备本地（ESP32 闭环）、本地采样间隔 20 ms，点 开始采样。
3. 状态栏出现 采样中、实际采样率约 50 Hz、采样点持续递增，就说明第一个变量已经跑通。

默认值适合大部分场景：20 ms 约等于 50 Hz；固定地址/全局变量通常保持 Halt OFF，不会明显打断目标运行；带寄存器或栈帧的变量仍可能短暂暂停内核，属正常现象。需要更快时可以选 10 ms（约 100 Hz），但目标被 halt 的时间会增加。容量上限是 256 路；超过单组容量会自动分组，组数越多每组刷新率越低，所以日常建议几十路，不要一上来全选。采样来源也可以切到 Web-DAP，但设备本地模式通常更快，先用默认值即可。页面不会记住上一次的变量选择，刷新后需要重新加载 ELF 并勾选变量。

每条曲线现在还可在变量行里设置目标刷新率（÷1 / ÷2 / ÷4 / ÷8，对应 50 / 25 / 12.5 / 6.25 Hz 目标）。它通过分组权重实现，实际刷新率是相对份额，页面会以“≈”显示，不保证精确值。

6 看曲线与停止

• Y 轴：默认“共享 auto”，可切换归一化 0–100% 或对数。
• 时间轴：默认显示最近 20 s 并跟随最新；可用缩放与平移回看历史，关掉“跟随最新”即可暂停窗口滚动。
• 冻结显示：只暂停图表重绘，采样仍在继续，适合截图或读数；关闭后恢复实时。
• 停止采样：结束本地采样并释放 DAP，目标恢复运行；之后其它调试器或下一次曲线会话才能重新占用探针。

鼠标悬停可看当前时间戳与数值；图例可以单独显示/隐藏曲线（B 模式默认只绘制 64 条可见曲线，其余仍在后台采样）。需要留档时用顶部的 导出 CSV 或 导出 PNG。确认第一个变量符合预期后，就可以继续加变量、调采样率，或到 完整手册 查看触发、断点、录制回放等进阶用法。

如果停止采样后还要继续用 OpenOCD/USBIP 调试，记得重新 attach 探针；曲线页不会替你恢复旧的 USBIP 会话。

进阶调试能力也已扩展：Watchpoint 支持 read / write / readwrite 与第二个 comparator；调试面板增加 UART trace、帧指针 backtrace、函数快照等入口。它们属于完整调试功能，详见完整手册第 9 章；SWO / RTOS 任务感知尚未实现。

常见问题

下一步

常见问题优先看上一节；如果准备把 DAP 接入团队网络、用自动化脚本或排查协议问题，直接读开发者附录。