Skip to content
BranchesTags

Repository files navigation

OctoLink

OctoLink 是一个面向嵌入式调试的桌面工具，也是一座连接硬件与 AI Agent 的桥。

OctoLink is a desktop tool for embedded debugging, and a bridge between hardware targets and AI agents.

它把 OpenOCD、GDB、串口终端、变量监视、实时曲线、仪表盘画布和 MCP Agent 接口整合在一个应用里。你可以手动调试目标板，也可以让 Claude 等 Agent 通过 MCP 读取变量、写入变量、控制目标和查看调试状态。

It combines OpenOCD, GDB, serial communication, variable watching, live plots, dashboards, and an MCP interface in one app. You can debug manually, or let an agent such as Claude inspect variables, write values, control the target, and read debug status through MCP.

功能概览 / Features

  • 设备调试 / Target debugging: 启动 OpenOCD、连接 GDB、继续运行、中断、单步、复位暂停。
  • 变量监视 / Variable watch: 从 ELF 符号或表达式添加变量，实时读取 GDB 变量。
  • 变量写入 / Variable write: 在监视变量旁直接输入新值，按回车写入，并自动回读校验。
  • 实时曲线 / Live plots: 把 GDB 变量或串口流数据绘制成实时波形，支持缩放、滚动窗口、游标测量和 CSV 导出。
  • 仪表盘画布 / Dashboard canvas: 拖放组件搭建调试面板，支持数值卡、状态灯、位域、矩阵、数组条形图和内嵌曲线。
  • 串口终端 / Serial terminal: 打开串口、发送文本或十六进制数据，查看终端日志和流式解析结果。
  • 数据流解析 / Stream parsing: 支持 raw、line_kv、json_lines、octolink_binary 等串口数据格式。
  • 符号浏览 / Symbol browser: 从 ELF 加载变量和函数符号，按源文件分组浏览。
  • Agent Bridge / MCP: 内置 MCP server，让 Claude Code、Claude Desktop 或其他 MCP 客户端调用 OctoLink 调试工具。
  • Debug Flow / 本地调试流程: Agent 生成有界声明式流程，由 OctoLink 按本地单调时钟完成定时读取、条件等待与目标停机，不依赖 Agent 后续响应。
  • PID Agent 调参 / PID Agent tuning: 独立 IDE 式工作台，可从 ELF/GDB/数据流选择变量，采集基线，分析阶跃与采样质量，事务写入增益并读回，自动观测、比较和回滚。
  • Claude 项目一键配置 / One-click Claude setup: 在 GUI 中给任意项目生成 Claude MCP 配置和 OctoLink skill。

快速开始 / Quick Start

中文用户可先阅读普通用户教程；需要完整工程配置和串口帧时，再查看中文快速上手。需要让 Agent 编排确定性的本地调试自动化时，请阅读 Debug Flow 指南。

1. 准备环境 / Install Requirements

  • Node.js + pnpm
  • Rust toolchain
  • OpenOCD
  • 可用的调试器，例如 CMSIS-DAP、ST-Link 或 J-Link
  • 目标工程的 ELF 文件

You need Node.js, pnpm, Rust, OpenOCD, a debug adapter such as CMSIS-DAP/ST-Link/J-Link, and the ELF file of your firmware.

2. 启动 OctoLink / Run OctoLink

pnpm install
pnpm tauri dev

开发模式会打开 Tauri 桌面窗口，并启动前端热更新。

Development mode opens the Tauri desktop window and enables frontend hot reload.

3. 打开或创建工作区 / Open a Workspace

  1. 在顶部菜单中新建或打开工作区。

  2. 选择当前固件的 ELF 文件和板卡实际使用的 OpenOCD CFG 文件。

  3. 保存工作区，后续可以从最近打开列表快速恢复。

  4. Create or open a workspace from the top menu.

  5. Select the current firmware ELF and the OpenOCD CFG actually used by the board.

  6. Save the workspace so it can be reopened from the recent workspace list.

基本操作流程 / Basic Workflow

