@totemsdk/edge-modbus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @totemsdk/edge-modbus
+
+Edge runtime adapter for Modbus — PLCs, RTUs, industrial sensors over serial/TCP.
+
+## Install
+
+```bash
+npm install @totemsdk/edge-modbus
+```
+
+## Design
+
+This package does **not** import `modbus-serial`, `net`, or `serialport`. All network/serial behaviour is injected via `ModbusTransportPort`. You provide the transport; the package handles framing, polling, and proof generation.
+
+## Quick start
+
+```ts
+import { createEdgeRuntime, createEdgeDevice, createCapabilitySet } from '@totemsdk/edge';
+import { createModbusGateway, createModbusSensorBridge } from '@totemsdk/edge-modbus';
+import type { ModbusTransportPort } from '@totemsdk/edge-modbus';
+
+// 1. Implement ModbusTransportPort for your environment
+const transport: ModbusTransportPort = {
+  async connect() { /* open TCP socket or serial port */ },
+  async disconnect() { /* close */ },
+  async sendFrame(frame) { /* send raw Modbus frame, return response */ },
+  onFrame(handler) { /* register inbound frame handler */ return () => {}; },
+  onError(handler) { /* register error handler */ return () => {}; },
+};
+
+// 2. Wire into Edge runtime
+const runtime = createEdgeRuntime({
+  deviceId: 'plc-gateway-01',
+  capabilities: createCapabilitySet(['transport:modbus', 'proof:create']),
+  ports: { /* proof port from edge-adapters */ },
+});
+
+// 3. Create gateway
+const gateway = createModbusGateway({ runtime, transport });
+await gateway.start();
+
+// 4. Read registers
+const result = await gateway.readRegisters(1, 0, 10);
+console.log(result.data?.values); // [123, 456, ...]
+
+// 5. Or use the sensor bridge for automated polling + proof generation
+const bridge = createModbusSensorBridge({
+  runtime,
+  transport,
+  gateway,
+  bindings: [
+    { sensorId: 'temp-zone-1', unitId: 1, functionCode: 3, address: 0, count: 2, intervalMs: 5000, dataType: 'temperature', unit: '°C' },
+    { sensorId: 'pump-status', unitId: 2, functionCode: 1, address: 0, count: 1, intervalMs: 1000, dataType: 'coil' },
+  ],
+});
+await bridge.start();
+```
+
+## Transport port
+
+You must implement `ModbusTransportPort`:
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Open TCP socket (port 502) or serial port |
+| `disconnect()` | Close the connection |
+| `sendFrame(frame)` | Send raw Modbus frame bytes, return response bytes |
+| `onFrame(handler)` | Register handler for unsolicited/inbound frames |
+| `onError(handler)` | Register handler for connection errors |
+
+## Supported function codes
+
+| Code | Name | Gateway method |
+|------|------|---------------|
+| 1 | Read Coils | `readCoils(unitId, address, count)` |
+| 3 | Read Holding Registers | `readRegisters(unitId, address, count)` |
+| 4 | Read Input Registers | Via sensor bridge |
+
+## Capabilities
+
+- `transport:modbus` — required for Modbus transport
+
+## License
+
+MIT

package/dist/gateway.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Modbus Edge Gateway — wires a ModbusTransportPort into an EdgeRuntime.
+ */
+import type { EdgeRuntime, EdgeOperationResult } from '@totemsdk/edge';
+import type { ModbusTransportPort } from './transport.js';
+export interface ModbusGatewayConfig {
+    runtime: EdgeRuntime;
+    transport: ModbusTransportPort;
+    /** Map unit IDs to sensor/device identifiers. */
+    unitMap?: Record<number, string>;
+}
+export interface ModbusGateway {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly status: 'stopped' | 'running' | 'error';
+    /** Read coils (function code 1). */
+    readCoils(unitId: number, address: number, count: number): Promise<EdgeOperationResult<{
+        values: boolean[];
+    }>>;
+    /** Read holding registers (function code 3). */
+    readRegisters(unitId: number, address: number, count: number): Promise<EdgeOperationResult<{
+        values: number[];
+    }>>;
+}
+export declare function createModbusGateway(config: ModbusGatewayConfig): ModbusGateway;

