ts-communication 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 X Communication
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -2,15 +2,26 @@
 
 面向 Node.js 和 TypeScript 的工业 PLC 通讯库，提供统一的异步连接、读取、写入和在线监测 API。
 
-## 支持的设备与协议
+所有协议客户端共享同一套方法命名（`ConnectServer` / `ReadInt16` / `WriteFloat` / `ConnectClose`）和同一种返回值（`OperateResult`），切换设备品牌时业务代码基本不用改动，也不需要在业务层处理底层报文。
 
-- Siemens S7：S7-200、S7-200 Smart、S7-300、S7-400、S7-1200、S7-1500
-- Melsec MC：MC 二进制 TCP/UDP 与 ASCII 兼容客户端
-- Omron FINS：FINS TCP/UDP 客户端
-- Inovance：AM、H3U、H5U、Easy、EVO 系列
-- Modbus：Modbus TCP、RTU、RTU over TCP、ASCII、UDP
+## 支持的设备与协议
 
-各协议客户端均按独立类提供，不需要在业务代码中处理底层报文。
+| 品牌 / 协议 | 客户端类 | 默认端口 | 默认字节序 |
+| --- | --- | --- | --- |
+| Siemens S7（S7-200 / 200 Smart / 300 / 400 / 1200 / 1500） | `SiemensS7Net` | 102 | ABCD |
+| Melsec MC 二进制 | `MelsecMcNet`、`MelsecMcUdp` | 6000 | DCBA |
+| Melsec MC ASCII | `MelsecMcAsciiNet`、`MelsecMcAsciiUdp` | 6000 | DCBA |
+| Omron FINS | `OmronFinsNet`、`OmronFinsUdp` | 9600 | CDAB |
+| Inovance 汇川（AM / H3U / H5U / Easy / EVO） | `InovanceTcpNet`、`InovanceSerial`、`InovanceSerialOverTcp` | 502 | CDAB |
+| Inovance EasyNet | `InovanceEasyNet` | 8000 | CDAB |
+| Invt 英威腾 TS600 | `InvtModbusTcp` | 502 | CDAB |
+| Delta 台达（DVP / AS300） | `DeltaTcpNet` | 502 | CDAB |
+| GE SRTP（PACSystems / 90 系列） | `GeSRTPNet` | 18245 | DCBA |
+| XinJE 信捷（XC / XD / XL） | `XinJETcpNet` | 502 | CDAB |
+| Modbus | `ModbusTcpNet`、`ModbusUdpNet`、`ModbusRtu`、`ModbusRtuOverTcp`、`ModbusAscii`、`ModbusAsciiOverTcp` | 502 | CDAB |
+| 调试工具 | `PingTest`、`TcpClient`、`TcpServer` | — | — |
+
+汇川、英威腾、台达、信捷客户端都继承自 Modbus，地址会按各自的规则自动换算成 Modbus 地址，因此同时具备 Modbus 的全部能力。
 
 ## 安装
 
@@ -18,12 +29,14 @@
 npm install ts-communication
 ```
 
-使用 Modbus RTU 或串口型客户端时，另外安装串口驱动：
+使用 `ModbusRtu`、`ModbusAscii` 或 `InovanceSerial` 等串口型客户端时，另外安装串口驱动：
 
 ```bash
 npm install serialport
 ```
 
+要求 Node.js 18 及以上版本。
+
 ## 快速开始
 
 ### Siemens S7
@@ -51,6 +64,8 @@ await plc.ConnectClose();
 
 常用 Siemens 地址：`M100`、`M10.2`、`I0.0`、`Q0.0`、`DB1.0`、`DB1.DBD100`、`V100`。
 
+`SiemensPLCS` 可选 `S1200`、`S1500`、`S300`、`S400`、`S200`、`S200Smart`。
+
 ### Melsec MC
 
 ```ts
