更新记录

1.0.1（2025-08-22）

完整ModbusTCP通信插件制作完成

平台兼容性

云端兼容性

uni-app(4.75)

uni-app x(4.75)

其他

ModbusTCP通信插件使用说明

插件简介

hmw-mtcp 是一个专为uni-app开发的ModbusTCP通信插件，支持Android平台，提供完整的ModbusTCP协议通信功能。插件支持多设备同时连接、自动定时读取、数据读写等功能，适用于工业物联网、设备监控等应用场景。

主要特性

• ✅ 多设备连接：支持同时连接多个ModbusTCP设备
• ✅ 自动定时读取：可配置定时自动读取设备数据
• ✅ 完整协议支持：支持读取保持寄存器、写入单个寄存器等功能
• ✅ 错误处理：完善的错误处理机制和状态管理
• ✅ 线程安全：后台线程处理网络操作，不阻塞UI
• ✅ 资源管理：自动管理连接资源，防止内存泄漏

技术规格

• 支持平台：Android (API 21+)
• uni-app版本：4.75+
• HBuilderX版本：3.6.8+
• 协议支持：ModbusTCP (基于TCP/IP的Modbus协议)
• 默认端口：502

安装配置

1. 插件安装

在HBuilderX中通过插件市场安装，或手动将插件文件复制到项目的 uni_modules 目录下。

2. 权限配置

在 manifest.json 中添加网络权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />"
        ]
      }
    }
  }
}

3. 导入插件

在需要使用的页面中导入插件：

import { 
  modbusConnect, 
  modbusReadHoldingRegisters, 
  modbusWriteSingleRegister, 
  modbusDisconnect,
  modbusGetConnectedDevices 
} from '@/uni_modules/hmw-mtcp';

API接口说明

数据类型定义

ModbusConnectionConfig

连接配置对象

type ModbusConnectionConfig = {
  host: string,        // 设备IP地址
  port: number,        // 端口号，默认502
  timeout?: number,    // 连接超时时间(ms)，默认5000
  unitId?: number      // 单元ID，默认1
}

ModbusConnectResult

连接结果对象

type ModbusConnectResult = {
  deviceId: string,    // 设备唯一标识
  connected: boolean,  // 连接状态
  message: string      // 连接消息
}

ModbusReadResult

读取结果对象

type ModbusReadResult = {
  deviceId: string,    // 设备ID
  address: number,     // 起始地址
  values: number[]     // 读取的数据数组
}

ModbusWriteResult

写入结果对象

type ModbusWriteResult = {
  deviceId: string,    // 设备ID
  address: number,     // 写入地址
  success: boolean     // 写入是否成功
}

核心API

1. modbusConnect - 连接设备

连接到ModbusTCP设备

modbusConnect({
  config: {
    host: '192.168.1.100',  // 设备IP地址
    port: 502,              // 端口号
    timeout: 5000,          // 连接超时(ms)
    unitId: 1               // 单元ID
  },
  success: (res) => {
    console.log('连接成功:', res.deviceId);
  },
  fail: (err) => {
    console.error('连接失败:', err.errMsg);
  },
  complete: (res) => {
    console.log('连接操作完成');
  }
});

2. modbusReadHoldingRegisters - 读取保持寄存器

读取设备的保持寄存器数据

modbusReadHoldingRegisters({
  deviceId: 'device-uuid',  // 设备ID
  address: 0,               // 起始地址
  quantity: 10,             // 读取数量
  success: (res) => {
    console.log('读取成功:', res.values);
  },
  fail: (err) => {
    console.error('读取失败:', err.errMsg);
  }
});

3. modbusWriteSingleRegister - 写入单个寄存器

向设备写入单个寄存器的值

modbusWriteSingleRegister({
  deviceId: 'device-uuid',  // 设备ID
  address: 0,               // 寄存器地址
  value: 1234,              // 要写入的值
  success: (res) => {
    console.log('写入成功');
  },
  fail: (err) => {
    console.error('写入失败:', err.errMsg);
  }
});

4. modbusDisconnect - 断开连接

断开与设备的连接

modbusDisconnect({
  deviceId: 'device-uuid',  // 设备ID
  success: (res) => {
    console.log('断开连接成功');
  },
  fail: (err) => {
    console.error('断开连接失败:', err.errMsg);
  }
});

5. modbusGetConnectedDevices - 获取已连接设备

获取当前所有已连接设备的ID列表

const connectedDevices = modbusGetConnectedDevices();
console.log('已连接设备:', connectedDevices);

完整使用示例

基础连接和读取示例

<template>
  <view class="container">
    <button @click="connectDevice">连接设备</button>
    <button @click="readData" :disabled="!connected">读取数据</button>
    <button @click="writeData" :disabled="!connected">写入数据</button>
    <button @click="disconnectDevice" :disabled="!connected">断开连接</button>

    <view class="data-display">
      <text>读取结果: {{ readResult }}</text>
    </view>
  </view>
</template>

<script>
import { 
  modbusConnect, 
  modbusReadHoldingRegisters, 
  modbusWriteSingleRegister, 
  modbusDisconnect 
} from '@/uni_modules/hmw-mtcp';