连接目标板 / Connect the Target

  1. 打开左侧的设备或调试配置区域。

  2. 填写 OpenOCD CFG 文件路径，确认 OpenOCD 命令预览正确。

  3. 点击 启动 OpenOCD。

  4. 点击 启动 GDB 或 连接。

  5. 连接成功后，状态区域会显示 OpenOCD、GDB 和目标状态。

  6. Open the device/debug panel from the left sidebar.

  7. Set the OpenOCD CFG path and check the generated OpenOCD command.

  8. Click Start OpenOCD.

  9. Click Start GDB or Connect.

  10. After connection, the status area shows OpenOCD, GDB, and target state.

浏览并添加变量 / Browse and Add Variables

  1. 打开左侧的 变量 面板。

  2. 点击 选择变量，从 ELF 符号树中浏览变量。

  3. 也可以在搜索框输入表达式，例如 uwTick、imu_data.roll。

  4. 点击变量旁的添加或拖拽点，把变量加入监视列表、曲线图或仪表盘。

  5. Open the Variables panel from the left sidebar.

  6. Click Select Variable to browse symbols from the ELF file.

  7. You can also type an expression such as uwTick or imu_data.roll.

  8. Add the variable to the watch list, plot, or dashboard using the add button or drag handle.

监视变量 / Watch Variables

  1. 打开右侧或底部的 监视变量 区域。

  2. 添加变量后，选择读取模式和数据类型。

  3. 启用轮询后，OctoLink 会持续读取变量。

  4. 可以搜索变量、批量显示或隐藏、清空历史数据。

  5. Open the Watch Variables panel.

  6. After adding variables, choose the read mode and data type.

  7. Enable polling to continuously read values from the target.

  8. Search variables, show/hide them in bulk, or clear history.

写入变量并回读 / Write and Verify Variables

  1. 目标需要处于暂停状态。运行中目标建议先点击 中断。

  2. 在监视变量旁的输入框中输入新值。

  3. 按回车写入。

  4. OctoLink 会立即回读一次，并显示写入是否成功。

  5. The target should be halted. If it is running, click Interrupt first.

  6. Type a new value into the input next to a watched variable.

  7. Press Enter to write it.

  8. OctoLink reads the value back and shows whether verification succeeded.

绘制实时曲线 / Plot Live Data

  1. 把变量拖到曲线图，或从监视变量中点击绑定曲线。

  2. 使用滚轮缩放 X 轴，拖动查看历史区间。

  3. 使用游标测量时间差和值差。

  4. 需要保存数据时导出 CSV。

  5. Drag variables into a plot, or bind them from the watch list.

  6. Use the mouse wheel to zoom the X axis and drag to inspect history.

  7. Use cursors to measure time and value differences.

  8. Export CSV when you need to save the sampled data.

使用仪表盘画布 / Build a Dashboard

  1. 打开 画布 面板。

  2. 从左侧组件库拖入数值卡、状态灯、位域、矩阵或曲线组件。

  3. 选中组件后，在右侧配置布局、绑定变量和显示选项。

  4. 支持框选、多选、整体移动、撤销、重做和保存画布文件。

  5. Open the Canvas panel.

  6. Drag numeric cards, LEDs, bitfields, matrices, or plots from the component library.

  7. Select a widget and configure layout, bindings, and display options on the right.

  8. Box selection, multi-select movement, undo, redo, and dashboard saving are supported.

使用串口终端和数据流 / Use Serial and Streams

  1. 打开 串口 面板。

  2. 选择端口、波特率、校验位、停止位和流控。

  3. 点击打开串口。

  4. 在终端中发送文本或十六进制数据。

  5. 如果串口输出是结构化数据，可以选择解码模式并把结果绑定到曲线或仪表盘。

  6. Open the Serial panel.

  7. Select port, baud rate, parity, stop bits, and flow control.

  8. Open the serial port.

  9. Send text or hexadecimal data from the terminal.

  10. If the output is structured, choose a decoder and bind stream values to plots or dashboards.

OctoLink Binary 与 OctoLite / OctoLink Binary and OctoLite

OctoLink 保留原有二进制帧协议，同时新增更轻量的 OctoLite V1 串口帧，适合高频标量、数组、矩阵和 bit matrix 数据上报。

OctoLink keeps the original binary frame protocol and adds the lighter OctoLite V1 serial frame for high-rate scalar, array, matrix, and bit-matrix telemetry.

