zhengsl/emcp

Fork 0

root 88ab0ca1ab 后端代码更新

2026-05-19 09:26:51 +08:00

23 KiB

Raw Permalink Blame History

电气量测控平台系统需求分析与架构设计技术方案

适配平台：RK3568 嵌入式平台（ubuntu 22.04系统） 技术栈：FastAPI + HTTP + WebSocket + Python + Web前端

一、文档概述

1.1 文档目的

本文档基于《电气量测控平台显示界面设计和数据接口说明》、gui.h头文件及项目功能描述，明确RK3568嵌入式平台上Python编写、Web界面展示的电气量测控配置软件的功能、性能、接口、数据存储需求，完成系统架构设计，为软件开发、测试及交付提供技术依据。

1.2 适用范围

本文档适用于RK3568嵌入式硬件，以Python为开发语言、FastAPI为服务框架、Web为交互界面的电气量测控配置软件，涵盖参数配置、实时数据交互、状态监测、报警管理等全流程功能设计。

1.3 参考资料

《电气量测控平台显示界面设计和数据接口说明》
gui.h嵌入式程序头文件
项目功能需求描述

二、系统需求分析

2.1 运行环境需求

硬件环境：RK3568嵌入式开发板（支持Linux系统、文件系统、SQLite数据库）
软件环境：Linux操作系统、Python 3.8、FastAPI、Uvicorn ASGI服务、SQLite数据库、JSON文件存储支持
交互环境：Web浏览器（支持WebSocket、动态数据渲染、按钮交互、表格/波形展示）

2.2 功能需求

2.2.1 参数配置管理功能

实现测控设备全维度参数配置，配置项支持JSON文件本地存储，关键参数通过接口下发至C语言嵌入式程序，具体配置项如下：

基础设备配置
- 设备软件版本信息展示与配置
- 通讯参数设置：串口、网口参数配置
- 操作密码设置：支持密码修改、本地JSON文件存储
装置通道配置
- AI通道设置：模拟量输入配置、信号类型、所属线路、数据阈值
- AO通道设置：模拟量输出配置
- 定值设置：电压/电流/功率等超限限值、检测延时、报警输出配置
系统管理配置
- 对时设置：参数实时下发嵌入式程序
- 灯光设置：屏幕亮度、屏保时间，参数实时下发嵌入式程序
配置回显要求
- 设备网络配置、通道配置、报警设置、系统设置页面在打开时需先读取已保存参数
- 已保存配置从本地JSON文件读取，并通过HTTP查询接口返回给Web界面显示

2.2.2 实时数据动态显示功能

数据读取周期：间隔0.5秒从C语言控制系统读取实时数据
数据类型：模拟量、开关量、AI采集数据
推送方式：WebSocket主动推送至Web界面，动态刷新展示
存储规则：动态数据仅内存缓存，不保存到本地

2.2.3 设备状态实时监测功能

从嵌入式系统动态读取设备状态，Web界面实时展示：

装置自检状态（正常/异常）
网络1状态、网络2状态
串口1状态、串口2状态

2.2.4 报警事件管理功能

报警数据采集：实时获取嵌入式设备报警事件
数据存储：报警事件保存至SQLite数据库
展示方式：WebSocket实时推送报警至Web界面，支持弹窗提醒+历史查询

2.3 数据交互需求

2.3.1 上行数据（嵌入式系统→Python服务）

实时数据：0.5秒/次，模拟量、开关量、AI采集数据
状态数据：装置自检、网络、串口状态
报警数据：实时报警事件数据

2.3.2 下行数据（Python服务→嵌入式系统）

配置数据：设备参数、通道配置、定值、对时、灯光参数
控制指令：开关量分/合控制信号

2.4 数据存储需求

JSON文件存储：设备版本、通讯参数、密码、AI/AO配置、定值配置等非实时参数
SQLite数据库：报警事件数据（支持历史查询）
动态数据：仅内存缓存，不持久化存储

2.5 性能需求

