# 正点原子逻辑分析仪波形查看器交接文档

## 1. 当前目标

本工具用于直接查看正点原子 ATK-Logic 导出的逻辑分析仪数据，不进入 IAR，不需要先转换成 CSV 再用 Excel 查看。

当前主图不是高低电平图，而是：

- 横轴：脉冲开始后的时间；
- 纵轴：脉冲频率，单位 Hz；
- 曲线：由相邻同方向脉冲边沿的时间差计算得到的瞬时频率；
- 关键节点：例如 `100 ms`，在图上画竖线、圆点并标出该节点后的最近完整周期频率。

## 2. 直接使用

双击：

```text
PythonTest\start_logic_csv_parser.bat
```

不需要打开 IAR，也不需要编译 PLC 工程。

界面操作：

1. 点击“选择文件”，选择 `.csv` 或 `.bin`；
2. CSV 直接点击读取；
3. BIN 先填写采集时的采样率和通道数，再点击“读取并显示”；
4. “显示通道”可以填写 `自动`、`4`、`0,1,4` 或 `0-7`；
5. “测量边沿”可以选自动、上升沿、下降沿；
6. “关键时间(ms)”可以填写 `100` 或 `100,200,500`；
7. 鼠标滚轮缩放时间，按住鼠标左键水平拖动，点击“适应窗口”恢复全范围。

## 3. 文件结构

### `logic_waveform.py`

解析和计算核心：

- `load_csv_waveform()`：读取 CSV 元数据、时间列和通道跳变；
- `load_bin_waveform()`：读取无文件头的原始 BIN；
- `load_waveform()`：根据扩展名选择 CSV 或 BIN；
- `WaveformChannel`：保存一个数字通道的跳变时间和电平；
- `FrequencyCurve`：保存频率曲线时间点和频率值；
- `build_frequency_curve()`：按边沿计算瞬时频率；
- `build_frequency_curves()`：批量生成通道曲线；
- `parse_marker_times_ms()`：解析关键时间输入。

### `parse_logic_gui.py`

Tkinter 图形界面：

- 文件选择和后台读取；
- 频率曲线绘制；
- Hz 纵轴和时间横轴；
- 关键时间标记；
- 缩放、拖动、光标频率显示；
- 自动、上升沿、下降沿选择。

### `parse_logic_csv.py`

原来的 CSV 通用解析和 CSV 输出命令行工具仍然保留，GUI 当前不把保存 CSV 作为主流程。

### `test_logic_waveform.py`

波形解析测试，覆盖：

- CSV 元数据和通道跳变；
- 16 通道 BIN；
- 通道选择；
- 上升沿、下降沿和自动边沿频率计算；
- 关键时间解析。

## 4. 频率计算定义

原始 CSV/BIN 中保存的是数字电平，不是频率。程序按以下方式换算：

```text
频率 = 1 / 相邻同方向边沿的时间差
```

注意事项：

- `times[0]` 是文件初始电平状态，不作为真实边沿；
- 自动模式使用捕获到的第一个真实边沿方向；
- 负逻辑脉冲通常应使用下降沿，正逻辑脉冲通常应使用上升沿；
- 第一个完整周期的频率会补到曲线起点；
- 关键时间显示的是该时间之后最近一个完整周期的实测频率，不是理论插值值；
- 横轴 `0 ms` 是第一个有效脉冲边沿，不是 CSV 文件的系统时间起点。

## 5. 已验证真实文件

测试目录：

```text
D:\xinjiedianqi\Study\TrainCamp_zengbingjie_PLSR\测试脉冲数据
```

### `DL16.csv`

- 文件注释采样率：20 MHz；
- 原始采样点数：125,351,087；
- CSV 跳变记录：8,001 行；
- 自动识别到 `Channel 4` 有脉冲变化；
- 自动选择下降沿；
- `100 ms` 节点最近测量时间约 `100.094 ms`；
- 该节点频率约 `361.984 Hz`；
- 随后曲线继续升高到约 `500 Hz`。

### `zxjs.bin`

- 文件大小约 49 MB；
- 该 BIN 没有文件头和采样率字段；
- 按 16 通道、每采样点 2 字节可读取；
- 测试使用 20 MHz、指定 Channel 4 时可以成功生成频率曲线；
- BIN 的采样率必须由用户按实际采集设置填写，否则时间和频率都会按比例错误。

## 6. 测试命令

在项目根目录执行：

```powershell
python -m unittest discover -s PythonTest -p "test_*.py"
python -m py_compile PythonTest\logic_waveform.py PythonTest\parse_logic_gui.py
```

当前最后一次验证结果：

```text
Ran 24 tests
OK
```

双击启动文件也已验证能够创建 `pythonw.exe` 图形进程。

## 7. 后续建议

后续如果继续完善，优先考虑：

1. 增加“目标频率/理论加速曲线”输入，与实测曲线叠加对比；
2. 增加加速度单位 `Hz/s` 显示；
3. 对长时间空闲段显示 0 Hz，而不是只显示跨空闲段后的低频点；
4. 增加频率曲线 CSV/图片导出，但不要恢复为唯一查看方式；
5. 如果获得正点原子 BIN 的官方采样率或工程文件格式，再把 BIN 的采样率自动识别补齐。

## 8. 当前已知限制

- BIN 原始数据没有采样率，程序无法仅凭 BIN 内容推断真实时间；
- 频率是由同方向边沿测得的周期计算出来的，边沿抖动会反映在曲线上；
- 当前关键时间默认按“第一个有效脉冲边沿”为零点，不使用 CSV 中的绝对系统时间；
- 当前主界面显示频率曲线，原始 0/1 电平阶梯图不再是主视图；
- 工作区本身存在其他 PLC、文档和测试文件修改，后续对话不要使用 `git reset --hard` 或整体回退。