# SL651-2014模拟上传工具 **Repository Path**: yqcgba/SL651-2014 ## Basic Information - **Project Name**: SL651-2014模拟上传工具 - **Description**: 基于《水文监测数据通信规约 SL651-2014》 Python模拟器，用于测试和验证 SL651 协议消息的构建与解析。模拟水文监测数据的开源工具，用于测试与验证数据上传系统，支持自定义水位、流量等参数，助力水利信息化开发。 - **Primary Language**: Python - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-08-07 - **Last Updated**: 2026-09-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SL651-2014 水文监测数据通信规约模拟器 基于 Flask 构建的 SL651 水文监测数据通信规约模拟工具，用于测试和验证 SL651-2014 协议消息的构建、解析与传输。本项目提供了完整的协议实现、Web 界面交互以及 API 接口调用能力。 ## 项目概述 SL651-2014 是中华人民共和国水利行业标准，规定了水文监测设备与监控中心之间的数据通信协议。本模拟器严格遵循该协议规范，实现了消息的编码解码、数据校验、报文封装等核心功能，为水文监测系统的开发和测试提供了可靠的工具支持。 本项目采用模块化设计，将协议实现与 Web 应用分离，便于独立扩展和维护。协议核心模块 `sl651_protocol.py` 封装了所有与 SL651 协议相关的编码逻辑，而 `app.py` 则负责提供 Web 服务和 API 接口，两者通过清晰定义的接口进行交互。 ## 功能特性 ### 协议支持能力 本模拟器完整实现了 SL651-2014 协议的核心功能，包括消息的完整构建与解析。在消息构建方面，支持按照协议规范封装各类数据报文，包含起始符、数据长度、监控中心地址、站点地址、密码、功能码、数据体、校验码和结束符等完整字段。消息解析功能可以准确还原接收到的原始报文，提取其中的站点信息、监测数据、时间戳等关键内容。 CRC16 校验算法是保证数据传输完整性的关键机制，本模拟器内置了符合协议要求的 CRC16 实现，能够自动计算并验证报文的校验码，确保数据在传输过程中未被篡改或损坏。同时，项目还提供了 BCD 编码转换功能，支持将整数和字符串转换为 BCD 字节码，这是 SL651 协议中数值数据的主要编码方式。 定时报文是水文监测中最常见的数据上报类型，本模拟器重点优化了这部分功能，支持构建包含站点基本信息、观测时间及多个监测要素的完整定时上报消息体，用户可以灵活配置上报时间、站点类型、监测要素等内容。 ### Web API 接口 模拟器提供了三个核心 API 接口，覆盖了测试和使用的完整流程。连接测试接口 `/api/test_connection` 允许用户在不发送实际数据的情况下测试与监控中心的网络连通性，这对于排查网络问题非常有帮助。该接口接收目标 IP 地址和端口号作为参数，返回连接测试结果。 数据上传接口 `/api/upload` 是模拟器的核心功能，用于向监控中心发送 SL651 格式的监测数据。接口接受完整的报文参数，包括监控中心地址、站点地址、密码、功能码、监测要素列表以及设备电压等信息，构建符合规范的报文并发送。 消息预览接口 `/api/preview` 提供了报文预览功能，用户可以在实际发送前查看将要发送的原始消息内容（以十六进制字符串形式呈现），这对于调试和验证协议实现非常有价值。 ### 数据验证机制 为了确保输入数据的合法性，本模拟器实现了多层次的数据验证机制。站址验证功能检查站点地址是否符合协议要求的 16 位字符格式，确保地址信息完整且有效。密码验证功能验证密码是否为 4 位数字，符合协议对认证信息的规范要求。网络验证功能则检查 IP 地址的格式是否正确以及端口号是否在合法范围内（1-65535），防止因网络参数错误导致的连接失败。 这些验证机制在 API 接口接收到请求时自动执行，对于不合法的输入会返回明确的错误信息，帮助用户快速定位和修正问题。 ## 运行环境 ### 环境要求 本项目需要以下运行环境支持：Python 版本要求 3.7 或更高版本，以确保所有语法特性和标准库函数正常工作；Flask 框架作为 Web 应用的基础，需要在项目中安装；其他依赖项见 requirements.txt 文件。 ### 安装步骤 首先从代码仓库克隆项目到本地，切换到项目目录后安装所需的 Python 依赖包。requirements.txt 文件包含了所有必要的依赖项及其版本要求，使用 pip 命令可以自动完成安装。安装完成后，直接运行 app.py 即可启动 Web 服务，默认监听 5000 端口。启动成功后，在浏览器中访问 http://localhost:5000 即可使用模拟器的完整功能。 ## 目录结构 ``` SL651-2014/ ├── LICENSE # 开源许可证文件 ├── README.md # 项目说明文档 ├── README.en.md # 英文说明文档 ├── sl651_simulator_v1.1/ # 主程序目录 │ ├── app.py # Flask Web 应用入口 │ ├── requirements.txt # Python 依赖清单 │ ├── sl651_protocol.py # SL651 协议核心实现 │ └── templates/ # 前端页面模板 │ └── index.html # Web 界面 ``` ## API 接口详细说明 ### 测试连接接口 连接测试接口用于验证与监控中心的网络连通性，请求方式为 POST，接收 JSON 格式的请求体。请求参数包括目标服务器的 IP 地址和端口号，需要确保指定的地址和端口可达。接口返回连接测试的成功或失败状态，并附带相关信息帮助用户了解测试结果。 ### 数据上传接口 数据上传接口是模拟器最核心的功能接口，请求方式为 POST。请求体需要包含完整的报文参数，其中 `center_addr` 表示监控中心地址，为整数值；`station_addr` 表示站点地址，为 16 位字符字符串；`password` 为 4 位数字密码；`func_code` 为功能码整数；`elements` 为监测要素数组，每个要素包含引导字节、监测值、总位数和小数位数；`voltage` 表示设备工作电压，默认为 12.5V。 ### 消息预览接口 消息预览接口的请求参数与数据上传接口相同，但不实际发送数据，仅返回构建后的原始消息内容。返回的十六进制字符串可直接用于协议分析或调试工具，是了解和验证协议实现的很好方式。 ## 协议实现详解 ### 编码机制 CRC16 校验是 SL651 协议中保障数据完整性的核心机制，本实现严格按照协议规范计算报文的校验码，确保与标准设备兼容。BCD 编码用于将十进制数值转换为二进制表示的压缩格式，在协议中被广泛用于站点地址、密码等字段的编码。数值编码功能支持不同精度和位数的数值转换，允许用户根据实际需求配置监测数据的显示格式。 ### 核心函数说明 协议模块 `sl651_protocol.py` 提供了以下核心函数：`build_message` 函数负责构建完整的 SL651 消息，包含所有协议规定字段的封装；`build_timed_report_body` 函数专门用于构建定时上报消息体，支持配置站点信息、上报时间、观测时间和多个监测要素；`decode_message` 函数实现消息的解析，将接收到的字节流转换为结构化的字典数据，便于程序处理和展示；`_crc16` 和 `_crc16_bytes` 函数提供 CRC16 校验值的计算；`_int_to_bcd` 和 `_bcd_str_to_bytes` 函数实现整数和字符串与 BCD 字节码之间的转换。 ## 使用指南 ### Web 界面操作 通过浏览器访问模拟器地址后，可以看到功能完整的 Web 界面。界面采用卡片式布局，将不同功能区域分开，便于操作。连接测试区域可以输入监控中心的地址和端口，点击测试按钮后会在下方显示连接状态。数据填报区域用于设置站点地址、密码、功能码等基础信息，以及配置要上报的监测要素。预览区域实时显示构建的原始消息内容，十六进制格式便于协议分析。 ### 监测要素配置 每个监测要素需要配置四个参数：引导字节（guide_byte）标识要素类型，监测值（value）为实际采集的数据， 总位数（total_digits）控制数值的显示宽度，小数位数（decimal_places）指定小数点后的精度。配置完成后点击预览或上传按钮即可查看或发送对应的报文。 ## 许可证 本项目遵循 LICENSE 文件中规定的开源许可证条款进行分发和使用。 ## 贡献与反馈 欢迎通过提交 Issue 或 Pull Request 的方式参与项目改进，共同完善 SL651 协议模拟器的功能。