数据刷新率：实时数据读取与WebSocket推送间隔≤0.5秒
响应速度：参数配置下发、开关控制指令响应时间≤1秒
稳定性：7×24小时连续运行
兼容性：适配RK3568硬件，兼容嵌入式C程序接口

2.6 通信服务需求

HTTP服务：基于FastAPI提供RESTful API，用于参数配置、状态查询、报警查询、控制指令
WebSocket服务：基于FastAPI提供双工通信，用于实时数据、报警数据主动推送至Web界面

三、系统架构设计

3.1 总体架构

系统采用分层架构 + 前后端分离设计，从下到上分为： 硬件层 → 嵌入式C程序层 → Python FastAPI服务层 → Web界面层

Web界面层（HTML/CSS/JS）
        ↓↑（HTTP + WebSocket）
Python FastAPI服务层（RESTful接口 + WebSocket推送 + 数据处理）
        ↓↑（内部进程/核间通讯）
嵌入式C程序层（数据采集 + 控制执行）
        ↓
硬件层（RK3568 + 测控硬件 + 通讯模块）

3.2 分层详细设计

3.2.1 硬件层

核心硬件：RK3568嵌入式开发板
外设模块：AI/AO采集模块、开关量模块、网络/串口模块、显示屏

3.2.2 嵌入式C程序层

数据采集模块：20ms周期采集模拟量、开关量、AI数据
控制执行模块：接收参数与指令，执行配置、对时、灯光、开关控制
状态监测模块：自检、网口、串口状态实时上报
报警生成模块：异常事件生成并上传
通讯模块：与Python服务双向数据交互

3.2.3 Python FastAPI服务层（核心）

采用FastAPI + Uvicorn搭建，提供HTTP接口和WebSocket推送双服务：

RESTful API模块：处理配置提交、状态查询、报警查询、控制指令
WebSocket推送模块：0.5秒推送实时数据、实时报警数据到Web端
参数配置模块：JSON文件读写、配置下发C程序
实时数据模块：定时读取C程序数据，缓存并通过WebSocket推送
报警管理模块：接收报警→存储SQLite→WebSocket推送前端
设备状态模块：采集并缓存设备运行状态

3.2.4 Web界面层

菜单区：配置、状态、数据、报警、控制入口
状态区：自检、网络、串口实时状态
主显示区：实时数据表格、配置表单、控制按钮、报警列表
报警区：WebSocket实时弹窗+滚动显示

3.3 数据流向设计

实时/报警数据流向 嵌入式C程序 → Python → WebSocket主动推送 → Web界面（0.5秒刷新）
参数配置流向 Web界面 → HTTP POST → Python → JSON存储 + 下发C程序
状态/查询流向 Web界面 → HTTP GET → Python → 返回数据展示
配置回显流向 Web界面进入设置页 → HTTP GET配置查询接口 → Python读取JSON配置 → 返回当前配置数据 → Web界面显示

四、接口详细设计（RESTful + WebSocket）

4.1 RESTful API 接口详情（完整参数+返回值）

所有接口统一返回格式：

{
  "code": 200,        // 200=成功，400=参数错误，500=服务异常
  "msg": "操作成功",
  "data": {}          // 业务数据
}

1. GET /api/real-time-data

作用：获取最新一次实时数据（备用，主用WebSocket）参数：无 返回data：

