# VirtualGateway-NewLand **Repository Path**: IoT-NewLand/VirtualGateway-NewLand ## Basic Information - **Project Name**: VirtualGateway-NewLand - **Description**: 虚拟网关-NewLand - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-05-09 - **Last Updated**: 2025-06-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: NewLand, Python ## README # 虚拟网关 - 新大陆物联网云平台接入工具 ## 项目简介 虚拟网关是一款专为新大陆物联网云平台设计的强大模拟工具。它能够精准模拟各类设备的复杂数据上报行为以及对云端指令的响应与处理。借助其直观的图形化用户界面 (GUI)，用户可以轻松创建、配置和管理虚拟传感器与执行器，从而高效地测试与云平台的连接稳定性、数据交互的准确性以及整体业务逻辑的正确性。 ## 核心功能 本项目提供全面且高度可配置的功能，以满足多样化的测试与开发需求： ### 1. 精细化参数配置 - **云平台连接参数**：灵活配置目标云平台的 IP 地址和端口号。 - **设备身份参数**：设定模拟设备的唯一标识符 (Device ID) 和传输密钥 (Key)，确保安全认证。 - **连接状态管理**：提供一键连接/断开云平台的操作，并实时显示当前网络连接状态。 - **配置持久化**：所有云平台及设备相关的核心参数，在用户输入完成并失去焦点时，将自动保存至 `config.json` 文件，确保配置的即时性和持久性。 ### 2. 高级虚拟传感器模拟 - **动态管理传感器**：支持用户便捷地添加、删除和修改虚拟传感器。每个传感器均可自定义显示名称、API 标识名 (与云平台对应)、数据类型 (如数字、浮点、字符串) 及所属设备分组。 - **复杂数据生成规则**：内置多种高级数据生成模式，以模拟真实世界传感器的多样化输出： - **随机模式 (Random)**：在用户设定的最小值和最大值之间生成符合均匀分布的随机数据。 - **固定值模式 (Fixed Value)**：传感器始终上报一个预设的固定值。 - **递增模式 (Increment)**：数据从初始值开始，按照设定的步长稳定递增，达到预设阈值后自动重置。 - **递减模式 (Decrement)**：数据从初始值开始，按照设定的步长稳定递减，达到预设阈值后自动重置。 - **正弦波模式 (Sine Wave)**：生成符合正弦函数变化规律的数据，用户可自定义振幅、周期、相位等关键参数。 - **自定义表达式模式 (Custom Expression)**：提供强大的基于 Python 的表达式引擎，允许用户编写自定义逻辑生成数据。支持丰富的内置变量和函数，如 `min_value`, `max_value`, `counter` (当前迭代次数), `last_value` (上一次生成的值), `random` (随机数模块), `math` (数学函数库), `time` (时间模块), 以及 `sin`, `cos`, `pi` 等常用数学常量与函数。 - **定时数据上报**：当前默认配置为每隔3秒自动触发传感器数据更新及上报至云平台。此间隔可在代码中调整。 - **多数据类型支持**：全面支持数字 (Integer)、浮点数 (Float) 和字符串 (String) 等常见数据类型。 ### 3. 交互式虚拟执行器 - **动态管理执行器**：支持用户便捷地添加、删除和修改虚拟执行器。每个执行器均可自定义显示名称、API 标识名 (与云平台对应)、数据类型 (如数字、布尔) 及所属设备分组。 - **手动状态控制**：用户可通过界面上的交互式控件 (如按钮) 直接改变虚拟执行器的状态。 - **云端指令响应 (双向通信)**：能够接收并解析来自新大陆物联网云平台的控制指令，并根据指令内容自动更新执行器的状态，模拟真实设备的远程控制能力。 - **多数据类型支持**：支持数字 (Integer) 和布尔 (Boolean) 等执行器常用数据类型。 ### 4. 灵活的设备分组管理 - **层级化管理**：允许用户对创建的虚拟传感器和执行器进行自定义分组，便于组织和管理大量模拟设备。 - **分组操作**：支持添加新的分组、重命名现有分组以及删除不再需要的分组。 - **便捷分配**：在创建或编辑传感器/执行器时，可方便地将其指派到已创建的任意分组。 - **清晰展示**：设备列表中会清晰显示每个传感器/执行器所属的分组信息。 ### 5. 强大的搜索与筛选功能 - **快速定位设备**：为传感器列表和执行器列表分别提供独立的搜索框。 - **多维度筛选**：支持基于设备显示名称 (使用 `@关键词` 格式)、API 标识名 (使用 `#关键词` 格式) 和所属分组 (使用 `%关键词` 格式) 进行精确筛选。 - **组合搜索**：允许用户组合使用多个筛选条件，以实现更复杂的查询需求。 - **实时结果更新**：搜索和筛选结果会随着用户输入动态实时更新，提供流畅的交互体验。 ### 6. 可靠的TCP通信协议栈 - **基于TCP/IP**：采用稳定可靠的 TCP 协议与新大陆物联网云平台进行底层通信。 - **设备认证流程**：严格遵循平台规范，实现设备注册请求和身份认证过程。 - **标准化数据交互**：支持传感器数据的规范化上报以及执行器控制指令的准确接收与解析。 - **心跳维持机制**：内置自动心跳包发送功能 (默认发送 `$#AT#`)，确保与云平台之间的长连接保持活动状态，防止意外断开。 - **智能断线重连**：提供可配置的自动断线重连机制，用户可设定最大重连尝试次数和每次重连之间的间隔时间，增强系统鲁棒性。 ### 7. 全面配置持久化 - **启动自动加载**：应用程序启动时，会自动从 `config.json` 文件加载所有先前保存的配置信息。 - **关闭自动保存**：应用程序正常关闭前，会将当前所有的配置状态（包括云平台参数、设备参数、传感器列表、执行器列表、日志配置、重连策略、分组信息等）完整保存到 `config.json`。 - **实时增量保存**：在参数配置输入框失去焦点、成功添加/删除/编辑传感器或执行器后，相关配置会立即自动保存，防止数据丢失。 ### 8. 详细的日志记录与管理 - **多维度日志类型**：系统能够记录包括应用运行状态、配置变更详情、网络连接事件、设备管理操作、数据传输过程等多种类型的日志信息。 - **自定义日志级别**：用户可以通过配置界面选择性地启用或禁用特定类型的日志记录，以满足不同的调试和监控需求。 - **便捷日志查阅与清理**：提供界面化的日志查看功能，并支持一键清除当前日志内容，方便管理日志文件。 ### 9. 优化的用户界面 (UI) - **现代化布局**：主窗口界面经过精心设计，移除了传统的菜单栏，使得整体布局更加简洁、直观。 - **功能集成**：将日志记录配置、断线重连配置以及程序退出等常用操作统一集成到参数配置区域，提升操作便捷性。 ## 系统环境要求 - **Python 版本**: 3.9 或更高版本 - **核心依赖库**: - PyQt5: 5.15.6 或更高版本 (用于构建图形用户界面) - pyqtgraph: 0.12.4 或更高版本 (虽然当前版本未直接大量使用其绘图功能，但保留此依赖以备后续可能的图表展示等功能扩展) - **操作系统兼容性**: Windows, Linux, macOS ## 安装与部署指南 1. **获取项目代码**：通过 Git 克隆或直接下载项目源代码压缩包。 2. **创建并激活 Python 虚拟环境** (强烈推荐，以隔离项目依赖)： ```bash python -m venv .venv # Windows 系统激活命令 .venv\Scripts\activate # Linux/macOS 系统激活命令 source .venv/bin/activate ``` 3. **安装项目依赖**：在激活的虚拟环境下，执行以下命令安装所有必需的 Python 包： ```bash pip install -r requirements.txt ``` ## 快速上手指南 1. **启动应用程序**： ```bash python main.py ``` 2. **配置云平台与设备参数**： - 在主界面的“参数配置”区域，准确填写云平台的 IP 地址、端口号，以及您在云平台上注册的设备 ID 和设备密钥。 - 这些参数在对应输入框失去焦点后会自动保存。 3. **配置日志与重连策略 (可选)**： - 在“参数配置”区域，点击相应的按钮（如“日志配置”、“重连配置”）会弹出专用对话框，允许您进行详细设置。 4. **配置设备分组 (可选)**： - 点击“参数配置”区域的“分组配置”按钮，打开分组管理对话框，您可以在此添加新的分组、重命名或删除现有分组。 5. **添加虚拟传感器**： - 切换到“虚拟传感器”标签页，点击“添加传感器”按钮。 - 在弹出的对话框中，填写传感器的基本信息 (名称、API标识等)，然后在“数据生成规则”标签页选择一种数据生成模式并配置其特定参数。 - 根据需要选择传感器所属的分组。 - 点击“确定”按钮完成添加。传感器配置会自动保存。 6. **添加虚拟执行器**： - 切换到“虚拟执行器”标签页，点击“添加执行器”按钮。 - 填写执行器的基本信息，并选择其所属分组。 - 点击“确定”按钮完成添加。执行器配置会自动保存。 7. **利用搜索与筛选**： - 在“虚拟传感器”或“虚拟执行器”标签页的搜索框中输入关键词。 - 可使用特定前缀进行精确搜索：`@名称` (按显示名称搜索), `#标识` (按API标识名搜索), `%分组` (按所属分组搜索)。 - 若不使用前缀，则默认为在所有可搜索字段中进行模糊匹配。 8. **连接到云平台**： - 在“参数配置”区域，点击“连接”按钮尝试与配置的云平台建立 TCP 连接。 - 连接成功后，状态栏将显示“已连接”，并且已配置的虚拟传感器将按照预设的3秒间隔自动更新数据并上报至云平台。 9. **进行交互操作**： - 在“虚拟执行器”标签页，您可以点击列表中每个执行器对应的状态控制按钮来手动改变其状态。 - 当虚拟网关接收到来自云平台的控制指令时，对应执行器的状态也会自动更新并在界面上反映出来。 ## 配置文件 (`config.json`) 详解 本程序使用 `config.json` 文件集中存储所有持久化配置信息。该文件采用 JSON 格式，其主要结构如下所示： ```json { "host": "云平台IP地址 (字符串)", "port": "云平台端口号 (整数)", "device_id": "设备ID (字符串)", "key": "设备密钥 (字符串)", "sensors": [ { "display_name": "传感器显示名称 (字符串)", "api_tag": "传感器API标识名 (字符串，与云平台对应)", "data_type": "传感器数据类型 (字符串: '数字', '浮点', '字符串')", "min_value": "最小值 (数字，用于随机、递增/减等模式)", "max_value": "最大值 (数字，用于随机、递增/减等模式)", "group": "所属分组名称 (字符串)", "generation_mode": "数据生成模式 (字符串: '随机', '固定值', '递增', '递减', '正弦波', '表达式')", "generation_params": { // 此对象内容根据 'generation_mode' 的不同而变化，例如： // "value": "固定值模式下的值", // "step": "递增/递减模式下的步长", // "amplitude": "正弦波模式下的振幅", // "period": "正弦波模式下的周期", // "expression": "自定义表达式模式下的Python表达式字符串" } } // ...更多传感器对象 ], "actuators": [ { "display_name": "执行器显示名称 (字符串)", "api_tag": "执行器API标识名 (字符串，与云平台对应)", "data_type": "执行器数据类型 (字符串: '数字', '布尔')", "value": "执行器当前值 (根据data_type决定类型)", "group": "所属分组名称 (字符串)" } // ...更多执行器对象 ], "logging": { "enabled_types": [ 0, // 对应某种日志类型，例如：应用运行 1, // 对应另一种日志类型，例如：配置变更 // ... 其他启用的日志类型索引 (整数列表) 7 ] }, "reconnect_enabled": true, // 是否启用自动断线重连 (布尔值: true/false) "max_reconnect_attempts": 5, // 最大重连尝试次数 (整数) "reconnect_interval": 5, // 重连间隔时间，单位：秒 (整数) "groups": [ "默认分组", "自定义分组1", "自定义分组2" // ...其他分组名称 (字符串列表) ] } ``` ## 项目模块化结构 ``` VirtualGateway-NewLand/ ├── main.py # 应用程序主入口脚本 ├── requirements.txt # Python项目依赖包列表 ├── config.json # 用户配置文件 (自动生成与管理) ├── logs/ # 日志文件存储目录 (自动生成) │ └── gateway_YYYYMMDD_HHMMSS.log # 日志文件示例 ├── LICENSE # 项目许可证文件 (MIT) ├── README.md # 项目说明文档 (本文档) ├── 设备接入协议-TCP.md # 新大陆物联网云平台TCP接入协议详细说明 (Markdown格式) ├── 设备接入协议-TCP.doc # 新大陆物联网云平台TCP接入协议详细说明 (Word格式) ├── ui/ # 用户界面 (UI) 模块 │ ├── __init__.py │ ├── main_window.py # 主应用程序窗口实现 │ ├── param_config_widget.py # 云平台及设备参数配置面板 │ ├── sensor_widget.py # 虚拟传感器管理及数据生成规则配置界面 │ ├── actuator_widget.py # 虚拟执行器管理界面 │ ├── log_management_dialog.py # 日志配置对话框 │ ├── log_management_widget.py # (可能与Dialog关联或作为独立组件) │ ├── reconnect_config_dialog.py # 断线重连配置对话框 │ ├── reconnect_config_widget.py # (可能与Dialog关联或作为独立组件) │ ├── group_config_dialog.py # 设备分组管理对话框 │ └── group_config_widget.py # (可能与Dialog关联或作为独立组件) ├── protocol/ # 通信协议处理模块 │ ├── __init__.py │ └── tcp_client.py # TCP客户端核心实现 (连接、认证、数据收发、心跳等) ├── data/ # 数据模型与业务逻辑模块 │ ├── __init__.py │ ├── sensor.py # 传感器数据结构定义及数据生成逻辑实现 │ └── actuator.py # 执行器数据结构定义 ├── config/ # 配置管理模块 │ ├── __init__.py │ └── settings.py # 配置文件 (config.json) 的读取、写入及默认值管理工具 └── utils/ # 通用工具模块 ├── __init__.py └── logger.py # 日志记录器实现 (格式化、文件输出、级别控制等) ``` ## 通信协议概要 本项目严格遵循新大陆物联网云平台定义的 TCP 设备接入协议。关于协议的完整帧格式、消息类型、字段定义等详细信息，请参阅项目根目录下提供的 `设备接入协议-TCP.md` (Markdown 版本) 或 `设备接入协议-TCP.doc` (Word 版本) 文档。 关键支持的协议交互类型包括： - **设备连接/断开请求与响应** (对应协议消息类型 1 和 2) - **传感器数据上报与平台确认** (对应协议消息类型 3 和 4) - **执行器状态数据上报** (通常作为传感器数据的一部分，使用消息类型 3 和 4 进行上报) - **接收并处理云平台下发的控制指令** (对应协议消息类型 5 和 6) - **周期性心跳包发送** (使用特定格式如 `$#AT#` 来维持 TCP 连接的活性) ## 重要注意事项 - **云平台预配置**：在首次使用本虚拟网关前，请确保您已在新大陆物联网云平台上创建了相应的设备实例，并为其配置了与您将在虚拟网关中使用的 API 标识名 (`api_tag`) 完全一致的传感器和执行器。 - **标识名一致性**：虚拟传感器和虚拟执行器的 API 标识名 (`api_tag`) 必须与云平台上对应数据点的标识符严格匹配，否则数据无法正确同步。 - **数据上报频率**：当前版本中，传感器数据的自动更新与上报频率硬编码为3秒。如需调整，请直接修改 `ui/sensor_widget.py` 文件中 `self.timer.start(3000)` 的参数值 (单位：毫秒)。 - **日志文件管理**：应用程序运行过程中产生的日志信息会持续写入 `logs/` 目录下的日志文件 (如 `gateway_YYYYMMDD_HHMMSS.log`)。请注意，这些日志文件会随时间累积而增大，建议根据实际需要定期进行归档、清理或设置日志轮转策略。 - **自定义表达式风险**：自定义表达式功能虽然强大且灵活，但也引入了潜在的风险。用户在编写表达式时，务必确保语法的正确性，并避免执行可能导致程序崩溃或产生非预期行为的恶意/错误代码。 ## 项目许可证 本项目基于 MIT 许可证授权。详细条款请参阅项目根目录下的 [LICENSE](LICENSE) 文件。