旧协议仍然可用：

The legacy protocol remains supported:

A5 5A | version | var_id:u16le | value_type | shape_len | shape... | payload_len:u16le | payload | crc

OctoLite V1 帧格式：

OctoLite V1 frame format:

AA | var_id:u8 | type_shape:u8 | seq:u8 | payload_len:u8 | payload | crc

  • type_shape: 高 4 位是类型，低 4 位是形状。

  • seq: 高 4 位是分片序号，低 4 位是 分片总数 - 1。单帧数据为 0x00。

  • crc: 从 var_id 到 payload 的逐字节 XOR。

  • 矩阵和 bit matrix 的第 0 个分片 payload 前两个字节是 rows, cols，后面是数据。

  • type_shape: high nibble is the data type, low nibble is the shape.

  • seq: high nibble is the chunk index, low nibble is chunk_count - 1. Single-frame data uses 0x00.

  • crc: byte-wise XOR from var_id through payload.

  • Matrix and bit-matrix chunk 0 starts with rows, cols, followed by data bytes.

嵌入式端可使用 User/drv/octolinker 中的 Lite API：

Firmware can use the Lite API in User/drv/octolinker:

Octolinker_SendLiteF32(&octo, 1, imu_roll);
Octolinker_SendLiteU16Array(&octo, 2, adc_values, adc_count);
Octolinker_SendLiteU8Matrix(&octo, 3, image_u8, rows, cols);
Octolinker_SendLiteBitMatrix(&octo, 4, packed_bits, rows, cols);

在 OctoLink 软件中，把串口流解析模式设为 octolink_binary 即可同时接收旧协议和 OctoLite V1。

In OctoLink, set the serial stream decoder to octolink_binary to receive both the legacy protocol and OctoLite V1.

Agent Bridge 和 MCP / Agent Bridge and MCP

Agent Bridge 是 OctoLink 的核心能力之一。它让 AI Agent 通过 MCP 调用 OctoLink，而不是只能通过截图或文本猜测硬件状态。

Agent Bridge is one of OctoLink's core features. It lets AI agents call OctoLink through MCP instead of guessing hardware state from screenshots or logs.

启动 MCP Server / Start the MCP Server

  1. 打开左侧 Agent Bridge 页面。

  2. 确认端口，默认是 48731。

  3. 点击 启动。

  4. 状态显示为运行中后，MCP 客户端即可连接。

  5. Open the Agent Bridge page from the left sidebar.

  6. Check the port. The default is 48731.

  7. Click Start.

  8. Once the status is running, MCP clients can connect.

给 Claude 项目一键配置 / Configure a Claude Project

在 Agent Bridge 页面中使用 Claude 项目配置：

  1. 选择你要让 Claude Code 调试的项目目录。
  2. 选择或确认 octolink-mcp-proxy.exe 路径。
  3. 点击生成配置。
  4. OctoLink 会写入项目内的 .claude/settings.json 和 OctoLink skill 文档。
  5. 用 Claude Code 打开该项目，Claude 就可以看到 OctoLink MCP 工具。

Use Claude Project Setup in the Agent Bridge page:

  1. Select the project directory Claude Code should work in.
  2. Select or confirm the octolink-mcp-proxy.exe path.
  3. Generate the configuration.
  4. OctoLink writes .claude/settings.json and the OctoLink skill document.
  5. Open that project with Claude Code, and Claude can use the OctoLink MCP tools.

也可以使用脚本：

You can also use the script:

pwsh scripts/setup-claude-octolink.ps1 -ProjectPath C:\path\to\embedded-project
pwsh scripts/setup-claude-octolink.ps1 -ProjectPath C:\path\to\embedded-project -BuildProxy
pwsh scripts/setup-claude-octolink.ps1 -ProjectPath C:\path\to\embedded-project -InstallSkill

Claude 如何调用 / How Claude Uses It

配置完成后，可以直接对 Claude 说：

After setup, you can ask Claude:

读取当前 GDB 状态，并读取 uwTick、imu_data.roll、imu_data.pitch。

Read the current GDB status, then read uwTick, imu_data.roll, and imu_data.pitch.

暂停目标，读取 0x20000000 开始的 64 字节内存，然后继续运行。

