# JlinkHEX

**Repository Path**: mingkjl/jlink-hex

## Basic Information

- **Project Name**: JlinkHEX
- **Description**: No description available
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JlinkHEX

JlinkHEX 是一个面向 Windows 的 J-Link HEX 固件烧录桌面工具。它使用 Python
和 PySide6（Qt）提供现代化图形界面，通过 SEGGER J-Link DLL 与调试器、目标
芯片通信，可完成连接、擦除、烧录、回读校验、加锁和复位等操作。

## 功能特点

- 自动查找常见目录中的 SEGGER J-Link 软件，也可手动指定安装目录。
- 基于 PySide6 的深色卡片式界面，配置、快捷操作、工作流和日志分区显示。
- 从 J-Link DLL 或设备数据库中发现目标器件，支持搜索和手动输入型号。
- 枚举当前连接的 J-Link，存在多个调试器时可按序列号选择。
- 支持 SWD、JTAG 接口以及自定义通信速度。
- 支持连接、整片擦除、烧录、校验、烧录并校验、加密（加锁）和目标复位。
- 可勾选多个步骤，通过“开始”按钮按固定顺序执行，并显示流程进度。
- 校验时解析 Intel HEX 文件，回读目标内存后逐字节比较。
- 自动保存上次使用的参数，并按照使用频率优先排列常用器件和 J-Link。
- 耗时操作在后台线程中执行，运行日志会实时显示在界面中。

## 运行环境

- Windows 10/11
- Python 3.10 或更高版本
- SEGGER J-Link Software and Documentation Pack
- J-Link 调试器、目标板及对应的 Intel HEX 固件

图形界面依赖 PySide6，其余功能使用 Python 标准库。PySide6 的 Python wheel
已经包含运行所需的 Qt 库，无需另外安装 Qt SDK。

J-Link 安装目录中应至少包含与 Python 位数匹配的 `JLink_x64.dll` 或
`JLinkARM.dll`。完整功能还需要 `JLink.exe`，回读校验以及 DLL 擦除失败后的
回退流程会使用它。

## 快速开始

1. 下载或克隆本项目：

   ```powershell
   git clone <repository-url>
   cd JlinkHEX
   ```

2. 建议创建虚拟环境并安装依赖：

   ```powershell
   python -m venv .venv
   .\.venv\Scripts\python -m pip install -r requirements.txt
   ```

3. 安装 SEGGER J-Link 软件，并连接 J-Link、目标板和目标板电源。

4. 启动程序：

   ```powershell
   .\.venv\Scripts\python app.py
   ```

   如果不使用虚拟环境，也可以在安装依赖后运行：

   ```powershell
   python app.py
   ```

## 使用方法

1. 确认“J-Link 目录”指向 SEGGER J-Link 的安装目录。程序会优先自动查找，
   未找到时可点击“浏览”手动选择。
2. 点击“选择”载入扩展名为 `.hex` 的固件。
3. 选择或输入准确的目标器件名称。
4. 刷新并选择要使用的 J-Link；只连接一个调试器时程序会自动选中它。
5. 根据目标板设置 SWD/JTAG 接口和通信速度，默认速度为 4000 kHz。
6. 点击单项操作按钮，或配置“开始按钮执行顺序”后点击“开始”。
7. 在底部日志区域查看连接参数、J-Link 输出、执行进度和错误提示。

“开始”流程的执行顺序固定为：

```text
连接 → 整片擦除 → 烧录 → 校验 → 加密 → 目标复位
```

未勾选的步骤会自动跳过。默认勾选“连接、烧录、校验、目标复位”，不默认执行
整片擦除和加密。

## 操作说明

| 操作 | 说明 |
| --- | --- |
| 连接 | 按当前器件、接口、速度和序列号连接目标芯片，并验证连接状态 |
| 目标复位 | 向已连接的目标芯片发送复位命令 |
| 整片擦除 | 优先调用 J-Link DLL 擦除接口，失败时回退到 J-Link Commander |
| 烧录 | 将选中的 Intel HEX 文件下载到目标芯片 |
| 校验 | 使用 J-Link Commander 回读 HEX 涉及的地址段，并逐字节比较 |
| 加密 | 调用 J-Link 通用 Lock 接口，为支持的目标器件启用保护 |
| 烧录并校验 | 依次完成 HEX 烧录和回读校验 |
| 开始 | 按勾选项执行组合流程，并显示当前步骤和完成进度 |

## 配置文件

程序会把界面参数保存在项目根目录的 `config.json` 中，包括：

- J-Link 安装目录和最近使用的 HEX 文件；
- 目标器件、J-Link 序列号、接口和速度；
- 常用器件与常用 J-Link 的使用次数。

配置文件损坏或不存在时，程序会使用默认值重新开始。该文件可能包含本机路径和
设备序列号，分享项目或提交代码前请先检查其中是否存在不希望公开的信息。

## 项目结构

```text
JlinkHEX/
├── app.py                         # 程序入口
├── config.json                    # 本地运行配置
├── requirements.txt               # Python 依赖
└── jlink_hex_tool/
    ├── __init__.py
    ├── gui.py                     # PySide6 界面、任务编排和日志
    ├── jlink.py                   # J-Link DLL/Commander 封装及 HEX 校验
    ├── device_catalog.py          # J-Link 目标器件发现
    └── config_store.py            # 配置读写与常用项排序
```

主要调用关系如下：

```text
PySide6 GUI
    ├── J-Link DLL：枚举、连接、擦除、烧录、加锁、复位
    ├── JLink.exe：回读校验及部分命令回退
    ├── 设备目录：发现和筛选目标器件
    └── config.json：保存本地配置和常用项
```

## 注意事项

- 整片擦除、烧录和加密会修改目标芯片，请在操作前确认器件型号、固件和接线。
- “加密”使用 J-Link 通用 Lock 接口，不同芯片的保护机制并不完全相同。请先阅读
  芯片手册并在可恢复的测试板上验证；部分器件解锁需要整片擦除，甚至需要专用的
  Option Bytes 或安全配置。
- 运行本工具前请关闭可能占用同一 J-Link 的 IDE、J-Flash、J-Link Commander
  或其他烧录软件。
- Python 与 J-Link DLL 的位数需要一致；64 位 Python 通常应配合
  `JLink_x64.dll`。
- 连接失败时，优先检查目标供电、VTref、GND、SWDIO/SWCLK 或 JTAG 接线、
  芯片型号、接口类型、速度以及读保护状态。

## 常见问题

### 无法加载 J-Link

确认选择的是完整的 SEGGER J-Link 安装目录，而不是单独复制 DLL 的目录。若仍然
失败，请检查 Python 与 DLL 的位数是否一致。

### 找不到目标器件

确认 J-Link 安装完整并尝试更新 SEGGER J-Link 软件。目标器件输入框也允许直接
填写 J-Link 支持的准确器件名称。

### 无法连接目标芯片

检查目标板供电和调试接口接线，确认器件型号正确，然后尝试降低通信速度，例如
从 4000 kHz 降至 1000 kHz 或 100 kHz。

### 校验失败或提示找不到 `JLink.exe`

校验功能依赖 J-Link Commander。请确认所选安装目录中存在 `JLink.exe`，并确保
目标存储器中的内容与所选 HEX 文件对应。