node-red-modbus-dynamic-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **modbus-source-router** node — routes incoming Modbus requests to different
+  flow outputs based on the client's source IPv4 address.  Rules are expressed
+  as CIDR blocks (`192.168.1.0/24`, `10.0.0.0/8`, `0.0.0.0/0`, …) and
+  evaluated top-to-bottom; the first matching rule wins.  When no rule matches,
+  the node sends a configurable Modbus exception response directly back to the
+  client via the server config node and emits nothing on any output.
+  IPv6-mapped IPv4 addresses (e.g. `::ffff:192.168.1.1`) are automatically
+  normalised before evaluation.
+
+## [0.1.0] — 2025-01-01
+
+### Added
+- Initial release.
+- **modbus-dynamic-server-config** — Modbus TCP server configuration node with
+  per-connection in-order response delivery and pending-request timeout.
+- **modbus-dynamic-server** — emits incoming Modbus requests into a Node-RED
+  flow as structured message objects.
+- **modbus-dynamic-server-response** — sends a dynamic payload back to a
+  waiting Modbus client.
+- **modbus-registers-config** — in-memory register map supporting holding,
+  input, coil, and discrete register types with multi-word encoding (int16,
+  uint16, int32, uint32, float32) and configurable word-order modes
+  (ABCD/CDAB/BADC/DCBA).
+- **modbus-registers-write** — writes a single value into a register map.
+- **modbus-registers-respond** — reads register values and responds to a
+  pending Modbus request in one step.
+- **modbus-proxy-target** — configuration node that maintains a persistent
+  Modbus TCP client connection used by proxy flows.
+- **modbus-dynamic-proxy** — forwards a pending Modbus request to a proxy
+  target and returns the response to the originating client.
+

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Christopher Piggott
+
+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,180 @@
+# node-red-modbus-dynamic-server
+
+### Advanced Modbus server nodes for Node-RED
+
+This package provides a set of Node-RED nodes for building flexible, general-purpose Modbus servers.
+
+Unlike the server functionality in `node-red-contrib-modbus`, these nodes allow incoming Modbus requests to be intercepted before a response is sent. This makes it possible to examine, modify, filter, forward, or fulfill requests dynamically in a flow.
+
+That enables use cases such as Modbus proxies, gateways, protocol conversion, request filtering, and other advanced server-side behaviors that are difficult or impossible with a conventional static register map.
+
+---
+
+## Included Nodes
+
+This package contains the following nodes:
+
+### Runtime nodes
+
+#### Core request/response
+
+- **modbus-dynamic-server**  
+  Receives incoming Modbus requests from the server and emits them into a flow for dynamic handling.
+
+- **modbus-dynamic-server-response**  
+  Sends a dynamic response back to the waiting Modbus client request.
+
+#### Routing and control
+
+- **modbus-source-router**  
+  Routes incoming Modbus requests to different flow outputs based on the client's source IP address.  
+  Rules are expressed as IPv4 CIDR blocks and evaluated top-to-bottom; the first matching rule wins.  
+  If no rule matches, a configurable Modbus exception response is sent and the message is not emitted.
+
+- **modbus-fc-filter**  
+  Allows or blocks requests by Modbus function code (`payload.fc`).  
+  Allowed requests continue unchanged; blocked requests are terminated with a configurable Modbus exception.
+
+- **modbus-server-exception**  
+  Convenience terminator node for custom reject paths.  
+  Sends a Modbus exception response for the current pending request and emits no output.
+
+#### Data handling
+
+- **modbus-registers-read**  
+  Reads and decodes values from the shared register map and emits them as a normal flow message.
+
+- **modbus-registers-write**  
+  Writes values into a local register store.
+
+- **modbus-registers-respond**  
+  Responds to Modbus requests using values from the local register store.
+
+#### Integration / proxy
+
+- **modbus-dynamic-proxy**  
+  Forwards requests dynamically to another Modbus target and returns the result.
+
+### Configuration nodes
+
+- **modbus-dynamic-server-config**  
+  Configures and owns the Modbus TCP server instance.
+
+- **modbus-registers-config**  
+  Defines local register storage used by register-based nodes.
+
+- **modbus-proxy-target**  
+  Defines a downstream Modbus target used for proxying or forwarding requests.
+
+---
+
+## How the pieces fit together
+
+A typical dynamic flow looks like this:
+
+1. A Modbus client sends a request to the configured server.
+2. `modbus-dynamic-server` emits a friendly request object into the flow.
+3. *(Optional)* `modbus-source-router` filters or routes the request based on the client's IP address.
+4. The flow decides what to do with the request:
+    - answer from local registers
+    - generate a value dynamically
+    - forward to another Modbus device
+    - reject or filter the request
+5. `modbus-dynamic-server-response` sends the final response back to the client.
+
+This separation makes it possible to implement dynamic server-side logic entirely in Node-RED flows.
+
+---
+
+## Message Contract
+
+Messages emitted by `modbus-dynamic-server` include internal request context in `msg._modbus`.
+
+This context is required by downstream nodes such as:
+
+- `modbus-dynamic-server-response`
+- `modbus-source-router`
+- `modbus-fc-filter`
+- `modbus-server-exception`
+- `modbus-dynamic-proxy`
+- `modbus-registers-respond`
+
+These nodes use `msg._modbus` to send a response back to the original Modbus client request.
+
+Flows must preserve this property. This is especially important when you use other nodes, including
+`function` nodes or custom nodes, to inspect requests, apply custom logic, transform payloads,
+or generate custom responses.
+
+
+Preferred:
+
+```js
+msg.payload = newValue;
+return msg;
+```
+
+Also valid (safe alternative):
+
+```js
+msg = { ...msg, payload: newValue }
+return msg
+```
+
+Not allowed:
+
+```js
+msg = { payload: newValue };
+return msg;
+```
+
+If msg._modbus is missing, downstream response/termination nodes will be unable to complete the original Modbus request and will raise an error.
+
+In general, modify the existing msg object rather than replacing it entirely.
+
+
+
+---
+
+## Use Cases
+
+### Protocol Conversion
+
+Requests can be intercepted, decoded, and translated into requests for another protocol. This is useful for protocol mediation and conversion involving systems such as OPC UA, BACnet, MQTT, Sparkplug, or custom APIs.
+
+### Modbus Gateway
+
+These nodes can be used to build a Modbus server that answers some requests from a local register cache while forwarding other requests to external devices, including Modbus TCP or Modbus serial targets.
+
+This makes it possible to build gateways, aggregators, and hybrid local/remote data services.
+
+### Security, Data Diode, and Request Filtering
+
+These nodes can also be used to build a Modbus TCP gateway that inspects requests and applies filtering rules before allowing them to proceed.
+
+For example, requests can be filtered based on client IP address, function code, unit ID, register address, or other request attributes. This makes it possible to implement read-only gateways, request whitelisting, and "data diode"-style patterns that prevent write operations or other side effects.
+
+---
+
+## Getting Started
+
+A minimal dynamic server setup usually includes:
+
+- one **modbus-dynamic-server-config** node
+- one **modbus-dynamic-server** node
+- one or more flow nodes such as `function`, `switch`, or `change`
+- one **modbus-dynamic-server-response** node
+
+More advanced flows may also use:
+
+- **modbus-source-router** to split traffic by client IP before any processing logic
+- **modbus-fc-filter** to allow only selected function codes (for example, read-only gateways)
+- **modbus-server-exception** to terminate requests from custom `switch`/`function` logic
+- **modbus-registers-read** to expose cached register values to other flows or dashboards
+- **modbus-registers-config** with **modbus-registers-write** and **modbus-registers-respond**
+- **modbus-proxy-target** with **modbus-dynamic-proxy**
+
+
+## Examples
+
+This package includes example flows in the `examples/` directory. After installation, they should be available from the Node-RED import dialog under the examples list for this module.
+

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "node-red-modbus-dynamic-server",
+  "version": "0.1.0",
+  "private": false,
+  "description": "A Modbus TCP server for Node-RED that lets you write your own functions to handle requests.",
+  "keywords": [
+    "node-red",
+    "modbus",
+    "modbus-tcp",
+    "modbus-server",
+    "modbus-tcp-server",
+    "modbus-gateway",
+    "modbus-proxy",
+    "industrial",
+    "iiot",
+    "protocol-translation",
+    "protocol-mediation",
+    "opcua",
+    "mqtt",
+    "sparkplug"
+  ],
+  "engines": {
+    "node": ">=18.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wz2b/node-red-modbus-dynamic-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wz2b/node-red-modbus-dynamic-server/issues"
+  },
+  "homepage": "https://github.com/wz2b/node-red-modbus-dynamic-server#readme",
+  "author": "Christopher Piggott",
+  "license": "MIT",
+  "node-red": {
+    "version": ">=3",
+    "nodes": {
+      "modbus-dynamic-server": "src/modbus-dynamic-server.js",
+      "modbus-dynamic-server-response": "src/modbus-dynamic-server-response.js",
+      "modbus-dynamic-server-config": "src/modbus-dynamic-server-config.js",
+      "modbus-registers-config": "src/modbus-registers-config.js",
+      "modbus-registers-write": "src/modbus-registers-write.js",
+      "modbus-registers-read": "src/modbus-registers-read.js",
+      "modbus-registers-respond": "src/modbus-registers-respond.js",
+      "modbus-proxy-target": "src/modbus-proxy-target.js",
+      "modbus-dynamic-proxy": "src/modbus-dynamic-proxy.js",
+      "modbus-source-router": "src/modbus-source-router.js",
+      "modbus-fc-filter": "src/modbus-fc-filter.js",
+      "modbus-server-exception": "src/modbus-server-exception.js"
+    }
+  },
+
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "img",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "mocha ./test --recursive --reporter dot --timeout 6000",
+    "lint": "eslint modbus/**/*.js"
+  },
+  "dependencies": {
+    "jsmodbus": "~4.0.10"
+  },
+  "devDependencies": {
+    "@node-red/nodes": "^3.1.9",
+    "eslint": "^8.0.0",
+    "mocha": "^10.4.0",
+    "node-red": "^4.0.2",
+    "node-red-node-test-helper": "^0.3.4"
+  }
+}