@@ -67,6 +82,15 @@ await plc.WriteInt16('D100', 1234);
 await plc.ConnectClose();
 ```
 
+常用三菱地址：`M100`、`X10`、`Y10`、`D100`、`W100`、`R100`、`SM100`、`B100`、`ZR100`（`X`、`Y`、`B`、`W` 等按十六进制解析）。
+
+MC 协议支持随机读取，一次报文读取多个不连续地址：
+
+```ts
+const random = await plc.ReadRandomInt16(['D100', 'D200', 'W50']);
+if (random.IsSuccess) console.log(random.Content); // [v1, v2, v3]
+```
+
 ### Omron FINS
 
 ```ts
@@ -82,7 +106,9 @@ if (result.IsSuccess) console.log(result.Content);
 await plc.ConnectClose();
 ```
 
-### Inovance
+常用欧姆龙地址：`D100`、`CIO100`、`W100`、`H100`、`A100`、`E100`（`E`/`EM` 区按十六进制解析）、`TIM10`、`CNT10`，位地址形如 `CIO100.05`。
+
+### Inovance 汇川
 
 ```ts
 import { InovanceSeries, InovanceTcpNet } from 'ts-communication';
@@ -100,7 +126,85 @@ await plc.WriteInt32('MD0', 100);
 await plc.ConnectClose();
 ```
 
-常用汇川地址：`M0`、`MX0.0`、`MW0`、`MD0`、`MB0`、`QX0.0`、`IX0.0`。地址格式会根据 `Series` 自动转换为对应的 Modbus 地址。
+常用汇川地址：`M0`、`MX0.0`、`MW0`、`MD0`、`MB0`、`QX0.0`、`IX0.0`。地址格式会根据 `Series`（`AM`、`H3U`、`H5U`、`Easy`、`EVO`）自动转换为对应的 Modbus 地址。
+
+### Invt 英威腾 TS600
+
+```ts
+import { InvtModbusTcp } from 'ts-communication';
+
+const plc = new InvtModbusTcp('192.168.1.60', 502, 1);
+const connected = await plc.ConnectServer();
+if (!connected.IsSuccess) throw new Error(connected.Message);
+
+const result = await plc.ReadInt16('D100');
+if (result.IsSuccess) console.log(result.Content);
+
+await plc.WriteInt16('D100', 1234);
+await plc.ConnectClose();
+```
+
+常用英威腾地址：`M0`、`S0`、`X0`（八进制）、`Y0`（八进制）、`D0`、`R0`、`T0`、`C0`。
+
+### Delta 台达
+
+```ts
+import { DeltaSeries, DeltaTcpNet } from 'ts-communication';
+
+const plc = new DeltaTcpNet('192.168.1.70', 502, 1);
+plc.Series = DeltaSeries.Dvp; // 或 DeltaSeries.AS
+
+const connected = await plc.ConnectServer();
+if (!connected.IsSuccess) throw new Error(connected.Message);
+
+const result = await plc.ReadInt16('D100');
+if (result.IsSuccess) console.log(result.Content);
+
+await plc.WriteInt16('D100', 1234);
+await plc.ConnectClose();
+```
+
+常用台达地址：`M0`、`S0`、`X0`（八进制）、`Y0`（八进制）、`D0`、`T0`、`C0`。`Dvp` 适用于 DVP-ES/EX/EC/SS 与 DVP-SA/SC/SX/EH，`AS` 适用于 AS300。
+
+### GE SRTP
+
+```ts
+import { GeSRTPNet } from 'ts-communication';
+
+const plc = new GeSRTPNet('192.168.1.80', 18245);
+const connected = await plc.ConnectServer();
+if (!connected.IsSuccess) throw new Error(connected.Message);
+
+const result = await plc.ReadInt16('R100');
+if (result.IsSuccess) console.log(result.Content);
+
+const bit = await plc.ReadBool('M100');
+if (bit.IsSuccess) console.log(bit.Content);
+
+await plc.WriteInt16('R100', 1234);
+await plc.ConnectClose();
+```
+
+常用 GE 地址：`R1`、`AI1`、`AQ1`（仅字访问）、`I1`、`Q1`、`M1`、`T1`、`S1`、`G1`、`SA1`、`SB1`、`SC1`。GE 地址从 1 开始计数，有效范围 1–65536。
+
+### XinJE 信捷
+
+```ts
+import { XinJESeries, XinJETcpNet } from 'ts-communication';
+
+const plc = new XinJETcpNet('192.168.1.90', 502, XinJESeries.XD);
+
+const connected = await plc.ConnectServer();
+if (!connected.IsSuccess) throw new Error(connected.Message);
+
+const result = await plc.ReadInt16('D100');
+if (result.IsSuccess) console.log(result.Content);
+
+await plc.WriteInt16('D100', 1234);
+await plc.ConnectClose();
+```
+
+`XinJESeries` 可选 `XC`、`XD`、`XL`；位地址（`X`、`Y`）按八进制解析。
 
 ### Modbus TCP
 
@@ -118,7 +222,66 @@ await plc.WriteUInt16('100', 88);
 await plc.ConnectClose();
 ```
 
