diff --git a/docs/VD测试工装V1.0培训手册.md b/docs/VD测试工装V1.0培训手册.md new file mode 100644 index 0000000..05bdf16 --- /dev/null +++ b/docs/VD测试工装V1.0培训手册.md @@ -0,0 +1,572 @@ +# VD 测试工装 V1.0 培训手册 + +> **版本**: V1.0 +> **日期**: 2026-05-31 +> **作者**: wangfq +> **适用对象**: 测试工程师、生产操作员、系统管理员 + +--- + +## 目录 + +1. [项目概述](#1-项目概述) +2. [系统架构](#2-系统架构) +3. [硬件环境](#3-硬件环境) +4. [EDC 服务](#4-edc-服务-edc_server) +5. [EDC 管理系统](#5-edc-管理系统-edc-web) +6. [通信协议](#6-通信协议) +7. [操作指南](#7-操作指南) +8. [常见问题](#8-常见问题) +9. [附录](#9-附录) + +--- + +## 1. 项目概述 + +### 1.1 项目简介 + +**VD 测试工装**（vd_test_fixture）是一套车检器自动化测试系统，用于**批量检测车检器（Vehicle Detector）的核心性能指标**。 + +**核心能力**: +- **灵敏度测试**: 检测车检器对不同信号强度的响应 +- **产品一致性测试**: 批量产品之间的性能差异分析 +- **自动化测试**: 支持设定测试次数，自动循环执行，实时进度反馈 +- **工装配置管理**: 支持 DG430 V2.0.x 协议的设备参数配置、版本查询、出厂初始化 + +### 1.2 术语说明 + +| 术语 | 全称 | 说明 | +|------|------|------| +| **EDC** | Edge Data Center | 边缘数据中心，系统的核心服务 | +| **DNT** | Data Network Terminal | 联网终端（PGLC），连接设备与 EDC | +| **DG430** | — | 地感测试工装硬件，执行实际测试动作 | +| **VD** | Vehicle Detector | 车检器（被测设备） | +| **SerialNet** | Serial Network | 串口网络透传，通过 UDP 将指令转发到 DG430 串口 | + +### 1.3 系统组成 + +``` +vd_test_fixture/ +├── edc_server/ # EDC 边缘数据中心（后端服务） +│ ├── src/server.py # UDP/TCP 异步网络服务 +│ ├── src/handlers.py # 业务处理 + 后台轮询 +│ ├── src/models.py # 数据库模型 (aiomysql) +│ ├── src/dg430.py # DG430 二进制协议解析 +│ └── src/protocol.py # PGLC JSON 协议解析 +├── edc-web/ # Flask Web 管理系统（前端） +│ ├── app/routes/ # 页面路由: 设备/测试/数据/工装/用户/日志 +│ ├── app/templates/ # Jinja2 页面模板 +│ └── app/static/ # CSS + JS +├── docs/ # 协议文档 + 培训手册 +└── MySQL # 共享数据库 (edc) +``` + +--- + +## 2. 系统架构 + +### 2.1 整体架构图 + +``` +┌──────────────────┐ 浏览器 HTTPS +│ edc-web │ ◄────────────────────── 操作人员 +│ Flask (Flask-Login) │ +│ 前端管理界面 │ +└────────┬─────────┘ + │ pymysql (同步) + ▼ +┌──────────────────┐ +│ MySQL │ +│ 数据库: edc │ +│ (共享存储) │ +└────────┬─────────┘ + │ aiomysql (异步) + ▼ +┌──────────────────┐ UDP :4900 ┌──────────────┐ RS485/TTL ┌────────────┐ +│ edc_server │ ◄──────────────► │ PGLC 联网终端 │ ◄───────────► │ DG430 工装 │ +│ Python/uvloop │ SerialNet 透传 │ (DNT) │ 串口协议 │ (测试硬件) │ +│ │ └──────────────┘ └──────┬─────┘ +│ UDP :5500/:5505 │ │ +│ TCP :5550 │ ▼ +└──────────────────┘ ┌──────────────┐ + │ 车检器(VD) │ + │ (被测设备) │ + └──────────────┘ +``` + +### 2.2 通信链路 + +``` +操作员浏览器 → edc-web (Flask, port 5000) → MySQL → edc_server (asyncio) → DNT → DG430 → 车检器 + ↕ + MySQL (同步) +``` + +**关键点**: +- edc_server 和 edc-web 共享同一 MySQL 数据库 +- edc_server 使用 aiomysql (异步)，edc-web 使用 pymysql (同步)，互不冲突 +- 前端通过 edc-web 的 REST API 下发指令，实际执行由 edc_server 的轮询任务完成 + +### 2.3 端口分配 + +| 端口 | 方向 | 协议 | 说明 | +|------|------|------|------| +| **5500** | 监听 | UDP | EDC 设备发现 / 心跳 | +| **5505** | 监听 | UDP | EDC 消息监听 | +| **5550** | 监听 | TCP | EDC 时间同步 / 数据上报 / 串口透传 | +| **4900** | 发送 | UDP | 向设备发送 SerialNet 透传指令 | +| **5550** | 发送 | TCP | 向设备发送 TCP 数据 | +| **5000** | 监听 | HTTP | edc-web Flask 管理界面 | + +--- + +## 3. 硬件环境 + +### 3.1 DG430 地感测试工装 + +DG430 是执行测试的核心硬件，负责控制电机驱动模拟车辆经过地感线圈，并采集车检器的响应数据。 + +**接口**: +| 接口 | 连接 | 说明 | +|------|------|------| +| IN1/GND | 地感存在信号 | 检测线圈是否有车 | +| IN2/GND | 地感脉冲信号 | 检测脉冲继电器 | +| IN3/COM | 按钮 | 按下开始测试 | +| IN4/COM | 按钮 | 按下复原位置 | +| PU+/PU-/DR+/DR-/MF+/MF- | 电机驱动器 | 控制电机前进/后退 | +| +5V/GND/NO/NC | 限位开关 | 有信号电机停转 | +| 485A/485B | RS485 | 接 PGLC 联网终端 | +| GND/LP | 地感线圈 | 模拟车辆通过 | +| SW3 | 激光探头 | 检测进入/离开 | + +**拨码开关**: +- DIP1=OFF, DIP2=OFF → 测试 132 系列地感 +- DIP1=ON, DIP2=OFF → 测试 110 系列地感 + +**声音提示**: +| 声音 | 含义 | +|------|------| +| 2 声 | 工作频率/峰峰值异常 | +| 3 声 | 灵敏度异常 | +| 4 声 | 灵敏度提升异常 (132 DIP5) | +| 5 声 | 非离开脉冲 | +| 6 声 | 脉冲继电器无输入 | + +### 3.2 PGLC 联网终端 (DNT) + +PGLC 终端是连接 EDC 服务和 DG430 工装的**网络桥接设备**: +- 通过 **RS485/TTL 串口** 连接 DG430 工装 +- 通过 **TCP/UDP 网络** 连接 EDC 服务 +- 负责串口数据与网络数据的双向透传 + +--- + +## 4. EDC 服务 (edc_server) + +### 4.1 功能概述 + +EDC 服务是整个系统的**数据中枢**，负责: + +1. **设备管理**: 发现、注册、心跳检测、在线状态维护 +2. **数据采集**: 接收设备上报的测试数据、原始传感数据 +3. **协议解析**: 解析 DG430 二进制协议，提取测试结果 +4. **指令透传**: SerialNet 透传机制，将前端指令下发给设备 +5. **后台轮询**: 自动化测试调度、超时检测、状态流转 + +### 4.2 启动方式 + +```bash +cd edc_server +source .venv/bin/activate + +# 配置环境变量 +export EDC_MYSQL_HOST=127.0.0.1 +export EDC_MYSQL_USER=dg +export EDC_MYSQL_PASSWORD=123456 +export EDC_MYSQL_DB=edc + +# 启动 +python run.py +``` + +### 4.3 数据库表结构 + +| 表名 | 用途 | 关键字段 | +|------|------|----------| +| `dnt_info` | 联网终端信息 | serial(唯一), ip, state(在线/离线) | +| `tb_state_tst` | 设备测试状态 | dnt_id, pcnum, serialnum, ppvalue, idle_freq, enter_freq, exit_freq | +| `tb_serialnet` | 透传发送队列 | dnt_id, send_pkg, rcv_pkg, state(0未发→1已发→2已完成→3超时) | +| `tb_fixture_param` | 工装测试参数 | dnt_id(UNIQUE), dev_type, test_mode, sens_min/max, freq_min/max | +| `tb_vechicle_base_test` | 车检器基准参数 | type_num(编码), relay_exist, relay_pluse, sens_min/max 等 | +| `tb_user` | 用户账号 | username, password_hash, role(admin/operator) | +| `tb_log` | 操作日志 | user_id, action_type, target, detail, result, ip | +| `tb_collect_{DeviceID}` | 设备原始数据采集表 | dat_type, raw_data, state(0未处理/1已处理) | + +### 4.4 关键流程 + +#### 设备注册流程 + +``` +设备上电 → TCP 时间同步 → UDP 上报 Count_Off → EDC 检查 serial + ├─ 已注册 → 更新 IP/网关 + last_login + └─ 未注册 → 插入 dnt_info + 创建 tb_collect_{DeviceID} +``` + +#### SerialNet 透传流程 + +``` +前端 → edc-web → INSERT tb_serialnet (state=0) + → serialnet_loop 轮询 → UDP 发送到设备 (state=1) + → 设备回复 TSReport(dat_type=8 或 9) + → parse_loop 解析 → UPDATE tb_serialnet (state=2, rcv_pkg=...) + → 前端轮询 api/fixture/serialnet/{id} → 显示结果 +``` + +#### 超时检测 + +- serialnet_loop 每轮检查 `state=1` 且 `update_time > 10s` 的记录 +- 超时记录置为 `state=3`（超时） + +--- + +## 5. EDC 管理系统 (edc-web) + +### 5.1 功能概述 + +edc-web 是基于 Flask 的 Web 管理系统，提供图形化操作界面。 + +**功能模块**: + +| 模块 | URL | 功能 | +|------|-----|------| +| **登录** | `/login` | 用户认证 (Flask-Login) | +| **设备管理** | `/devices` | 联网终端列表、在线状态、名称修改 | +| **测试操作** | `/test-op/` | 单次测试、手动控制、自动化测试 | +| **测试数据** | `/test-data` | 历史测试数据查询、分页、导出 | +| **工装配置** | `/fixture/` | DG430 V2.0 配置指令、参数管理 | +| **用户管理** | `/users` | 账号管理 (admin only) | +| **操作日志** | `/logs` | 操作记录审计 | + +### 5.2 启动方式 + +```bash +cd edc-web +source .venv/bin/activate + +# 配置环境变量（与 edc_server 相同） +export EDC_MYSQL_HOST=127.0.0.1 +export EDC_MYSQL_USER=dg +export EDC_MYSQL_PASSWORD=123456 +export EDC_MYSQL_DB=edc + +# 启动（默认 5000 端口） +python run.py +``` + +**首次启动**: 自动创建默认管理员 `admin / admin123`。 + +### 5.3 用户角色 + +| 角色 | 权限 | +|------|------| +| **admin** | 全部功能：设备管理、测试操作、用户管理、日志查看 | +| **operator** | 受限功能：设备管理、测试操作 | + +--- + +## 6. 通信协议 + +### 6.1 DG430 串口协议 + +DG430 与 PGLC 终端之间的通信协议，采用**一问一答**方式。 + +**数据包格式** (7 字节): + +``` +┌──────┬──────┬──────┬──────┬──────┬──────┬──────┐ +│ STX │ ADDR │ LEN │ CMD │ DATA │ XOR │ SUM │ +│ 0x7F │ 1B │ 1B │ 1B │ LEN-1│ 1B │ 1B │ +└──────┴──────┴──────┴──────┴──────┴──────┴──────┘ +``` + +#### 测试操作指令 (V1.0) + +| 指令 | CMD | Hex (addr=0x01) | 说明 | +|------|-----|-----------------|------| +| 开始测试 | B0 | `7F 81 01 B0 30 32` | 启动一次测试流程 | +| 测试复原 | B1 | `7F 81 01 B1 31 33` | 恢复到初始位置 | +| 电机前进 | BA | `7F 81 01 BA 3A 3C` | 电机正转 | +| 电机后退 | BB | `7F 81 01 BB 3B 3D` | 电机反转 | +| 电机停止 | BC | `7F 81 01 BC 3C 3E` | 电机停止 | + +#### 工装配置指令 (V2.0.x) NEW + +| 指令 | CMD | 说明 | +|------|-----|------| +| 获取版本号 | 4A | 查询 DG430 固件和硬件版本 | +| 配置测试参数 | 4B | 下发工装参数（动态构造） | +| 查询测试参数 | 4C | 查询当前全部参数 | +| 出厂初始化 | 4D | 恢复出厂设置 | +| 设备复位 | 4E | 重启 DG430 设备 | + +> ⚠️ **端序注意**: B2 上报和 0x4B/0x4C 的 2 字节字段**统一用小端** (`_le16`)。协议文档测试用例写的是大端，但实际硬件发送小端。 + +#### B2 状态上报 + +设备完成测试后自动上报状态数据包，包含: + +| 字段 | 说明 | 范围 | +|------|------|------| +| State | 设备状态 | 正常/故障 | +| Mode | 工作模式 | — | +| Sens | 灵敏度 | 实际值 | +| PPValue | 峰峰值 | mV | +| IdleFreq | 开始工作频率 | kHz | +| EnterFreq | 进入工作频率 | kHz | +| EnterDist | 进入距离 | mm | +| ExitDist | 离开距离 | mm | +| EnterSpeed | 进入速度 | dm/s | +| ExitSpeed | 离开速度 | dm/s | + +### 6.2 PGLC 网络接口协议 + +EDC 服务与 PGLC 终端之间的 JSON 协议。 + +#### 主要方法 + +| Method | 方向 | 说明 | +|--------|------|------| +| `TimeStamp` | 设备→EDC | 时间同步请求 | +| `Count_Off` | 设备→EDC | 设备注册/发现 | +| `TSReport` | 设备→EDC | 子设备数据上报 | +| `SerialNet` | EDC→设备 | 串口透传指令下发 | +| `Heartbeat` | 设备→EDC | 心跳包 | + +#### SerialNet 透传格式 + +```json +{ + "Method": "SerialNet", + "Params": { + "Addr": 1, + "SerialCmd": "7F8101B03032", + "SerialDat": "", + "WorkMode": 1 + } +} +``` + +--- + +## 7. 操作指南 + +### 7.1 登录系统 + +1. 浏览器访问 `http://<服务器IP>:5000/login` +2. 默认账号: `admin` / `admin123` +3. 登录后跳转到设备管理页 + +### 7.2 设备管理 + +**查看设备列表**: +- 首页展示所有联网终端 +- 显示序列号、名称、IP、在线状态 + +**修改设备名称**: +- 点击设备行的名称编辑图标 +- 输入新名称后提交保存 + +**进入测试**: +- 点击设备行右侧的 **「测试」** 按钮 + +### 7.3 手动测试操作 + +在测试操作页面: + +1. **单次测试**: 点击 **「开始测试」** 按钮，DG430 执行一次完整测试流程 +2. **手动控制** (仅 admin): + - **测试复原**: 恢复初始位置 + - **电机前进/后退/停止**: 手动控制电机 +3. **实时数据**: 页面自动显示设备上报的最新测试数据 + +### 7.4 自动化测试 + +1. 在测试次数输入框中填入测试次数（如 `10`） +2. 点击 **「开始」** 按钮 + - 进度条显示 `已完成/总数` + - 成功/失败计数实时更新 + - 平均值区域持续刷新 +3. 如需中途停止，点击 **「结束」** 按钮 + +**自动化流程**: +``` +开始 → INSERT tb_serialnet (0xB0, state=0) + → serialnet_loop 发送 UDP (state=1) + → 等待设备 B2 上报 + → parse_loop 解析存入 tb_state_tst + → 匹配 serialnet 记录 (state=2) + → 前端轮询进度 → 自动发送下一次 0xB0 + → ...重复... + → 全部完成 / 超时(fail) / 手动结束 +``` + +**超时处理**: 单次测试超时 10 秒，超时计入失败，自动继续下一次。 + +### 7.5 工装配置管理 (V2.0 新增) + +1. 从设备页面进入 **「工装配置」** + +**工装参数设置**: +- 选择设备类型、测试模式 +- 配置灵敏度范围、频率范围、峰峰值范围 +- 配置 / 查询 / 初始化操作 + +**DG430 版本查询**: +- 点击 **「获取设备版本号」**，查看硬件/固件版本 + +**通信日志**: +- 每次指令发送后，下方自动显示通信日志 +- `→ 发送` (绿色): 发出的指令 hex +- `← 收到` (橙色): 设备返回的 hex +- `✓ 成功` / `✗ 失败`: 解析结果 + +### 7.6 测试数据查询 + +1. 点击 **「测试信息」** 菜单 +2. 功能: + - **分页浏览**: 翻页查看历史数据 + - **关键字搜索**: 按设备编码、批次号搜索 + - **日期筛选**: 按日期范围过滤 + - **导出**: 导出测试数据 + +### 7.7 用户管理 (admin only) + +1. 点击 **「用户管理」** 菜单 +2. 功能: + - 添加新用户（用户名、密码、角色） + - 修改用户角色 + - 删除用户 + +### 7.8 操作日志 + +1. 点击 **「操作日志」** 菜单 +2. 记录类型: + - `login` / `logout`: 登录/登出记录 + - `command`: 指令下发记录 + +--- + +## 8. 常见问题 + +### 8.1 设备离线 + +**现象**: 设备列表显示"离线" + +**排查**: +1. 检查设备供电是否正常 +2. 检查网络连接（ping 设备 IP） +3. 查看 edc_server 日志，确认是否收到心跳 +4. 设备超时阈值: 默认 120 秒（`EDC_DEVICE_TIMEOUT`） + +### 8.2 测试超时 + +**现象**: 自动化测试中连续超时 + +**排查**: +1. 检查 DG430 工装是否正常上电 +2. 检查 RS485 连接是否正确 +3. 在工装配置页发送「获取设备版本号」，验证通信链路 +4. 超时阈值: 10 秒 + +### 8.3 速度显示异常 + +**现象**: 速度值看起来偏大 10 倍 + +**原因**: DG430 协议存储的是 dm/s（分米/秒），系统已自动转换为 m/s（米/秒）。如果发现显示值异常，检查转换逻辑。 + +### 8.4 首次启动无管理员 + +**现象**: 无法登录 + +**解决方案**: edc-web 首次启动时自动创建 `admin / admin123`。如果手动清空过 `tb_user` 表，重启 edc-web 即可重新创建。 + +### 8.5 串口通信失败 + +**现象**: 工装配置指令无响应 + +**排查**: +1. 确认 PGLC 终端固件支持 SerialNet 透传 +2. 确认 RS485 波特率: 19200，TTL 波特率: 115200 +3. 确认 0x4B/0x4C 指令使用了小端字节序 + +--- + +## 9. 附录 + +### A. DG430 指令速查 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ DG430 指令速查表 │ +├────────┬──────────┬─────────────────────────────────────────┤ +│ CMD │ 指令 │ Hex (addr=0x01) │ +├────────┼──────────┼─────────────────────────────────────────┤ +│ 0xB0 │ 开始测试 │ 7F 81 01 B0 30 32 │ +│ 0xB1 │ 测试复原 │ 7F 81 01 B1 31 33 │ +│ 0xBA │ 电机前进 │ 7F 81 01 BA 3A 3C │ +│ 0xBB │ 电机后退 │ 7F 81 01 BB 3B 3D │ +│ 0xBC │ 电机停止 │ 7F 81 01 BC 3C 3E │ +│ 0x4A │ 版本查询 │ 7F 81 01 4A CA CC │ +│ 0x4B │ 配置参数 │ 动态构造 │ +│ 0x4C │ 查询参数 │ 7F 81 01 4C CC CE │ +│ 0x4D │ 出厂初始化 │ 7F 81 01 4D CD CF │ +│ 0x4E │ 设备复位 │ 7F 81 01 4E CE D0 │ +└────────┴──────────┴─────────────────────────────────────────┘ +``` + +### B. 环境变量速查 + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `EDC_MYSQL_HOST` | 127.0.0.1 | MySQL 地址 | +| `EDC_MYSQL_PORT` | 3306 | MySQL 端口 | +| `EDC_MYSQL_USER` | dg | 数据库用户 | +| `EDC_MYSQL_PASSWORD` | 123456 | 数据库密码 | +| `EDC_MYSQL_DB` | edc | 数据库名 | +| `EDC_UDP_PORT` | 5500 | UDP 设备发现 | +| `EDC_UDP_MSG_PORT` | 5505 | UDP 消息监听 | +| `EDC_TCP_PORT` | 5550 | TCP 数据上报 | +| `EDC_DEVICE_UDP_PORT` | 4900 | 设备端 UDP | +| `EDC_DEVICE_TCP_PORT` | 5550 | 设备端 TCP | +| `EDC_DEVICE_TIMEOUT` | 120 | 设备离线超时(秒) | +| `EDC_PARSE_POLL_INTERVAL` | 0.5 | 解析轮询间隔(秒) | +| `EDC_LOG_LEVEL` | INFO | 日志级别 | +| `EDC_WEB_PORT` | 5000 | Web 管理端口 | + +### C. 数据库快速参考 + +```sql +-- 查看在线设备 +SELECT serial, name, ip, state, last_login FROM dnt_info WHERE state=1; + +-- 查看最近测试数据 +SELECT s.*, d.serial, d.name +FROM tb_state_tst s +JOIN dnt_info d ON s.dnt_id = d.id +ORDER BY s.create_time DESC LIMIT 20; + +-- 查看待发送指令 +SELECT * FROM tb_serialnet WHERE state=0; + +-- 查看操作日志 +SELECT l.*, u.username +FROM tb_log l +JOIN tb_user u ON l.user_id = u.id +ORDER BY l.create_time DESC LIMIT 50; +``` + +### D. 修订历史 + +| 版本 | 日期 | 说明 | 作者 | +|------|------|------|------| +| V1.0 | 2026-05-31 | 初始版本 | wangfq |