louis/flow_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

新增气体流量控制 GUI 与 Windows 可执行程序

Browse Source 
新增 Tkinter 单窗口操作界面和后台设备状态机，支持连接与断开 PLC、在线设置目标流量、实时显示传感器数据与下发总开度，并在监测及闭环阶段统一执行安全保护。

默认将 valve_model_004.json 内置到单文件 EXE，同时支持校验并选择外部阀模型；整理标定 JSON/PNG 到 valve_model 目录并同步配置路径。补充运行层离线测试、PyInstaller 构建配置、交付文件和完整的 README 使用及重新打包说明。
This commit is contained in:
louis
2026-09-03 17:35:40 +08:00
parent d7ed4181df
commit ead625bf2d
51 changed files with 44578 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+70 -23
View File
@@ -1,21 +1,23 @@
# 气体流量控制与阀门开环标定
本项目基于信捷 **Easy521 PLC**（Modbus TCP）提供三个可独立运行的在线入口和两个离线工具：
本项目基于信捷 **Easy521 PLC**（Modbus TCP）提供一个图形闭环入口、三个可独立运行的命令行在线入口和两个离线工具：
- [gui_main.py](gui_main.py)：Windows 单窗口操作界面，支持连接/断开设备、设置目标流量、实时监视三路传感器与下发总开度，以及选择外部 `A_eff` 模型；
- [main.py](main.py)：以 10 Hz 周期运行单回路气体流量闭环控制，支持增量式 PID，并可选“前馈反解打底 + PI 修残差”与按阀前压力缩放增益的增益调度；
- [open_loop.py](open_loop.py)：随机扫描阀门开度，并在末尾追加闭阀端精细行程扫描；采集阀前/阀后的压力与阀后流量，用于开环标定、动态特性观察和临界压力比分析。
- [test_valve.py](test_valve.py)：在 Windows 终端中手动切换阀门开度，同时观察并记录阀后流量、阀前/阀后压力和电机行程。
- [identify_valve.py](identify_valve.py)：离线从开环扫点 CSV 拟合阀特性表，产出供前馈使用的 `valve_model.json`。
- [test_valve_model.py](test_valve_model.py)：阀特性模型与前馈反解的离线自测，不接触硬件。
三个在线入口都会持续保存 CSV，并在运行结束时为有效采样数据生成 PNG 曲线图。闭环程序还会持续进行滑动窗口稳态判定，并在首次达到稳态时输出一次控制性能报告。
三个命令行在线入口都会持续保存 CSV，并在运行结束时为有效采样数据生成 PNG 曲线图。命令行闭环程序还会持续进行滑动窗口稳态判定，并在首次达到稳态时输出一次控制性能报告。GUI 保持轻量，只写轮转运行日志，不生成 CSV、PNG 或性能报告。
## 重要安全说明
> 本项目会直接控制真实阀门。首次运行前必须核对 IP、站号、寄存器地址、传感器量程、阀门行程方向、压力上限和执行机构的断电/失驱位置，并准备独立的机械或电气急停手段。
三个入口当前的阀门初始化与退出策略如下：
四个在线入口当前的阀门初始化与退出策略如下：
- **图形界面 `gui_main.py` / `FlowControl.exe`**：启动后不会自动连接；连接成功后先主动设置 `100%` 开度，再进入传感器监测，首次设置目标流量时启动闭环。点击断开、关闭窗口或发生故障时，会再次尝试设置 `100%` 开度，然后断开 PLC；
- **闭环 `main.py`**：连接成功后先主动设置 `100%` 开度，再开始初始采样、性能报告和控制计时；故障、正常退出或 `Ctrl+C` 时再次尝试设置 `100%` 开度，然后断开 PLC。
- **开环 `open_loop.py`**：连接成功后先主动设置 `100%` 开度，再创建记录器并开始实验计时；实验结束、异常或 `Ctrl+C` 时再次尝试设置 `100%` 开度，然后断开设备。
- **手动测试 `test_valve.py`**：连接成功后先主动设置 `100%` 开度，再创建记录器并开始采样；退出时再次尝试设置 `100%` 开度，然后断开设备。该脚本不执行流量/压力越限和连续读取失败保护，只适合在具备独立安全措施的受控测试中使用。
@@ -57,18 +59,48 @@ opening = 100% -> motor_position = 800（当前打开端/机械死区边界）
项目使用 Python 3，直接依赖：
- `pymodbus`：Modbus TCP/RTU 通讯；
- `matplotlib`：使用 `Agg` 后端生成 PNG，无显示器环境也可运行。
- `matplotlib`：命令行入口使用 `Agg` 后端生成 PNG，无显示器环境也可运行；
- `tkinter`：GUI 使用的 Python 标准库组件；制作 EXE 时另需 `PyInstaller`。
示例安装：
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install pymodbus matplotlib
python -m pip install pymodbus matplotlib pyinstaller
```
仓库当前没有锁定依赖版本。若 `PcControl.py` 导入 `pymodbus.payload` 或调用 `slave=` 参数时报错，请使用与现有 [PcControl.py](PcControl.py) API 兼容的 `pymodbus` 版本。
## 图形界面与 Windows 可执行程序
交付目录为 `可执行程序/`，包含以下三个文件：
- `FlowControl.exe`：Windows 64 位单文件程序，无需安装 Python，默认内置 `valve_model_004.json`；
- `valve_model_004.json`：内置模型的外置备份和自定义模型格式参考，删除该外置副本不会影响内置模型；
- `使用说明.txt`：现场操作、安全策略和故障说明。
双击 `FlowControl.exe` 后，核对 PLC 地址、端口和站号，再点击“连接设备”。连接成功后程序保持 `100%` 开度并以 `0.25 s` 周期监测阀后流量、阀前压力和阀后压力；首次设置 `0~300 SLM` 目标时启动 10 Hz 闭环，运行中可继续修改目标。界面显示的“下发总开度”为最终命令：
```text
总开度 = clamp(前馈开度 + PI 修正量, 0, 100)
```
GUI 的 Modbus 读写与控制周期全部在单一后台线程中串行执行，避免通信超时阻塞界面。监测和闭环阶段都会执行流量/压力越限保护；连续读取失败、写入失败、控制周期严重超时或其他通信异常会停止闭环，尝试恢复 `100%` 开度并断开设备。运行日志写到 EXE 同目录的 `logs/flow_control.log`，单文件最大约 2 MB，保留 3 份历史文件。
默认模型只能在未连接状态下切换。点击“选择 JSON…”可加载其他模型，程序会在连接前检查 JSON 结构、有限数值、标定点数量、`800~1000` 行程范围以及 `motor_open` / `motor_closed` 与当前配置是否一致；无效模型不会进入控制。点击“使用内置”可恢复 `valve_model_004.json`。
源码运行与重新打包命令为：
```powershell
python gui_main.py
python gui_main.py --smoke-test
python -m PyInstaller --noconfirm --clean --distpath "可执行程序" --workpath "build/flow_control_gui" flow_control_gui.spec
Copy-Item valve_model/valve_model_004.json 可执行程序/valve_model_004.json -Force
```
`--smoke-test` 只检查内置模型和关键依赖，不打开界面，也不会连接真实设备。
## 闭环控制
### 运行
@@ -129,13 +161,13 @@ opening_to_motor_position()
| 模式 | 用途 | Kp / Ki / Kd | 最大开度速度 |
| --- | --- | --- | ---: |
| `FAR` | 大误差时快速接近目标 | `0.5 / 0.5 / 0.0` | `200%/s` |
| `NEAR` | 小误差时抑制振荡和稳态误差 | `0.05 / 0.01 / 0.0` | `2%/s` |
| `NEAR` | 小误差时抑制振荡和稳态误差 | `0.1 / 0.1 / 0.0` | `2%/s` |
切换阈值同时考虑绝对误差下限和目标流量比例：
```text
near_threshold = min(3 SLM, max(1 SLM, 5% * target))
far_threshold = min(12 SLM, max(4 SLM, 20% * target))
near_threshold = min(2 SLM, max(1 SLM, 5% * target))
far_threshold = min(8 SLM, max(4 SLM, 20% * target))
FAR -> NEAR：|error| <= near_threshold，连续满足 10 个采样周期
NEAR -> FAR ：|error| >= far_threshold，连续满足 10 个采样周期
@@ -147,7 +179,7 @@ NEAR -> FAR ：|error| >= far_threshold，连续满足 10 个采样周期
### 前馈 + 增益调度（MFC 结构）
闭环当前默认启用“前馈反解打底 + PI 修残差”的 MFC 结构，并加载仓库根目录的 `valve_model.json`；按阀前压力缩放 Kp/Ki 的增益调度仍默认关闭。投用前必须确认阀前/阀后压力接线和阀特性表与当前硬件一致；不满足时应关闭前馈或重新辨识。
闭环当前默认启用“前馈反解打底 + PI 修残差”的 MFC 结构，并加载 `valve_model/valve_model_004.json`；按阀前压力缩放 Kp/Ki 的增益调度仍默认关闭。投用前必须确认阀前/阀后压力接线和阀特性表与当前硬件一致；不满足时应关闭前馈或重新辨识。
静态阀特性建模为：
@@ -170,7 +202,7 @@ PI 修正量 correction = PI(目标流量 - 实测流量) # 输出限幅改为
即前馈把开度送到稳态工作点附近，PI 只负责修正模型残差和动态偏差；PI 输出不再是 `0~100%` 的全行程，而是围绕前馈的修正量（限幅由 `FEEDFORWARD_CORRECTION_BAND_PCT` 控制，当前默认 ±50%）。
为避免接近目标后压力噪声持续改写前馈，同时又能响应下游负载变化，控制器维护一个 `FEEDFORWARD_UPDATE_WINDOW_S=3 s` 的流量绝对误差滑动窗口。窗口首次积满后，程序在每个控制周期都重新计算最近 3 秒的平均绝对误差，并与 `FEEDFORWARD_UPDATE_ERROR_THRESHOLD_SLM=5 SLM` 比较：均值不大于阈值时冻结上一次前馈开度，只让 PI correction 逐周期更新；均值超过阈值时重新根据当前目标流量和阀前/阀后压力反解前馈。因此，下游扰动持续影响流量并使 3 秒误差均值越过阈值后，前馈会自动解除冻结。
为避免接近目标后压力噪声持续改写前馈，同时又能响应下游负载变化，控制器维护一个 `FEEDFORWARD_UPDATE_WINDOW_S=3 s` 的流量绝对误差滑动窗口。窗口首次积满后，程序在每个控制周期都重新计算最近 3 秒的平均绝对误差，并与 `FEEDFORWARD_UPDATE_ERROR_THRESHOLD_SLM=2 SLM` 比较：均值不大于阈值时冻结上一次前馈开度，只让 PI correction 逐周期更新；均值超过阈值时重新根据当前目标流量和阀前/阀后压力反解前馈。因此，下游扰动持续影响流量并使 3 秒误差均值越过阈值后，前馈会自动解除冻结。
窗口未首次积满或尚无缓存前馈时，每个周期都尝试反解前馈。窗口一旦积满，其“已就绪”状态不会因采样抖动和旧样本淘汰而反复失效；但滑动均值仍会持续更新，冻结状态并不会锁死。目标改变、控制器重启或进入零流量分支会清空窗口并重新累计 3 秒。当前周期反解失败时继续复用上次有效前馈；如果从未得到有效前馈，则以 `0%` 为基值并由 correction 调整。
@@ -189,7 +221,7 @@ Kp_eff = scale · Kp_base，Ki_eff = scale · Ki_base # Kd 不调度
| --- | --- | --- |
| `FEEDFORWARD_ENABLED` | `True` | 启用前馈反解打底 + PI 修残差 |
| `GAIN_SCHEDULE_ENABLED` | `False` | 启用按阀前压力缩放 Kp/Ki |
| `VALVE_MODEL_PATH` | `"valve_model.json"` | 阀特性表 JSON 路径（空串 = 关闭前馈） |
| `VALVE_MODEL_PATH` | `"valve_model/valve_model_004.json"` | 阀特性表 JSON 路径（空串 = 关闭前馈） |
| `PRESSURE_BEFORE_ADDR` | `720` | 阀前压力 P1 的寄存器地址（D720） |
前馈生效需同时满足：`FEEDFORWARD_ENABLED=True`、`VALVE_MODEL_PATH` 指向有效 JSON、`PRESSURE_BEFORE_ADDR` 与 `PRESSURE_AFTER_ADDR` 均已配置。任一条件缺失时自动退化为纯 PID，并在启动日志中提示。
@@ -298,9 +330,9 @@ python test_valve.py
前馈需要一张 `A_eff(x)` 阀特性表。先用 [open_loop.py](open_loop.py) 扫点得到开环 CSV（时间戳命名、从不覆盖），再用 [identify_valve.py](identify_valve.py) 离线拟合。`--csv` 支持多个路径与 glob 模式，可把多次实验合并重拟合，数据越多表越稳：
```powershell
python identify_valve.py --csv open_loop_data/open_loop_YYYYMMDD_HHMMSS.csv --out valve_model.json
python identify_valve.py --csv "open_loop_data/*.csv" --out valve_model.json --plot
python identify_valve.py --plot # 省略 --csv 时默认合并 open_loop_data/ 下全部 CSV
python identify_valve.py --csv open_loop_data/open_loop_YYYYMMDD_HHMMSS.csv --out valve_model/valve_model.json
python identify_valve.py --csv "open_loop_data/*.csv" --out valve_model/valve_model.json --plot
python identify_valve.py --plot --out valve_model/valve_model.json # 默认合并 open_loop_data/ 下全部 CSV
```
- 每个 CSV 按 `step_index` 分组，每组取末尾 `--tail` 个采样点平均，得到稳态 `(行程 x, 流量 Q, 阀前压 P1, 阀后压 P2)`，并按开度访问顺序标记逼近方向（上升 / 下降 / 该文件起始步）；
@@ -310,7 +342,7 @@ python identify_valve.py --plot # 省略 --csv 时默认合并 open_loop_da
非单调表可能让同一个有效面积对应多个行程，反解时选择数值更大的行程，即更靠近关闭端的交点。目标有效面积小于表中最小实测值时直接返回机械全关行程 `MOTOR_CLOSED_POSITION`；恰好等于最小值时仍返回对应实测行程。
将 `config.VALVE_MODEL_PATH` 指到该 JSON、确认 `PRESSURE_BEFORE_ADDR` 接线无误、并把 `FEEDFORWARD_ENABLED` 设为 `True` 后，闭环即可启用前馈。当前配置已指向 `valve_model.json` 并默认启用，重新标定后应覆盖该文件或同步修改配置路径。
将 `config.VALVE_MODEL_PATH` 指到该 JSON、确认 `PRESSURE_BEFORE_ADDR` 接线无误、并把 `FEEDFORWARD_ENABLED` 设为 `True` 后，闭环即可启用前馈。当前配置已指向 `valve_model/valve_model_004.json` 并默认启用；重新标定后应覆盖该文件或同步修改配置路径。
[test_valve_model.py](test_valve_model.py) 是纯计算离线自测，不接触硬件，可在任意环境运行：
@@ -364,19 +396,19 @@ python -m pytest -q
| `TARGET_SWITCH_KEY` | `s` | 运行中按此键进入"输入新目标流量"模式 |
| `CONTROL_PERIOD_S` / `MAX_CONTROL_DT_S` | `0.1` / `0.3` | 目标周期 / 超时阈值 |
| `PID_FAR_KP` / `PID_FAR_KI` / `PID_FAR_KD` | `0.5` / `0.5` / `0.0` | 大误差快速模式 PID 参数 |
| `PID_NEAR_KP` / `PID_NEAR_KI` / `PID_NEAR_KD` | `0.05` / `0.01` / `0.0` | 小误差稳定模式 PID 参数 |
| `PID_NEAR_KP` / `PID_NEAR_KI` / `PID_NEAR_KD` | `0.1` / `0.1` / `0.0` | 小误差稳定模式 PID 参数 |
| `OPENING_MIN_PCT` / `OPENING_MAX_PCT` | `0` / `100` | PID 输出开度范围 |
| `MAX_OPENING_RATE_FAR_PCT_S` / `MAX_OPENING_RATE_NEAR_PCT_S` | `200` / `2` | FAR/NEAR 每秒最大开度变化百分比 |
| `PID_NEAR_ERROR_MIN_SLM` / `PID_NEAR_ERROR_MAX_SLM` / `PID_NEAR_ERROR_TARGET_RATIO` | `1` / `3` / `0.05` | FAR 进入 NEAR 的误差阈值下限、上限和目标比例 |
| `PID_FAR_ERROR_MIN_SLM` / `PID_FAR_ERROR_MAX_SLM` / `PID_FAR_ERROR_TARGET_RATIO` | `4` / `12` / `0.20` | NEAR 返回 FAR 的误差阈值下限、上限和目标比例 |
| `PID_NEAR_ERROR_MIN_SLM` / `PID_NEAR_ERROR_MAX_SLM` / `PID_NEAR_ERROR_TARGET_RATIO` | `1` / `2` / `0.05` | FAR 进入 NEAR 的误差阈值下限、上限和目标比例 |
| `PID_FAR_ERROR_MIN_SLM` / `PID_FAR_ERROR_MAX_SLM` / `PID_FAR_ERROR_TARGET_RATIO` | `4` / `8` / `0.20` | NEAR 返回 FAR 的误差阈值下限、上限和目标比例 |
| `PID_MODE_SWITCH_CONFIRM_CYCLES` | `10` | 模式切换条件需连续满足的采样周期数（当前约 1 秒） |
| `MOTOR_CLOSED_POSITION` / `MOTOR_OPEN_POSITION` | `1000` / `800` | 当前反向控制区间；打开端为机械死区边界 |
| `INITIAL_OPENING_PCT` | `100` | 闭环 PID 内部初始输出 |
| `PRESSURE_BEFORE_ADDR` | `720` | 阀前压力 P1 的寄存器地址（前馈/增益调度/开环共用） |
| `VALVE_MODEL_PATH` | `"valve_model.json"` | 阀特性表 JSON 路径；空串关闭前馈 |
| `VALVE_MODEL_PATH` | `"valve_model/valve_model_004.json"` | 阀特性表 JSON 路径；空串关闭前馈 |
| `FEEDFORWARD_ENABLED` | `True` | 是否启用前馈反解打底 + PI 修残差 |
| `FEEDFORWARD_CORRECTION_BAND_PCT` | `50` | 前馈开启时 PI 修正量的对称限幅（±%） |
| `FEEDFORWARD_UPDATE_ERROR_THRESHOLD_SLM` / `FEEDFORWARD_UPDATE_WINDOW_S` | `5` / `3` | 前馈冻结/更新的流量绝对误差均值阈值与窗口长度 |
| `FEEDFORWARD_UPDATE_ERROR_THRESHOLD_SLM` / `FEEDFORWARD_UPDATE_WINDOW_S` | `2` / `3` | 前馈冻结/更新的流量绝对误差均值阈值与窗口长度 |
| `GAIN_SCHEDULE_ENABLED` | `False` | 是否启用按阀前压力缩放 Kp/Ki |
| `GAIN_SCHEDULE_REF_ABS_KPA` | `501.325` | 满压调好基准增益对应的绝对压力（400 + 101.325） |
| `GAIN_SCHEDULE_FLOOR_ABS_KPA` | `60` | 绝对压力下限，防止 P1 很低时增益爆炸 |
@@ -394,6 +426,8 @@ python -m pytest -q
| 文件 | 职责 |
| --- | --- |
| [gui_main.py](gui_main.py) | Tkinter 单窗口界面、用户输入校验、状态与实时数据展示 |
| [control_runtime.py](control_runtime.py) | GUI 后台工作线程、模型校验、设备状态机与安全连接/断开 |
| [main.py](main.py) | 闭环入口：参数解析、日志、控制循环、记录器、性能报告与收尾 |
| [flow_control.py](flow_control.py) | 闭环控制层、传感器读取、开度/行程映射、前馈与增益调度、故障处理 |
| [controllers.py](controllers.py) | 通用增量式 PID，含输出限幅和输出变化率限幅 |
@@ -403,16 +437,21 @@ python -m pytest -q
| [open_loop.py](open_loop.py) | 独立开环扫点、传感器记录和压力比分析 |
| [test_valve.py](test_valve.py) | Windows 终端手动开度测试、每秒采样、CSV 与三联图 |
| [valve_model.py](valve_model.py) | 静态阀特性模型 `Q_ss = A_eff(x)·P1_abs·F(r)` 与前馈反解（纯计算） |
| [identify_valve.py](identify_valve.py) | 从一份或多份开环扫点 CSV（支持 glob 合并）拟合 `A_eff(x)` 表，输出 `valve_model.json` |
| [identify_valve.py](identify_valve.py) | 从一份或多份开环扫点 CSV（支持 glob 合并）拟合 `A_eff(x)` 表，输出阀模型 JSON |
| [test_valve_model.py](test_valve_model.py) | 阀特性模型与前馈反解的离线自测 |
| [test_flow_control.py](test_flow_control.py) | 前馈误差滑窗、采样抖动与复位逻辑的离线测试 |
| [test_performance_reporter.py](test_performance_reporter.py) | 闭环性能报告器与压力带判稳的离线测试 |
| [PcControl.py](PcControl.py) | Modbus 硬件客户端；本项目三个入口实际使用 `Easy521ModbusClient` |
| [test_control_runtime.py](test_control_runtime.py) | GUI 运行层、模型加载、连接、控制与安全断开的离线测试 |
| [flow_control_gui.spec](flow_control_gui.spec) | PyInstaller 单文件 EXE 构建配置和内置模型资源声明 |
| [PcControl.py](PcControl.py) | Modbus 硬件客户端；GUI 和三个命令行入口使用 `Easy521ModbusClient` |
## 项目结构
```text
flow_control/
├── gui_main.py # 图形界面入口
├── control_runtime.py # GUI 后台设备与闭环运行层
├── flow_control_gui.spec # Windows 单文件打包配置
├── main.py
├── open_loop.py
├── test_valve.py
@@ -426,11 +465,19 @@ flow_control/
├── test_valve_model.py # 阀特性模型离线自测
├── test_flow_control.py # 前馈误差滑窗离线测试
├── test_performance_reporter.py # 闭环判稳逻辑离线测试
├── test_control_runtime.py # GUI 运行层离线测试
├── PcControl.py
├── README.md
├── valve_model/ # 标定 JSON 与诊断 PNG
│ ├── valve_model.json
│ ├── valve_model_001.json ... valve_model_004.json
│ └── valve_model.png ... valve_model_004.png
├── 可执行程序/
│ ├── FlowControl.exe
│ ├── valve_model_004.json
│ └── 使用说明.txt
├── data/ # 闭环 CSV / PNG；历史数据可能已人工分组
├── open_loop_data/ # 开环 CSV / PNG（首次运行时创建）
├── test_valve_data/ # 手动阀门测试 CSV / PNG
├── valve_model.json # identify_valve.py 产出的阀特性表（供前馈使用）
└── logs/ # flow_control.log / open_loop.log
```