-Modbus 地址支持站号和功能码前缀，例如：`s=2;100`、`x=4;100`、`format=ABCD;100`。
+#### Modbus 地址前缀
+
+地址可以携带以下前缀，多个前缀可以组合使用：
+
+| 前缀 | 含义 | 示例 |
+| --- | --- | --- |
+| `s=` | 站号（覆盖客户端的 `Station`） | `s=2;100` |
+| `x=` | 读取功能码 | `x=4;100`（读输入寄存器） |
+| `w=` | 写入功能码 | `w=6;100` |
+| `format=` | 该次访问使用的字节序 | `format=ABCD;100` |
+
+支持的功能码：`1`、`2`、`3`、`4`、`5`、`6`、`15`、`16`、`22`。位地址可以写成 `100.3` 的形式（位序号 0–15）。
+
+#### 常用可调选项
+
+```ts
+plc.Station = 1;                  // 默认站号
+plc.AddressStartWithZero = true;  // 地址是否从 0 开始，false 时内部减 1
+plc.StationCheckMatch = true;     // 是否校验响应站号
+plc.DisableFunctionCode06 = false;// 单字写入是否禁用功能码 06（改用 16）
+plc.BroadcastStation = -1;        // 广播站号，命中时不等待响应
+```
+
+`ReadCoil`、`ReadDiscrete`、`WriteMask` 也可直接使用。
+
+### Modbus RTU / 串口客户端
+
+串口客户端不使用 `ConnectServer`，而是配置串口参数后调用 `Open()` / `Close()`：
+
+```ts
+import { ModbusRtu } from 'ts-communication';
+
+const plc = new ModbusRtu(1);
+plc.PortName = 'COM3';   // Linux 下形如 '/dev/ttyUSB0'
+plc.BaudRate = 9600;
+plc.DataBits = 8;
+plc.StopBits = 1;
+plc.Parity = 'none';
+
+const opened = await plc.Open();
+if (!opened.IsSuccess) throw new Error(opened.Message);
+
+const result = await plc.ReadInt16('100');
+if (result.IsSuccess) console.log(result.Content);
+
+await plc.Close();
+```
+
+汇川串口客户端用法相同，额外设置 `Series`：
+
+```ts
+import { InovanceSerial, InovanceSeries } from 'ts-communication';
+
+const plc = new InovanceSerial(1);
+plc.Series = InovanceSeries.H5U;
+plc.PortName = 'COM3';
+await plc.Open();
+```
+
+若串口设备通过串口服务器接入网络，改用 `ModbusRtuOverTcp` 或 `InovanceSerialOverTcp`，它们走 TCP，使用 `ConnectServer()` / `ConnectClose()`。
 
 ## C# 数值类型
 