Interrupt the target, read 64 bytes from 0x20000000, then continue execution.

把 motorSpeed 写成 1500，写完后回读确认。

Write motorSpeed = 1500 and verify it by reading the value back.

MCP 工具能力 / MCP Tool Capabilities

类别 / Category 能力 / Capability
后端状态 / Backend status 查询 OctoLink、OpenOCD、GDB、串口、离线符号状态
调试上下文 / Debug context 获取当前工作区、目标状态、连接状态和可用工具摘要
GDB 表达式 / GDB expressions 读取单个或多个表达式，支持安全暂停读取
变量写入 / Variable write 写入 GDB 变量并回读校验，需要 confirm: true
内存读取 / Memory read 读取 u32 或字节数组形式的目标内存
断点 / Breakpoints 列出、设置、删除断点
目标控制 / Target control continue、interrupt、step、next、reset halt
串口 / Serial 枚举端口、打开、关闭、写入、清理计数器
离线符号 / Offline symbols 查询离线符号加载状态和符号数据
Inspector 调试 / Inspector debug 获取会话状态、读取源码上下文、设置源码位置、清空 timeline
Debug Flow / 调试流程 校验并本地执行定时读取、条件等待、暂停、继续、延时与审计日志

会改变目标状态的工具通常要求传入 confirm: true。这是为了避免 Agent 无意中复位、继续运行或写坏变量。

Tools that change target state usually require confirm: true. This prevents an agent from accidentally resetting, continuing, or writing to the target.

Debug Flow：让 Agent 写流程，让 OctoLink 按时执行

对时间敏感的调试不应依赖 Agent 每一步的响应速度。Agent 可以先生成完整的 octolink.debug-flow/v1 文档，OctoLink 会静态校验步骤、总时长、最坏读取次数和权限等级；经一次授权后，本地执行器独立完成定时读取、条件判断和停机，并保留有界审计日志。

MCP 调用顺序为 debug_flow_validate → debug_session_takeover → debug_flow_start → debug_flow_get，必要时使用 debug_flow_cancel。完整格式、温度越限停机示例和安全边界见 Debug Flow 中文指南。

Debug Flow 面向毫秒至秒级调试自动化，不是硬实时安全联锁。设备限位、急停和失控保护仍必须放在 MCU 固件或独立安全硬件中。

Agent Debug Inspector

OctoLink 包含一个独立的 Agent Debug Inspector 窗口，用于实时查看调试会话：目标状态、断点、监视变量、源码（带当前行高亮）和 Agent 时间线（记录每次 MCP 工具调用）。

OctoLink includes a separate Agent Debug Inspector window for real-time observation of the debug session: target state, breakpoints, watched variables, source code with current-line highlight, and an agent timeline logging every MCP tool call.

  • 手动打开 / Manual: 在 Agent Bridge 侧边栏点击 Open Inspector。
  • 自动打开 / Auto-open: 在 Agent Bridge 侧边栏勾选 Auto-open Inspector on MCP start，MCP 启动时 Inspector 会自动弹出。
  • MCP 默认不弹 / MCP default: MCP Server 不会自动打开 Inspector，除非你启用自动打开或手动打开。
  • 不影响主窗口 / No main window impact: Inspector 是只读观察窗口，关闭或崩溃不影响主窗口和 MCP Server。

MCP 还提供 4 个高层调试工具供 Agent 使用：

Four high-level debug tools are available for agents:

工具 / Tool 说明 / Description
debug_get_session_state 获取 Inspector 会话快照：目标状态、断点、变量、timeline 摘要
debug_get_source_context 获取源码上下文片段，支持指定 file:line 和上下文行数
debug_open_source_location 设置 Inspector 源码位置，窗口下次刷新跳到该位置
debug_clear_session_timeline 清空 Inspector timeline 记录

常见问题 / Troubleshooting

pnpm tauri dev 无法启动 / pnpm tauri dev does not start

确认 Node、pnpm、Rust 已安装，并且 src-tauri/Cargo.toml 中默认运行目标为 octolink。

Make sure Node, pnpm, and Rust are installed, and that the default binary in src-tauri/Cargo.toml is octolink.

