@totemsdk/edge-modbus 0.1.0 → 0.2.2

package/dist/gateway.js

@@ -1,10 +1,10 @@
-"use strict";
 /**
  * Modbus Edge Gateway — wires a ModbusTransportPort into an EdgeRuntime.
+ *
+ * Uses a unit-prefixed PDU (no CRC or MBAP header) at the transport boundary.
+ * The binding owns TCP transaction framing or RTU CRC validation.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createModbusGateway = createModbusGateway;
-function createModbusGateway(config) {
+export function createModbusGateway(config) {
     let status = 'stopped';
     let unsubFrame;
     let unsubError;
@@ -14,8 +14,8 @@ function createModbusGateway(config) {
             if (status === 'running')
                 return;
             await config.transport.connect();
-            unsubFrame = config.transport.onFrame((frame) => {
-                // Frames are dispatched by the sensor bridge
+            unsubFrame = config.transport.onFrame((_frame) => {
+                // Unsolicited frames are not expected in Modbus request/response model
             });
             unsubError = config.transport.onError(() => {
                 status = 'error';
@@ -29,62 +29,204 @@ function createModbusGateway(config) {
             status = 'stopped';
         },
         async readCoils(unitId, address, count) {
-            try {
-                const request = buildModbusFrame(unitId, 1, address, count);
-                const response = await config.transport.sendFrame(request);
-                const values = parseCoilResponse(response, count);
-                return { ok: true, data: { values } };
-            }
-            catch (e) {
-                return { ok: false, error: String(e) };
-            }
+            return readBits(config.transport, unitId, 1, address, count);
         },
-        async readRegisters(unitId, address, count) {
-            try {
-                const request = buildModbusFrame(unitId, 3, address, count);
-                const response = await config.transport.sendFrame(request);
-                const values = parseRegisterResponse(response, count);
-                return { ok: true, data: { values } };
-            }
-            catch (e) {
-                return { ok: false, error: String(e) };
-            }
+        async readDiscreteInputs(unitId, address, count) {
+            return readBits(config.transport, unitId, 2, address, count);
+        },
+        async readHoldingRegisters(unitId, address, count) {
+            return readRegisters(config.transport, unitId, 3, address, count);
+        },
+        async readInputRegisters(unitId, address, count) {
+            return readRegisters(config.transport, unitId, 4, address, count);
+        },
+        async writeSingleCoil(unitId, address, value) {
+            if (typeof value !== 'boolean')
+                return { ok: false, error: 'Coil value must be boolean', errorCode: 'MODBUS_INVALID_REQUEST' };
+            return writeSingle(config.transport, unitId, 5, address, value ? 0xFF00 : 0x0000);
+        },
+        async writeSingleRegister(unitId, address, value) {
+            return writeSingle(config.transport, unitId, 6, address, value);
+        },
+        async writeMultipleCoils(unitId, address, values) {
+            return writeMultipleCoilsImpl(config.transport, unitId, address, values);
+        },
+        async writeMultipleRegisters(unitId, address, values) {
+            return writeMultipleRegistersImpl(config.transport, unitId, address, values);
         },
     };
 }
-function buildModbusFrame(unitId, functionCode, address, count) {
-    const buf = new Uint8Array(8);
-    buf[0] = 0;
-    buf[1] = 0; // transaction ID
-    buf[2] = 0;
-    buf[3] = 0; // protocol ID
-    buf[4] = 0;
-    buf[5] = 2; // length
-    buf[6] = unitId;
-    buf[7] = functionCode;
-    const addr = new Uint8Array(2);
-    new DataView(addr.buffer).setUint16(0, address, false);
-    const cnt = new Uint8Array(2);
-    new DataView(cnt.buffer).setUint16(0, count, false);
-    const result = new Uint8Array(8 + 4);
-    result.set(buf);
-    result.set(addr, 8);
-    result.set(cnt, 10);
-    return result;
-}
-function parseCoilResponse(response, count) {
+// ── Unit-prefixed PDU builders (no CRC or MBAP header) ───────────────────
+class ModbusRequestError extends Error {
+}
+class ModbusExceptionError extends Error {
+}
+function validateRange(unitId, address, count, maximum) {
+    if (!Number.isInteger(unitId) || unitId < 1 || unitId > 247 ||
+        !Number.isInteger(address) || address < 0 || address > 0xffff ||
+        !Number.isInteger(count) || count < 1 || count > maximum || address + count > 0x10000) {
+        throw new ModbusRequestError('Invalid Modbus unit, address or quantity');
+    }
+}
+function validateRegister(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new ModbusRequestError('Register value must be an unsigned 16-bit integer');
+    }
+}
+function buildReadFrame(unitId, fc, address, count) {
+    validateRange(unitId, address, count, fc <= 2 ? 2000 : 125);
+    const buf = new Uint8Array(6);
+    buf[0] = unitId;
+    buf[1] = fc;
+    new DataView(buf.buffer).setUint16(2, address, false);
+    new DataView(buf.buffer).setUint16(4, count, false);
+    return buf;
+}
+function buildWriteSingleFrame(unitId, fc, address, value) {
+    validateRange(unitId, address, 1, 1);
+    validateRegister(value);
+    const buf = new Uint8Array(6);
+    buf[0] = unitId;
+    buf[1] = fc;
+    new DataView(buf.buffer).setUint16(2, address, false);
+    new DataView(buf.buffer).setUint16(4, value, false);
+    return buf;
+}
+function buildWriteMultipleCoilsFrame(unitId, address, values) {
+    validateRange(unitId, address, values.length, 1968);
+    for (const value of values) {
+        if (typeof value !== 'boolean')
+            throw new ModbusRequestError('Coil values must be boolean');
+    }
+    const byteCount = Math.ceil(values.length / 8);
+    const buf = new Uint8Array(7 + byteCount);
+    buf[0] = unitId;
+    buf[1] = 15; // FC 15
+    new DataView(buf.buffer).setUint16(2, address, false);
+    new DataView(buf.buffer).setUint16(4, values.length, false);
+    buf[6] = byteCount;
+    for (let i = 0; i < values.length; i++) {
+        if (values[i]) {
+            buf[7 + Math.floor(i / 8)] |= (1 << (i % 8));
+        }
+    }
+    return buf;
+}
+function buildWriteMultipleRegistersFrame(unitId, address, values) {
+    validateRange(unitId, address, values.length, 123);
+    for (const value of values)
+        validateRegister(value);
+    const byteCount = values.length * 2;
+    const buf = new Uint8Array(7 + byteCount);
+    buf[0] = unitId;
+    buf[1] = 16; // FC 16
+    new DataView(buf.buffer).setUint16(2, address, false);
+    new DataView(buf.buffer).setUint16(4, values.length, false);
+    buf[6] = byteCount;
+    for (let i = 0; i < values.length; i++) {
+        new DataView(buf.buffer).setUint16(7 + i * 2, values[i], false);
+    }
+    return buf;
+}
+// ── Response parsers (RTU format — no MBAP header) ────────────────────────
+function checkResponse(response, unitId, expectedFunction) {
+    if (response.length < 2 || response[0] !== unitId)
+        throw new Error('Modbus response unit/length mismatch');
+    const fc = response[1];
+    if (fc === (expectedFunction | 0x80)) {
+        if (response.length !== 3 || response[2] === 0)
+            throw new Error('Malformed Modbus exception response');
+        throw new ModbusExceptionError(`Modbus exception: function=${expectedFunction} code=${response[2]}`);
+    }
+    if (fc !== expectedFunction)
+        throw new Error('Modbus response function mismatch');
+}
+function checkReadLength(response, byteCount) {
+    if (response.length !== 3 + byteCount || response[2] !== byteCount) {
+        throw new Error('Modbus response byte count/length mismatch');
+    }
+}
+function checkWriteResponse(response, request) {
+    checkResponse(response, request[0], request[1]);
+    if (response.length !== 6 || response.some((byte, index) => byte !== request[index])) {
+        throw new Error('Modbus write acknowledgement mismatch');
+    }
+}
+function writeFailure(error) {
+    return { ok: false, error: String(error), errorCode: error instanceof ModbusRequestError
+            ? 'MODBUS_INVALID_REQUEST' : error instanceof ModbusExceptionError
+            ? 'MODBUS_EXCEPTION' : 'MODBUS_WRITE_OUTCOME_UNKNOWN' };
+}
+function parseBitResponse(response, count) {
+    checkReadLength(response, Math.ceil(count / 8));
     const values = [];
     for (let i = 0; i < count; i++) {
-        const byte = response[9 + Math.floor(i / 8)] ?? 0;
+        const byte = response[3 + Math.floor(i / 8)];
         values.push(((byte >> (i % 8)) & 1) === 1);
     }
     return values;
 }
 function parseRegisterResponse(response, count) {
+    checkReadLength(response, count * 2);
     const values = [];
     for (let i = 0; i < count; i++) {
-        const offset = 9 + i * 2;
-        values.push(new DataView(response.buffer, response.byteOffset + offset, 2).getUint16(0, false));
+        values.push(new DataView(response.buffer, response.byteOffset + 3 + i * 2, 2).getUint16(0, false));
     }
     return values;
 }
+// ── Operation implementations ─────────────────────────────────────────────
+async function readBits(transport, unitId, fc, address, count) {
+    try {
+        const request = buildReadFrame(unitId, fc, address, count);
+        const response = await transport.sendFrame(request);
+        checkResponse(response, unitId, fc);
+        return { ok: true, data: { values: parseBitResponse(response, count) } };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+}
+async function readRegisters(transport, unitId, fc, address, count) {
+    try {
+        const request = buildReadFrame(unitId, fc, address, count);
+        const response = await transport.sendFrame(request);
+        checkResponse(response, unitId, fc);
+        return { ok: true, data: { values: parseRegisterResponse(response, count) } };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+}
+async function writeSingle(transport, unitId, fc, address, value) {
+    try {
+        const request = buildWriteSingleFrame(unitId, fc, address, value);
+        const response = await transport.sendFrame(request);
+        checkWriteResponse(response, request);
+        return { ok: true };
+    }
+    catch (e) {
+        return writeFailure(e);
+    }
+}
+async function writeMultipleCoilsImpl(transport, unitId, address, values) {
+    try {
+        const request = buildWriteMultipleCoilsFrame(unitId, address, values);
+        const response = await transport.sendFrame(request);
+        checkWriteResponse(response, request);
+        return { ok: true };
+    }
+    catch (e) {
+        return writeFailure(e);
+    }
+}
+async function writeMultipleRegistersImpl(transport, unitId, address, values) {
+    try {
+        const request = buildWriteMultipleRegistersFrame(unitId, address, values);
+        const response = await transport.sendFrame(request);
+        checkWriteResponse(response, request);
+        return { ok: true };
+    }
+    catch (e) {
+        return writeFailure(e);
+    }
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { createModbusGateway } from './gateway.js';
 export type { ModbusGatewayConfig, ModbusGateway } from './gateway.js';
 export { createModbusSensorBridge } from './sensor-bridge.js';
 export type { ModbusSensorBinding, ModbusSensorBridgeConfig, ModbusSensorBridge } from './sensor-bridge.js';
+export { NativeModbusTransport } from './native-transport.js';
+export type { NativeModbusConfig } from './native-transport.js';

package/dist/index.js

@@ -1,7 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createModbusSensorBridge = exports.createModbusGateway = void 0;
-var gateway_js_1 = require("./gateway.js");
-Object.defineProperty(exports, "createModbusGateway", { enumerable: true, get: function () { return gateway_js_1.createModbusGateway; } });
-var sensor_bridge_js_1 = require("./sensor-bridge.js");
-Object.defineProperty(exports, "createModbusSensorBridge", { enumerable: true, get: function () { return sensor_bridge_js_1.createModbusSensorBridge; } });
+export { createModbusGateway } from './gateway.js';
+export { createModbusSensorBridge } from './sensor-bridge.js';
+export { NativeModbusTransport } from './native-transport.js';

package/dist/native-transport.d.ts

@@ -0,0 +1,36 @@
+/**
+ * NativeModbusTransport — connects to the edge-modbus Go binary over TCP.
+ *
+ * The Go binary listens on a local TCP socket (default 127.0.0.1:15002)
+ * and accepts newline-delimited JSON requests. This class implements
+ * ModbusTransportPort by forwarding all calls to the Go process.
+ *
+ * Usage:
+ *   const transport = new NativeModbusTransport({ host: '127.0.0.1', port: 15002 });
+ *   await transport.connect();
+ *   const response = await transport.sendFrame(requestFrame);
+ *   transport.disconnect();
+ */
+import type { ModbusTransportPort } from './transport.js';
+export interface NativeModbusConfig {
+    host?: string;
+    port?: number;
+    /** Connection timeout in ms. Default 5000. */
+    connectTimeoutMs?: number;
+    /** Per-request timeout in ms. Default 10000. */
+    requestTimeoutMs?: number;
+}
+export declare class NativeModbusTransport implements ModbusTransportPort {
+    private socket;
+    private buffer;
+    private pending;
+    private frameHandlers;
+    private errorHandlers;
+    private readonly config;
+    constructor(config?: NativeModbusConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    sendFrame(frame: Uint8Array): Promise<Uint8Array>;
+    onFrame(handler: (frame: Uint8Array) => void): () => void;
+    onError(handler: (err: Error) => void): () => void;
+}

package/dist/native-transport.js

@@ -0,0 +1,129 @@
+/**
+ * NativeModbusTransport — connects to the edge-modbus Go binary over TCP.
+ *
+ * The Go binary listens on a local TCP socket (default 127.0.0.1:15002)
+ * and accepts newline-delimited JSON requests. This class implements
+ * ModbusTransportPort by forwarding all calls to the Go process.
+ *
+ * Usage:
+ *   const transport = new NativeModbusTransport({ host: '127.0.0.1', port: 15002 });
+ *   await transport.connect();
+ *   const response = await transport.sendFrame(requestFrame);
+ *   transport.disconnect();
+ */
+let requestCounter = 0;
+export class NativeModbusTransport {
+    constructor(config = {}) {
+        this.socket = null;
+        this.buffer = '';
+        this.pending = new Map();
+        this.frameHandlers = [];
+        this.errorHandlers = [];
+        this.config = {
+            host: config.host ?? '127.0.0.1',
+            port: config.port ?? 15002,
+            connectTimeoutMs: config.connectTimeoutMs ?? 5000,
+            requestTimeoutMs: config.requestTimeoutMs ?? 10000,
+        };
+    }
+    async connect() {
+        const net = await import('net');
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.socket?.destroy();
+                reject(new Error(`NativeModbusTransport: connect timeout (${this.config.connectTimeoutMs}ms)`));
+            }, this.config.connectTimeoutMs);
+            this.socket = net.createConnection({ host: this.config.host, port: this.config.port }, () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.socket.on('data', (chunk) => {
+                this.buffer += chunk.toString('utf-8');
+                const lines = this.buffer.split('\n');
+                this.buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg.id && this.pending.has(msg.id)) {
+                            const { resolve: res, reject: rej } = this.pending.get(msg.id);
+                            this.pending.delete(msg.id);
+                            if (msg.ok && msg.frame) {
+                                res(hexToBytes(msg.frame));
+                            }
+                            else {
+                                rej(new Error(msg.error ?? 'unknown error'));
+                            }
+                        }
+                    }
+                    catch {
+                        // ignore parse errors on partial lines
+                    }
+                }
+            });
+            this.socket.on('error', (err) => {
+                for (const handler of this.errorHandlers) {
+                    try {
+                        handler(err);
+                    }
+                    catch { }
+                }
+            });
+            this.socket.on('close', () => {
+                for (const [, pending] of this.pending) {
+                    pending.reject(new Error('NativeModbusTransport: connection closed'));
+                }
+                this.pending.clear();
+            });
+        });
+    }
+    async disconnect() {
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+    }
+    async sendFrame(frame) {
+        if (!this.socket) {
+            throw new Error('NativeModbusTransport: not connected');
+        }
+        const id = `modbus-${++requestCounter}`;
+        const request = { id, frame: bytesToHex(frame) };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`NativeModbusTransport: request ${id} timed out (${this.config.requestTimeoutMs}ms)`));
+            }, this.config.requestTimeoutMs);
+            this.pending.set(id, {
+                resolve: (data) => { clearTimeout(timer); resolve(data); },
+                reject: (err) => { clearTimeout(timer); reject(err); },
+            });
+            this.socket.write(JSON.stringify(request) + '\n');
+        });
+    }
+    onFrame(handler) {
+        this.frameHandlers.push(handler);
+        return () => {
+            this.frameHandlers = this.frameHandlers.filter(h => h !== handler);
+        };
+    }
+    onError(handler) {
+        this.errorHandlers.push(handler);
+        return () => {
+            this.errorHandlers = this.errorHandlers.filter(h => h !== handler);
+        };
+    }
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error('Invalid hex string');
+    const arr = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < arr.length; i++) {
+        arr[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return arr;
+}

package/dist/sensor-bridge.d.ts

@@ -1,5 +1,7 @@
 /**
  * Modbus Sensor Bridge — maps Modbus register reads to Edge proof inputs.
+ *
+ * Shares gateway validation so malformed responses never become sensor proofs.
  */
 import type { EdgeRuntime } from '@totemsdk/edge';
 import type { ModbusTransportPort } from './transport.js';
@@ -23,7 +25,6 @@ export interface ModbusSensorBridgeConfig {
 export interface ModbusSensorBridge {
     start(): Promise<void>;
     stop(): Promise<void>;
-    /** Force a single poll cycle. */
     poll(): Promise<void>;
 }
 export declare function createModbusSensorBridge(config: ModbusSensorBridgeConfig): ModbusSensorBridge;

package/dist/sensor-bridge.js

@@ -1,25 +1,23 @@
-"use strict";
 /**
  * Modbus Sensor Bridge — maps Modbus register reads to Edge proof inputs.
+ *
+ * Shares gateway validation so malformed responses never become sensor proofs.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createModbusSensorBridge = createModbusSensorBridge;
-function createModbusSensorBridge(config) {
+import { createModbusGateway } from './gateway.js';
+export function createModbusSensorBridge(config) {
     const timers = [];
     let running = false;
+    const gateway = config.gateway ?? createModbusGateway({ runtime: config.runtime, transport: config.transport });
     async function pollBinding(binding) {
         try {
-            let values;
-            if (binding.functionCode === 1) {
-                const frame = buildReadFrame(binding.unitId, 1, binding.address, binding.count);
-                const response = await config.transport.sendFrame(frame);
-                values = parseCoils(response, binding.count);
-            }
-            else if (binding.functionCode === 3 || binding.functionCode === 4) {
-                const frame = buildReadFrame(binding.unitId, binding.functionCode, binding.address, binding.count);
-                const response = await config.transport.sendFrame(frame);
-                values = parseRegisters(response, binding.count);
-            }
+            const args = [binding.unitId, binding.address, binding.count];
+            const result = binding.functionCode === 1 ? await gateway.readCoils(...args)
+                : binding.functionCode === 2 ? await gateway.readDiscreteInputs(...args)
+                    : binding.functionCode === 3 ? await gateway.readHoldingRegisters(...args)
+                        : binding.functionCode === 4 ? await gateway.readInputRegisters(...args) : undefined;
+            if (!result?.ok || !result.data)
+                return;
+            const values = result.data.values;
             if (config.runtime.ports.proof) {
                 await config.runtime.ports.proof.createProof({
                     subject: `sensor:${binding.sensorId}`,
@@ -61,28 +59,3 @@ function createModbusSensorBridge(config) {
         },
     };
 }
-function buildReadFrame(unitId, fc, address, count) {
-    const buf = new Uint8Array(12);
-    new DataView(buf.buffer).setUint16(0, 1, false); // transaction ID
-    new DataView(buf.buffer).setUint16(4, 6, false); // length
-    buf[6] = unitId;
-    buf[7] = fc;
-    new DataView(buf.buffer).setUint16(8, address, false);
-    new DataView(buf.buffer).setUint16(10, count, false);
-    return buf;
-}
-function parseCoils(response, count) {
-    const result = [];
-    for (let i = 0; i < count; i++) {
-        const byte = response[9 + Math.floor(i / 8)] ?? 0;
-        result.push(((byte >> (i % 8)) & 1) === 1);
-    }
-    return result;
-}
-function parseRegisters(response, count) {
-    const result = [];
-    for (let i = 0; i < count; i++) {
-        result.push(new DataView(response.buffer, response.byteOffset + 9 + i * 2, 2).getUint16(0, false));
-    }
-    return result;
-}

package/dist/transport.d.ts

@@ -9,7 +9,13 @@ export interface ModbusTransportPort {
     connect(): Promise<void>;
     /** Close the connection. */
     disconnect(): Promise<void>;
-    /** Send a raw Modbus frame and receive the response. */
+    /**
+     * Exchange [unitId, functionCode, ...PDU data], with no CRC or MBAP header.
+     * Reads return [unitId, functionCode, byteCount, ...data]; successful writes
+     * return [unitId, functionCode, addressHi, addressLo, valueOrCountHi, valueOrCountLo].
+     * The binding must validate wire CRC/MBAP transaction identity and must not
+     * retry writes automatically when the physical outcome is uncertain.
+     */
     sendFrame(frame: Uint8Array): Promise<Uint8Array>;
     /** Register a handler for unsolicited/inbound frames. */
     onFrame(handler: (frame: Uint8Array) => void): () => void;

package/dist/transport.js

@@ -1,8 +1,7 @@
-"use strict";
 /**
  * Modbus transport port — injected by the caller.
  *
  * Supports Modbus TCP (port 502) and Modbus RTU (serial).
  * The caller provides the actual socket/serial implementation.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};