@@ -145,6 +308,8 @@ await plc.ReadInt64('D110');
 await plc.WriteFloat('D104', 12.5);
 ```
 
+完整方法集：`ReadBool`、`ReadByte`、`ReadInt16`、`ReadUInt16`、`ReadInt32`、`ReadUInt32`、`ReadFloat`、`ReadDouble`、`ReadInt64`、`ReadUInt64`、`ReadString`、`Read`（原始字节），以及对应的 `Write*` 方法。`ReadInt64` / `ReadUInt64` 返回 `bigint`，写入时可传 `bigint` 或 `number`。
+
 当传入 `length` 时，读取方法返回数组；不传入时返回单个值。
 
 ## 统一结果处理
@@ -156,10 +321,40 @@ const result = await plc.ReadInt16('D100');
 if (result.IsSuccess) {
   console.log(result.Content);
 } else {
-  console.error(result.Message);
+  console.error(result.Message, result.ErrorCode);
 }
 ```
 
+`OperateResult` 字段：`IsSuccess`、`Content`、`Message`、`ErrorCode`。
+
+## 连接与超时
+
+```ts
+plc.ConnectTimeOut = 5000;  // 连接超时（毫秒）
+plc.ReceiveTimeOut = 5000;  // 接收超时（毫秒）
+plc.AutoReConnect = true;   // 请求时若连接已断开，自动重连
+```
+
+读写方法会在需要时自动建立连接，因此 `ConnectServer()` 主要用于提前确认设备可达。
+
+## 并发与通信锁
+
+客户端内置通信锁和请求队列，同一个实例上的并发读写会自动串行化，不会互相插入报文：
+
+```ts
+const [a, b, c] = await Promise.all([
+  plc.ReadInt16('D100'),
+  plc.ReadInt16('D200'),
+  plc.ReadFloat('D300'),
+]);
+```
+
+如果外部已经保证了串行访问，可以关闭锁以减少开销：
+
+```ts
+plc.EnableCommunicationLock = false;
+```
+
 ## 长任务与轮询
 
 库客户端可以在 Node.js Worker、Electron Worker 或其他后台线程中长期复用。建议保持一个客户端实例由一个工作线程独占，并在循环中复用连接：
