# VarScope

**Repository Path**: restar_2/VarScope

## Basic Information

- **Project Name**: VarScope
- **Description**: 可以监视变量，可以看变量波形，不支持修改变量，不支持指针结构体的监视
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VarScope

`VarScope` 是一个面向嵌入式调试的 Windows 桌面变量观察工具。它通过 `elf + OpenOCD + 调试器` 直接读取 MCU 固件里的全局变量，并把变量值实时显示、绘图、记录和导出。

它不占用串口，适合在程序运行时观察 PID、IMU、姿态角、电机反馈、控制量等变量。只要 elf 中保留了调试信息，VarScope 就可以解析全局变量、结构体成员和数组元素。

## 背景

一开始做这个工具，是因为我没有找到一款足够顺手的软件来配合 DAPLink / CMSIS-DAP 做变量观察和调试。很多时候，我只是想在机器人程序运行时快速看几个全局变量、控制量或者传感器反馈，但又不想额外占用串口，也不想为了临时调试写一套通信协议。

刚好我也想亲身体验一下 vibe coding，于是尝试把这个想法做成一个能实际使用的小工具，并给它取名为 `VarScope`。

设计和优化过程中，我一直尽量朝着简单、直接、少配置的方向做：打开软件，选好 `.elf` 和 OpenOCD `.cfg`，连接目标板，然后搜索变量、添加变量、开始绘图。能少点一步就少点一步，能不让使用者理解内部细节就不暴露内部细节。

## 下载

用户可以在右侧 Releases 中下载最新版 `VarScope-portable-版本号.zip`。

![alt text](image.png)

## 主要功能

- 通过 elf/DWARF 解析全局变量、结构体成员和数组元素。
- 通过 OpenOCD 读取目标板内存，不占用串口。
- 支持单独添加变量，也支持批量添加变量。
- 支持变量实时 Watch、实时曲线绘图、点值查看和 CSV 导出。
- 支持主图局部缩放、框选放大、全局视图拖动观察。
- 支持保存常用 elf / cfg 路径，方便下次快速打开。

## 适用场景

VarScope 比较适合这些调试场景：

- RoboMaster / 嵌入式项目中观察 PID、IMU、姿态角、电机反馈等变量。
- 使用 DAPLink、CMSIS-DAP、ST-Link 等调试器连接目标板。
- 已经有带调试信息的 `.elf`文件。
- 希望在不占用串口的情况下观察程序运行状态。

## 快速开始

### 使用便携版

下载 `VarScope-portable-版本号.zip` 后，先完整解压到一个固定目录。第一次使用前，请在解压后的 `VarScope` 文件夹中打开 PowerShell，输入下面这一行指令安装运行依赖：

```powershell
python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 1000 --retries 10 -r requirements.txt
```

如果网络不稳定，可以使用：

```powershell
python -m pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 1000 --retries 10 -r requirements.txt
```

依赖安装完成后，运行 `VarScope.exe` 即可。

便携版仍然需要电脑具备这些外部条件：

- Python 和 pip 可用，用于执行上面的依赖安装命令。
- OpenOCD 可用。
- 调试器驱动正常，例如 ST-Link、DAPLink 或 CMSIS-DAP 驱动。
- 有当前工程对应的 `.elf`。
- 有当前目标板和调试器对应的 OpenOCD `.cfg` 文件。

### 创建桌面快捷方式

便携版解压后，进入 `VarScope` 文件夹，直接双击内置的文件：

```text
Create-Desktop-Shortcut.cmd
```

脚本会在桌面创建 `VarScope` 快捷方式，后续可以通过快捷方式直接打开软件。

## 基本使用流程

1. 打开 `VarScope.exe`或者桌面快捷方式。
2. 在 `elf` 一栏选择带调试信息的`.elf`固件文件。
3. 在 `cfg` 一栏选择当前板子和调试器对应的 OpenOCD 配置文件。
4. 点击 `连接`，等待状态显示为绿色，表示已连接。
5. 在变量输入框里搜索变量名。
6. 选择变量后点击 `添加变量`，或使用 `批量添加` 一次添加多个变量。
7. 点击 `开始绘图` 开始采集和绘图。
8. 点击 `停止绘图` 停止采集。
9. 如果需要保存数据，点击 `导出 CSV`。

![alt text](image-2.png)

## 变量搜索和添加

VarScope 支持直接搜索 elf/DWARF 中解析出的变量。常见表达式包括：

```text
variable
struct.member
array[index]
array[index].member
```

示例：

```text
gyro.x
gyro.y
gyro.z
Eulr.pitch
Eulr.roll
Eulr.yaw
motor[0].speed
```

说明：

- 结构体本身通常不是可直接绘图的数值，应该添加结构体内部的具体成员。
- 如果变量搜索不到，请确认 elf 是 Debug 构建，并且没有被编译器优化掉。
- 如果变量能搜索到但无法采集，请检查变量类型是否为可读取的基础数值类型。

## 主要交互

### 添加变量

可以通过两种方式添加变量：

- `添加变量`：选择一个变量后单独添加。
- `批量添加`：一次添加多个变量，适合同时观察一组姿态角、电机反馈或控制量。

![alt text](image-1.png)

### 绘图观察

点击 `开始绘图` 后，主图会显示最近一段时间的变量变化，全局视图会显示更长时间范围内的整体趋势。

常用操作：

- `开始绘图` / `停止绘图`：控制数据采集和曲线刷新。
- `点值`：开启后，鼠标移动到主图附近时，可以查看对应时刻附近的变量值。
- 鼠标滚轮：缩放主图。
- 鼠标左键框选：放大选中的局部区域。
- 全局视图：查看整体数据走势，并拖动当前主图观察区域。
- `回到最新`：让主图回到最新数据窗口，并继续跟随刷新。
- 勾选列：控制某个变量是否参与绘图。

![alt text](image-3.png)

### 清空变量

点击 `清空变量` 后，会同时清空 Watch 栏和当前图像中的变量曲线。

## 存档功能

上方的 `存档` 功能用于保存常用工程配置。它会记录当前选择的 elf 和 cfg 路径，方便下次快速切换。
并且，在存档菜单中把光标放在对应存档上，可以点击叉号删除存档。

![alt text](image-4.png)

注意：存档保存的是路径，不是把 elf 和 cfg 文件复制进 VarScope。因此如果移动了工程目录，旧存档可能需要重新选择文件。

## 数据文件位置

便携版运行时会在 `VarScope.exe` 旁边的 `runtime` 目录保存数据：

- 采集会话：`runtime/sessions/capture-*.sqlite`
- 工程存档：`runtime/saved_presets.json`

移动或分享便携版时，保持整个 `VarScope` 文件夹结构不变即可。

## 从源码运行

如果你是在源码工程里运行 VarScope，同样先按上面的依赖安装命令安装 `requirements.txt`。

源码版启动命令：

```powershell
python launch_varscope.py
```

## 常见问题

### 打不开或缺少 DLL

请确认你没有只复制 `VarScope.exe`，而是完整解压并保留整个 `VarScope` 文件夹。

### 连接失败

优先检查这些内容：

- OpenOCD 是否能被找到。
- `.cfg` 文件是否适配当前调试器和目标芯片。
- ST-Link、DAPLink 或 CMSIS-DAP 驱动是否安装正常。
- 目标板是否正常供电。
- 调试接口接线是否正常。

### 变量搜索不到

优先检查这些内容：

- elf 是否是 Debug 版本。
- 编译时是否保留了调试信息。
- 变量是否是全局变量或静态存储期变量。
- 变量是否被优化掉。

## 反馈与迭代

这个工具还会继续迭代。如果使用过程中遇到问题，或者有功能建议，可以发到我的邮箱：`2410048988@qq.com`。

后续我也会在 GitHub 上持续整理 issue、修复问题和增加新功能。

## 许可证

本项目使用 MIT License 开源，详见 [LICENSE](LICENSE)。