{
  "code": 200,
  "msg": "获取实时数据成功",
  "data": {
    "line_list": [
      {
        "line_no": 1,
        "pri_val": {
          "Ua": 6000.0,
          "Ub": 6002.5,
          "Uc": 5998.3,
          "Ia": 150.2,
          "Ib": 148.9,
          "Ic": 151.6,
          "Pa": 820.5,
          "Pb": 815.3,
          "Pc": 825.7,
          "Pt": 2461.5,
          "Qa": 120.3,
          "Qb": 118.6,
          "Qc": 122.9,
          "Qt": 361.8,
          "Sa": 835.2,
          "Sb": 829.7,
          "Sc": 840.3,
          "St": 2505.2,
          "PFa": 0.98,
          "PFb": 0.97,
          "PFc": 0.99,
          "PFt": 0.98,
          "Uab": 10400.1,
          "Ubc": 10395.6,
          "Uca": 10398.2,
          "frq": 50.00
        },
        "sec_val": {
          "Ua": 57.6,
          "Ub": 57.7,
          "Uc": 57.5,
          "Ia": 1.2,
          "Ib": 1.18,
          "Ic": 1.22,
          "Pa": 68.2,
          "Pb": 67.8,
          "Pc": 68.6,
          "Pt": 204.6,
          "Qa": 9.8,
          "Qb": 9.6,
          "Qc": 10.1,
          "Qt": 29.5,
          "Sa": 69.5,
          "Sb": 68.9,
          "Sc": 70.1,
          "St": 208.5,
          "PFa": 0.98,
          "PFb": 0.97,
          "PFc": 0.99,
          "PFt": 0.98,
          "Uab": 100.0,
          "Ubc": 99.8,
          "Uca": 99.9,
          "frq": 50.00
        }
      },
      {
        "line_no": 2,
        "pri_val": {},
        "sec_val": {}
      },
      {
        "line_no": 3,
        "pri_val": {},
        "sec_val": {}
      },
      {
        "line_no": 4,
        "pri_val": {},
        "sec_val": {}
      }
    ],
    "switch": {
      "di1": 1,
      "di2": 0,
      "di3": 1,
      "di4": 0,
      "di5": 1,
      "di6": 0,
      "di7": 1,
      "di8": 0,
      "di9": 1,
      "di10": 0,
      "di11": 1,
      "di12": 0,
      "do1": 1,
      "do2": 0,
      "do3": 1,
      "do4": 0,
      "do5": 1,
      "do6": 0,
      "do7": 1,
      "do8": 0,
      "do9": 1,
      "do10": 0,
      "do11": 1,
      "do12": 0
    },
    "ai_collect": {
      "ai1": 4.52,
      "ai2": 3.86,
      "ai3": 5.21,
      "ai4": 2.99,
      "ai5": 6.10,
      "ai6": 1.75,
      "ai7": 3.22,
      "ai8": 4.91,
      "ai9": 2.18,
      "ai10": 5.47,
      "ai11": 3.06,
      "ai12": 4.33
    }
  }
}

2. GET /api/device-status

作用：获取设备当前运行状态参数：无 返回data：

{
  "self_check": "正常",
  "net1": "正常",
  "net2": "正常",
  "uart1": "正常",
  "uart2": "断开"
}

3. GET /api/config/device

作用：读取设备基础配置，用于设备/网络配置界面打开时回显当前参数参数：无 返回data：

{
  "password": "",
  "hardware_version": {
    "board_version": "B001.001.001",
    "display_version": "S001.001.001",
    "other_version": "Y001.001.001"
  },
  "software_version": {
    "display_program": "001.001.001",
    "communication_program": "001.001.001",
    "measurement_program": "001.001.001"
  },
  "net": [
    {
      "nic": "网卡一",
      "ip": "192.168.1.10",
      "mask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "protocol": "Modbus TCP"
    }
  ],
  "uart": [
    {
      "port": "COM1",
      "baud": 9600,
      "parity": "NONE",
      "data_bits": 8,
      "stop_bits": 1,
      "protocol": "Modbus RTU"
    }
  ]
}

说明：

net 按 nic 标识各网卡配置
uart 按 port 标识各串口配置
界面如需按单个网卡或单个串口精确读取，可调用后续独立查询接口

4. POST /api/config/device

作用：提交设备基础配置（版本、通讯、密码） 请求body参数：

