# flexlink

**Repository Path**: liuxcfreddy/flexlink

## Basic Information

- **Project Name**: flexlink
- **Description**: flexlink更自由的上位机
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FlexLink - 更自由的调试上位机

目前网络上有很多好用的上位机，但是我一直苦于这几件事：

- 功能丰富的上位机数据格式过于死板
- 通讯简单的不够智能

举个例子 VOFA+ 这个上位机，数据格式解析简单，控件丰富，但是，对于数据属性的定义，只能依靠上位机本身自己修改；下位机一旦修改之后，数据定义就变了，很麻烦。所以我想有一个上位机，不是让下位机的程序去适应上位机，而是让上位机去适应下位机。

所以我希望开发一个更自由的协议去链接。

## FlexLink 数据格式协议

FlexLink 的单条消息为一帧，一帧当中有若干个包。帧头帧尾均可以通过通讯协议配置自定义。

协议核心特点：

- **统一编解码**：编码和解码共用同一套 JSON 配置（`flexlink_code`）
- **可变数据包**：一帧可包含任意数量的数据包，每个包有自己的包头、包尾、类型
- **消息包支持**：DataType=0 的特殊包，携带文本描述，显示在系统消息窗口
- **帧结构**：`FrameHead(2B) | PacketCount(1B) | Packets(N) | FrameTail(1B) | Checksum(1B)`
- **数据包结构**：`PacketHead(1B) | SeqNum(1B) | DataType(1B) | DataBody(NB) | DescriptionString(MB) | PacketTail(1B)`

详情请看 [json配置说明.md](json配置说明.md)，配置兼容性说明见 [doc/8.统一编解码配置为flexlink_code方案.md](doc/8.统一编解码配置为flexlink_code方案.md)。

---

# 软件功能介绍

## 主窗口

- 支持 **UDP 通讯** 和 **串口通讯**，通讯与协议编解码完全解耦
- 点击 **加载配置** 按钮加载指定的 `config.json`，配置热加载，无需重启
- **帧录制**：一键记录/停止记录接收到的数据帧，生成 `Frame-年月日时分秒.csv`
- **日志记录**：操作日志自动写入 `log/操作日志.md`

## 曲线绘图窗口

- 一键全局自适应大小、纵轴自适应、横轴自适应
- 自由勾选要显示的数据包，右上角图例显示
- 不同数据包随机分配颜色（也可手动设置）
- **包数据录制**：勾选的数据包可一键开始/停止记录，生成 `Packetdata-年月日时分秒.csv`

## 数据显示窗口

- 实时显示所有接收到数据包的当前值
- 一个包一个显示框，浮点数显示到小数点后 3 位

## 消息窗口

两个 Tab：

- **系统消息** — 软件自身故障/警告/执行结果，三级颜色区分（绿/黄/红）
- **字节流消息** — 接收/发送原始字节流，支持 HEX/String 显示切换和 **对比模式**（16 字节一行）

编码选择：UTF-8/GBK 切换，支持中文设备通信。

消息包支持：DataType=0 的特殊数据包进入系统消息窗口显示描述文本。

底部发送栏提供三种发送模式：

| 模式 | 按钮 | 用途 |
|------|------|------|
| HEX | 输入十六进制 `AA BB CC` | 原样发送原始字节 |
| STRING | 输入字符串 | 按选定编码（UTF-8/GBK）编码后发送 |
| MSG | 输入 `0x00` 格式 | 发送 DataType=0 消息包 |

窗口可独立弹出或恢复吸附，数据不丢失。

## 数据发送窗口

- 根据加载的 JSON 配置文件自动生成发送列表
- 每条可手动输入数值，带类型校验（范围、整数/浮点）
- 勾选想要发送的数据包，点击 **立即发送** 触发单次发送
- 设置发送周期，可周期性地发送勾选的数据帧
- 支持 DataType=0 消息包的发送（填写 0~255 的整数）

## CSV 数据回放

- 加载已录制的 CSV 文件，将数据回放到数据监视和曲线绘图窗口
- 支持 `PacketData` 格式和 `Frame` 格式的 CSV 文件

## C 代码生成

位于 `CodeGeneration/` 目录下的 `C_Code_Generation.py` 脚本，可根据 JSON 配置文件自动生成嵌入式 C 代码：

- `flexlink_protocol.h` — 帧长度宏、数据偏移宏、函数声明
- `flexlink_protocol.c` — 帧缓冲区初始化、数据读取/写入封装、校验和计算

详情请看 [CodeGeneration/readme.md](CodeGeneration/readme.md)。

---

## 页面描述

