# 天空星调试助手

**Repository Path**: lcsc/sky-star-web-debugger

## Basic Information

- **Project Name**: 天空星调试助手
- **Description**: 基于 WebUSB + DAPLink 的嵌入式调试工具，支持 SVD 寄存器解析、实时示波器、内存查看等功能
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 2
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 嵌入式, 天空星

## README

# 天空星调试助手

> [!tip]
>
> 基于 WebUSB + DAPLink 的嵌入式调试工具，支持 SVD 寄存器解析、实时示波器、内存查看等功能。
>
> ![Version](https://img.shields.io/badge/Version-V0.2-blue)![Author](https://img.shields.io/badge/Author-LCKFB--YZH-green)![Platform](https://img.shields.io/badge/Platform-Chrome%20%7C%20Edge-orange)
>
> **在线使用链接**：[天空星调试助手](https://wiki.lckfb.com/storage/html/web-debugger/)
>
> **开源仓库链接：**[天空星调试助手: 基于 WebUSB + DAPLink 的嵌入式调试工具，支持 SVD 寄存器解析、实时示波器、内存查看等功能](https://gitee.com/lcsc/sky-star-web-debugger)

---

* 寄存器页面演示：

![20260123-111612](./assets/20260123-111612.gif)

* 内核界面展示：

![image-20260123111812139](./assets/image-20260123111812139.png)

* 示波器界面演示：

![20260123-112723](./assets/20260123-112723.gif)

* 内存界面展示：

![image-20260123112946268](./assets/image-20260123112946268.png)

---

## 一 📖 项目简介

**天空星调试助手** 是一款基于 Web 技术的嵌入式 MCU 调试工具，由立创开发板团队开发。它利用 **WebUSB** 标准直接在浏览器中与支持 webusb 协议的 DAPLink 仿真器通信，无需安装任何驱动或桌面软件，即可实现：

- 🔧 **寄存器级调试**：基于 SVD 文件解析，可视化查看和修改 MCU 外设寄存器.
- 📊 **实时示波器**：非侵入式内存变量监控，最高可达数百 Hz 采样率(受限于数据传递链路，采样率目前还不稳定)
- 💾 **内存查看器**：读取 Flash/RAM 等任意地址空间
- 🧠 **内核寄存器**：查看 Cortex-M 核心寄存器（R0-R15、xPSR 等），目前只能在MCU暂停运行时查看。

## 什么是"非侵入式"？

与传统的 printf 调试、逻辑分析仪需要修改代码或添加硬件探头不同，本工具的示波器功能通过 **SWD 调试接口直接读取 MCU 内存**，具有以下优势：

| 对比项 | 传统 printf | 逻辑分析仪 | 本工具示波器 |
|--------|-------------|------------|--------------|
| 是否需要修改代码 | ✅ 需要 | ❌ 不需要 | ❌ 不需要 |
| 是否占用串口资源 | ✅ 占用 | ❌ 不占用 | ❌ 不占用 |
| 是否影响程序时序 | ✅ 有影响 | ❌ 无影响 | ⚠️ 极微影响¹ |
| 是否需要额外硬件 | ❌ 不需要 | ✅ 需要 | ❌ 仅需 立创DAPLink |
| 能否监控任意变量 | ⚠️ 需预埋 | ⚠️ 仅限 IO | ✅ 任意内存地址 |

> ¹ 由于 SWD 调试访问会短暂占用总线，高频采样时可能对极端实时性要求的场景有微弱影响，但对于绝大多数应用场景可忽略不计。

---

## 二 ✨ 功能特点

## 2.1  寄存器视图 (Registers)

- **SVD 文件解析**：自动解析 CMSIS-SVD 格式文件，提取外设、寄存器、位域等完整信息（目前仅测试了STM32F407,其他芯片版本请等待后续适配）
- **左侧树形导航**：按外设分组（GPIO、TIM、SPI、I2C、UART 等）组织，方便快速定位具体外设
- **实时同步**：
  - Fast 刷新：活动(展开的)寄存器高频刷新（默认 100ms）
  - Slow 刷新：页面可见寄存器低频刷新（默认 500ms）
- **位域操作**：
  - 1 位字段：采用开关控件。
  - 2 位字段：采用分段选择器，更形象。
  - 多位字段：支持 HEX/DEC 输入。
- **二进制视图**：32 位逐位显示，点击即可切换（改写）单个位
- **快速复制**：点击地址/十六进制值/十进制值即可复制

## 2.2  示波器视图 (Scope) 

这是本工具最具特色的功能，实现了 **纯软件实时数据可视化**：

> [!warning]
>
> 【目前采样率还不稳定，但是估计web下也做不到精准的采样率】

### 2.2.1 核心能力

| 功能 | 说明 |
|------|------|
| **多通道监控** | 同时监控多个内存地址/变量 |
| **多数据类型** | 支持 U8/S8/U16/S16/U32/S32/Float |
| **高精度时间戳** | 微秒级精度，支持 ΔT 测量 |
| **采样率可调** | 2ms ~ 1s 或自定义（支持小数，如 2.5ms）|
| **大容量缓冲** | 默认 50000 点/通道，可自定义 |
| **游标测量** | A/B 双游标，自动计算 ΔT 和频率 |
| **自动缩放** | 每通道可独立设置 Auto/手动 Y 轴范围 |

**高级功能**：

- **ELF 符号加载**：导入 ELF 文件后，可直接输入变量名（如 `g_adc_value`）自动获取地址
- **Mask & Shift**：可以提取位域，例如 `Mask=0xFF00, Shift=8` 提取第 8-15 位
- **表达式变换**：支持 `x*2+1`、`Math.abs(x)` 等自定义计算
- **Gain 增益**：支持线性缩放系数
- **单位显示**：可以为通道添加物理单位（如 mV、°C）
- **线宽/颜色**：每通道可以独立设置

### 2.2.2 非侵入式原理

```html
┌─────────────┐      SWD/JTAG       ┌─────────────┐
│   浏览器     │◄───────────────────►│   DAPLink   │
│  (WebUSB)   │    WebUSB + DAP     │  (仿真器)    │
└─────────────┘                     └──────┬──────┘
                                           │
                                           │ SWD
                                           ▼
                                    ┌─────────────┐
                                    │    MCU      │
                                    │  (目标板)    │
                                    │             │
                                    │  RAM/Flash  │◄── 直接读取内存
                                    └─────────────┘
```

**工作流程**：

1. 浏览器通过 WebUSB 连接 DAPLink
2. 使用 CMSIS-DAP 协议发送内存读取命令
3. DAPLink 通过 SWD 接口读取 MCU 指定地址
4. 数据返回浏览器并绘制波形

**为什么这里是"非侵入式"**：

- 不需要在目标代码中添加任何调试代码
- 不占用 MCU 的串口、定时器等外设资源
- 程序正常运行时即可进行监控
- 甚至可以监控未公开源码的固件运行情况（只要知道变量或者寄存器地址）

## 2.3 内核视图 (Core)

显示 Cortex-M 核心寄存器：
- R0 ~ R12：通用寄存器
- SP：堆栈指针
- LR：链接寄存器
- PC：程序计数器
- xPSR：程序状态寄存器

> 💡 需要在暂停（Halt）状态下读取，才可以正确获取

## 2.4  内存视图 (Memory)

- **双窗格设计**：可同时查看两个不同区域（如 Flash 和 RAM）
- **预设大小**：1K/2K/5K/10K/128K/256K/512K/1M
- **显示宽度**：8-bit / 16-bit / 32-bit 切换
- **ASCII 预览**：同步显示可打印字符
- **导出功能**：保存为 BIN 或 TXT 文件

---

## 三 🚀 核心优势

### 3.1 零安装，即开即用

无需安装任何软件、驱动或浏览器插件。只需：
- 一个支持 WebUSB 的浏览器（Chrome/Edge）。
- 一个支持 WebUSB 的 DAPLink 仿真器,推荐使用我们的[立创DAPLink](https://item.szlcsc.com/56199685.html)。

### 3.2 跨平台

理论上Windows、macOS、Linux、ChromeOS 均可使用，只要有现代浏览器，但是我自己只测试了Windows。

### 3. 非侵入式调试

示波器功能无需修改目标代码，适合：
- 分析已部署固件的运行状态
- 调试没有空闲串口的系统
- 监控对时序敏感的实时控制逻辑

### 4. 采用开放标准

- 使用标准 CMSIS-SVD 文件（各芯片厂商均有提供），目前只支持STM32F4的SVD解析。
- 支持标准 ELF 符号文件
- 基于开源 DAPjs 库

---

## 四📝 使用步骤

### 4.1 准备工作

1. **浏览器**：确保使用最新版 Chrome 或 Edge（其他浏览器不支持 WebUSB）
2. **硬件**：
   - 支持 WebUSB 的 DAPLink 仿真器（如[立创 DAPLink仿真器](https://item.szlcsc.com/56199685.html)）
   - 目标 MCU 开发板（需引出 SWD 接口）
3. **文件**：
   - 目标 MCU 的 SVD 文件（可从芯片厂商官网或 Keil Pack 中获取），目前只支持[STM32F407](https://gitee.com/lcsc/fdb/releases/download/attachment-20251230/STM32F407.svd)的SVD解析。
   - （可选）ELF 文件（用于符号解析）

### 4.2 操作流程

#### Step 1: 加载 SVD 文件

> [!tip]
>
> 点击 [📂 SVD] 按钮 → 选择 .svd 文件（如 STM32F407.svd）

加载成功后，左侧树形菜单将显示所有外设。

![image-20260123115307040](./assets/image-20260123115307040.png)

中间的 **加载SVD文件** 或者右上角的 SVD,在弹出来的打开文件中，选择**STM32F407.svd** 。

#### Step 2: 连接硬件

> [!tip]
>
> 1. 将 DAPLink 通过 USB 连接到电脑
> 2. 将 DAPLink 通过 SWD 连接到目标板（SWDIO/SWCLK/GND）
> 3. 点击页面右上角 [🔌 连接] 按钮
> 4. 在弹出的 USB 设备选择框中选择 DAPLink

![20260123-115713](./assets/20260123-115713.gif)

连接成功后：
- 状态指示灯变为白色亮起
- 连接按钮变为  **断开**  状态，下方的系统日志有 `DAPLink 连接成功` 的文字提示

#### Step 3: 选择模式

| 模式 | 说明 |
|------|------|
| 🧮 计算 | 离线模式，仅进行 SVD 解析和位域计算，无需DAPLink仿真器。 |
| 🐞 调试 | 在线模式，与硬件实时同步读写，需要用DAPLink仿真器和天空星连接好。 |

默认就会是 **调试模式**。

![image-20260123120032858](./assets/image-20260123120032858.png)

#### Step 4: 使用各功能

**寄存器调试**：

1. 从左侧树形菜单选择外设（如 GPIOB，我们选择他的ODR寄存器展开看看）。
2. 点击寄存器条目展开详情。
3. 修改位域值，会自动同步到硬件，目标硬件的寄存器变化也会同步到这里。

![image-20260123120130518](./assets/image-20260123120130518.png)

**示波器监控**：

1. 切换到 "示波器" 标签页
2. 输入要监控的内存地址（如 `0x20000000`）或变量名
3. 选择数据类型（如 U32）
4. 点击 [+ 添加]
5. 调整采样率和缓冲区大小
6. 使用鼠标滚轮缩放波形，暂停后拖动时间轴回看历史

![20260123-112723](./assets/20260123-112723.gif)

**内存查看**：
1. 切换到 "内存" 标签页
2. 输入起始地址和大小
3. 点击 [读取]
4. 可切换显示宽度或导出文件

![image-20260123112946268](./assets/image-20260123112946268.png)

---

## 五 🎯 适用场景

### 5.1 嵌入式开发调试

- 验证外设寄存器配置是否正确
- 观察 GPIO 状态变化
- 分析定时器计数器行为

### 5.2  电机控制与实时系统

- 监控 PID 控制变量（Kp, Ki, Kd, 误差值）
- 观察 PWM 占空比变化
- 分析闭环控制响应曲线

### 5.3 传感器数据采集

- 实时绘制 ADC 采样值
- 监控温度、压力等物理量变化
- 对比多路传感器数据

### 5.4 固件逆向与分析

- 在不修改固件的情况下观察关键变量
- 分析未知协议的状态机变化
- 定位内存泄漏或异常写入

### 5.5 教学与演示

> [!tip]
>
> 笔者做这个，可以说纯粹是为了这盘醋包了盘饺子，本来只是为了写天空星[第九章内容](https://wiki.lckfb.com/zh-hans/fdb/basic/new-lighting-project-register.html#_7-4-%E7%94%A8%E7%BD%91%E9%A1%B5%E8%BF%9E%E6%8E%A5daplink%E4%BB%BF%E7%9C%9F%E5%99%A8%E7%9B%B4%E6%8E%A5%E4%BF%AE%E6%94%B9%E5%AF%84%E5%AD%98%E5%99%A8%E6%9D%A5%E7%82%B9%E7%81%AF)时，为了详细的为大家展示寄存器操作，只是想做一个svd文件解析，方便大家计算寄存器的值和理清概念而已，只是后来功能越做越多。

- 直观展示寄存器位域含义
- 演示 MCU 工作原理
- 学生实验数据记录

---

## 六 ⚠️ 注意事项

### 6.1 硬件相关

1. **DAPLink 兼容性**：必须使用支持 WebUSB 的 DAPLink 固件，普通 DAPLink/ST-Link/J-Link 不支持
2. **供电**：确保目标板已正确供电
3. **接线**：最少需要 SWDIO、SWCLK、GND 三根线

### 6.2 浏览器相关

1. **浏览器限制**：仅 Chrome（77+）和 Edge（Chromium 版）支持 WebUSB
2. **HTTPS 要求**：WebUSB 需要安全上下文，本地文件需通过 HTTP Server 访问或使用 `file://` 协议（部分浏览器可能受限）
3. **权限弹窗**：首次连接需在浏览器弹窗中选择设备

### 6.3 性能相关

1. **采样率限制**：
   - 受 USB 传输、SWD 时钟、浏览器调度等因素影响
   - 实际采样率可能低于设定值
   - 单通道通常可达 100-500 Hz，多通道会降低

2. **缓冲区大小**：
   - 默认 50000 点/通道，可调整
   - 过大可能导致浏览器内存占用过高

3. **MCU 状态**：
   - 暂停状态（Halt）下读取核心寄存器更准确
   - 运行状态下读取内存可能获得中间值

### 6.4 SVD 文件相关

**兼容性**：只测试了 STM32F407 芯片的SVD文件，其他芯片目前尚不兼容，需要等待后续更新，目前其他芯片版本是没有适配计划的。

### 6.5 安全相关

1. **数据安全**：所有操作在本地浏览器完成，不会上传任何数据，我们的网页也只是单纯的静态网页而已。
2. **写操作风险**：修改寄存器会直接影响硬件，请谨慎操作，避免烧毁硬件设备。

---

## 七❓ 常见问题

### Q: 点击连接后没有设备列表？

A: 请检查：
1. 是否使用最新的 Chrome/Edge 浏览器
2. DAPLink 是否正确连接且被系统识别
3. DAPLink 固件是否支持 WebUSB

![image-20260123121100463](./assets/image-20260123121100463.png)

### Q: 连接成功但无法读取寄存器？

A: 请检查：
1. 是否已切换到 调试 模式
2. SWD 接线是否正确
3. 目标板是否已上电
4. 尝试点击复位按钮

### Q: 示波器采样率很低？

A: 可能原因：
1. 通道数过多，尝试减少
2. 目标板响应慢，检查 SWD 时钟设置
3. USB 总线繁忙，尝试使用独立 USB 端口

### Q: 如何获取变量地址？

A: 有以下几种方法：
1. **Map 文件**：编译时生成 .map 文件，搜索变量名
2. **ELF 文件**：使用本工具的 ELF 加载功能
3. **调试器**：在 IDE（如 Keil、IAR）中查看变量地址
4. **链接脚本**：查看固定地址变量的定义

---

## 八🔧 技术原理

### 8.1 架构概述

```
┌─────────────────────────────────────────────────────────────┐
│                        浏览器 (Chrome/Edge)                  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  SVD 解析器  │  │  UI 渲染层   │  │     示波器绘制引擎    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    DAPjs 库                             ││
│  │  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐│ │
│  │  │ CortexM  │  │ CmsisDAP │  │       WebUSB           ││ │
│  │  └──────────┘  └──────────┘  └────────────────────────┘│ │
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              │ USB
                              ▼
                    ┌─────────────────┐
                    │    DAPLink      │
                    │   (CMSIS-DAP)   │
                    └────────┬────────┘
                             │ SWD
                             ▼
                    ┌─────────────────┐
                    │    目标 MCU     │
                    │  (Cortex-M)     │
                    └─────────────────┘
```

### 8.2 核心技术栈

| 技术 | 用途 |
|------|------|
| **WebUSB API** | 浏览器与 USB 设备通信 |
| **DAPjs** | CMSIS-DAP 协议实现 |
| **Canvas API** | 示波器波形绘制 |
| **DOMParser** | SVD (XML) 文件解析 |
| **performance.now()** | 高精度时间戳 |
| **requestAnimationFrame** | 高效绘制调度 |

### 8.3 性能优化措施

1. **批量内存读取**：使用 `readBlock` 合并相邻地址的读取请求
2. **绘制与采样分离**：采样循环和绘制循环独立运行
3. **节流刷新**：UI 更新频率与采样频率解耦
4. **二分查找**：快速定位历史数据点
5. **环形缓冲**：自动裁剪超出容量的旧数据

---

## 九 📚 相关资源

- [立创开发板官网](https://lckfb.com/)
- [示例 SVD 文件 (STM32F407)](https://gitee.com/lcsc/fdb/releases/download/attachment-20251230/STM32F407.svd)
- [立创 DAPLink 仿真器购买](https://item.szlcsc.com/56199685.html)
- [CMSIS-SVD 规范](https://www.keil.com/pack/doc/CMSIS/SVD/html/index.html)
- [DAPjs 项目](https://github.com/ARMmbed/dapjs)
- [WebUSB API 文档](https://developer.mozilla.org/en-US/docs/Web/API/WebUSB_API)

---

## 十🙏 致谢

- ARM CMSIS-DAP 开源协议
- DAPjs 开源库贡献者
- 所有提供反馈的嵌入式开发者