{
  "password": "123456",
  "hardware_version": {
    "board_version": "B001.001.001",
    "display_version": "S001.001.001",
    "other_version": "Y001.001.001"
  },
  "software_version": {
    "display_program": "001.001.001",
    "communication_program": "001.001.001",
    "measurement_program": "001.001.001"
  },
  "net": [
    {
      "nic": "网卡一",
      "ip": "",
      "mask": "",
      "gateway": "",
      "protocol": ""
    },
    {
      "nic": "网卡二",
      "ip": "192.168.1.56",
      "mask": "255.255.255.255",
      "gateway": "192.168.1.56",
      "protocol": "Modbus TCP"
    }
  ],
  "uart": [
    {
      "port": "COM1",
      "baud": 0,
      "parity": "",
      "data_bits": 0,
      "stop_bits": 0,
      "protocol": ""
    },
    {
      "port": "COM2",
      "baud": 115200,
      "parity": "NONE",
      "data_bits": 8,
      "stop_bits": 1,
      "protocol": "Modbus RTU"
    }
  ]
}

返回data：{"save_path":"/config/device.json","send_status":"成功"}

说明：

设备整体保存时，网卡配置按 nic 合并更新
串口配置按 port 合并更新
未出现在本次提交中的其他网卡或串口配置会保留，不会因数组顺序变化被误覆盖

5. GET /api/config/device/net

作用：按网卡标识读取单个网卡配置参数：

nic=网卡一：按 nic 查询对应网卡信息 返回data：

{
  "nic": "网卡一",
  "ip": "192.168.1.10",
  "mask": "255.255.255.0",
  "gateway": "192.168.1.1",
  "protocol": "Modbus TCP"
}

6. POST /api/config/device/net

作用：按网卡标识保存单个网卡配置 请求body参数：

{
  "nic": "网卡一",
  "ip": "192.168.1.10",
  "mask": "255.255.255.0",
  "gateway": "192.168.1.1",
  "protocol": "Modbus TCP"
}

返回data：{"save_path":"/config/device.json","target":"net","nic":"网卡一","send_status":"成功"}

说明：

服务端会根据 nic 更新对应网卡对象
若不存在相同 nic，则追加到 net 数组

7. GET /api/config/device/uart

作用：按串口标识读取单个串口配置参数：

port=COM1：按 port 查询对应串口信息 返回data：

{
  "port": "COM1",
  "baud": 9600,
  "parity": "NONE",
  "data_bits": 8,
  "stop_bits": 1,
  "protocol": "Modbus RTU"
}

8. POST /api/config/device/uart

作用：按串口标识保存单个串口配置 请求body参数：

{
  "port": "COM1",
  "baud": 9600,
  "parity": "NONE",
  "data_bits": 8,
  "stop_bits": 1,
  "protocol": "Modbus RTU"
}

返回data：{"save_path":"/config/device.json","target":"uart","port":"COM1","send_status":"成功"}

说明：

服务端会根据 port 更新对应串口对象
若不存在相同 port，则追加到 uart 数组

9. GET /api/config/channel

作用：读取通道配置，用于通道配置界面打开时回显当前参数参数：无 返回data：

{
  "ai_channel": [{"ch":1,"singal_type":"4-20mA","line_no":1,"type":"UA","limit_low":0,"limit_high":20}],
  "ao_channel": [{"ch":1,"singal_type":"1-5v","line_no":2,"type":"UA","limit_low":0,"limit_high":20}]
}

10. POST /api/config/channel

作用：提交AI/AO通道配置(AI：12通道，AO：12通道) 请求body参数：

{
  "ai_channel": [{"ch":1,"singal_type":"4-20mA","line_no":1,"type":"UA","limit_low":0,"limit_high":20}],
  "ao_channel": [{"ch":1,"singal_type":"1-5v","line_no":2,"type":"UA","limit_low":0,"limit_high":20}]
}

返回data：{"save_path":"/config/channel.json","send_status":"成功"}

11. GET /api/config/line_alarm_setting

作用：读取线路报警设置，用于报警设置界面打开时回显当前线路参数参数：

line_no=1：按线路号读取对应线路的报警设置 返回data：

{
  "line_no": 1,
  "over_limit_alarm": [
    {
      "category": "电压",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    }
  ],
  "fault_alarm": [
    {
      "category": "PT断线",
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    }
  ]
}

12. POST /api/config/line_alarm_setting

作用：提交定值报警阈值配置 请求body参数：

