# ProtoDebug

**Repository Path**: qingefable/ProtoDebug

## Basic Information

- **Project Name**: ProtoDebug
- **Description**: 可视化协议调试软件。
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ProtoDebug — LNP 协议调试工具

基于 Qt6/QML 的协议调试上位机,对接 [larkSDK](../larkproject/lark) 的 **LNP(Lark Network Protocol)组件**,提供协议帧监控、终端、Lua 脚本、两阶段 ACK 调试与链路诊断能力。架构参照 Serial-Studio。

## 功能

| 模块 | 说明 |
|---|---|
| 协议监控 | LNP 帧实时列表(方向/地址/RSP 类型/Prio/净荷/CRC),分片标记与自动重组,结构化过滤(`cmd:0x02*;sender:0x0001`) |
| 终端 | 原始字节收发,HEX dump / ASCII,时间戳,VT-100/ANSI 渲染,命令历史 |
| 协议编辑器 | LNP 帧构造(地址/Cmd/Seq 自动/Prio/TTL/RSP/ACK 请求位),实时 CRC8/CRC16/FLAGS 预览,一键发送 |
| ACK 生命周期 | REQ_ACK_NOW / REQ_ACK_FINISH 两阶段跟踪,独立超时,NOW 超时一键重传,NACK 原因码,迟到 ACK(孤儿)标记 |
| 链路诊断 | 核心段 ping(净荷回显 + RTT)、对端统计拉取(端口表 + 全局)、本地分帧计数(resync/CRC 错) |
| Lua 脚本 | `on_frame_recv` / `on_frame_send` 回调(可过滤帧),`send/log/set_timer/hex_to_bytes/plot_add` 等 API |
| 指令台 | 树形指令/分组(嵌套+折叠),Abc/HEX/LNP 三种发送方式,模板占位符(`%d`/`%.3f`/`[u16]`/`[f32]`/`[crc]`),8 种校验,循环发送(次数/间隔/无限,再点停止),JSON 导入导出,滑条/开关/模式控件可绑定指令参数化发送 |
| 工作区 | 动态标签页 + 自由布局;曲线(统计看板/XY 模式/点线模式/游标/触发)、FFT(谐波阶次柱状图/THD/谐波表)、数值、仪表、姿态 3D(STL)、滑条、开关、模式控件;帧绑定 + Lua 双通道;多选/框选/复制粘贴/布局 JSON 导入导出;CSV 导出与加载回放 |

## LNP v1 帧格式

```
SOF(1)=0xAA | ver/len(2): len低12bit+ver高4bit | CRC8(1) poly 0x07 种子 0xFF,覆盖前 3 字节
FLAGS(2) | SENDER(2) | RECEIVER(2) | SEQ(2) | CMD(2) | PAYLOAD(N) | CRC16(2) CCITT-FALSE
```
- 所有多字节字段小端;CRC16 覆盖 SOF~净荷末字节;最小帧 16B,实用上限 256B(净荷 240B)
- FLAGS:bit0 REQ_ACK_NOW | bit1 REQ_ACK_FINISH | bit2-3 RSP_TYPE(REQ/ACK_NOW/ACK_FINISH/NACK) | bit4-6 PRIO(0 最高) | bit7 FRAG | bit8 ADDR_OMIT | bit9-11 TTL | bit12 FWD
- CMD 高字节 = 业务段,低字节 = opcode;`0x00xx` 为核心段(ping 0x0001 / stats 0x0002)
- 协议规范见 lark 仓库 `doc/design/Link层设计文档.md` §4

## 构建与运行

依赖:Qt 6.10+(`~/Qt`,模块 Core/Gui/Quick/QuickControls2/Widgets/Network,可选 SerialPort/Bluetooth)、CMake 3.16+、Lua 5.4.7 源码(见下)。

