Birdiebot WiFi DAP 完整用户手册

1 产品与安全信息

1.1 它是什么，不是什么

Birdiebot WiFi DAP 的定位是“无线调试探针 + 自带 Web 管理面板”。设备本体是一块带 USB-OTG 的 ESP32 系列主控（当前发布版为 8 MB Flash；具体板级配置见开发者附录），通过 SWD/JTAG 连接目标 MCU；主机侧既可以用标准 CMSIS-DAP 工具链，也可以直接用浏览器完成大部分日常操作。

它不是 J-Link，也不是高速数据采集卡：变量曲线受 Wi-Fi 往返和目标暂停影响，不能等价于 J-Link HSS；Ozone 原生只支持 J-Link，本设备的 Ozone 虚拟 J-Link 路径仍是实验性功能。它也不支持多个目标同时调试，DAP 会话在同一时刻只服务一个客户端。

1.2 默认网络与“实验室模式”

默认固件是无登录、无鉴权、HTTP 明文的实验室模式。设备始终启用 Host/Origin 校验用于降低浏览器跨源攻击风险，但这不是身份认证，不能替代网络隔离。

1.3 电气与接线安全

• 电平：DAP 的 SWD/JTAG 与 UART 均为 3.3 V 逻辑，不要接 5 V 信号；目标板若为 5 V 系统，必须确认其调试口是 3.3 V 容忍或加电平转换。
• 共地：SWD 的 GND、UART 的 GND 必须与目标板共地；只接信号线不接地是最常见的“检测不到目标”原因之一。
• 供电：建议目标板自供电，DAP 由 USB 供电；不要用 DAP 的调试口给目标大电流供电，也不要把目标电源倒灌进 DAP。上电顺序建议先接好地线和信号线，再给目标上电。
• 复位：nRESET 为开漏模拟，目标板需要上拉；没有接 nRESET 时仍可通过 SWD 的 SYSRESETREQ 软件复位。
• USB：默认 S3 固件的 USB-NCM 与 USB-Serial/JTAG 不能同时工作；使用 NCM 时主机看不到 USB 串口是正常现象，不是变砖。

1.4 操作安全与互斥

• 单 DAP 会话：USBIP/OpenOCD/Ozone/Web 变量曲线/Web 目标烧录共享同一个 DAP，任意时刻只允许一个占用者。烧录或采样前先停止其它调试器。
• 烧录期间：不要刷新页面、断开 USB/Wi-Fi 或同时使用 OpenOCD；目标烧录当前不提供页面中止按钮。失败后先重检测，再决定是否重试。
• OTA：只上传应用 .bin，不要上传 merge 全量包或 zip；OTA 无签名、无防降级，只从可信主机操作。
• 曲线采样：设备本地周期采样会按配置暂停/恢复目标，高频或长时间采样会影响目标实时性；调试控制环时优先固定地址 + 低采样率。
• 无线环境：2.4 GHz Wi-Fi 干扰会直接影响采样率、烧录速度和 DAP 稳定性；对速度敏感时使用有线 NCM。

1.5 不要声称的能力边界

2 硬件连接

2.1 两套接入方式怎么选

两种接入共用完全相同的 Web UI 与 DAP 协议。速度数字来自 STM32H723/345 KB 镜像的实测记录，换目标、换主机、换 Wi-Fi 环境都会变化，不应作为 SLA。

2.2 无线连接：AP 与 STA

设备默认工作在 Smart APSTA：AP 热点一直可用；设备作为 STA 连上路由器后，30 秒后关闭 AP；STA 掉线 10 秒后重新开启 AP。因此在 STA 已连接时找不到热点是正常行为，不代表设备坏了。

1. 上电，等待约 5–15 秒。默认板 Wi-Fi 状态灯 GPIO4 在 STA 获取 IP 后点亮。
2. 主机/手机搜索 SSID Birdiebot-DAP-XXXX，其中 XXXX 是设备 STA MAC 末 2 字节的大写十六进制。默认口令 12345678。
3. 连上后浏览器打开 http://192.168.1.1/。若设备已通过 Wi-Fi 页接入路由器，则改访问路由器分配给它的 IP；也可尝试 mDNS 主机名 birdiebot-dap-XXXX.local。
4. 进入 Wi-Fi 页可扫描、连接局域网、保存多个网络。设备最多记忆 8 个网络，并按“上次成功 → 优先级 → 最近成功”的顺序自动轮换重连。

2.3 有线连接：USB-NCM（默认 S3 固件）

iC1 是项目内部对 USB-NCM 有线链路的代号；它不再是独立发布硬件或独立固件，默认 S3 固件同时包含 NCM 与 Wi-Fi。

有线模式需要主控原生 USB-OTG 引脚接到 USB 口；默认 S3 发布固件已经包含 USB-NCM 与 Wi-Fi，无需再刷单独 wired 构建。旧 scripts/build-wired.sh / sdkconfig.wired.defaults 保留为兼容/精简构建。NCM 与 Wi-Fi 在同一固件中同时可用。

Windows 10/11

1. 用 USB 数据线连接设备。系统应自动加载 USB NCM 驱动并出现新的以太网适配器。
2. 先等待系统通过 DHCP 自动取得 192.168.7.x；若没有自动地址，再在“网络适配器 → IPv4”中静态设置 192.168.7.2、掩码 255.255.255.0，网关留空。
3. 执行 ping 192.168.7.1；安装 usbip-win 0.3.x，执行 usbip.exe attach_ude -r 192.168.7.1 -b 1-1。设备管理器会出现 CMSIS-DAP（VID:PID = C251:F00A）。

Linux

内核通常自动创建 enx* 或 usb0 接口，并直接通过 DHCP 取得地址；没有自动地址时再静态兜底，然后 attach：

# 优先等待 DHCP；若未自动取址，再静态兜底：
sudo ip addr replace 192.168.7.2/24 dev enxXXXXXXXXXXXX
sudo ip link set enxXXXXXXXXXXXX up
ping -c 3 192.168.7.1
sudo usbip attach -r 192.168.7.1 -b 1-1

如果使用 NetworkManager，通常直接 DHCP 即可；只有 NM 清空兜底静态地址时才需要把该接口设为 unmanaged（nmcli device set enx... managed no）。设备经 OTA 重启后主机偶尔会保留旧的 USB 设备对象；物理拔插一次，或重新绑定对应 xHCI 控制器即可。

2.4 SWD/JTAG 引脚与接线

