# openocd-remote

**Repository Path**: waterguy/openocd-remote

## Basic Information

- **Project Name**: openocd-remote
- **Description**: OpenOCD remote debug bridge - GDB/Telnet relay with SSH tunnel support
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenOCD Remote

远程 OpenOCD 连接、烧录与调试工具 — 内置 GDB 工具链，支持 SSH 隧道、GDB/Telnet Bridge 透传、Cortex-Debug 集成。

> 作者：atul / 划水佬 | 许可证：GPL-3.0-or-later
>
> 开源地址：[https://gitee.com/waterguy/openocd-remote](https://gitee.com/waterguy/openocd-remote)

---

## 目录

- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [安装](#安装)
- [CLI 使用指南](#cli-使用指南)
  - [Daemon 管理](#1-daemon-管理)
  - [连接 OpenOCD](#2-连接-openocd)
  - [烧录固件](#3-烧录固件)
  - [擦除 Flash](#4-擦除-flash)
  - [执行 Tcl 命令](#5-执行-tcl-命令)
  - [Bridge 透传](#6-bridge-透传)
  - [工具链检测](#7-工具链检测)
  - [Cortex-Debug 配置生成](#8-cortex-debug-配置生成)
  - [连接历史](#9-连接历史)
- [GUI 使用指南](#gui-使用指南)
  - [界面布局](#界面布局)
  - [直连模式](#直连模式)
  - [SSH 隧道模式](#ssh-隧道模式)
  - [烧录面板](#烧录面板)
  - [Bridge 透传面板](#bridge-透传面板)
  - [Cortex-Debug 集成](#cortex-debug-集成)
- [EIDE Custom CLI 烧录器配置](#eide-custom-cli-烧录器配置)
- [架构设计](#架构设计)
- [开发](#开发)
- [打包发布](#打包发布)

---

## 功能特性

| 特性 | 说明 |
|------|------|
| **双连接模式** | 直连 IP / SSH 隧道，SSH 自动端口转发 |
| **内置 GDB** | x86_64 arm-none-eabi-gdb 10.2，无需额外安装 |
| **固件烧录** | 支持 hex/bin/elf/s19，烧录后自动复位+验证 |
| **GDB Bridge** | 本地 GDB 端口透传到远程 OpenOCD |
| **Telnet Bridge** | 本地 Telnet 端口透传到远程 OpenOCD |
| **Cortex-Debug 集成** | 一键生成 VS Code launch.json + tasks.json |
| **连接状态持久化** | 自动记忆上次连接模式、SSH 账号密码 |
| **连接历史** | CRUD 管理，双击历史条目快速重连 |
| **GDB 可用性验证** | 自动跳过损坏的工具链（如 i686 缺 DLL） |
| **跨平台** | Windows 为主，Linux/macOS 兼容 |

---

## 快速开始

### 下载即用

从 [Release](https://gitee.com/waterguy/openocd-remote/releases) 下载压缩包，解压后：

```
# GUI — 双击 openocd-remote.exe
openocd-remote.exe

# CLI — 命令行使用
openocd-remote.exe flash firmware.hex
```

### 从源码运行

```bash
git clone https://gitee.com/waterguy/openocd-remote.git
cd openocd-remote
pip install -e .

# CLI
openocd-remote flash firmware.hex

# GUI
python -m src
```

---

## 安装

### 方式一：发布包（推荐）

下载 `openocd-remote-vX.X.zip`，解压即用，无需 Python 环境。

### 方式二：从源码安装

```bash
pip install -e ".[dev]"   # 含开发依赖（pytest 等）
pip install -e ".[pack]"  # 含打包依赖（pyinstaller）
```

> **注意**：内置 GDB 工具链在 `tools/gdb/` 目录（70MB），需单独放置。
> 运行 `openocd-remote config detect` 可查看当前工具链状态。

---

## CLI 使用指南

所有 CLI 操作通过 IPC 与 Daemon 通信，Daemon 自动启停，无需手动管理。

### 1. Daemon 管理

```bash
# 启动 Daemon（通常自动触发，无需手动）
openocd-remote daemon start

# 查询 Daemon 状态
openocd-remote daemon status

# 停止 Daemon
openocd-remote daemon stop
```

**Daemon 状态输出示例：**
```
Daemon: 运行中
  PID:         12345
  IPC 端口:    8329
  版本:        1
  连接状态:    已连接
  连接模式:    ssh
  活跃适配器:  gdb_bridge, telnet_bridge
```

### 2. 连接 OpenOCD

#### 直连模式

```bash
openocd-remote connect 192.168.1.100
```

#### SSH 隧道模式

```bash
openocd-remote connect --ssh \
  --ssh-host 192.168.1.100 \
  --ssh-user root \
  --ssh-password 123456 \
  --remote-tcl-port 6666 \
  --remote-telnet-port 4444 \
  --remote-gdb-port 3333
```

**SSH 参数说明：**

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--ssh` | — | 启用 SSH 隧道模式 |
| `--ssh-host` | — | SSH 服务器地址 |
| `--ssh-port` | 22 | SSH 服务器端口 |
| `--ssh-user` | — | SSH 用户名 |
| `--ssh-password` | — | SSH 密码 |
| `--ssh-key` | — | SSH 私钥路径（替代密码） |
| `--remote-tcl-port` | 6666 | 远程 OpenOCD Tcl 端口 |
| `--remote-telnet-port` | 4444 | 远程 OpenOCD Telnet 端口 |
| `--remote-gdb-port` | 3333 | 远程 OpenOCD GDB 端口 |

#### 断开连接

```bash
openocd-remote disconnect
```

### 3. 烧录固件

```bash
# 基本烧录（自动验证 + 复位运行）
openocd-remote flash firmware.hex

# 烧录但不复位
openocd-remote flash firmware.hex

# 烧录后复位运行
openocd-remote flash firmware.hex --reset

# 跳过烧录验证
openocd-remote flash firmware.hex --no-verify

# 指定烧录地址（bin 格式需要）
openocd-remote flash firmware.bin --address 0x08000000
```

**参数说明：**

| 参数 | 说明 |
|------|------|
| `filepath` | 固件文件路径（.hex/.bin/.elf/.s19） |
| `--address` | 烧录起始地址（bin 格式必填，默认 0x08000000） |
| `--reset` | 烧录后复位运行 |
| `--no-verify` | 跳过烧录验证 |

**输出示例：**
```
正在烧录: firmware.hex
  烧录后将复位运行
烧录完成: ** Verified OK **
```

### 4. 擦除 Flash

```bash
# 擦除全部
openocd-remote erase

# 擦除指定区域
openocd-remote erase --address 0x08000000 --size 0x10000
```

### 5. 执行 Tcl 命令

```bash
# 单条命令
openocd-remote command "halt"

# 交互模式
openocd-remote command -i
```

**交互模式示例：**
```
OpenOCD Tcl> halt
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x08001234 msp: 0x20002000

OpenOCD Tcl> resume
resuming...

OpenOCD Tcl> exit
```

### 6. Bridge 透传

GDB Bridge 将远程 OpenOCD 的 GDB 端口映射到本地，供 VS Code Cortex-Debug 连接。

```bash
# 启动 GDB Bridge（默认监听 127.0.0.1:13333）
openocd-remote bridge start gdb

# 启动 Telnet Bridge（默认监听 127.0.0.1:14444）
openocd-remote bridge start telnet

# 指定监听端口
openocd-remote bridge start gdb --listen-port 3333

# 停止 Bridge
openocd-remote bridge stop gdb

# 查询 Bridge 状态
openocd-remote bridge status gdb
openocd-remote bridge status       # 查询全部
```

**Bridge 默认端口：**

| Bridge 类型 | 默认本地端口 | 对应远程端口 |
|-------------|-------------|-------------|
| GDB Bridge  | 13333       | 3333        |
| Telnet Bridge | 14444     | 4444        |

> 默认端口避开远程 OpenOCD 的 3333/4444，避免冲突。

### 7. 工具链检测

```bash
openocd-remote config detect
```

**输出示例：**
```
  arm-none-eabi-gdb.exe: 可用
    路径: I:\AI\openocd-remote\tools\gdb\bin\arm-none-eabi-gdb.exe
    来源: 内置
  openocd.exe: 可用
    路径: D:\OpenOCD\bin\openocd.exe
    来源: 系统 PATH
```

**工具链搜索优先级：** 内置 > 系统 PATH > EIDE 工具目录

> 内置 GDB 优先，且经过 `gdb --version` 启动验证，不可用的路径自动跳过。

### 8. Cortex-Debug 配置生成

```bash
# 自动探测 ELF + GDB，生成到 .vscode/
openocd-remote config debug-generate

# 指定 ELF 和 GDB
openocd-remote config debug-generate --elf build/firmware.elf --gdb /path/to/gdb

# 指定 GDB 连接端口
openocd-remote config debug-generate --gdb-port 13333

# 仅预览不写入
openocd-remote config debug-generate --dry-run

# 指定输出路径
openocd-remote config debug-generate --output .vscode/launch.json
```

**生成的 launch.json 配置使用 `servertype: "external"` + `request: "attach"` 模式：**

- Bridge 作为外部 GDB Server 透传
- Cortex-Debug 不执行 target-download
- 若 Daemon 未运行，自动添加 preLaunchTask/postDebugTask

### 9. 连接历史

```bash
# 列出所有历史
openocd-remote history list

# 添加历史条目
openocd-remote history add --name "开发板" --host 192.168.1.100 --mode direct

# 添加 SSH 历史条目
openocd-remote history add --name "远程服务器" --host 10.0.0.1 --mode ssh

# 删除历史条目
openocd-remote history remove <id>
```

---

## GUI 使用指南

### 启动

```
# 直接双击 openocd-remote.exe（无参数 = GUI 模式）
# 或命令行：
openocd-remote.exe
```

GUI 启动后自动启动 Daemon 并恢复上次的连接模式。

### 界面布局

```
┌──────────────────────────────────────────────────────────┐
│  菜单栏: 文件 | Daemon | 帮助                            │
├────────────┬──────────────────────────┬──────────────────┤
│            │  ┌─────────────────────┐ │                  │
│  连接管理   │  │ Tcl 命令 | 烧录 | 调试│ │  Bridge 透传     │
│  (左侧)    │  │                     │ │  (右侧)          │
│            │  │    中央 Tab 区域     │ │                  │
│  · 直连/SSH│  │                     │ │  · GDB Bridge    │
│  · 配置表单│  │                     │ │  · Telnet Bridge │
│  · 连接/断开│  │                     │ │  · Cortex-Debug  │
│            │  │                     │ │    配置导出       │
│            │  └─────────────────────┘ │                  │
├────────────┴──────────────────────────┴──────────────────┤
│  连接历史 (底部) — 双击条目可快速重连                       │
├──────────────────────────────────────────────────────────┤
│  状态栏: Daemon: 运行中 | OpenOCD: 已连接 (SSH)           │
└──────────────────────────────────────────────────────────┘
```

### 直连模式

1. 在左侧「连接管理」面板选择「直连」
2. 输入 OpenOCD 主机 IP 地址
3. 点击「连接」

### SSH 隧道模式

1. 在左侧「连接管理」面板选择「SSH」
2. 填写 SSH 服务器地址、用户名、密码
3. 确认远程 OpenOCD 端口（默认 6666/4444/3333）
4. 点击「连接」

> SSH 模式的账号密码会自动保存，下次启动自动恢复。

### 烧录面板

中央 Tab →「烧录」标签页：

1. 点击「浏览」选择固件文件（自动检测格式）
2. 可选：配置起始地址、Flash Bank
3. 勾选/取消「烧录后复位运行」「烧录后验证」
4. 点击「烧录」，进度条实时显示

```
┌─ 固件文件 ────────────────────────────┐
│ [E:\project\build\firmware.hex] [浏览] │
├─ 参数配置 ────────────────────────────┤
│ 文件格式:  [自动检测 ▼]               │
│ 起始地址:  [0x08000000          ]     │
│ Flash Bank: [自动]                    │
│ ☑ 烧录后复位运行                      │
│ ☑ 烧录后验证                          │
├───────────────────────────────────────┤
│       [烧录]    [验证]                 │
│ ████████████████████░░░░ 80%          │
│ 开始烧录: firmware.hex                │
│ 烧录成功: ** Verified OK **           │
└───────────────────────────────────────┘
```

### Bridge 透传面板

右侧「Bridge 透传」面板：

1. 确保已连接远程 OpenOCD
2. 点击 GDB Bridge「启动」→ 本地 13333 端口映射到远程 3333
3. 点击 Telnet Bridge「启动」→ 本地 14444 端口映射到远程 4444
4. 状态实时显示（已连接客户端数、转发字节数等）

### Cortex-Debug 集成

右侧「Bridge 透传」面板下方的 Cortex-Debug 区域：

1. 先启动 GDB Bridge
2. 选择项目目录（含 .vscode/ 的工作区）
3. ELF 文件和 GDB 路径自动检测
4. 点击「写入 launch.json」或「复制配置」

生成的配置可直接在 VS Code 中按 F5 启动调试。

---

## EIDE Custom CLI 烧录器配置

在 EIDE 项目的 `.code-workspace` 或 `eide.json` 中配置自定义烧录器：

### 烧录命令

```json
{
  "burner": {
    "type": "custom",
    "command": "openocd-remote",
    "args": ["flash", "${hexFile}"],
    "cwd": "${workspaceFolder}"
  }
}
```

### 擦除命令

```json
{
  "burner": {
    "type": "custom",
    "command": "openocd-remote",
    "args": ["erase"],
    "cwd": "${workspaceFolder}"
  }
}
```

### 合并配置（烧录 + 复位 + 验证）

```json
{
  "burner": {
    "type": "custom",
    "command": "openocd-remote",
    "args": ["flash", "${hexFile}", "--reset"],
    "cwd": "${workspaceFolder}"
  }
}
```

> **前提**：使用 CLI 前需确保 Daemon 已运行并已连接远程 OpenOCD。
> 可通过 `openocd-remote daemon start` + `openocd-remote connect ...` 预先建立连接。

---

## 架构设计

### 七层分治架构

本项目采用 **七层分治架构** — 一种强调**单向依赖**和**职责隔离**的工程化架构模式。每一层只允许依赖规定方向上的下层，杜绝循环依赖和跨层耦合，使代码可独立测试、可独立演进。

```
                  coordination (.ai/)    → 开发状态持久化、上下文容灾
                       ↓ 可读取所有层
    ┌─────────────────┼─────────────────┐
    ↓                 ↓                 ↓
presentation      interface          core
(PySide6 GUI)     (IPC 客户端)       (业务核心)
    ↓                 ↓                 ↓
    └─────────────────┼─────────────────┘
                      ↓ 均可依赖
                  shared              → 常量、类型、异常、日志 (零依赖)
                      ↑ 被所有层依赖
                  testing             → 各层测试 (不被任何层依赖)
                      ↑ 被所有层依赖
                  docs                → 人与项目交互接口 (禁止被代码层依赖)
```

> 本项目的七层分治实践由 [ai-coordination](https://github.com/Atul-8/ai-coordination) 驱动 —
> 一款面向 AI 辅助开发的 **六/七层分治架构 Skill**，自动同步 `.ai/` 对接层、
> 强制依赖规则检查、错误五步法提炼、开发状态容灾续接。
> **让你的 AI 编程助手始终在架构纪律内工作。**

#### 各层职责与项目映射

| 层级 | 职责 | 依赖方向 | 本项目映射 |
|------|------|---------|-----------|
| **coordination** | 开发状态持久化、上下文容灾、错误知识库 | 可读取所有层，禁止被代码层依赖 | `.ai/` 目录 — 工作状态、操作日志、META 规则 |
| **presentation** | 用户交互、视图渲染、输入输出 | → interface, shared | `src/presentation/` — GUI 窗口、面板、应用入口 |
| **interface** | 对外接口封装、协议适配、类型契约 | → core, shared | `src/interface/` — IPC 通信服务、Adapter 管理 |
| **core** | 业务逻辑、算法实现、数据处理 | → shared only | `src/core/` — 连接、Adapter、IPC Server、Daemon |
| **shared** | 跨层通用基础能力 | 无依赖（零依赖层） | `src/shared/` — 常量、类型、异常、日志 |
| **testing** | 各层接口验证、集成回归守护 | 可依赖所有被测层 | `testing/` — 单元/契约/集成测试 |
| **docs** | 人与项目数据交互接口 | 可读取所有层，禁止被代码层依赖 | `docs/` — 使用指南、架构说明 |

#### 依赖规则一图看懂

```
coordination ← 可读取所有层，不被任何层依赖
     │
     ▼
presentation ──→ interface ──→ core ──→ shared（零依赖）
     │               │           │         ▲
     └───────────────┴───────────┘         │
              均可依赖                      │
                                           │
testing ──→ 可依赖所有被测层 ──────────────┘
docs ──→ 可读取所有层，不被任何代码层运行时依赖
```

**核心纪律：**
- `presentation` 禁止直接依赖 `core` — 必须通过 `interface` 层中转
- `core` 禁止依赖 `interface` 或 `presentation` — 业务逻辑与 UI 解耦
- `shared` 零依赖 — 不 import 项目内任何其他模块
- `coordination` 和 `docs` 是元数据层，不参与运行时代码依赖

### 核心数据流

```
用户 → GUI / CLI
        ↓
   IPC Client (JSON+newline over TCP)
        ↓
   Daemon (后台进程)
        ├── ConnectionSession → SSH Tunnel / Direct → 远程 OpenOCD
        ├── GDB Bridge Adapter → TcpRelay → 本地:13333 ↔ 远程:3333
        ├── Telnet Bridge Adapter → TcpRelay → 本地:14444 ↔ 远程:4444
        └── ConnectionHistory → JSON 持久化
```

### 单入口设计

```
openocd-remote.exe
  ├── (无参数 / --gui)  → GUI 模式 (PySide6, 自动隐藏控制台)
  ├── --daemon          → Daemon 子进程模式 (自动启动)
  └── 其他参数           → CLI 模式 (argparse)
```

> Daemon 子进程由 `DaemonManager` 通过 `sys.executable --daemon` 启动，
> 确保 PyInstaller 打包后也能正常工作。

### 内置工具链

```
tools/gdb/
  ├── bin/
  │   ├── arm-none-eabi-gdb.exe      # GDB 主程序
  │   ├── arm-none-eabi-gdb-py3.exe  # GDB Python 脚本版
  │   ├── arm-none-eabi-nm.exe       # 符号表工具
  │   ├── arm-none-eabi-objdump.exe  # 反汇编工具
  │   └── *.dll                       # 运行时依赖
  └── lib/python3.7/                 # GDB Python 脚本依赖
```

> 来源：xPack x86_64 mingw 工具链 (GDB 10.2)，无系统 Python DLL 依赖。

---

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest testing/ -v

# 运行 GUI（开发模式）
python -m src

# 运行 CLI（开发模式）
python -m src --help
python -m src flash firmware.hex
```

---

## 打包发布

```bash
# 安装打包依赖
pip install -e ".[pack]"

# 构建 onedir 分发包
pyinstaller openocd-remote.spec --clean -y

# 产物位于
dist/openocd-remote/
  ├── openocd-remote.exe
  └── _internal/
      ├── tools/gdb/          # 内置 GDB 工具链
      ├── PySide6/            # Qt 运行时
      └── ...                 # Python 依赖
```

> 打包后约 203MB（含 PySide6 运行时 + 内置 GDB 70MB）。
> 分发时压缩整个 `dist/openocd-remote/` 目录即可。

---

## 许可

GPL-3.0-or-later