{
  "line_no": 1,
  "over_limit_alarm": [
    {
      "category": "电压",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
    {
      "category": "电流",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
    {
      "category": "差流",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": false
    },
    {
      "category": "功率",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
    {
      "category": "频率",
      "limit": 180,
      "delay": 180,
      "output_node": "开出1",
      "enabled": false
    }
  ],
  "fault_alarm": [
    {
      "category": "PT断线",
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
    {
      "category": "CT断线",
      "delay": 180,
      "output_node": "开出1",
      "enabled": false
    }
  ]
}

返回data：{"save_path":"/config/setting.json","send_status":"成功"}

说明：

setting.json 中的 line_alarm_setting 按数组对象存储
保存接口按单条线路配置提交
服务端会根据 line_no 对数组中的对应线路进行覆盖更新，不存在时追加

13. GET /api/config/ai_alarm_setting

作用：读取AI报警设置，用于报警设置界面打开时回显当前AI报警参数参数：无 返回data：

[
  {
    "channel_no": 1,
    "singal_type": "4-20mA",
    "limit_low": 0,
    "limit_high": 20,
    "delay": 180,
    "output_node": "开出1",
    "enabled": true
  }
]

14. POST /api/config/ai_alarm_setting

作用：提交AI报警设置 请求body参数：

[
  {
      "channel_no": 1,
      "singal_type": "4-20mA",
      "limit_low":0,
      "limit_high":20,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
 {
      "channel_no": 2,
      "singal_type": "1-5v",
      "limit_low":0,
      "limit_high":20,
      "delay": 180,
      "output_node": "开出1",
      "enabled": true
    },
  ]

返回data：{"save_path":"/config/setting.json","send_status":"成功"}

15. GET /api/config/system

作用：读取系统设置，用于系统设置界面打开时回显当前参数参数：无 返回data：

{
  "time_sync": "auto",
  "brightness": 80,
  "screen_saver": 60
}

16. POST /api/config/system

作用：提交系统对时、灯光配置 请求body参数：

{
  "time_sync": "auto",
  "brightness": 80,
  "screen_saver": 60
}

返回data：{"send_status":"成功"}

17. GET /api/alarm/list

作用：分页查询历史报警参数：

page=1：页码，从 1 开始
size=20：每页条数，最大 100
no=L1：按线路号/通道号精确筛选
type=current：按报警类型字段精确筛选
start_time=2026-05-16T10:30:00：按报警开始时间筛选
end_time=2026-05-16T11:30:00：按报警结束时间筛选

示例请求：

GET /api/alarm/list?page=1&size=20&no=L1&type=current&start_time=2026-05-16T10:30:00&end_time=2026-05-16T11:30:00

说明：

所有筛选条件均为可选
未传筛选条件时，默认按分页查询全部历史报警
start_time 和 end_time 使用日期时间格式

返回data：

[
{
  "id": 1,
  "alarm_type": "operate_alarm",
  "time": "2025-01-01 12:00:00", 
  "no": "",
  "type": "",  
  "content": "告警内容",
  "level": "告警等级"
}
]

18. POST /api/control/switch

作用：下发开关量控制指令 请求body参数：

{"ch":1,"action":1}  // 1=合，0=分

返回data：{"control_status":"执行成功"}

4.2 WebSocket 接口（主动推送）

1. WebSocket 地址：`ws://ip:port/ws/real-time`

推送内容：实时数据（0.5秒/次）

{
  "type": "real_time",
  "data": {
    "line_list": [
      {
        "line_no": 1,
        "pri_val": {
          "Ua": 6000.0,
          "Ub": 6002.5,
          "Uc": 5998.3,
          "Ia": 150.2,
          "Ib": 148.9,
          "Ic": 151.6,
          "Pa": 820.5,
          "Pb": 815.3,
          "Pc": 825.7,
          "Pt": 2461.5,
          "Qa": 120.3,
          "Qb": 118.6,
          "Qc": 122.9,
          "Qt": 361.8,
          "Sa": 835.2,
          "Sb": 829.7,
          "Sc": 840.3,
          "St": 2505.2,
          "PFa": 0.98,
          "PFb": 0.97,
          "PFc": 0.99,
          "PFt": 0.98,
          "Uab": 10400.1,
          "Ubc": 10395.6,
          "Uca": 10398.2,
          "frq": 50.00
        },
        "sec_val": {
          "Ua": 57.6,
          "Ub": 57.7,
          "Uc": 57.5,
          "Ia": 1.2,
          "Ib": 1.18,
          "Ic": 1.22,
          "Pa": 68.2,
          "Pb": 67.8,
          "Pc": 68.6,
          "Pt": 204.6,
          "Qa": 9.8,
          "Qb": 9.6,
          "Qc": 10.1,
          "Qt": 29.5,
          "Sa": 69.5,
          "Sb": 68.9,
          "Sc": 70.1,
          "St": 208.5,
          "PFa": 0.98,
          "PFb": 0.97,
          "PFc": 0.99,
          "PFt": 0.98,
          "Uab": 100.0,
          "Ubc": 99.8,
          "Uca": 99.9,
          "frq": 50.00
        }
      },
      {
        "line_no": 2,
        "pri_val": {},
        "sec_val": {}
      },
      {
        "line_no": 3,
        "pri_val": {},
        "sec_val": {}
      },
      {
        "line_no": 4,
        "pri_val": {},
        "sec_val": {}
      }
    ],
    "switch": {
      "di1": 1,
      "di2": 0,
      "di3": 1,
      "di4": 0,
      "di5": 1,
      "di6": 0,
      "di7": 1,
      "di8": 0,
      "di9": 1,
      "di10": 0,
      "di11": 1,
      "di12": 0,
      "do1": 1,
      "do2": 0,
      "do3": 1,
      "do4": 0,
      "do5": 1,
      "do6": 0,
      "do7": 1,
      "do8": 0,
      "do9": 1,
      "do10": 0,
      "do11": 1,
      "do12": 0
    },
    "ai_collect": {
      "ai1": 4.52,
      "ai2": 3.86,
      "ai3": 5.21,
      "ai4": 2.99,
      "ai5": 6.10,
      "ai6": 1.75,
      "ai7": 3.22,
      "ai8": 4.91,
      "ai9": 2.18,
      "ai10": 5.47,
      "ai11": 3.06,
      "ai12": 4.33
    }
  }
}

2. WebSocket 地址：`ws://ip:port/ws/alarm`

推送内容：实时报警事件（触发即推）

{
  "alarm_type": "line_alarm",
  "time": "2025-01-01 12:00:00", 
  "no": "1",
  "type": "",  
  "content": "告警内容",
  "level": "告警等级"
},
{
  "alarm_type": "ai_alarm",
  "time": "2025-01-01 12:00:00", 
  "no": "2",
  "type": "",  
  "content": "告警内容",
  "level": "告警等级"
},
{
  "alarm_type": "operate_alarm",
  "time": "2025-01-01 12:00:00", 
  "no": "3",
  "type": "",  
  "content": "告警内容",
  "level": "告警等级"
}

五、数据存储设计

5.1 JSON配置文件

路径：/config/
文件：device.json、channel.json、setting.json

5.2 SQLite报警数据库

表：alarm_event

字段	类型	说明
id	INTEGER	主键
alarm_type	TEXT	告警类型（line_alarm,ai_alarm,operate_alarm）
time	DATETIME	事件发生时间
no	TEXT	线路号/通道号
type	TEXT	类型
content	TEXT	告警详情
level	TEXT	告警等级

六、安全与可靠性设计

密码加密存储，接口权限校验
WebSocket断线自动重连
配置文件修改自动备份
服务异常自动重启

七、总结

本方案基于RK3568平台，采用FastAPI + HTTP + WebSocket架构，满足电气量测控平台全部需求：

RESTful API 负责配置、查询、控制
WebSocket 负责实时数据、报警数据主动推送
JSON 存储配置，SQLite 存储报警
0.5秒实时刷新，界面无卡顿、数据不丢失

系统架构轻量化、高性能，完全适配嵌入式平台运行。

23 KiB Raw Permalink Blame History Unescape Escape