下表是默认发布板的参考引脚；引脚不是焊死的——换板/改 IO 时修改 components/board/boards/*.h 的 PIN_* 宏并通过 Kconfig 选板即可（详见开发者附录 §3.7）。公版接线以 docs/board-pins.md 和实际板文件为准，不要凭旧版 ESP8266 资料接线。

SWD 最少四根线：SWCLK、SWDIO、GND，以及目标板自身的供电。需要硬复位时再增加 nRESET。JTAG 需要 TCK、TMS、TDI、TDO 与 GND，nTRST 可选但当前不驱动。接线尽量短，SWD 线不要与电机驱动、开关电源或大电流走线并行。

DAP 默认 SWD 时钟为 2 MHz，Web 目标烧录页的检测卡片可手动选择“自动 / 500 kHz / 1 / 2 / 4 / 10 MHz”；该选择同时作用于 Web 目标检测、Web 烧录和本地变量采样。OpenOCD 等外部工具仍可在目标配置之后用 adapter speed 覆盖。遇到长线、干扰或低电压目标时先降到 1 MHz 或更低。

2.5 UART 接线

UART 桥使用 UART1，默认 115200 8N1。注意“TX 接 RX、RX 接 TX”：

• DAP GPIO10（UART1 TX）→ 目标 RX
• DAP GPIO9（UART1 RX）← 目标 TX
• GND 与目标 GND 共地；目标 3.3 V 逻辑

控制台 UART0 是另一组引脚（默认 GPIO43/44，115200，可按板级配置修改），只用于固件启动日志，不会被 Web UART 或 TCP 1346 占用。调试目标串口时要把目标接到 GPIO10/9，而不是 GPIO43/44。

2.6 供电、共地与接口速查

上电后的快速自检：设备指示灯是否正常、能否搜到 AP、Web 页面是否打开、About 页是否显示协议匹配、UART 页是否可启停、目标检测是否返回 DEV_ID。任何一项失败，先查接线与供电，再查网络。

3 首次使用与快速开始

3.1 开箱检查

• DAP 板、USB 数据线（能传数据，不是纯充电线）、目标板、SWD 杜邦线。
• 目标板供电与调试口定义（3.3 V、GND、SWCLK、SWDIO；需要时加 nRESET）。
• 一台带 Wi-Fi 的电脑/手机；有线模式还需 USB-NCM 驱动与 usbip 客户端。默认 S3 固件已内置 NCM，不需要额外刷 wired 固件。
• 浏览器使用 Chrome、Edge、Firefox 或 Safari 的较新版本；不支持过旧的 IE。

3.2 六步完成第一次连接

1. 接目标：按第 2 章接好 SWD 四线并共地，目标板上电。先不接 USB，检查没有短路。
2. 给 DAP 上电：USB 线连接 DAP 与主机。等待设备启动，默认板 Wi-Fi 灯在 STA 获取 IP 后亮起。
3. 接入网络：无线模式下连接 SSID Birdiebot-DAP-XXXX（口令 12345678）；有线模式等待主机 DHCP 自动取址（兜底静态 192.168.7.2/24），确认能 ping 192.168.7.1。
4. 打开 Web：无线 AP 模式访问 http://192.168.1.1/；有线模式访问 http://192.168.7.1/；设备接入路由器后访问其 STA IP。页面默认进入目标烧录页。
5. 确认版本与连接：右上角状态应为“已连接”；进入“关于”页确认协议匹配，记下固件/Web UI 版本与 SN。
6. 做一次目标动作：到“目标烧录”页点“检测目标”，或在 UART 页选择正确波特率后点“开始数据收发”。有 DEV_ID 或串口输出，即第一条链路打通。

3.3 首次连通检查清单

3.4 接下来做什么

4 Web 界面与通用操作

4.1 页面地图

本手册是静态文档；设备内嵌的 Web UI 是另一套页面（路径带 #/）。两者都有顶部导航和深色主题，但功能不同。设备 UI 默认进入目标烧录页（/#/target），桌面顶部主导航提供目标烧录 / 变量曲线 / UART / Wi-Fi / 更新五个入口，移动端抽屉里还有“关于”。更新页默认启用。

4.1.1 状态总览、首次引导与命令面板

• 状态总览 Dashboard：目标烧录页顶部集中显示 DAP 状态/会话、Wi-Fi SSID/RSSI/IP、目标检测信息和当前链路（Wi-Fi 或 USB-NCM）。
• 首次使用引导：首次打开自动出现“连接 → 检测 → 加载 ELF → 采样 → 烧录”的引导，可跳过，也可从页面重新打开；引导只做提示，不会自动执行危险操作。
• 全局命令面板：按 Ctrl K（macOS 为 ⌘ K）打开，可搜索页面与动作；它不搜索文档内容。

4.2 顶部栏与连接状态

• 品牌区：左侧图标与产品名，移动端点击可回到首页；品牌下方小字显示当前页面。
• 连接状态：绿色“已连接”表示 WebSocket 正常；黄色“连接中”表示正在建立或刚加载；红色“未连接”表示断线。状态同时显示在移动端抽屉顶部。
• 语言：中文/English 切换，选择会保存在浏览器本地；切换后当前页面文案即时更新。
• 主题：太阳/月亮图标切换深色/浅色，偏好保存在本地。设备 UI 深色优先。
• 全屏：移动端抽屉里提供全屏/窗口切换，适合手机看曲线。
• 搜索：本手册页面顶部提供章节搜索（Ctrl K）；设备 UI 另有全局命令面板（Ctrl K），可搜索页面/动作，但不搜索文档内容。

连接状态来自单条 WebSocket 连接（ws://设备IP/ws）。固件每 1.5 秒发送心跳，前端超过约 2 秒收不到任何消息就判定断线。断线时页面仍能显示已加载的数据，但所有控制操作会失败；先恢复网络再刷新页面。

4.3 信息图标、标签与表格

页面中大量出现圆形的小 i 图标。它不是装饰：鼠标悬停会显示说明，单击可把说明钉住，点击页面其它位置关闭；触屏上直接点按即可。看到不熟悉的字段、采样率、Halt、Out of scope、组权重等，先点它。

设备多数表单是“本地编辑 + 显式保存”：改完输入框后必须点“保存/连接/开始”，不会自动生效；Wi-Fi 切换尤其注意，可能导致页面立即断线。

4.4 桌面与手机布局

桌面端顶部显示全部主入口，右侧显示语言、主题和连接状态；窗口宽度小于约 980 px 时，左上角出现“目录/菜单”按钮，侧栏改为抽屉，顶部只保留当前页面与状态点。变量曲线页在窄屏下默认折叠“更多控件”中的高级区域，图表支持单指平移、双指/滚轮缩放。

手机端建议：横屏看曲线、关闭系统省电模式、保持页面在前台；iOS/Android 浏览器在后台会节流定时器，采样统计和曲线刷新会变慢，但设备本地采样仍在运行，返回前台后恢复显示。

4.5 通用故障处理

• 页面能打开但操作 403：Host/Origin 校验拦截。用 IP 地址访问；或把使用的主机名加入固件允许来源。403 不是登录失效。
• 页面空白/样式错乱：强制刷新、清缓存，确认固件内嵌 Web 资源与当前固件版本匹配。
• 协议不匹配：刷新网页；仍不匹配说明网页/固件版本差距过大，需升级固件或重新构建。
• 状态一直红色：检查是否连错 AP、设备是否重启、是否有另一个页面占满连接；刷新页面。
• 找不到按钮：窄屏下先展开抽屉或“更多控件”；更新页默认存在，只有显式裁剪 OTA 的构建才没有。

5 目标检测与烧录

5.1 检测目标：能看到什么

点击“检测目标”，设备通过 SWD 读取目标调试信息。一次只探测一个目标；换板后必须重新检测。检测卡片旁有 SWD 时钟选择：默认“自动”（2 MHz → 1 MHz → 500 kHz 探测），也可固定 500 kHz / 1 / 2 / 4 / 10 MHz；该设置同时作用于目标检测、Web 烧录和本地变量采样。长线、低电压或干扰环境建议先用自动或 1 MHz，不要承诺 4/10 MHz 一定可用。检测成功后页面显示以下只读字段：

检测失败时页面会提示“未检测到目标芯片，请检查接线与供电”。常见原因按顺序排查：目标未上电、未共地、SWDIO/SWCLK 接反、nRESET 被拉低、目标处于低功耗/安全启动状态、SWD 时钟过高、DAP 正被另一个会话占用。

5.2 内置 profile 自动匹配

STM32 的 DBGMCU_IDCODE 只有 DEV_ID（器件组）和 REV_ID；SWD 还能读 CPUID、UID、FSIZE 和 Flash 基地址。设备把 DEV_ID + FSIZE 两个条件同时匹配到内置只读 profile，才给出“芯片型号”的代表值；匹配不到时显示“未知”，不会猜测其它容量或器件组。

例如 DEV_ID 0x410 + 64 KiB 会匹配 F103C8T6；DEV_ID 0x483 + 1 MiB 会匹配 H723VGT6；DEV_ID 0x450 + 2 MiB 会匹配 H743VIT6。若 DEV_ID 不在表内、FSIZE 读不到，或该组合没有内置项，就显示未知，但仍会显示检测到的系列/DEV_ID/Flash/UID。

5.3 烧录支持矩阵

“代码支持”表示该家族的擦除/编程序列已实现并通过 host 测试与固件编译；“已实机”表示有现场硬件回归记录。新增家族即使代码支持，也可能尚未覆盖所有容量/双 bank 形态，第一次使用请先烧小镜像并回读校验。

明确不支持烧录（只识别/只显示边界）

当 supported=false 时，页面会禁用“开始烧录”并提示“该芯片系列可识别，但暂不支持烧录”。此类目标仍可用于变量曲线和识别，不要尝试用其它家族的镜像强行烧录。

5.4 选择固件与镜像转换

支持 .bin、.elf/.out、.hex/.ihex、.srec/.s19/.mot。浏览器会先解析并转换成“从目标 Flash 基地址开始的裸镜像”，再计算 SHA-256；设备端只接收裸镜像。

• BIN：原样使用，默认从 0x08000000 开始；必须与目标链接地址一致。
• ELF/OUT：只取 PT_LOAD 中落在目标 Flash 范围的段；RAM-only 段和调试信息会被忽略。页面会显示忽略的段数。
• Intel HEX / S-Record：解析地址记录、校验和，合并数据块；地址必须在目标 Flash 范围内。
• 空隙：镜像内未覆盖的字节按规则填充——一般填 0xFF（擦除态），HEX/SREC 的小对齐间隙可能填 0x00；页面会统计填充字节。
• 大小：镜像不得超过目标 flash_size；页面显示 Flash 占用百分比。超过时禁用烧录。
• SHA-256：浏览器计算源文件哈希，设备写入后再计算实际镜像哈希；两者用于核对。

5.5 烧录流程

1. 检测：确认目标已识别且支持烧录；记下 DEV_ID、Flash 大小和 UID0/1/2。
2. 选文件：点“选择固件文件”，等待解析/转换完成；核对格式、镜像大小、Flash 占用、段数、SHA-256。
3. 确认：检查“开始烧录”按钮可用（目标 detected、supported 不为 false、文件转换成功、哈希已算完）。
4. 开始：点击后确认弹窗，设备先获取 DAP、探测、擦除、分块写入，再回读校验。页面显示浏览器上传进度与设备状态（如 ERASE/PROGRAM/VERIFY）。
5. 等待：不要刷新页面、不要断开 USB/Wi-Fi、不要启动 OpenOCD。烧录期间其它 DAP 请求会失败。
6. 结果：成功后页面显示写入字节数、系列/型号、IDCODE、UID 与 SHA-256；需要看新固件运行时点“复位目标”。

如果烧录失败，页面会显示错误标题和技术细节。先记录错误文本与当前目标/镜像信息，再按 5.7 节处理；不要连续盲目重试。

5.6 校验（Verify）与结果判读

Web 目标烧录没有单独的“Verify”按钮，但流程末尾包含设备端回读校验：写入完成后读取目标 Flash 并与镜像计算 SHA-256 比对，结果中的 SHA-256 应与浏览器显示的源文件哈希一致。若不一致，页面会报失败，目标可能无法启动。

另外两条验证路径：

• OpenOCD：使用 verify_image app.bin 0x08000000 或 flash write_image erase app.bin 0x08000000; verify_image app.bin 0x08000000。
• 变量曲线页：“目标检测 / ELF 匹配”卡片提供“验证 ELF/目标固件”按钮。它用 no-halt 单变量采样读取 ELF 首个 PT_LOAD Flash 段前 4 字节并与 ELF 文件比较；采样中需先停止。这个校验是快速一致性检查，不是整镜像校验。

5.7 常见失败与处理

6 UART、WiFi、OTA、设备管理

6.1 Web UART 终端

UART 页用于看目标日志、发 AT 指令、做二进制协议调试；它不是默认首页，默认首页是目标烧录页。页面分为设置窗（左）、数据窗（中）、快捷窗（右），可通过“布局”按钮切换横/竖排、自适应和面板显隐。

收发配置

• 接口/端口：当前固件提供一个 UART 实例（UART1，GPIO10/9）。
• 波特率、数据位、校验、停止位、流控：默认 115200-8N1；必须与目标一致。修改后需要重新启停或按页面提示应用。
• 开始/停止数据收发：数据窗的启停按钮控制接收显示；停止后后台仍可能接收，恢复时注意缓存。
• 发送格式：文本或 HEX；文本支持 \n、\xNN 转义；HEX 模式只接受合法十六进制，错误会提示。
• 循环发送：设置周期（ms）后重复发送；实际频率受界面刷新率影响，需要精确节拍时关闭自动刷新。
• 缓存帧数/清屏/自动刷新：缓存用于回看；“清空”只清显示，不改变设备端数据。

显示与断帧

• 显示模式：文本、HEX、HEXDUMP；时间戳、自动换行、接收/发送高亮、ANSI 转义解码、过滤。
• 断帧策略按优先级组合：超时、匹配规则、固定字节。典型用法：以 \n 匹配断后；有特殊帧头时用“匹配断前”；大块二进制用固定 1024 字节断帧。
• 未满足断帧规则的数据先进入临时显示区，超过 8192 字节会自动断帧。

快捷命令

右栏可新增/编辑/删除命令，支持拖拽排序、导入/导出、重置和“保存到本地”。常用 AT 指令可以做成按钮一键发送；带参数的宏命令可在发送前编辑。快捷命令属于浏览器本地配置，换浏览器/清缓存会丢失。

6.2 UART TCP 透传桥（1346）

设备同时提供裸 TCP 透传桥：数据从 TCP 写入目标 UART TX，目标 UART RX 数据从 TCP 返回。默认端口 1346，默认波特率 115200，无鉴权。

nc DEVICE_IP 1346

新建连接后的首个文本包如果是 2–7 位数字（例如 115200），桥会切换到该波特率；否则按普通数据透传。Web UART 与 TCP 桥共用同一 UART 服务，可同时连接；多客户端按广播语义处理，调试时注意不要互相干扰。控制台 UART0（GPIO43/44）不经过该桥。

6.3 Wi-Fi 配置

连接与扫描

在“连接 Wi-Fi”输入 SSID 或点“扫描”选择网络，输入密码后点“连接”。连接成功后设备会记录该网络（自动记忆默认开启），并按规则自动重连。若当前页面正通过设备 AP 访问，连接另一个网络会导致页面断开，这是预期行为；连接前先确认你知道设备在新网络中的 IP。

已保存网络

• 最多保存 8 个网络；列表显示 SSID、最近成功时间、优先级、当前连接标记。
• 支持自动记忆开关、添加、连接、删除；超过上限会按优先级淘汰旧网络。
• 上电/掉线后的轮换顺序：上次成功的网络 → 其它已保存网络（优先级升序、最近成功降序）→ 扫描到的已保存网络 → 退避重试（5/10/20/30 秒封顶）。
• 不会自动连接未保存的开放网络。

模式与 AP

• 智能热点 + 常开终端（AP+STA）：STA 连上后 30 秒关闭 AP；STA 断开 10 秒后重开 AP。默认模式。
• 仅开启热点（AP）：不连外部网络，适合近场配置。
• 常开热点 + 常开终端（AP+STA）：AP 与 STA 同时保持，方便但增加功耗与干扰。
• AP 默认 SSID Birdiebot-DAP-XXXX，默认口令 12345678，默认地址 192.168.1.1/24，最多 4 个客户端。首次使用务必改口令，可恢复默认 SSID。
• STA 支持 DHCP 或静态 IP/DNS；改静态 IP 前确认不冲突，否则会失去设备访问。

6.4 mDNS / SSDP 发现

设备有两种局域网发现方式，只用于“找到设备”，不提供鉴权，也不替代 IP 直连：

mDNS

浏览器直接打开 http://birdiebot-dap-XXXX.local/。设备实例名为 Birdiebot WiFi DAP，服务类型 _http._tcp，端口 80；部分设备的实例名还会带 MAC 后缀。命令行验证：

# 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

Windows 默认没有完整的 mDNS 解析器时，主机名可能失败；先确保设备和电脑在同一网段，必要时装 Bonjour 或直接用 IP。AP 模式下设备 IP 是 192.168.1.1；STA 模式下在 Wi-Fi 页查看路由器分配的 IP。

SSDP

向 239.255.255.250:1900 发送 M-SEARCH，设备返回 200 响应，其中 LOCATION 指向 http://<设备IP>/SSDP.xml：

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

拿到 IP 后可直接用浏览器或 curl http://<设备IP>/SSDP.xml 查看友好名、型号、序列号和厂商信息。SSDP 与 mDNS 都依赖同一二层局域网；访客网络/VLAN 隔离、主机防火墙 UDP 1900/5353 被拦截时都会失败。失败时直接用 IP，不要反复重启设备。

6.5 浏览器本地 OTA（8 MB 双槽发布构建，默认启用）

固件支持浏览器选择本地 app 镜像流式上传，写入空闲 OTA 槽、校验、切换启动分区并重启；默认启用双槽回滚。4 MB 目标（C3/ESP32 构建）没有 OTA 分区，不能使用该功能。

页面操作

1. 进入“更新”，核对当前运行槽、固件版本、OTA 槽容量与可用空间。
2. 选择或拖入 .bin 应用镜像；页面校验镜像头、版本、大小，并计算 SHA-256。
3. 点击“上传并更新”；浏览器上传与设备接收/校验是两条进度，设备状态依次为 IDLE → RECEIVING → VERIFYING → READY → APPLYING。
4. 成功后设备约 1 秒重启；等待页面重新连接。新镜像首启处于待确认状态，应用稳定运行约 10 秒后标记有效。

如果新镜像在确认前崩溃/复位，bootloader 会自动回滚到旧槽。上传过程中断/失败不会破坏当前运行镜像，但目标槽内容不完整；重新上传会重新擦除该槽。

HTTP 端点与脚本

上传端点为 POST /api/ota/upload，要求 Content-Type: application/octet-stream、Content-Length，可选 X-SHA256；只接受 ESP-IDF 应用镜像，大小 4 KB–3 MB。没有可用页面时可用仓库脚本：

python3 scripts/ota_upload.py --host DEVICE_IP \
  --file build/<target>/birdiebot_wifi_dap.bin --info

也可用等价 HTTP 客户端直接上传，但必须带 Content-Length，且不要用 chunked。设备不会接受 merge/全量包、zip 或非 app 镜像。

失败与回滚

6.6 版本、状态与恢复

• 协议匹配：绿色“协议匹配”表示网页与固件协议 v1 一致；不匹配时刷新网页或升级固件。协议不匹配会禁用 OTA 等操作。
• 版本信息：“复制版本信息”会复制 Web 版本、协议版本、Git 标签、构建时间、固件版本/日期、SN、硬件版本/生产日期。反馈问题时附上这段文本。
• 重启：默认更新页提供重启按钮；若使用裁剪构建没有页面入口，断电重新上电即可。重启不会丢失已保存的 Wi-Fi 配置。
• Wi-Fi 失联恢复：STA 断开 10 秒后 AP 重开；用默认 AP 或已知网络重新连接。若 AP 被改为未知名称，需要对设备重新烧录/擦除 NVS。
• 有线救砖：BOOT(GPIO0 拉低)+RESET 进入 ROM 下载模式，用 esptool 烧录；或通过 UART0 下载；默认固件保留 Wi-Fi OTA，可回退。
• 日志与 coredump：UART0 115200 是首选日志通道；设备有 coredump 分区（debug 构建使用），崩溃后可用对应 IDF 版本分析。coredump 可能含 Wi-Fi 口令等敏感信息，按敏感数据处理。

7 Web-DAP 在线调试

7.1 传输架构与端口

设备在 TCP 3240 上提供 DAP 代理。连接建立后的首包决定协议：USBIP、elaphureLink 或 WebSocket-DAP；之后统一转成 CMSIS-DAP 命令。无线和有线共享同一套 DAP 代码，因此端口、VID/PID、工具步骤完全相同，只是网络路径不同。

• USBIP：主机把远端 USB 设备“搬”到本地，之后 OpenOCD/Keil/pyOCD 看到标准 CMSIS-DAP v2 探针。
• elaphureLink：Keil 插件或 OpenOCD-elaphureLink 直连 3240，不需要 USBIP 驱动。
• WebSocket-DAP：浏览器端工具使用，二进制帧就是 CMSIS-DAP 命令包；曲线页的 Web-DAP 模式也走它。

设备对外呈现的探针 VID:PID 为 C251:F00A，USBIP busid 固定 1-1。同一时刻只允许一个 DAP 会话，详见 7.5 节。

7.2 USBIP 接入

Windows

1. 安装 usbip-win 0.3.x（kmdf/ude 驱动）。
2. 确认主机与设备同网：无线 AP 模式设备 IP 为 192.168.1.1；有线 NCM 为 192.168.7.1；STA 模式用路由器分配 IP。
3. 执行 usbip.exe attach_ude -r DEVICE_IP -b 1-1。旧版 HID 用法为 usbip.exe -D -a DEVICE_IP 1-1，但本固件默认 WinUSB，推荐 attach_ude。
4. 设备管理器出现 CMSIS-DAP 后，在 Keil/OpenOCD 中按 CMSIS-DAP 选型使用。

Linux

sudo modprobe vhci-hcd
sudo usbip attach -r DEVICE_IP -b 1-1
usbip port
# 调试结束
sudo usbip detach -p 00

Linux 内核自带 usbip 客户端，但本项目的主验证平台是 Windows usbip-win 与 Linux 开发验证；遇到枚举问题先确认内核模块、防火墙和 3240 可达。

7.3 OpenOCD 配置

推荐使用 OpenOCD master（或含 DAP_TransferBlock 支持的新版 0.13 开发快照），读大块内存比 0.12 快约 2.4 倍。0.11 对 CMSIS-DAP 2.1 的两字节 capabilities 响应不兼容，会报 SWD not supported，需要补丁；不建议日常使用。

sudo usbip attach -r DEVICE_IP -b 1-1
openocd -f interface/cmsis-dap.cfg \
  -c "cmsis_dap_vid_pid 0xc251 0xf00a" \
  -c "transport select swd" \
  -f target/stm32h7x.cfg \
  -c "adapter speed 2000" \
  -c "reset_config none" \
  -c "cortex_m reset_config sysresetreq" \
  -c "init; reset halt"

要点：adapter speed 必须放在目标配置文件之后，否则会被目标脚本的默认值覆盖；STM32H7 可尝试 1900–4000 kHz，STM32F1/F4 从 1000–2000 kHz 起。目标脚本按芯片选择（target/stm32f1x.cfg、stm32f4x.cfg 等）。需要烧录时：

-c "flash write_image erase app.bin 0x08000000; verify_image app.bin 0x08000000; reset run; shutdown"

若 OpenOCD 打不开 USBIP 设备，可改用 OpenOCD-elaphureLink 直连 3240，或换 Linux 测试机；这不是 DAP 固件问题。

7.4 Ozone：原生限制与实验路径

Ozone 原生只支持 J-Link 探针，不能直接把 CMSIS-DAP 当 J-Link 使用。仓库里的“虚拟 J-Link”方案通过代理 DLL 把 Ozone 的 J-Link API 桥接到 OpenOCD telnet，已打通连接、PC/寄存器读取和 Data Sampling 能力门禁；但 Ozone 不主动读取 HSS 数据，Timeline/HSS 曲线仍未打通。因此：

• 生产/关键调试：使用真实 J-Link（EDU Mini 即可）或 OpenOCD + GDB；不要依赖虚拟 J-Link。
• 实验：需要 Windows、官方 J-Link DLL、代理 DLL 和已 attach 的 OpenOCD；具体构建/替换步骤见 docs/ozone-virtual-jlink.md。仅把这个路径当作验证性功能。
• 替代：需要看变量时用本设备的变量曲线（第 8、9 章），需要断点/单步时用 OpenOCD + GDB 或 Keil。

7.5 DAP 占用与互斥

USBIP、OpenOCD、Keil、Ozone、Web 变量曲线、Web 目标烧录都使用同一个 DAP。任意时刻只能有一个占用者；第二个会话会失败、排队或被“踢掉”。

曲线页通过 POST /api/dap/kick 请求关闭当前 DAP 代理会话；若无会话则 no-op。这个操作对正在烧录的 OpenOCD 是破坏性的，执行前确认没有关键写入。停止曲线采样后，主机需要重新 usbip attach 才能继续 USBIP 调试。

7.6 断线、重连与会话清理

• USBIP 断线：先 detach 再 attach；同一主机连续 attach 时 busid 仍为 1-1。旧固件偶发第二会话 CMD_INFO failed，升级到包含 DAP 会话 drain 修复的版本；临时可重新插拔/重启设备。
• Wi-Fi 断线：OpenOCD 会报 USB 超时/管道错误；恢复网络后重新 attach。烧录中断可能留下不完整镜像，重新烧录整个文件。
• 有线 NCM 断线：检查主机网卡 IP 是否被 NetworkManager 清空；设备 OTA 重启后若 cdc_ncm 绑定失败，物理拔插 USB 或重新绑定 xHCI。
• DAP 任务忙：Web 曲线/烧录正在使用 DAP 时，OpenOCD 会看到超时；停止占用者后重试。
• 目标无响应：检查目标是否处于低功耗/安全状态，降低 SWD 时钟，使用 nRESET 或 SYSRESETREQ 复位。

7.7 速度预期与优化

优化顺序：优先有线 NCM；使用 OpenOCD master/新版；把 adapter speed 放在目标配置之后并逐档测试；减少 Wi-Fi 干扰与距离；避免同时跑曲线/串口大数据流。不要期待提高 SWD 时钟能无限加速——Wi-Fi 往返和 USBIP 调度经常才是瓶颈。

8 变量曲线基础

8.1 先分清两种采样来源

设备本地模式下，固定地址/全局变量/固定指针可以“Halt OFF”，每拍只读内存，不暂停目标；需要读栈帧、寄存器、指针链时则每拍 halt/resume，目标实时性会受影响。默认 20 ms 兼顾可读性与干扰；10 ms 适合需要 100 Hz 的场合，但 halt 占用更高；5 ms 仅在固定地址/指针等无需 halt 的场景有意义。日常建议几十路（例如 20–60 路），256 是容量上限，不是推荐工作点。每行变量还可单独设置目标刷新率（÷1/÷2/÷4/÷8），通过分组权重实现；实际刷新率是相对份额，页面会标记“≈”，不能保证精确 Hz。

8.2 ELF、DWARF 与变量树

上传 ELF 后，页面解析 DWARF 2–5，列出变量名、类型、地址、大小和来源 file:line，结构体/联合/数组/指针可展开。若 ELF 没有 DWARF，会回退到符号表：只能看到符号名和固定地址，类型显示未知，名称会做反混淆。

• 实时可采样：变量有固定地址（全局/静态），或指针链全部为固定地址；设备本地高速路径。
• 调试可采样：局部变量/参数位于栈帧或寄存器，需要 halt 后读取；Web-DAP 调试模式或设备本地 halt 路径。
• 不可采样：被优化掉、无位置信息、地址越界、寄存器值变量（设备本地模式明确不支持 DW_OP_reg 值）。
• PC 范围/多段位置：变量可能只在某个函数或 PC 段有效；越界时设备填 0 并计入 Out of scope，不计入 Invalid。

8.3 选择变量与手动地址

• 变量树支持搜索变量名/地址、按源文件或命名空间分组、展开/折叠、仅显示可采样、仅当前有效/当前函数；首屏只渲染部分行，点“显示更多”。
• 勾选变量或 Shift 连选当前可见行；也可“全选可见/全选可采样/清空选择/选当前文件/选当前组”。
• 手动地址：十六进制、4 字节对齐、非 0；多个地址用逗号或空格分隔，支持 0x20000000 这类写法。
• 设备本地上限 256 路；达到上限会提示，不能继续添加。超过 64 路时页面自动按每组 64 路分组，并额外受每组 sum(size) ≤ 256 B 约束：4 字节变量最多 4 组覆盖 256 路；8 字节变量会拆成 8 组（协议最多 8 组）。
• 选中的曲线可上移/下移、单独隐藏、改显示格式、删除；选择不会自动记住（刷新页面后需重选）。每行还可设置目标刷新率（÷1/÷2/÷4/÷8）：单桶 ÷N 不能降低绝对总帧率，混合桶会被归一化；实际刷新率是相对份额，UI 会显示“≈”和相应警告。

8.4 开始与停止

1. 打开“变量曲线”，确认“采样来源”为“设备本地（ESP32 闭环）”。
2. 点“上传 ELF”选择文件，等待解析；记录 DWARF 变量数与固定地址数。
3. 搜索并勾选变量；需要固定地址时可直接填手动地址。曲线数显示为 n/256。
4. 如需限定 SWD 速率，先到“目标烧录”页的检测卡片选择手动 SWD 时钟；该设置同时作用于目标检测、Web 烧录和本地变量采样。
5. 选择本地采样间隔（默认 20 ms）与触发方式（基础阶段保持“周期采样”）。
6. 点“开始采样”。若提示 DAP 被占用，先停止 OpenOCD/USBIP 或其它采样。
7. 观察曲线与状态；点“停止采样”。停止/刷新/离开页面都会尝试恢复目标运行，但推荐显式停止。

8.5 状态字段怎么读

8.6 常见错误

• “没有可采样变量”：ELF 无 DWARF 或所有变量都被优化；换 -O0/-Og -g3 固件与匹配 ELF。
• “寄存器值变量暂不支持设备本地采样”：该变量直接存放在寄存器；改用 Web-DAP 调试模式，或选择固定地址/栈帧变量。
• 启动失败/busy：OpenOCD、USBIP、目标烧录或另一个标签页占用 DAP；停止后重试。
• 目标变量值不变：目标可能被 halt、断点停住或固件 assert；看 Halt/复位/恢复目标。
• 选到 256 后无法再加：这是容量上限；减少曲线或分多次采样。
• 画面卡顿：路数过多时默认 B 模式只画前 64 条；不要盲目切 A 模式，详见 9.7 节。

9 变量曲线进阶

9.1 精确行断点与源码联动

ELF 卡片切换到“源码”视图，可打开本地 C/C++ 项目文件夹（只读、不上传）。页面解析 DWARF 的 .debug_line 行表，把变量/行号映射到源码；源码行号旁的 gutter 可点击，直接把该行设置为设备本地断点地址。地址来自行表中最合适的可执行地址（优先 is_stmt/Flash），不再用函数入口或变量地址近似。

1. 上传/解析 ELF（可与“源码”视图共用同一解析流程；项目里发现 ELF 也可直接使用）。
2. 在“源码”视图打开项目文件夹，或选择 ELF；文件树/过滤/变量映射状态会显示。
3. 找到目标代码行，点击行号 gutter。页面会切到本地断点模式并填入地址；若该行是宏/声明/已优化/无行表，会提示“该行没有可用地址”。
4. 必要时在“断点地址”基础上填 Offset，把断点放到初始化之后的指令；最终地址会显示并校验。
5. 选择变量与最小采样间隔，开始采样；命中信息在状态行显示。

• 断点地址必须在目标 Flash 0x08000000–0x08FFFFFF，半字对齐；Thumb bit0 会被忽略。
• 函数入口处局部变量可能尚未初始化；优先放在初始化语句之后，或使用 Offset。
• FPB 硬件断点是独占资源，与其它调试器同时使用时先断开。
• 没有行表时无法精确映射；页面会提示，不会伪造地址。

9.2 PC 联动、当前函数与 stale 标记

本地采样帧可以携带当前 PC。页面显示 PC 与源码位置，并提供“PC 行联动”开关：打开后源码视图自动滚动/高亮当前行；关闭后不抢你的滚动位置。变量树可勾选“仅当前有效”“当前函数”过滤，不在当前 PC/函数范围的变量会标红点/灰显。

• PC 范围：来自 DWARF subprogram 的 low_pc/high_pc 或 loclist variants；文件作用域全局变量没有 PC 范围，不参与门控。
• Out of scope：固件按 PC 门控填 0 并单独计数；不是变量坏掉，而是“这个函数当前不在栈上”。
• 无 PC 会话：纯固定地址的 no-halt 采样不带 PC，不做 stale 判定；需要 PC 时至少包含一个 halt/断点会话。
• 行表缺失：只能显示 PC，无法联动源码行；这不是变量解析失败。

9.3 触发方式：周期、断点、Watchpoint、条件

断点触发

函数下拉来自 ELF 的 Flash FUNC 符号（最多 2000 个，按地址排序，C++ 名称反混淆）；也可手工填地址。最小间隔是两次命中的节流下限，避免高频函数把目标反复停住。状态行显示 Hits / Sampled / 实际帧率；停止时恢复 comparator 与目标运行。

Watchpoint

Watchpoint 使用 DWT comparator，监视地址必须按大小对齐；支持 read / write / readwrite 三种访问类型，命中后读取当前变量并记录触发 seq。可用“前 N 帧/后 N 帧”跳转到触发附近。第二个 comparator（watch2）可同时监视另一个地址，但 DWT comparator 总数有限，资源不足时按固件返回的错误原文处理。目标必须实际运行；如果命中后目标不再运行，先检查是否被其它断点/调试器占用。

函数快照

函数快照在 breakpoint 命中后冻结/标记触发帧，固件可 one-shot 补采 N 帧；旧固件忽略该字段时，前端使用首帧冻结作为 fallback。它用于抓函数执行瞬间的局部变量，不改变原有断点节流语义。

UART trace、backtrace 与边界

调试面板新增 UART trace（按字节流记录/查看）和帧指针 backtrace；两者用于现场排障，不等同于完整调试器。当前 SWO 与 RTOS 任务感知尚未实现；backtrace 仅为帧指针原型，遇到优化/无帧指针代码时可能不完整。详细字段与端点见开发者附录。

条件触发

条件由设备在每拍采样后读取一个地址并比较：支持 == != > >= < <=、1/2/4 字节、无符号/有符号、once（默认命中一次后停止/停止采样）或 continuous，并可勾选“命中后停止”。它只决定“何时停/何时标触发”，不改变已采数据；可与周期/断点/Watchpoint 组合。条件地址不会自动从变量列表推断，需手工填或从变量地址复制。

9.4 图表与数据分析

坐标轴与视图

• Y 轴：共享 auto（默认）、归一化 0–100%（每个变量按窗口内自身 min/max）、对数 log10（忽略 ≤0）。指针/地址大值压扁小曲线时用归一化或对数。
• 时间轴：1 / 2 / 5 / 10 / 20 / 60 秒；滚轮以光标为中心缩放，拖拽平移，双击复位；Follow latest 跟随最新数据。Hover 十字线显示当前时间和各曲线值。
• 冻结显示：Freeze 暂停重绘但采样继续；Unfreeze 恢复；导出使用冻结时视图。
• 显示缩放：全局 multiplier/offset 只影响显示/图表，不改变原始数据；保存在浏览器本地。

双光标与统计

点击图表设置光标 A，Shift+点击设置光标 B；overlay 显示两条竖线。下方统计面板按曲线列出 A 值、B 值、Δ、窗口 min/max/avg，以及整段 Δt。Esc 清除光标。统计与 CSV 导出都按当前 X 视图范围/当前 Y 模式。

FFT、平滑与派生曲线

• FFT：对当前窗口第一条绘制曲线做简单 DFT（N≤256，去均值，取 Top 8 频率/幅值）；按需执行，不是实时频谱，也不是窗函数分析。
• 平滑：每条曲线可选 1/3/5/9 点滑动平均，仅绘制时计算，不改变 ring/CSV/latest 原始值。
• 派生曲线：A+B / A−B，仅显示与导出，不参与采集；采样中不能创建，本地 start 会过滤派生曲线。至少需要两条曲线。

渲染模式与格式

默认 B 模式最多绘制 drawCap 条（32/64/128，默认 64），其余曲线仍被选中/采样，可在 Selected/图例中切换可见；页面显示“绘制 n/N”。切到 A 模式会绘制全部可见曲线并提示性能风险；可见 >128 时 B 自动降到 32，A 模式可能降帧。格式支持 u8/i8/u16/i16/u32/i32/f32/hex/bool/enum，auto 按 DWARF 类型显示枚举名/64 位/浮点/指针 hex。Canvas 约 30 fps 节流，Worker/OffscreenCanvas 可用时优先在 Worker 渲染，失败自动回退主线程。

9.5 录制、回放与导出

录制不会自动开始：先开始采样，再点“开始录制”；页面把 series 元数据与每帧相对时间/group/原始 payload 写入浏览器 IndexedDB。录制上限 6000 帧，达到后自动停止。停止捕获后可命名保存；Recordings 列表支持加载、删除、刷新。回放支持时间轴拖动、播放/暂停、0.5×/1×/2×/4× 倍速，并复用 Y 轴/时间轴/hover/统计；回放期间不写入录制，退出回放清空。

录制保存在当前浏览器的 IndexedDB 中，清站点数据/换浏览器/隐私模式会丢失；它不保存变量选择，也不会自动上传。录制不含派生曲线。

9.6 对象 Watch 与对象预设

变量区第三个标签是“对象”（Objects）：把全局对象根当成 Ozone 式对象浏览器，按需展开字段，而不是把几千个节点一次性铺平。

• 根发现：每颗目标默认优先 xrobot_debug_handle，也可在根下拉里选其它固定地址且含子成员的对象/指针/数组。真实 ELF 常有上百个候选根。
• 浏览：搜索名称/路径/类型/地址；过滤仅可采样/仅固定地址/仅有值；单击选中、Ctrl/Cmd 多选、Shift 区间、双击展开；右侧显示类型、地址、当前值、stale 状态。
• Watch：变量行的 ☆ 加入独立 Watch 列表（当前值/min/max/变化次数）；Watch 与曲线选择独立，未选曲线时也能等待值；对象视图支持 Watch subtree/Watch visible/Watch selected 批量操作。
• 加入曲线：Add curve/Add selected 批量加入，去重并受 256 上限约束；源码跳转会切到 Source 并定位。
• 对象预设：按根保存字段路径列表到 localStorage，可命名保存/加载/删除；预设只记录路径，不自动记录变量选择；换 ELF/根后需要重新加载。
• 解析上限：解析器每个变量最多 64 个子节点、3 层展开、节点预算；数组可能只 materialise 前 64 项，界面显示声明长度（如 64/256）；超大子树会显示提示，仍需惰性展开。

9.7 性能与容量建议

每变量目标刷新率会进一步影响有效样本：÷N 只改变该系列的分组权重，不保证精确的 50/25/12.5/6.25 Hz，混合桶会被归一化。统一 NCM+WiFi 固件的 start 请求体上限为 6 KiB（6144 B），典型几十路没问题，超大选择可能返回 413；不要假设所有 256 路请求都一定能上传。当前 ring 为每系列 6000 点（约 50 Hz 下 120 秒），256 路内存约 24 MB；不要用 256 路长时间录制。页面性能还受 Canvas 绘制条数、变量树 DOM、浏览器后台节流影响。遇到卡顿先用 B 模式、降低 drawCap、减少绘制/选中数，再考虑 A 模式或 Worker 诊断。

按 D 可展开诊断面板，复制设备/ELF/性能/录制 JSON；按 F 冻结、+/- 切时间窗、方向键平移、Space 启停采样、Esc 清光标。输入框获得焦点时快捷键不生效。

10 典型工作流

10.1 同时观察几十个变量

1. 确认目标固件与 ELF 来自同一次构建；记录 ELF 路径/SHA-256。
2. “变量曲线”选设备本地、20 ms；上传 ELF，打开“仅显示可采样变量”。
3. 按源文件/命名空间分组，用“选当前文件/选当前组”批量勾选 20–60 路；超过 64 路会自动分组。
4. 开始采样；Halt 应为 OFF（固定地址/指针）。若 Halt ON，说明包含栈帧/寄存器变量，评估目标实时性。
5. 默认 B 模式 drawCap 64；变量更多时只绘制前 64 条，其余仍采样。需要看全部时再切 A，并注意帧率。
6. Y 轴按数据形态选择 auto/归一化/对数；需要对比时设 A/B 光标，导出 CSV 归档。

10.2 只在条件满足时抓取

1. 确定条件变量/寄存器的绝对地址与宽度（4 字节对齐），例如某个状态字的 0x24001234。
2. 本地模式选“周期采样”，间隔 20 ms；勾选条件触发，填地址、大小 4、操作符（如 >=）、阈值、无符号。
3. 模式选 once，勾选“命中后停止”；开始采样。状态会显示 Armed / Met / Hits / Trigger seq。
4. 命中后停止；用“跳转条件触发”按钮定位到触发前后帧，检查变量快照。
5. 需要连续记录多次命中时改 continuous，并取消 stop after，但注意录制帧数上限 6000。

如果条件一直不命中，先确认地址有效、目标在运行、阈值/有符号设置正确；条件读取失败会按固件错误路径提示，不要用“条件触发”代替断点。

10.3 源码断点抓局部变量

1. 上传带 DWARF/行表的调试 ELF（建议 -O0 -g3），在源码视图打开项目。
2. 点击目标行号设置断点；若局部变量在函数入口未初始化，添加 Offset 或选初始化之后的行。
3. 选择栈帧/指针变量，最小间隔 20 ms；开始采样。
4. 观察 Hits/Sampled 与实际帧率；变量值出现 Out of scope 说明当前 PC 不在该函数，属正常。
5. 抓够后停止，导出 CSV/录制；记录断点地址、Offset、ELF 哈希和目标 UID。

10.4 烧录并验证新固件

1. 目标上电、SWD 接好；关闭 OpenOCD/USBIP/曲线采样。
2. 目标烧录页检测，记录系列、DEV_ID、Flash 大小、UID0/1/2。
3. 选择 app-only BIN/ELF，核对转换后镜像大小、Flash 占用与 SHA-256。
4. 开始烧录，等待设备回读校验完成；成功后记录返回的 SHA-256 与写入字节数。
5. 点“复位目标”，观察 UART/指示灯；需要整镜像校验时用 OpenOCD verify_image 或曲线页 ELF 快速校验。
6. 失败时保留页面错误文案与 UART0 日志；按 5.7 节处理后再重试。

10.5 Ozone / OpenOCD 调试剧本

标准路径：USBIP attach → OpenOCD（或 Keil/pyOCD）→ halt/断点/烧录。Ozone 原生不支持 CMSIS-DAP；需要 Ozone 时：

1. 先用 USBIP + OpenOCD 验证探针和目标正常，记录 IDCODE。
2. 若使用真实 J-Link：直接按 Ozone 官方流程连接，不经过本设备。
3. 若试用实验性虚拟 J-Link：在 Windows 上按 docs/ozone-virtual-jlink.md 准备代理 DLL，OpenOCD 保持运行，Ozone 通过 USB 连接虚拟探针。
4. 只把它用于连接/PC/寄存器/单步等基础验证；Timeline/HSS 未打通，不要用于依赖高速采样的分析。
5. 调试结束先关 Ozone，再停 OpenOCD/USBIP；需要曲线时重新按第 8 章接管。

曲线与调试切换：OpenOCD 正在使用时，曲线页会提示接管并断开当前会话；停止采样后主机要重新 usbip attach。反过来，OpenOCD 正在烧录时不要启动曲线。

10.6 分享一次录制/测试结果

1. 开始采样后点“开始录制”，复现故障；达到 6000 帧会自动停止。
2. 停止采样并保存录制，命名包含目标/固件/变量/工况。
3. 在 Recordings 面板加载回放，确认关键帧；导出 JSON/CSV，同时导出关键截图/PNG。
4. 附上目标 UID0/1/2、DEV_ID、Flash 大小、ELF SHA-256、Web/固件版本、采样间隔与触发配置。
5. 对方在本地浏览器导入/加载或直接分析 CSV/JSON；录制不会自动上传，注意敏感数据脱敏。