package/dist/gateway.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Modbus Edge Gateway — wires a ModbusTransportPort into an EdgeRuntime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModbusGateway = createModbusGateway;
+function createModbusGateway(config) {
+    let status = 'stopped';
+    let unsubFrame;
+    let unsubError;
+    return {
+        get status() { return status; },
+        async start() {
+            if (status === 'running')
+                return;
+            await config.transport.connect();
+            unsubFrame = config.transport.onFrame((frame) => {
+                // Frames are dispatched by the sensor bridge
+            });
+            unsubError = config.transport.onError(() => {
+                status = 'error';
+            });
+            status = 'running';
+        },
+        async stop() {
+            unsubFrame?.();
+            unsubError?.();
+            await config.transport.disconnect();
+            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) };
+            }
+        },
+        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) };
+            }
+        },
+    };
+}
+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) {
+    const values = [];
+    for (let i = 0; i < count; i++) {
+        const byte = response[9 + Math.floor(i / 8)] ?? 0;
+        values.push(((byte >> (i % 8)) & 1) === 1);
+    }
+    return values;
+}
+function parseRegisterResponse(response, count) {
+    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));
+    }
+    return values;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ModbusTransportPort, ModbusMessage } from './transport.js';
+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';

package/dist/index.js

@@ -0,0 +1,7 @@
+"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; } });

package/dist/sensor-bridge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Modbus Sensor Bridge — maps Modbus register reads to Edge proof inputs.
+ */
+import type { EdgeRuntime } from '@totemsdk/edge';
+import type { ModbusTransportPort } from './transport.js';
+import type { ModbusGateway } from './gateway.js';
+export interface ModbusSensorBinding {
+    sensorId: string;
+    unitId: number;
+    functionCode: number;
+    address: number;
+    count: number;
+    intervalMs: number;
+    dataType: 'coil' | 'register' | 'input';
+    unit?: string;
+}
+export interface ModbusSensorBridgeConfig {
+    runtime: EdgeRuntime;
+    transport: ModbusTransportPort;
+    gateway?: ModbusGateway;
+    bindings: ModbusSensorBinding[];
+}
+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

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Modbus Sensor Bridge — maps Modbus register reads to Edge proof inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createModbusSensorBridge = createModbusSensorBridge;
+function createModbusSensorBridge(config) {
+    const timers = [];
+    let running = false;
+    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);
+            }
+            if (config.runtime.ports.proof) {
+                await config.runtime.ports.proof.createProof({
+                    subject: `sensor:${binding.sensorId}`,
+                    claims: [{
+                            sensorId: binding.sensorId,
+                            unitId: binding.unitId,
+                            address: binding.address,
+                            values,
+                            unit: binding.unit,
+                            timestamp: Date.now(),
+                        }],
+                });
+            }
+        }
+        catch {
+            // Poll failures are non-fatal — next cycle retries
+        }
+    }
+    return {
+        async start() {
+            if (running)
+                return;
+            for (const binding of config.bindings) {
+                await pollBinding(binding);
+                timers.push(setInterval(() => pollBinding(binding), binding.intervalMs));
+            }
+            running = true;
+        },
+        async stop() {
+            for (const t of timers)
+                clearInterval(t);
+            timers.length = 0;
+            running = false;
+        },
+        async poll() {
+            for (const binding of config.bindings) {
+                await pollBinding(binding);
+            }
+        },
+    };
+}
+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

@@ -0,0 +1,32 @@
+/**
+ * Modbus transport port — injected by the caller.
+ *
+ * Supports Modbus TCP (port 502) and Modbus RTU (serial).
+ * The caller provides the actual socket/serial implementation.
+ */
+export interface ModbusTransportPort {
+    /** Open the connection. */
+    connect(): Promise<void>;
+    /** Close the connection. */
+    disconnect(): Promise<void>;
+    /** Send a raw Modbus frame and receive the response. */
+    sendFrame(frame: Uint8Array): Promise<Uint8Array>;
+    /** Register a handler for unsolicited/inbound frames. */
+    onFrame(handler: (frame: Uint8Array) => void): () => void;
+    /** Register a handler for connection errors. */
+    onError(handler: (err: Error) => void): () => void;
+}
+export interface ModbusMessage {
+    /** Unit/slave ID (1-247). */
+    unitId: number;
+    /** Modbus function code (1-6, 15, 16). */
+    functionCode: number;
+    /** Starting address (0-based). */
+    address: number;
+    /** Register/coil count or value. */
+    value: number | number[];
+    /** Raw frame bytes. */
+    raw: Uint8Array;
+    /** Timestamp of receipt. */
+    receivedAt: number;
+}

package/dist/transport.js

@@ -0,0 +1,8 @@
+"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 });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@totemsdk/edge-modbus",
+  "version": "0.1.0",
+  "description": "Edge runtime adapter for Modbus — PLCs, RTUs, industrial sensors over serial/TCP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "dependencies": {
+    "@totemsdk/edge": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT",
+  "author": "Totem SDK",
+  "homepage": "https://totem.ing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "directory": "packages/totem-sdk/packages/edge-modbus"
+  },
+  "keywords": ["totem", "totemsdk", "minima", "blockchain", "edge", "modbus", "transport"],
+  "bugs": { "url": "https://github.com/totem-sdk/totem-sdk/issues" }
+}