@@ -176,7 +371,37 @@ while (running) {
 
 ## 字节序
 
-客户端公开 `ByteTransform` 和 `DataFormat`，可根据 PLC 配置选择 `ABCD`、`BADC`、`CDAB` 或 `DCBA`。不同协议有各自的默认字节序，数值异常时应先确认 PLC 的字节排列方式。
+客户端公开 `ByteTransform` 和 `DataFormat`，可根据 PLC 配置选择 `ABCD`、`BADC`、`CDAB` 或 `DCBA`：
+
+```ts
+import { DataFormat } from 'ts-communication';
+
+plc.ByteTransform.DataFormat = DataFormat.ABCD;
+plc.ByteTransform.IsStringReverseByteWord = false; // 字符串是否按字内交换字节
+```
+
+各协议的默认字节序见上面的协议表。数值读出来明显不对（例如浮点数变成极大值、32 位整数高低字反了）时，应先确认 PLC 侧的字节排列方式，再调整 `DataFormat`。Modbus 系客户端还可以只针对单次访问指定：`format=DCBA;100`。
+
+## 调试工具
+
+```ts
+import { PingTest, TcpClient, TcpServer } from 'ts-communication';
+
+// 连通性检查
+const ping = await PingTest.ping('192.168.1.10');
+console.log(ping.success, ping.time, ping.message);
+console.log(await PingTest.isHostOnline('192.168.1.10', 2000));
+
+// 手动收发报文
+const client = new TcpClient('192.168.1.10', 502);
+await client.connect();
+const response = await client.sendAndReceive(Buffer.from([0x00, 0x01]), 5000);
+
+// 本地模拟服务端
+const server = new TcpServer(5000, '0.0.0.0');
+await server.start();
+await server.stop();
+```
 
 ## TypeScript
 
@@ -186,11 +411,18 @@ while (running) {
 import { SiemensS7Net } from 'ts-communication';
 ```
 
+从源码构建：
+
+```bash
+npm run build
+```
+
 ## 注意事项
 
 - 使用真实设备前，请确认 PLC IP、端口、站号、机架/槽号以及访问权限。
-- Siemens S7-1200/S7-1500 通常使用 TCP `102` 端口，并需要允许 PUT/GET 访问。
+- Siemens S7-1200/S7-1500 通常使用 TCP `102` 端口，并需要在 PLC 组态中允许 PUT/GET 访问。
 - 串口协议需要操作系统具有对应串口权限，并正确配置波特率、数据位、停止位和校验位。
+- 一个客户端实例对应一条物理连接，不要在多个线程/进程之间共享同一个实例。
 - 所有示例都应检查 `IsSuccess` 后再读取 `Content`。
 
 ## License

package/dist/Invt/InvtModbusTcp.d.ts

@@ -0,0 +1,88 @@
+import { ModbusTcpNet } from '../modbus/ModbusTcpNet';
+import { OperateResult } from '../core/Core';
+/**
+ * 英威腾 TS600 系列 PLC 的 Modbus TCP 通讯类
+ * 支持通过 PLC 原生地址格式进行读写操作
+ */
+export declare class InvtModbusTcp extends ModbusTcpNet {
+    constructor(ipAddress?: string, port?: number, station?: number);
+    /**
+     * 将英威腾 PLC 地址转换为 Modbus 地址
+     * @param address 英威腾 PLC 地址，例如：M100、S100、X0、Y0、T100、C100、D100、R100
+     * @param modbusCode Modbus功能码
+     * @returns 转换后的Modbus地址
+     */
+    TranslateToModbusAddress(address: string, modbusCode: number): OperateResult<string>;
+    /**
+     * 读取寄存器数据
+     */
+    Read(address: string, length: number): Promise<any>;
+    /**
+     * 读取布尔类型数据
+     */
+    ReadBool(address: string, length?: number): Promise<any>;
+    /**
+     * 读取线圈
+     */
+    ReadCoil(address: string, length?: number): Promise<any>;
+    /**
+     * 写入数据
+     */
+    Write(address: string, value: any): Promise<any>;
+    /**
+     * 读取Int16类型数据
+     */
+    ReadInt16(address: string, length?: number): Promise<any>;
+    /**
+     * 读取UInt16类型数据
+     */
+    ReadUInt16(address: string, length?: number): Promise<any>;
+    /**
+     * 读取Int32类型数据
+     */
+    ReadInt32(address: string, length?: number): Promise<any>;
+    /**
+     * 读取UInt32类型数据
+     */
+    ReadUInt32(address: string, length?: number): Promise<any>;
+    /**
+     * 读取Float类型数据
+     */
+    ReadFloat(address: string, length?: number): Promise<any>;
+    /**
+     * 读取Double类型数据
+     */
+    ReadDouble(address: string, length?: number): Promise<any>;
+    /**
+     * 读取 64 位整数。父类的类型读取路径使用原始读取，避免已转换地址再次映射。
+     */
+    ReadInt64(address: string, length?: number): Promise<any>;
+    ReadUInt64(address: string, length?: number): Promise<any>;
+    ReadString(address: string, length: number, encoding?: BufferEncoding): Promise<any>;
+    /**
+     * 写入Int16类型数据
+     */
+    WriteInt16(address: string, value: number): Promise<any>;
+    /**
+     * 写入UInt16类型数据
+     */
+    WriteUInt16(address: string, value: number): Promise<any>;
+    /**
+     * 写入Int32类型数据
+     */
+    WriteInt32(address: string, value: number): Promise<any>;
+    /**
+     * 写入UInt32类型数据
+     */
+    WriteUInt32(address: string, value: number): Promise<any>;
+    /**
+     * 写入Float类型数据
+     */
+    WriteFloat(address: string, value: number): Promise<any>;
+    /**
+     * 写入Double类型数据
+     */
+    WriteDouble(address: string, value: number): Promise<any>;
+    WriteInt64(address: string, value: bigint | number): Promise<any>;
+    WriteUInt64(address: string, value: bigint | number): Promise<any>;
+}