# ModbusCtrl

**Repository Path**: devcld/ModbusCtrl

## Basic Information

- **Project Name**: ModbusCtrl
- **Description**: 基于modbus的局域网控制软件。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 局域网远程控制工具

基于 **Tauri 2** + **Vue 3** + **Naive UI** 的 Modbus 设备管理与配置桌面应用。

## 核心功能

| 模块 | 说明 |
|------|------|
| **设备配置** | UDP 广播搜索局域网设备、配置网络参数、固件升级、串口配置 |
| **设备管理** | 添加/编辑/删除设备，关联型号与分组，实时状态监控、定时任务 |
| **型号管理** | 维护寄存器模板（数据类型、地址、读写属性、报警规则）、支持导入导出 |
| **场景管理** | 批量执行多设备寄存器写入 |
| **分组管理** | 多层级设备分组 |
| **系统设置** | 主题切换、语言、开机自启、通讯网卡选择、官方店铺链接 |

## 通讯协议

- **Modbus TCP** — 标准 Modbus TCP 协议（端口 502）
- **Modbus RTU over TCP** — RTU 帧通过 TCP 传输，适用于串口网关设备
- **UDP 搜索** — 广播地址 `255.255.255.255:5002` 发现局域网设备

---

## 项目架构

```
┌─────────────────────────────────────────────────┐
│                   Tauri Shell                   │
│  ┌───────────────────┐  ┌─────────────────────┐ │
│  │   Vue 3 前端       │  │   Rust 后端          │ │
│  │                   │  │                     │ │
│  │  views/           │  │  lib.rs             │ │
│  │  ├── HomeView     │  │  ├── Modbus 协议    │ │
│  │  ├── DeviceConfig │  │  ├── UDP 搜索       │ │
│  │  ├── DeviceManage │  │  ├── 连接池管理     │ │
│  │  ├── DeviceModel  │  │  ├── 文件 I/O       │ │
│  │  ├── GroupManage  │  │  └── 设备重启       │ │
│  │  ├── SceneManage  │  │                     │ │
│  │  └── SystemSettings│ │  前后端通过         │ │
│  │                   │  │  Tauri IPC 通信    │ │
│  │  stores/          │  └─────────────────────┘ │
│  │  ├── device       │                         │
│  │  ├── group        │                         │
│  │  ├── theme        │                         │
│  │  └── user         │                         │
│  └───────────────────┘                         │
└─────────────────────────────────────────────────┘
```

### 前端架构

```
src/
├── main.ts              # 入口文件，初始化 Pinia/i18n/Router
├── App.vue              # 根组件，NaiveUI 配置提供者、深色/浅色主题
├── router/index.ts      # 路由配置，Token 鉴权守卫
├── layouts/
│   └── TopMenuLayout.vue # 顶部导航布局，设备轮询启停
├── stores/              # Pinia 状态管理
│   ├── device.ts        # 设备通讯核心：轮询、读写、报警、操作队列
│   ├── group.ts         # 分组数据
│   ├── theme.ts         # 主题、网卡选择、持久化
│   └── user.ts          # 用户登录状态
├── views/               # 页面组件
│   ├── HomeView.vue     # 首页仪表盘、快捷操作
│   ├── LoginView.vue    # 登录页
│   ├── DeviceConfig.vue # 设备配置（搜索、基础/高级配置、模板、固件）
│   ├── DeviceManage.vue # 设备管理（CRUD、实时数据、报警、定时任务）
│   ├── DeviceModelManage.vue # 型号管理（寄存器模板、导入导出）
│   ├── GroupManage.vue  # 分组管理（树形结构）
│   ├── SceneManage.vue  # 场景管理（批量操作）
│   └── SystemSettings.vue # 系统设置
├── utils/
│   ├── modbus.ts        # Modbus IPC 封装（读写寄存器、连接清理）
│   ├── udp.ts           # UDP 搜索、消息监听、设备响应解析
│   └── storage.ts       # 数据持久化（调用 Rust 文件 I/O）
├── locales/
│   ├── index.ts         # i18n 初始化、语言切换
│   ├── zh-CN.ts         # 中文
│   └── en.ts            # 英文
└── sys-methods/         # Tauri 系统能力封装
    ├── power/           # 关机、重启、休眠
    ├── audio/           # 音量控制
    ├── autostart/       # 开机自启
    ├── bluetooth/       # 蓝牙控制
    ├── network/         # 网络设置
    ├── notification/    # 系统通知
    ├── file/            # 文件操作
    └── system/          # 其他系统方法
```

### Rust 后端架构

