wangfq/vd_test_fixture
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: V1.0 培训手册 — 项目概述、架构、硬件、edc_server、edc-web、协议、操作指南

Browse Source
This commit is contained in:
wangfq
2026-06-01 08:03:14 +08:00
parent dbe5d1cefb
commit 00ec02eb9e
1 changed files with 572 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

572
docs/VD测试工装V1.0培训手册.md Normal file
View File

@@ -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/<dnt_id>` | 单次测试、手动控制、自动化测试 |
| **测试数据** | `/test-data` | 历史测试数据查询、分页、导出 |
| **工装配置** | `/fixture/<dnt_id>` | 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 |