export default {
  data() {
    return {
      deviceId: '',
      connected: false,
      readResult: []
    }
  },
  methods: {
    // 连接设备
    connectDevice() {
      modbusConnect({
        config: {
          host: '192.168.1.100',
          port: 502,
          timeout: 5000,
          unitId: 1
        },
        success: (res) => {
          this.deviceId = res.deviceId;
          this.connected = true;
          uni.showToast({ title: '连接成功' });
        },
        fail: (err) => {
          uni.showToast({ title: '连接失败: ' + err.errMsg, icon: 'none' });
        }
      });
    },

    // 读取数据
    readData() {
      modbusReadHoldingRegisters({
        deviceId: this.deviceId,
        address: 0,
        quantity: 10,
        success: (res) => {
          this.readResult = res.values;
          uni.showToast({ title: '读取成功' });
        },
        fail: (err) => {
          uni.showToast({ title: '读取失败: ' + err.errMsg, icon: 'none' });
        }
      });
    },

    // 写入数据
    writeData() {
      modbusWriteSingleRegister({
        deviceId: this.deviceId,
        address: 0,
        value: 1234,
        success: (res) => {
          uni.showToast({ title: '写入成功' });
        },
        fail: (err) => {
          uni.showToast({ title: '写入失败: ' + err.errMsg, icon: 'none' });
        }
      });
    },

    // 断开连接
    disconnectDevice() {
      modbusDisconnect({
        deviceId: this.deviceId,
        success: (res) => {
          this.connected = false;
          this.deviceId = '';
          uni.showToast({ title: '断开连接成功' });
        },
        fail: (err) => {
          uni.showToast({ title: '断开连接失败: ' + err.errMsg, icon: 'none' });
        }
      });
    }
  }
}
</script>

多设备管理示例

export default {
  data() {
    return {
      devices: [],
      timers: {}
    }
  },
  methods: {
    // 添加设备
    addDevice(config) {
      modbusConnect({
        config: config,
        success: (res) => {
          this.devices.push({
            id: res.deviceId,
            name: config.name,
            host: config.host,
            port: config.port,
            connected: true
          });
        }
      });
    },

    // 启动定时读取
    startAutoRead(deviceId, interval = 5000) {
      if (this.timers[deviceId]) {
        clearInterval(this.timers[deviceId]);
      }

      this.timers[deviceId] = setInterval(() => {
        modbusReadHoldingRegisters({
          deviceId: deviceId,
          address: 0,
          quantity: 10,
          success: (res) => {
            console.log(`设备${deviceId}数据:`, res.values);
          }
        });
      }, interval);
    },

    // 停止定时读取
    stopAutoRead(deviceId) {
      if (this.timers[deviceId]) {
        clearInterval(this.timers[deviceId]);
        delete this.timers[deviceId];
      }
    },

    // 批量读取所有设备
    readAllDevices() {
      this.devices.forEach(device => {
        if (device.connected) {
          modbusReadHoldingRegisters({
            deviceId: device.id,
            address: 0,
            quantity: 10,
            success: (res) => {
              console.log(`${device.name}数据:`, res.values);
            }
          });
        }
      });
    }
  }
}

错误处理

错误码说明

错误处理最佳实践

// 统一错误处理函数
function handleModbusError(error) {
  switch(error.errCode) {
    case 9020001:
      uni.showToast({ title: '设备连接失败，请检查网络', icon: 'none' });
      break;
    case 9020002:
      uni.showToast({ title: '数据读取失败', icon: 'none' });
      break;
    case 9020003:
      uni.showToast({ title: '数据写入失败', icon: 'none' });
      break;
    case 9020004:
      uni.showToast({ title: '设备未连接', icon: 'none' });
      break;
    default:
      uni.showToast({ title: '操作失败: ' + error.errMsg, icon: 'none' });
  }
}

// 使用示例
modbusConnect({
  config: { host: '192.168.1.100', port: 502 },
  fail: handleModbusError
});

注意事项

1. 网络权限

• 确保应用已获得网络访问权限
• 在manifest.json中正确配置网络权限

2. 线程安全

• 所有网络操作都在后台线程执行
• 回调函数在主线程中执行，可以安全更新UI

3. 资源管理

• 及时断开不需要的连接，避免资源浪费
• 应用退出时确保所有连接都已断开

4. 超时设置

• 根据网络环境合理设置连接超时时间
• 建议超时时间不少于3秒

5. 地址范围

• 寄存器地址范围：0-65535
• 读取数量限制：1-125个寄存器
• 写入值范围：0-65535

6. 设备兼容性

• 确保目标设备支持ModbusTCP协议
• 验证设备的单元ID和寄存器映射

常见问题

Q: 连接失败怎么办？

A:

1. 检查设备IP地址和端口是否正确
2. 确认设备已开启ModbusTCP服务
3. 检查网络连通性
4. 验证防火墙设置

Q: 读取数据为空怎么办？

A:

1. 确认寄存器地址是否正确
2. 检查读取数量是否超出设备支持范围
3. 验证设备是否有数据

Q: 如何实现断线重连？

A:

function autoReconnect(config, maxRetries = 3) {
  let retryCount = 0;

  function tryConnect() {
    modbusConnect({
      config: config,
      success: (res) => {
        console.log('重连成功');
        retryCount = 0;
      },
      fail: (err) => {
        retryCount++;
        if (retryCount < maxRetries) {
          setTimeout(tryConnect, 5000); // 5秒后重试
        }
      }
    });
  }

  tryConnect();
}

Q: 如何优化性能？

A:

1. 合理设置定时读取间隔，避免过于频繁
2. 批量读取多个连续寄存器，减少通信次数
3. 及时断开不需要的连接
4. 使用连接池管理多设备连接

技术支持

• 留言即可

许可证

本插件遵循商业许可证，使用前请仔细阅读许可协议。