```bash
# 首次:Lua 源码不入库,需先解压
tar xzf lib/lua-5.4.7.tar.gz -C lib

# 配置 + 构建
cmake -DCMAKE_PREFIX_PATH=~/Qt/6.11.1/macos -DCMAKE_BUILD_TYPE=Debug -B app/build/Qt_6_11_1_for_macOS-Debug -S .
cmake --build app/build/Qt_6_11_1_for_macOS-Debug

# 运行
app/build/Qt_6_11_1_for_macOS-Debug/ProtoDebug.app/Contents/MacOS/ProtoDebug
```

CLI 参数:`--tcp-connect host:port`(自动连接并进终端模式)、`--hex-mode`、`--timestamp`、`--demo`(注入演示帧)、`--screenshot <path>`(截图后退出)。

macOS 构建自动 ad-hoc 签名(蓝牙权限,防 BLE SIGKILL)。运行时配置写在 `~/Library/Application Support/ProtoDebug/ProtoDebug/settings.ini`,**不要**写进 app bundle(破坏签名)。

## 无硬件回环测试

```bash
# 1. 启动 LNP 回环服务器(自动应答 ACK_NOW / 延时 300ms ACK_FINISH / stats)
python3 app/tests/lnp_echo_server.py 9001

# 2. 应用内:链路类型选「网络」→ Socket 类型 TCP → 127.0.0.1:9001 → 打开连接
#    控制命令(stdin): j=注入垃圾字节  o=孤儿ACK  r=主动REQ  s=静默(测超时)  q=退出
```

单测(scratch 程序,编译命令见各文件头注释):

- `app/tests/test_lnp_codec.cpp` — 编解码参考向量 + round-trip 矩阵
- `app/tests/test_lnp_framer.cpp` — 分帧/重同步/乱序重组
- `app/tests/test_lnp_ack.cpp` — 两阶段 ACK 超时/重传/orphan/NACK 语义
- `app/tests/test_checksum.cpp` — 指令台 8 种校验算法已知向量
- `app/tests/test_template.cpp` — 指令模板填充/[crc] 挖位回填/LNP 组帧
- `app/tests/test_fft.cpp` / `test_plot_binding.cpp` — FFT 与声明式绑定
- `app/tests/test_loadcsv.cpp` — CSV 导入回放
- `app/tests/test_stl.cpp` — STL 二进制/ASCII 解析

## 目录结构

```
app/
├── src/
│   ├── DataModel/     # ProtocolEngine(LNP 编解码)、Lnp.h(协议常量)、LnpAckManager(ACK 未决表)、
│   │                  # DataMonitorModel(监控表)、QuickCommandManager(指令台树+发送引擎)、
│   │                  # SettingsManager
│   ├── IO/            # ConnectionManager(链路门面)、DeviceManager、FrameProcessor(LNP 分帧)、
│   │                  # LnpReassembler(分片重组)、Drivers/(UART/Network/BLE)
│   ├── Workspace/     # PlotDataSource(曲线数据枢纽)、PlotWidget/FFTWidget/GaugeWidget/AttitudeWidget
│   │                  # (QQuickPaintedItem 自绘)、FftCalculator、StlMesh(STL 解析)
│   ├── Script/        # LuaEngine(Lua 5.4 嵌入)
│   ├── Terminal/      # 终端模型 + QQuickPaintedItem 渲染(移植自 Serial-Studio)
│   └── Misc/          # ModuleManager(装配/接线)、Theme/Fonts/Timer/Translator
├── qml/
│   ├── Panes/         # Dashboard(监控+终端+工作区)、ToolPanel(协议编辑/快捷指令/链路诊断)、
│   │                  # ScriptEditor、Setup
│   └── Widgets/       # QuickCmd、DiagPanel(链路诊断)、StatusBar 等
├── tests/             # 单测 scratch 程序 + lnp_echo_server.py(不入 CMake)
lib/                   # lua-5.4.7(需解压)、QCodeEditor(vendored)
config/script.lua      # 示例 Lua 脚本
docs/交接文档.md        # 架构/设计决策/已知问题交接
```

详细架构与开发约定见 [CLAUDE.md](CLAUDE.md) 与 [docs/交接文档.md](docs/交接文档.md)。