MCP 客户端看不到工具 / MCP tools do not appear

  1. 确认 OctoLink GUI 中 MCP Server 已启动。

  2. 确认端口和 Claude 配置一致，默认 48731。

  3. 确认 octolink-mcp-proxy.exe 路径正确。

  4. 重启 Claude Code 或 Claude Desktop。

  5. Make sure the MCP Server is running in the OctoLink GUI.

  6. Make sure the port matches the Claude config. The default is 48731.

  7. Check the octolink-mcp-proxy.exe path.

  8. Restart Claude Code or Claude Desktop.

读取或写入变量超时 / Variable read or write times out

GDB 对运行中的目标读取变量并不总是稳定。建议先中断目标，或者使用安全读取工具让 OctoLink 自动暂停、读取、恢复。

GDB reads on a running target are not always reliable. Interrupt the target first, or use the safe read tool so OctoLink can halt, read, and resume automatically.

写入变量失败 / Variable write fails

写入变量前请确认：

  • 目标处于暂停状态。
  • 表达式存在并且有符号信息。
  • 值的格式适合目标变量类型。
  • MCP 调用中包含 confirm: true。

Before writing a variable, check that:

  • The target is halted.
  • The expression exists and debug symbols are available.
  • The value format matches the target variable type.
  • The MCP call includes confirm: true.

Proxy 连接异常 / Proxy connection issues

如果旧的 MCP proxy 进程异常残留，可能会导致新连接超时。重启 MCP Server 或结束旧 proxy 进程后再试。

If an old MCP proxy process is left behind, new connections may time out. Restart the MCP Server or terminate the old proxy process and try again.

开发命令 / Development Commands

# Frontend and Tauri development
pnpm install
pnpm tauri dev

# Production frontend build
pnpm build

# Rust backend check
cd src-tauri
cargo check

# MCP proxy build
cd src-tauri
cargo build --bin octolink-mcp-proxy

# MCP proxy tests
cd src-tauri
cargo test --bin octolink-mcp-proxy

发布打包 / Release Packaging

Windows release 建议使用一键脚本：

Use the release script for Windows packaging:

powershell scripts/package-release.ps1 -Version 0.1.0

默认只构建 NSIS 安装包，避免 Windows 首次打包时因为下载 WiX 而失败。需要 MSI 时可以运行：

By default the script builds the NSIS installer only, which avoids the first-run WiX download on Windows. To build MSI as well:

powershell scripts/package-release.ps1 -Version 0.1.0 -Bundles "nsis,msi"

NSIS 安装向导使用 OctoLink 品牌页面，模板和可维护的源图位于 src-tauri/windows。安装、静默更新和卸载行为仍沿用与当前 Tauri CLI 版本匹配的官方模板。

The NSIS wizard uses an OctoLink-branded interface. Its template and maintainable source artwork live in src-tauri/windows; install, silent-update and uninstall behavior remains based on the official template matching the current Tauri CLI version.

脚本会完成这些步骤：

The script does the following:

  1. 更新 package.json、src-tauri/tauri.conf.json、src-tauri/Cargo.toml 中的版本号。
  2. 构建前端。
  3. 构建 release 版 octolink-mcp-proxy.exe。
  4. 把 proxy 复制到 src-tauri/resources/octolink-mcp-proxy.exe，并将 src-tauri/resources 目录作为 Tauri bundle resource 打进安装包。
  5. 执行 pnpm tauri build 并打印安装包路径。

用户发布包只需要安装主程序安装包，不需要单独安装 octolink-mcp-proxy.exe。Agent Bridge 的 Claude 项目配置会自动解析安装目录中的内置 proxy 路径，并写入目标项目的 .mcp.json / .claude/settings.json。

End users only need the main OctoLink installer. They do not need to install octolink-mcp-proxy.exe separately. Agent Bridge resolves the bundled proxy path automatically and writes it into the target project's .mcp.json / .claude/settings.json.

MCP smoke test 需要先打开 OctoLink GUI 并启动 MCP Server：

Run the MCP smoke test after starting the OctoLink GUI and MCP Server:

powershell scripts/mcp-proxy-smoke.ps1 -Build

更多文档 / More Documentation

推荐开发环境 / Recommended IDE

  • VS Code
  • Tauri extension
  • rust-analyzer

License

To be decided.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages