# JlinkTool

**Repository Path**: sylvanowong/jlink-tool

## Basic Information

- **Project Name**: JlinkTool
- **Description**: 面向 STM32F405RG 的 J-Link 在线调试与数据采集技能。
  通过 SEGGER J-Link SDK 建立长连接，支持基于 ELF/AXF/DWARF
  调试符号按变量名读取 MCU 运行参数，支持连续采集、实时数据导出、
  采集过程中按变量名写入指定参数，以及写入前后事件记录。
  支持采集线程、写入控制线程、单一 J-Link SDK 工作线程和导出线程分离，
  支持
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: Dev-Master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# JlinkTool

## 介绍

JlinkTool 是一款 AI 驱动的 J-Link 在线调试工具，专门用于分析 MCU（微控制器）运行时的参数。通过 SEGGER J-Link 连接设备，结合 ELF/DWARF 调试符号实现按变量名读取 MCU 内存，支持单次读取、周期采样、变量类型解码以及 CSV/JSON 数据导出，为 AI 在线调试固件提供便利。

**主要功能：**

- AI 智能接入 J-Link 在线分析 MCU 参数
- 通过 ELF/DWARF 调试符号按变量名读取内存
- 支持单次读取和连续采集模式
- 变量类型自动解码
- 数据导出支持 CSV 和 JSONL 格式
- 支持变量写入操作
- 适用于 STM32F405RG 等主流 MCU 平台

---

## 软件架构

```
JlinkTool/
├── stm32-jlink-debug/          # 核心调试模块
│   ├── scripts/               # Python 脚本实现
│   │   ├── jlink_debug.py     # J-Link 调试核心脚本
│   │   ├── jlink_sdk_capture.py # SDK 模式采集
│   │   ├── sequence_capture.py # 序列采集
│   │   └── single_phase_capture.py # 单阶段采集
│   ├── agents/               # AI Agent 配置
│   │   └── openai.yaml       # OpenAI 集成配置
│   ├── references/           # 参考文档
│   │   └── stm32f405rg.md    # STM32F405RG 参考指南
│   └── README.md             # 详细使用文档
└── Release/                   # 发布版本
    └── stm32-jlink-debug-V1.0/
```

---

## 环境搭建

### 1. 安装 SEGGER J-Link 软件

- 下载并安装 [SEGGER J-Link 软件包](https://www.segger.com/downloads/jlink/)
- 确保 J-Link 驱动正确安装

### 2. 安装 Python

- 需要 Python 3.6 或更高版本
- 安装必要的依赖（ctypes 等标准库通常已包含）

### 3. 准备 AXF 文件

- 确保目标固件编译时包含完整的调试符号（DWARF 信息）
- AXF/ELF 文件需要包含变量符号表

### 4. 连接硬件

- 使用 J-Link 调试器连接目标 MCU
- 确认设备连接正常

### 5. 安全检查

- 确保 J-Link 未被其他程序占用
- 检查 DLL 路径配置正确
- 验证 AXF 文件包含所需变量符号

---

## 使用说明

### 基本用法

#### 1. 查询变量符号（首次验证）

```bash
python scripts/jlink_debug.py --device STM32F405RG --symbols your_firmware.axf
```

#### 2. 单次读取

```bash
python scripts/single_phase_capture.py --device STM32F405RG --variable variable_name
```

#### 3. 连续采集

```bash
python scripts/sequence_capture.py --device STM32F405RG --variables var1,var2 --rate 100
```

#### 4. 采集并写入

```bash
python scripts/jlink_sdk_capture.py --device STM32F405RG --write PosRef=628.32
```

### AI Skill 使用方式

项目提供了 `SKILL.md` 文档，详细说明了如何将调试工具集成到 AI Agent 中使用：

```yaml
# agents/openai.yaml 配置示例
model: gpt-4
tools:
  - jlink_debug
    device: STM32F405RG
    speed: 4000
```

### 数据导出

支持多种数据导出格式：

**CSV 格式：**
```bash
python scripts/jlink_debug.py --export csv --output data.csv
```

**JSONL 格式：**
```bash
python scripts/jlink_debug.py --export jsonl --output data.jsonl
```

**实时写盘：**
```bash
python scripts/jlink_debug.py --realtime-write --output ./data/
```

---

## 默认变量

### 采集变量

- `posRef` - 位置参考值
- `velocity` - 速度值
- `current` - 电流值

### 可写变量

- `PosRef` - 目标位置参考值
- `Enable` - 使能控制

---

## 常见故障排除

### J-Link 被占用
确保没有其他程序（如 Keil、IAR）正在使用 J-Link。

### 找不到 DLL
检查 J-Link 软件安装路径，确保 DLL 可访问。

### AXF 找不到变量
- 确认固件编译时启用调试符号
- 检查 AXF 文件路径正确

### 读取值为 0
- 确认变量地址有效
- 检查变量是否已初始化

### 读取值为 0xFFFFFFFF
- 可能是内存未映射
- 检查内存地址范围

### 采集命令超时
- 检查 J-Link 连接稳定性
- 适当增加 timeout 参数

---

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

---

## 许可证

本项目遵循开源许可证，具体信息请查看 LICENSE 文件。

---

## 参考资料

- [STM32F405RG 参考文档](stm32-jlink-debug/references/stm32f405rg.md)
- [AI Skill 使用说明](stm32-jlink-debug/SKILL.md)
- [SEGGER J-Link 官网](https://www.segger.com/downloads/jlink/)

---

## 联系方式

如有疑问，请在 Issues 中提出。