```
src-tauri/
├── src/
│   ├── lib.rs           # 核心后端逻辑
│   │   ├── 全局连接池   # MODBUS_POOL: LazyLock<Mutex<HashMap>>
│   │   ├── 设备信号量   # DEVICE_SEMAPHORES: 串行化每设备操作
│   │   ├── 操作超时     # call_with_timeout (5000ms)
│   │   ├── 连接重试     # 连接错误自动重试一次
│   │   ├── 批量读取     # modbus_read_device_registers
│   │   ├── UDP 搜索    # search_devices (广播发现)
│   │   ├── 设备重启    # clear_device_connection
│   │   └── 文件 I/O    # load_data / save_data
│   └── main.rs          # 入口
├── Cargo.toml           # Rust 依赖
├── capabilities/        # Tauri 权限配置
└── icons/               # 应用图标
```

### 核心设计

**设备操作队列** — 每台设备独立的 Promise 链，串行化读写操作：
```
设备 A: [读] → [写(高优先级)] → [读] → [读] → ...
设备 B:       [读] → [读] → [写(高优先级)] → ...
```

- 读取操作 `normal` 优先级，排队执行
- 写入操作 `high` 优先级，插队到队列最前面
- 写入期间，轮询读取不覆盖该寄存器的值（乐观更新保护）

**连接池** — Rust 全局 `MODBUS_POOL`，每设备 `{ip}:{port}:{slave_id}:{mode}` 独立缓存：
- 复用已有 TCP 连接，避免重复建连
- 连接错误自动重试一次，失败清除缓存
- 连续 3 次读取超时，自动发送设备重启命令

**Per-device 轮询** — 每台设备独立 `setTimeout` 轮询周期（1 秒）：
- 启动时随机错开 0-1 秒，避免同时发包
- 设备页面（DeviceConfig）进入时暂停轮询，离开时恢复

---

## 环境准备

### 必需

- **Node.js** ≥ 18（[下载](https://nodejs.org/)）
- **Rust** 最新稳定版（[安装](https://www.rust-lang.org/tools/install)）
- **pnpm**（推荐）

```bash
npm install -g pnpm
```

### 平台依赖

**macOS**: 安装 Xcode Command Line Tools
```bash
xcode-select --install
```

**Windows**: 安装 [Visual Studio C++ 生成工具](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（Rust 安装程序会自动提示）

---

## 快速开始

```bash
# 克隆项目
git clone <repo-url>
cd TvTa-ui-main

# 安装依赖
pnpm install

# 启动开发模式
pnpm tauri dev
```

---

## 开发指南

### 开发模式

```bash
pnpm tauri dev
```

启动 Vite 前端开发服务器 + Rust 后端，支持热更新。前端代码修改即时生效，Rust 代码修改自动重新编译。

### 构建发布

```bash
pnpm tauri build
```

产物位置：
| 平台 | 路径 |
|------|------|
| macOS (.dmg) | `src-tauri/target/release/bundle/dmg/` |
| macOS (.app) | `src-tauri/target/release/bundle/macos/` |
| Windows (.exe) | `src-tauri/target/release/bundle/nsis/` |

### 常见问题

**Q: 构建时报 `version mismatched Tauri packages`？**
A: NPM 和 Rust 的 Tauri 包版本需要匹配。执行：
```bash
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm tauri build
```

**Q: Windows 上 `oxc-parser` 报错？**
A: `unocss` 的 `presetAttributify` 依赖原生模块，在 Windows 上可能安装失败。本项目已移除该依赖，重新安装即可：
```powershell
Remove-Item -Recurse -Force node_modules
Remove-Item -Force pnpm-lock.yaml
pnpm install
```

**Q: Rust crates.io 下载慢？**
A: 使用中科大镜像源，在 `~/.cargo/config.toml` 中添加：
```toml
[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
```

---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 跨平台框架 | **Tauri 2** | Rust 后端 + WebView 前端，体积小、性能高 |
| 前端框架 | **Vue 3** + **TypeScript** | Composition API |
| UI 组件库 | **Naive UI** | 深色/浅色主题、国际化 |
| 状态管理 | **Pinia** | 设备、分组、主题、用户 |
| 路由 | **Vue Router** | Token 鉴权守卫 |
| 国际化 | **Vue I18n** | 中文/英文切换 |
| CSS | **UnoCSS** | 原子化 CSS |
| Modbus | **tokio-modbus** | TCP + RTU over TCP |
| 异步运行时 | **tokio** | Rust 异步 I/O |
| 文件存储 | **JSON** | 设备/型号/模板/场景数据 |