| 面板 | 默认位置 | 特性 |
|------|---------|------|
| 通讯设置 | 主页面顶部 | 固定，含 UPD/串口设置 |
| 曲线绘图 | 主页面右侧上方 | 可拖出成为独立窗口 |
| 数据显示 | 主页面左侧上方 | 可拖出成为独立窗口 |
| 消息窗口 | 主页面左侧下方 | 可拖出成为独立窗口，含系统消息和字节流两个 Tab |
| 数据发送 | 主页面右侧下方 | 可拖出成为独立窗口，支持单次/周期发送 |

---

## 开发环境搭建

### 1. 创建虚拟环境（如未自带）

```bash
python3 -m venv .venv
```

### 2. 激活虚拟环境

**Windows**（PowerShell）：
```powershell
.venv\Scripts\activate.ps1
```
> 如遇执行策略限制，先执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

**Windows**（CMD）：
```cmd
.venv\Scripts\activate.bat
```

**macOS / Linux**：
```bash
source .venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

激活后确认：
```bash
python --version      # Python 3.13.x
pip list              # 应包含 PySide6, pyserial, pyinstaller
```

### 4. 在 VSCode 中开发

1. 用 VSCode 打开项目根目录
2. 按 `Ctrl+Shift+P` → `Python: Select Interpreter` → 选择虚拟环境中的 `python`

   | 平台 | 解释器路径 |
   |------|-----------|
   | Windows | `.venv\Scripts\python.exe` |
   | macOS / Linux | `.venv/bin/python` |

3. 创建 `.vscode/launch.json`：

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "FlexLink",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/main.py",
            "console": "integratedTerminal"
        }
    ]
}
```

4. 按 `F5` 启动调试，或在终端中直接运行。

> QML 文件建议安装 `Qt QML Syntax Highlight` 插件获得语法高亮。

---

## 运行方法

### 源码运行

```bash
# Windows
.venv\Scripts\python main.py

# macOS / Linux
.venv/bin/python main.py
```

首次运行前需确保 `config.json` 存在于项目根目录（程序启动时会自动加载）。

### 打包为可执行文件

```bash
python build.py              # 默认 onedir 模式（文件夹分发，启动快）
python build.py --onefile    # 单文件模式（启动稍慢，一个文件即用）
python build.py --clean      # 清理缓存后构建
```

| 平台 | onedir 输出 | onefile 输出 |
|------|------------|-------------|
| Windows | `dist/FlexLink/` 文件夹 | `dist/FlexLink.exe` |
| macOS | `dist/FlexLink.app` | `dist/FlexLink` |
| Linux | `dist/FlexLink/` 文件夹 | `dist/FlexLink` |

打包后的产物可直接分发，无需安装 Python 或任何运行环境。

### 跨平台注意事项

- **串口设备名**：Windows 为 `COM3` 等，macOS 为 `/dev/cu.usbserial-*`，Linux 为 `/dev/ttyUSB0` 或 `/dev/ttyACM0`。软件启动后点击串口下拉框旁的 **R** 按钮刷新列表即可。
- **UDP 端口**：Linux/macOS 下绑定 1024 以下的端口需要 `sudo`，建议使用 1024 以上的端口号。
- **文件路径**：`config.json` 和 CSV 录制文件均使用相对路径，放在项目根目录即可。

---

## 项目结构

```
FlexLink/
├── main.py                     # 入口文件
├── main.qml                    # 主窗口 QML
├── build.py                    # PyInstaller 打包脚本
├── config.json                 # 协议配置文件（可热加载）
├── config1.json                # 对端测试用配置文件
├── requirements.txt            # Python 依赖
│
├── qml/
│   ├── CommSettings.qml        # 通讯设置面板
│   ├── CurvePlot.qml           # 曲线绘图面板
│   ├── DataDisplay.qml         # 数据显示面板
│   ├── MessagePanel.qml        # 消息窗口面板（系统消息 + 字节流）
│   └── SendPanel.qml           # 数据发送面板
│
├── src/
│   ├── ui/
│   │   └── bridge.py           # Python ↔ QML 桥接层
│   ├── protocol/
│   │   ├── config_loader.py    # JSON 配置解析
│   │   ├── decoder.py          # 协议解码器（状态机）
│   │   └── encoder.py          # 协议编码器
│   ├── communication/
│   │   ├── comm_base.py        # 通信基类
│   │   ├── udp_comm.py         # UDP 通信
│   │   └── serial_comm.py      # 串口通信
│   └── data/
│       ├── data_manager.py     # 数据管理（缓冲区 50000 点）
│       └── csv_recorder.py     # CSV 录制
│
├── CodeGeneration/
│   ├── C_Code_Generation.py    # C 代码自动生成脚本
│   ├── Code/
│   │   ├── flexlink_protocol.c # 生成的 C 源文件
│   │   └── flexlink_protocol.h # 生成的 C 头文件
│   └── readme.md
│
├── doc/                        # 方案设计与修复记录（12 篇）
├── log/                        # 操作日志
└── media/                      # 字体等资源文件
```