hlp/VX5_KRO_GearPump
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1042版本发行

Browse Source
This commit is contained in:
byons
2026-07-30 08:24:45 +08:00
parent 241367e8d6
commit dea3229996
23 changed files with 3127 additions and 3303 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/项目架构说明文档.md
+190 -87
View File
@@ -15,8 +15,8 @@
3. [整体架构](#3-整体架构)
4. [目录结构](#4-目录结构)
5. [核心模块详解](#5-核心模块详解)
6. [数据流与通信机制](#6-数据流与通信机制)
7. [场景与打印渲染系统](#7-场景与打印渲染系统)
6. [场景与打印渲染系统](#6-场景与打印渲染系统)
7. [数据流与通信机制](#7-数据流与通信机制)
8. [RFID刷卡模块](#8-rfid刷卡模块)
9. [编译构建系统](#9-编译构建系统)
10. [关键配置与宏定义](#10-关键配置与宏定义)
@@ -65,25 +65,25 @@
```
┌─────────────────────────────────────────────────────────┐
│ UI 表现层 │
│ InkJetPrinter (主窗口) + MainWidget (打印主界面) │
│ 各功能页面: SystemManage, SystemSetting, LogInfo, ... │
│ UI 表现层 │
│ InkJetPrinter (主窗口) + MainWidget (打印主界面) │
│ 各功能页面: SystemManage, SystemSetting, LogInfo, ... │
│ 场景编辑器: TestPrintWidget, PicScene │
├─────────────────────────────────────────────────────────┤
│ 业务逻辑层 │
│ SysPara (系统参数管理) │
│ SysPara (系统参数管理) │
│ DevOp (设备操作) │
│ RunTimeCtrl (运行时间统计) │
│ RFIDManager (刷卡管理) │
├─────────────────────────────────────────────────────────┤
│ 通信层 │
│ Serial (串口通信封装) │
│ Modbus (Modbus协议) │
│ Serial (串口通信封装) │
│ Modbus (Modbus协议) │
├─────────────────────────────────────────────────────────┤
│ 硬件抽象层 │
│ FPGA (喷印控制、充电电压、相位检测) │
│ STM32 (墨路控制、传感器采集) │
│ RFID读卡器 (IC卡读写) │
│ STM32 (墨路控制、传感器采集) │
│ RFID读卡器 (IC卡读写) │
└─────────────────────────────────────────────────────────┘
```
@@ -302,11 +302,7 @@ RunTimeCtrl (运行时间控制)
- 计数器读写: 产品计数、同步计数
**FPGA地址空间**:
通信地址与定义位于[连续墨点喷码机通信协议](连续墨点喷码机通信地址.xlsx)，大致内存分布如下
- `0x0000-0x01FF`: 状态读取区
- `0xA400-0xA5FF`: 打印控制寄存器
- `0xB000-0xCFFF`: 数据写入区（DAC表、打印数据、日历数据等）
- `0xE000-0xFFFF`: 数字字符点阵数据
通信地址与定义位于[连续墨点喷码机通信协议](连续墨点喷码机通信地址.xlsx)
### 5.6 串口通信 (Serial)
@@ -328,7 +324,14 @@ RunTimeCtrl (运行时间控制)
### 5.7 日志系统 (Log)
**职责**: 提供分级日志记录功能。
#### 5.7.1 基于LogInfo的用户日志系统
**主要类**:
- `LogInfo` - 用户日志的核心类，提供日志记录、显示和保存功能，跟踪用户操作和系统事件。
#### 5.7.2 基于QDebug的日志系统
**职责**: 提供程序运行时的日志记录功能，用于开发调试和问题排查。
**类层次**:
- `Logger` - 日志基类，定义日志格式、级别过滤
@@ -356,20 +359,164 @@ qCritical() << "error"; // 错误日志
---
## 6. 数据流与通信机制
### 6.1 打印数据流
## 6. 场景与打印渲染系统
### 6.1 架构概述
场景系统基于 Qt Graphics View 框架，用于编辑和预览喷码内容。
```
PicScene (QGraphicsScene) # 场景，管理所有图元
├── 图元基类
│ ├── PicTextItem # 普通文本
│ ├── PicDateItem # 日期变量 (yyyy-MM-dd HH:mm:ss...)
│ ├── PicCounterItem # 计数器 (可变数字)
│ ├── PicImageItem # 图片 (Logo)
│ ├── PicCodeItem # 条码/二维码
│ └── PicScheduleShiftItem # 班次 (班次代码替换)
│
├── 图元编辑器
│ ├── ItemEditor # 普通文本编辑器
│ ├── DateVarSet # 日期变量编辑器
│ ├── CounterCarSet # 计数器编辑器
│ ├── ImageLoader # 图片读取器
│ ├── BarcodeEditor # 条码/二维码编辑器
│ └── ScheduleShiftsEditor # 班次 (班次代码替换)编辑器
│
├── 图元模型
│ ├── ItemEditor # 普通文本编辑器
│ ├── DateVarSet # 日期变量编辑器
│ ├── CounterCarSet # 计数器编辑器
│ ├── ImageLoader # 图片读取器
│ ├── BarcodeEditor # 条码/二维码编辑器
│ └── ScheduleShiftsEditor # 班次 (班次代码替换)编辑器
```
### 6.2 作业文件格式
作业文件使用XML格式（VBfiles结构），保存场景内容和打印设置：
```xml
<VBfiles>
<!-- 打印设置 -->
<PrintSettings timeTriggerPrintMode="0" triggerInterval="90" ... />
<!-- 文本图元 -->
<VBfile>
<pointer_x>55</pointer_x>
<pointer_y>0</pointer_y>
...
<itemAttrs sourceType="1" dir="0" letterSpace="1" fontFamilay="WenQuanYi7" source="FGJ" ... />
</VBfile>
<!-- 日期图元 -->
<VBfile>
<pointer_x>55</pointer_x>
<pointer_y>0</pointer_y>
...
<itemAttrs sourceType="3" datetimePattern="HH:mm:ss" ... />
</VBfile>
<!-- 计数器图元 -->
<VBfile>
<pointer_x>83</pointer_x>
<pointer_y>17</pointer_y>
...
<itemAttrs sourceType="6" counter_type="7" digital_num="8" ... />
</VBfile>
<!-- 条码/二维码图元 -->
<VBfile>
<pointer_x>0</pointer_x>
<pointer_y>0</pointer_y>
...
<itemAttrs sourceType="5" dir="0" barcodeContentPattern="dr66re{t}{c}" barcodeType="2" qrcodeFormat="0" ... />
</VBfile>
<!-- 图片图元 -->
<VBfile>
<pointer_x>0</pointer_x>
<pointer_y>0</pointer_y>
...
<itemAttrs sourceType="2" dir="0" source="/home/plg/doc/scene.png" ... />
</VBfile>
</VBfiles>
```
### 6.3 关键类说明
- **PicSceneLoader** - 场景文件的加载/保存/预览，负责XML序列化/反序列化
- **ViewModels** - 定义 `DateItemModel`、`CounterViewModel` 等视图模型，用于编辑器与图元之间的数据传递
- **ItemCommon** - 图元工具函数，如根据日期模型生成文本字符串
- **打印设置** - `PrintSettingModel` 与作业文件绑定，包含触发模式、字宽、同步器参数等
- **TestPrintWidget** - 场景编辑器，提供图元的创建、编辑、删除、预览功能
---
## 7. 数据流与通信机制
### 7.1 打印内容数据流
```
用户编辑场景 (PicScene)
└── 图元 (PicTextItem, PicDateItem, PicCodeItem, ...)
└── 渲染为 QImage
└── imageToPrintData() 转换为点阵数据
└── SendPrintDataToFpga() 通过 Serial 发送
└── FPGA 接收并驱动喷头喷印
├── 普通静态图元 (PicTextItem, PicImageItem, ...)
│ └─── onPreviewScene() 静态文本或图片渲染为 QImage
│ └── imageToPrintData() 转换为点阵数据
│ └── SendPrintDataToFpga() 在打印开始前一次性发送所有静态打印内容
│ └── FPGA 接收并驱动喷头喷印
│
├─── PicCounterItem 计数器图元
│ └── onPreviewScene() 构建变量控制结构体（位置、大小、类型等）
│ └── DevOp::writeFpgaVariCtrl() 发送至FPGA，由FPGA直接硬件控制
│
└─── 软解动态图元 (PicDateItem PicScheduleShiftItem PicCodeItem)
└── onPreviewScene() 与静态图元一样，进入onPreviewScene()
└── variableItemsUpdate() 动态检查图元是否发生变化，更新数据
└── SendPrintDataToFpga() 局部发送更新后的点阵数据至FPGA
```
### 6.2 设备状态轮询
**打印内容相关的几个重要的函数：**
[SendPrintDataToFpga()](../mainwidget.cpp#L935) 负责将打印数据、打印设置和变量控制通过串口发送给FPGA，FPGA接收后驱动喷头进行喷印。该函数被设计成支持全量更新与局部更新，静态图元在打印开始前一次性发送，而动态图元则在每次变化时局部更新。局部更新时，SendPrintDataToFpga不会发送打印设置和变量控制数据，只会按列为单位更新打印缓冲区的点阵数据。
[imageToPrintData()](../mainwidget.cpp#L675) 将 QImage 转换为点阵数据，该函数可将图像填充至打印缓冲区的指定位置，随后由 SendPrintDataToFpga() 发送至FPGA。动态软解图元（如日期、计数器、二维码）在每次变化时调用该函数刷新打印缓冲区。
[onPreviewScene()](../mainwidget.cpp#L1888) 是场景预览的核心函数，负责将场景中的所有图元渲染为 QImage，并调用 imageToPrintData() 全量写入打印缓冲区。
[variableItemsUpdate()](../mainwidget.cpp#L1024) 动态检查图元是否发生变化，配合 imageToPrintData()、SendPrintDataToFpga() 实现局部更新打印数据。
### 7.2 从文件到打印的数据流向
本节中 *发送打印设置与打印内容到FPGA* 的术语基本可以代指调用[MainWidget::SendPrintDataToFpga](../mainwidget.cpp#L933)函数。
区别于标准VX5，此韩国定制版中，明确了发送打印内容与打印设置到FPGA的时机与作用范围，所有发送打印内容与打印设置的动作只在[MainWidget::on_m_StartBtn_clicked()](../mainwidget.cpp#L756)中进行，除此之外其它时机发送打印内容与设置的行为继承自标准VX5，实际在韩国定制版中属于冗余设计。
QtUI 按工作文件为单位对喷码内容进行管理，工作文件使用 XML 格式保存场景内容和打印设置。用户在编辑界面（TestPrintWidget）中创建或修改工作文件后，点击“保存”按钮将场景数据序列化为 XML 文件。随后，用户在打印主界面（MainWidget）中选择工作文件并点击“打印”。
重要的工作流程位于[InkjetPrinter::loadWorkFileAndPreparePrint](../InkJetPrinter.cpp#L12684)函数中，流程如下：
```
用户点击 [MainWidget::m_AddBtn](../MainWidget.cpp#L143) (调入文件喷印) 发送 sendButtonClickedSignal(2) 信号
└── InkJetPrinter::getMainWidgetButtonClickedSlot() 接收信号打开 DialogFileOperation 对话框
└── InkjetPrinter::loadWorkFileAndPreparePrint() 通过对话框输入的文件名打开文件
└── PicSceneLoader::loadSceneFromFile() 解析 XML 文件，恢复场景内容和打印设置
└── MainWidget::generatePrintContent() 将场景渲染为打印数据并写入缓冲区
└── 等待用户按下 开始打印
└── MainWidget::SendPrintDataToFpga() 全量发送打印数据与设置到FPGA，并开始打印
```
注意打开并解析工作文件的过程中不会直接发送打印数据到FPGA，只有在用户点击“打印”按钮后，才会调用 SendPrintDataToFpga() 将打印数据发送至FPGA。
### 7.3 工作文件编辑
韩国QtUI中，*工作文件编辑* 被解耦为一个独立模块，它只负责对工作文件进行新建、编辑和调用[PicSceneLoader](../scene/PicSceneLoader.h)模块保存，其主要实现基本位于[TestPrintWidget](../testprintwidget.h)，[TestPrintWidget](../testprintwidget.h)通过读取指定工作文件（或新建），在编辑完成后可以对文件进行保存。
```
用户点击 (新建文件) (编辑文件) 发送信号到InjkectPrinter
└── InkJetPrinter判断当前文件名，将文件名传给TestPrintWidget，并切换到TestPrintWidget视图
└── TestPrintWidget完成编辑后询问用户是否保存已编辑的工作文件
├── 用户选择保存，TestPrintWidget 使用 PicSceneLoader 写入xml工作文件
│ └─ 保存文件后发出信号通知 InjkectPrinter
│ └─ InkjectPrinter 切换到 MainWidget 并调用 loadWorkFileAndPreparePrint 载入刚刚保存的文件
│ └─ 之后的流程与 7.2 小节一致
│
└── 用户选择不保存，TestPrintWidget 直接发出信号通知 InjkectPrinter
└─ InkjectPrinter 切换到 MainWidget，然后什么也不做
```
### 7.4 设备状态轮询
```
timerHandler()
@@ -387,7 +534,7 @@ timerHandler()
└── autoControlValvePump() # 自动控制执行
```
### 6.3 信号槽通信概览
### 7.5 信号槽通信概览
```
Serial::receivedFromFPGA ──→ InkJetPrinter::saveFPGAStatus()
@@ -398,56 +545,7 @@ RunTimeCtrl::sig_alertTimeout ──→ InkJetPrinter::slt_warningMaintenance()
RFIDManager::sig_showMsg ──→ InkJetPrinter::slt_showMsg()
```
---
## 7. 场景与打印渲染系统
### 7.1 架构概述
场景系统基于 Qt Graphics View 框架，用于编辑和预览喷码内容。
```
PicScene (QGraphicsScene) # 场景，管理所有图元
└── myView (QGraphicsView) # 视图，提供缩放和交互
└── 图元基类
├── PicTextItem # 普通文本
├── PicDateItem # 日期变量 (yyyy-MM-dd HH:mm:ss...)
├── PicCounterItem # 计数器 (可变数字)
├── PicImageItem # 图片 (Logo)
├── PicCodeItem # 条码/二维码
└── PicScheduleShiftItem # 班次 (班次代码替换)
```
### 7.2 作业文件格式
作业文件使用XML格式（VBfiles结构），保存场景内容和打印设置：
```xml
<VBfiles>
<VBfile>
<!-- 打印设置 -->
<PrintSettings triggerMode="0" ... />
<!-- 文本图元 -->
<VB itemType="text" x="10" y="20" text="ABC" ... />
<!-- 日期图元 -->
<VB itemType="date" x="50" y="20" pattern="yyyy-MM-dd" ... />
<!-- 计数器图元 -->
<VB itemType="counter" x="100" y="20" counterType="7" ... />
<!-- 条码/二维码图元 -->
<VB itemType="code" x="10" y="50" codeType="QR" ... />
<!-- 图片图元 -->
<VB itemType="image" x="200" y="0" ... />
</VBfile>
</VBfiles>
```
### 7.3 关键类说明
- **PicSceneLoader** - 场景文件的加载/保存/预览，负责XML序列化/反序列化
- **ViewModels** - 定义 `DateItemModel`、`CounterViewModel` 等视图模型，用于编辑器与图元之间的数据传递
- **ItemCommon** - 图元工具函数，如根据日期模型生成文本字符串
- **ItemEditor** - 图元通用编辑器（字体、颜色、位置等）
- **打印设置** - `PrintSettingModel` 与作业文件绑定，包含触发模式、字宽、同步器参数等
---
@@ -464,6 +562,7 @@ PicScene (QGraphicsScene) # 场景，管理所有图元
- 保养卡识别与提醒
- 自动扣减卡内余额
- 卡片使用标记（防重复使用）
- 超级卡的识别与处理
**加密**: 使用SM3（哈希）+ SM4（对称加密）国密算法保护卡片数据。
@@ -541,10 +640,12 @@ make
```cpp
#define UP_PRINTER_MAJOR_VER 6
#define UP_PRINTER_MINOR_VER 7
#define UP_PRINTER_RIVISION_VER 4
#define UP_PRINTER_RIVISION_VER 5
#define SUB_VERSION "_KOR"
```
版本号分为年、月、本月第几次编译，SUB_VERSION表示是否是标准版，"_Std" 表示标准版，"_KOR" 表示韩国定制版、"_RFID" 表示是标准版基础上增加了刷卡功能，如果客户定制版本包含了刷卡功能，则显示客户后缀。
---
## 11. 上手指南
@@ -552,15 +653,15 @@ make
### 11.1 开发环境搭建
1. **安装Qt**: 推荐 Qt 5.12+ 用于桌面开发调试
2. **获取代码**: 通过SVN或Git获取项目源码
3. **编译运行**:
```bash
cd 项目目录
qmake
make
./QtUI
```
4. **注意事项**: x86桌面版仅用于UI调试，硬件相关功能（串口、FPGA通信）不可用
2. **获取代码**: 找到你的领导，通过SVN获取源码
3. **编译运行**:
1. 直接使用 InkjetUbuntu-T1 虚拟机中的 QtCreator 打开此项目，然后编译调试。
2. 使用 VSCode ssh 连接 InkjetUbuntu-T2（从T1升级至Ubuntu20.04，以支持VSCode SSH连接） 虚拟机，然后直接在windows上远程开发，此方式需要自行配置编译环境，编译为ARM版本的命令为：
```bash
$ /home/inkjet/QtSDK/bin/qmake ./QtUI.pro -spec linux-aarch64-gnu-g++ CONFIG+=release
$ make -j8
```
4. **注意事项**: x86桌面版仅用于UI调试，硬件相关功能（串口、FPGA通信）不可用。
### 11.2 代码阅读顺序建议
@@ -581,6 +682,7 @@ make
| 修改FPGA通信 | `DevOp.h/cpp` + `Serial/` | 注意地址空间分配和CRC校验 |
| 修改UI样式 | `.ui` 文件 | 使用 Qt Designer 编辑 |
| 添加新功能页面 | 仿照现有页面模式 | 创建 .h/.cpp/.ui 三件套 |
| 添加网络通信 ||
### 11.4 关键设计模式
@@ -591,9 +693,9 @@ make
### 11.5 调试技巧
1. **日志**: 使用 `qInfo()/qWarning()/qCritical()` 输出，日志文件位于 `/home/plg/conf/`
1. **日志**: Debug模式下使用 `qInfo()/qWarning()/qCritical()` 输出，日志文件位于 `/home/plg/conf/`，发行版使用`LogInfo::setRunStatus()`
2. **崩溃分析**: `dump.h/cpp` 安装了信号处理器，崩溃时会生成core dump
3. **FPGA调试**: 可通过 `SystemManage` 界面手动控制阀门和泵
3. **泵阀手动控制**: 可通过 `SystemManage` 界面手动控制阀门和泵
4. **模拟模式**: 设置 `SIMULATE_PRINTING_MODE 1` 可在无硬件环境调试打印逻辑
### 11.6 注意事项
@@ -611,5 +713,6 @@ make
**文档更新记录**
- 2026-07-23: 创建此文档 — 卜永仕
- 2026-07-29：继续完善了此文档 - 卜永仕
- 2026-07-23：创建此文档 — 卜永仕