package/src/modbus-dynamic-proxy.html

@@ -0,0 +1,108 @@
+<script type="text/html" data-template-name="modbus-dynamic-proxy">
+	<div class="form-row">
+		<label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+		<input type="text" id="node-input-name" placeholder="Name">
+	</div>
+
+	<div class="form-row">
+		<label for="node-input-proxyTarget"><i class="fa fa-exchange"></i> Proxy Target</label>
+		<input type="text" id="node-input-proxyTarget">
+	</div>
+</script>
+
+<script type="text/javascript">
+  RED.nodes.registerType('modbus-dynamic-proxy', {
+	category: 'modbus',
+	color: '#E9967A',
+	defaults: {
+	  name: { value: '' },
+	  proxyTarget: { value: '', type: 'modbus-proxy-target', required: true }
+	},
+	inputs: 1,
+	outputs: 1,
+	icon: 'arrow-out.svg',
+	label: function () {
+	  return this.name || 'Modbus Dynamic Proxy'
+	}
+  })
+</script>
+
+<script type="text/html" data-help-name="modbus-dynamic-proxy">
+	<p>Forwards an incoming Modbus request from a <code>modbus-dynamic-server</code> node to a
+	remote Modbus device (via TCP or serial) using a <code>modbus-proxy-target</code> config node.
+	The response is automatically forwarded back to the server and also emitted on the node's
+	output for inspection or logging.</p>
+
+	<h3>Inputs</h3>
+	<dl class="message-properties">
+		<dt>_modbus.requestId <span class="property-type">string</span></dt>
+		<dd>Required internal request context field emitted by
+		<code>modbus-dynamic-server</code>.</dd>
+
+		<dt>_modbus.eventName <span class="property-type">string</span></dt>
+		<dd>Required internal Modbus function-code event name, e.g.
+		<code>readHoldingRegisters</code>.</dd>
+
+		<dt>_modbus.configNodeId <span class="property-type">string</span></dt>
+		<dd>Required internal config-node identifier used to submit response payloads.</dd>
+
+		<dt>payload <span class="property-type">object</span></dt>
+		<dd>The Modbus request object from the server, containing <code>address</code>,
+		<code>quantity</code>, and <code>body</code>.</dd>
+
+		<dt class="optional">requestBuffer <span class="property-type">Buffer</span></dt>
+		<dd>The raw Modbus TCP request bytes to send to the target. If not provided, the proxy will
+		attempt to construct it from the request object (basic support only).</dd>
+	</dl>
+
+	<h3>Outputs</h3>
+	<ol class="node-ports">
+		<li>Proxied response
+			<dl class="message-properties">
+				<dt>payload <span class="property-type">Buffer</span></dt>
+				<dd>The raw response bytes received from the remote Modbus device. Useful for caching,
+				inspection, or logging. On error, <code>null</code>.</dd>
+
+				<dt>modbusProxy <span class="property-type">object</span></dt>
+				<dd>Metadata about the proxied request:
+					<ul>
+						<li><code>requestId</code> — the UUID of the original server request.</li>
+						<li><code>eventName</code> — the Modbus FC event name (e.g., <code>readHoldingRegisters</code>).</li>
+						<li><code>fc</code> — function code number (1–16).</li>
+						<li><code>address</code> — register/coil starting address.</li>
+						<li><code>quantity</code> — number of registers/coils requested.</li>
+						<li><code>proxied: true</code> — indicates a successful proxy.</li>
+						<li><code>proxyError</code> — (on failure) description of the error (timeout, connection, etc).</li>
+						<li><code>exception</code> — (on failure) Modbus exception code sent to client.</li>
+						<li><code>parseError: true</code> — (if set) response could not be parsed.</li>
+						<li><code>targetType</code> — <code>tcp</code> or <code>serial</code>.</li>
+					</ul>
+				</dd>
+			</dl>
+		</li>
+	</ol>
+
+	<h3>Details</h3>
+	<p>The proxy node uses internal request context (<code>msg._modbus</code>) to complete
+	the original client request. Both success and failure paths (including timeouts) result in an
+	appropriate Modbus response being sent to the client:</p>
+	<ul>
+		<li><b>Success:</b> response from target is parsed and relayed back to client; <code>msg.modbusProxy.proxied</code> is <code>true</code>.</li>
+		<li><b>Timeout:</b> exception code 4 (Gateway Path Unavailable) is sent to client; payload is <code>null</code>.</li>
+		<li><b>Connection error:</b> exception code 4 is sent to client; payload is <code>null</code>.</li>
+		<li><b>Parse error:</b> exception code 4 is sent to client; <code>msg.modbusProxy.parseError</code> is <code>true</code>.</li>
+	</ul>
+	<p>The output is useful for caching layers: capture the response payload and original request
+	parameters (<code>fc</code>, <code>address</code>, <code>quantity</code>) to implement a request
+	deduplication cache that avoids repeated proxying within a configured time window.</p>
+	<p>Flows must preserve <code>msg._modbus</code>:</p>
+	<pre><code>// CORRECT
+msg.payload = newValue;
+return msg;
+
+// INCORRECT: request context is lost
+msg = { payload: newValue };
+return msg;</code></pre>
+	<p>Multiple proxy nodes can share the same target; requests are queued and processed in order.</p>
+</script>
+