node-red-contrib-modbus-modpackqt 1.1.84 → 2.0.0

package/README.md

@@ -1,6 +1,7 @@
 # node-red-contrib-modbus-modpackqt
 
-**Node-RED Modbus nodes powered by [ModPackQT](https://modpackqt.com)** — drag-and-drop nodes to read and write Modbus TCP registers (master & slave) from your Node-RED flows. No hand-written HTTP calls. No protocol handling. Just connect and go.
+**Embedded Modbus TCP / RTU master + slave server for Node-RED — no extra apps required.**
+By [ModPackQT](https://modpackqt.com).
 
 [![npm version](https://img.shields.io/npm/v/node-red-contrib-modbus-modpackqt.svg)](https://www.npmjs.com/package/node-red-contrib-modbus-modpackqt)
 [![Node-RED](https://img.shields.io/badge/Node--RED-%E2%89%A52.0.0-red)](https://nodered.org)
@@ -8,224 +9,195 @@
 
 ---
 
-## What is ModPackQT?
+## What you get
 
-[ModPackQT](https://modpackqt.com) is an industrial Modbus Master/Slave platform for engineers and technicians. It provides:
+- **Modbus master** — read (FC1–FC4) and write (FC5/FC6/FC15/FC16) over **TCP** or **RTU (serial)**
+- **Embedded Modbus TCP slave server** — push values from any flow, let PLCs / SCADA / HMIs read them
+- **Free passive traffic monitor** — see every Modbus op (timing, values, errors) in real time
+- **Outputs raw register values** — pair with [`node-red-contrib-bytes-modpackqt`](https://www.npmjs.com/package/node-red-contrib-bytes-modpackqt) to decode int / float / string / bitmask
+- **Zero external dependencies** — Modbus runs inside the Node-RED process
 
-- **Modbus TCP and RTU** communication via a local gateway app
-- **Built-in slave simulator** — simulate a PLC register map without hardware
-- **Real-time data visualization**, profile management, and AI-assisted setup
-- A **REST API** that this Node-RED palette talks to
-
-👉 [Download ModPackQT](https://modpackqt.com/download) · [Modbus Tutorial](https://modpackqt.com/resources/tutorial) · [Resources Hub](https://modpackqt.com/resources)
+---
 
-> **Requires the ModPackQT Gateway app to be running locally.**
-> The gateway is what the nodes talk to — not the cloud server directly.
+> ## ⚠️ Read before deploying in production
+>
+> This software writes to industrial control equipment. A wrong write can damage
+> equipment, ruin a batch, or cause a safety incident.
+>
+> - **Test against the embedded slave server first** — never wire a new write
+>   directly to a real device.
+> - **Not for safety-instrumented systems** (SIS / SIL-rated loops). This is
+>   for monitoring and supervisory control, not safety interlocks.
+> - **You are responsible** for what your flows do. See
+>   [`DISCLAIMER.md`](./DISCLAIMER.md) for the full safe-use checklist and
+>   [`LICENSE`](./LICENSE) for the legal terms.
 
 ---
 
-## Installation
+## Install
 
-### Option 1 — Node-RED Palette Manager (recommended)
+**Recommended (one shot):** install both palettes — Modbus + decoders — together.
 
-1. Open Node-RED → **Menu (☰) → Manage palette → Install**
-2. Search for **`modbus-modpackqt`**
-3. Click **Install**
-4. Restart Node-RED — the **ModPackQT** palette group appears in the sidebar
-
-### Option 2 — npm CLI
+Palette manager → Manage palette → Install:
+- `node-red-contrib-modbus-modpackqt`
+- `node-red-contrib-bytes-modpackqt`
 
+**npm:**
 ```bash
 cd ~/.node-red
-npm install node-red-contrib-modbus-modpackqt
-# Restart Node-RED after installation
+npm install node-red-contrib-modbus-modpackqt node-red-contrib-bytes-modpackqt
+# then restart Node-RED
 ```
 
 ---
 
-## Prerequisites
-
-1. **Sign up at [modpackqt.com](https://modpackqt.com)**
-   A free account works for all master nodes. Slave nodes require a **paid plan**.
-
-2. **Download and start the ModPackQT Gateway app**
-   Download it from [modpackqt.com/download](https://modpackqt.com/download) and run it.
-   By default it listens on **port 8502** (`localhost:8502`).
+## 5-minute walkthrough
 
-3. **Create an API key**
-   In the ModPackQT web app go to **Settings → API Keys → New Key**. Paste it into the `modpackqt-config` node.
+### 1. Read a temperature float from a PLC
 
-4. **For slave nodes** — create and start at least one slave in the ModPackQT app first (Slave Simulator → New Slave). Note the **Slave ID** shown — you'll need it in Node-RED.
-
-> **Plan limits**
->
-> | Feature | Free | Paid |
-> |---|---|---|
-> | Master Read (`modpackqt-master-read`) | ✓ | ✓ |
-> | Master Write (`modpackqt-master-write`) | ✓ | ✓ |
-> | Slave Write (`modpackqt-slave-write`) | ✗ | ✓ |
-> | Slave Read (`modpackqt-slave-read`) | ✗ | ✓ |
->
-> [View plans & upgrade →](https://modpackqt.com/#pricing)
-
----
+```
+[inject every 5s] → [modbus master read FC3 addr=100 qty=2] → [decode-float32 BE] → [debug]
+```
 
-## Available Nodes
+| Step | Setting |
+|---|---|
+| Add a runtime config | TCP, timeout 3000 ms |
+| Master read | Host `192.168.1.10`, port `502`, unit `1`, FC `3`, address `100`, qty `2` |
+| `decode-float32` | Endian `BE` (try `LE_SWAP` if value looks wrong — Siemens often uses CDAB) |
 
-| Node | Category | Purpose |
-|---|---|---|
-| `modpackqt-config` | Config | Shared gateway connection (host, port, API key) |
-| `modpackqt-master-read` | Modbus Master | Read Modbus TCP registers — FC1/FC2/FC3/FC4 |
-| `modpackqt-master-write` | Modbus Master | Write Modbus TCP registers — FC5/FC6/FC15/FC16 |
-| `modpackqt-slave-read` | Modbus Slave *(paid)* | Read registers from a ModPackQT slave |
-| `modpackqt-slave-write` | Modbus Slave *(paid)* | Push values into a ModPackQT slave (build a live Modbus device from Node-RED) |
+**`msg.payload` along the wire:**
+- After Modbus read: `[16828, 0]` (raw registers)
+- After decode-float32: `23.5` (clean float — done)
 
----
+### 2. Send a setpoint back
 
-## Node-RED Modbus Master — Read Registers (FC1/FC2/FC3/FC4)
+```
+[inject 23.5] → [encode-float32 BE] → [modbus master write FC16 addr=200]
+```
 
-The `modpackqt-master-read` node reads registers from **any Modbus TCP slave device** by routing the request through the ModPackQT Gateway app.
+The encoder converts `23.5` → `[16828, 0]`, the write node sends it to the PLC.
 
-**Supported function codes:**
-- **FC1** — Read Coils
-- **FC2** — Read Discrete Inputs
-- **FC3** — Read Holding Registers
-- **FC4** — Read Input Registers
+### 3. Watch what's happening (debug visibility)
 
-**Config options:**
+Drop a **modbus traffic** node anywhere on the canvas, point it at the same runtime config, wire to a Debug node. You'll see one message per Modbus op:
 
-| Property | Description |
-|---|---|
-| Gateway | Config node pointing at your running ModPackQT Gateway app |
-| Target Host | IP/hostname of the Modbus TCP slave to read from |
-| Target Port | Port of the Modbus TCP slave (default: 502) |
-| Unit ID | Modbus unit ID of the slave (1–247) |
-| Function Code | FC1 / FC2 / FC3 / FC4 |
-| Start Address | First register address (0-based) |
-| Quantity | Number of registers/coils to read (1–125) |
-| Poll Interval | Auto-poll every N ms (0 = trigger on input msg only) |
-
-**Output:**
 ```json
 {
-  "payload": { "success": true, "values": [100, 200, 300] },
-  "topic": "modbus/read/192.168.1.10:502"
+  "ts": "2026-05-09T14:23:01.234Z",
+  "direction": "read",
+  "kind": "master",
+  "target": "192.168.1.10:502",
+  "unitId": 1,
+  "fc": 3,
+  "address": 100,
+  "quantity": 2,
+  "values": [16828, 0],
+  "durationMs": 12,
+  "ok": true
 }
 ```
 
----
+Filter by direction, function code, or target if you only want a slice. **Free, doesn't count toward your daily op cap.**
 
-## Node-RED Modbus Master — Write Registers (FC5/FC6/FC15/FC16)
+### 4. Be a Modbus slave (let SCADA read your values)
 
-The `modpackqt-master-write` node writes registers to **any Modbus TCP slave device**.
+In the runtime config check **Enable embedded Modbus TCP slave server**, set port `1502`. Then:
 
-**Supported function codes:**
-- **FC5** — Write Single Coil
-- **FC6** — Write Single Holding Register
-- **FC15** — Write Multiple Coils
-- **FC16** — Write Multiple Holding Registers
-
-**Input:** `msg.payload` — a number (FC5/FC6) or array of numbers (FC15/FC16)
+```
+[any source] → [encode-int32 BE] → [modbus slave write holding addr=0]
+```
 
-**Output:** Original `msg` with `msg.success = true`
+External masters connecting to `your-host:1502`, unit `1`, FC `3`, address `0`, qty `2` will read the latest value back.
 
 ---
 
-## Building a Modbus Slave from Node-RED *(Paid plan)*
+## Cookbook (combined with the bytes palette)
 
-Use `modpackqt-slave-write` to make Node-RED the **data source** for a live Modbus slave device. Any external Modbus master (PLC, SCADA, HMI) that connects to the ModPackQT slave port will read whatever values you last pushed from Node-RED.
-
-**Typical flow:**
+### Decode a status bitmask
 ```
-[MQTT / Sensor / Timer] → [Function: scale to integer] → [modpackqt-slave-write addr=0] → [External Modbus master reads]
+[master read FC3 addr=50 qty=1] → [decode-bitmask bits=8] → [debug]
+// payload = [true, true, false, true, false, false, false, false]
 ```
 
-**Use cases:**
-- Publish MQTT sensor data as Modbus TCP registers
-- Simulate a PLC register map for HMI/SCADA testing
-- Bridge OPC-UA, REST, or database data to Modbus
-
-**Slave write input — all of these work:**
-```js
-msg.payload = 234;               // single integer
-msg.payload = [234, 1013, 65];   // array — writes 3 registers starting at address 0
-msg.payload = "[234, 1013, 65]"; // JSON string also works (inject string type)
+### Read a device serial number string
 ```
-
-**Override at runtime:**
-```js
-msg.slaveId      = "42";    // select a different slave per message
-msg.address      = 10;      // start at register 10 instead of the configured address
-msg.registerType = "coil";  // override register type
+[master read FC3 addr=10 qty=8] → [decode-string BE encoding=utf8 trim=true] → [debug]
+// payload = "SN-2025-A0042"
 ```
 
-**Slave read output:**
-```json
-{
-  "payload": {
-    "values": [234, 1013, 65],
-    "registerType": "holding",
-    "address": 0,
-    "quantity": 3,
-    "slaveId": "42"
-  },
-  "topic": "slave/42/holding/0"
-}
+### Bridge MQTT → Modbus
+```
+[mqtt in topic=setpoint] → [encode-float32 BE] → [master write FC16 addr=200]
 ```
 
----
-
-## Example Flows
-
-### Poll Holding Registers Every 5 Seconds (Modbus Master)
-
+### Bridge Modbus → MQTT
 ```
-[Inject (repeat 5s)] → [modpackqt-master-read FC3 target=192.168.1.10:502 unitId=1 addr=0 qty=10] → [Debug]
+[poll every 5s] → [master read FC3 addr=100 qty=2] → [decode-float32 BE] → [mqtt out topic=temp]
 ```
 
-### Write a Setpoint Register from a Button
-
+### Mirror a remote PLC into local slave server
 ```
-[Inject (payload=1234)] → [modpackqt-master-write FC6 target=192.168.1.10:502 unitId=1 addr=100] → [Debug]
+[poll 1s] → [master read FC3 addr=0 qty=10] → [slave write holding addr=0]
+// any local SCADA can now read from your Node-RED slave instead of hammering the PLC
 ```
 
-### Build a Slave — Publish Sensor Data as Modbus (Paid plan)
-
+### Alert on Modbus errors
 ```
-[MQTT in] → [Function: msg.payload = parseInt(msg.payload * 10)] → [modpackqt-slave-write Holding addr=0] → [Debug]
+[modbus traffic filter=any] → [switch ok==false] → [email out]
 ```
 
-Any Modbus master on the network now reads live sensor values from the slave.
+---
 
-### Import the Demo Flow
+## Available nodes
 
-1. Open Node-RED → **Menu → Import**
-2. Choose `examples/basic-flow.json` from the package directory
-3. Update the config node with your gateway host/port
-4. Click **Deploy**
+| Node | Purpose |
+|---|---|
+| `modpackqt-config` | Shared runtime — master mode (TCP/RTU), serial settings, optional slave server, API key |
+| `modpackqt-master-read` | Read FC1/FC2/FC3/FC4 from a remote Modbus device |
+| `modpackqt-master-write` | Write FC5/FC6/FC15/FC16 to a remote Modbus device |
+| `modpackqt-slave-read` | Read from the embedded slave's register store (verify what masters see) |
+| `modpackqt-slave-write` | Push values into the embedded slave's register store |
+| `modpackqt-traffic` | **Passive monitor** — emits one message per Modbus op. Free, with filters, full visibility into what's happening on the wire. |
 
 ---
 
-## Configuration Node
+## Why Modbus + bytes are split into two palettes
+
+Most Modbus packages bake type decoding into the read node — one giant dropdown for int16 / int32 / float32 / Siemens-CDAB / etc. That made sense in 2010 but it's a mess: every protocol re-implements the same decoders, and you can't reuse them for MQTT / TCP / BLE / file payloads.
 
-Add one `modpackqt-config` node per gateway instance. All other nodes reference it.
+We split them on purpose:
+- **Modbus nodes** speak Modbus and output raw registers — nothing else.
+- **Bytes nodes** decode any binary payload into typed values.
 
-| Property | Default | Description |
+You write less code, your flows stay readable, and the same decoder works whether the data came from a PLC, an MQTT broker, or a UDP socket.
+
+---
+
+## Pricing
+
+| | Free | Paid |
 |---|---|---|
-| Host | `localhost` | Hostname or IP of the machine running the ModPackQT Gateway app |
-| Port | `8502` | Port that the ModPackQT Gateway app listens on |
-| API Key | _(empty)_ | Optional — sent as `x-api-key` header if set |
+| Master read / write | ✓ | ✓ |
+| Embedded slave server | ✓ | ✓ |
+| **Traffic monitor** | ✓ | ✓ |
+| Daily ops cap | **1,000 / day** per Node-RED instance | **Unlimited** |
+| Branding in node status | Visible | Hidden |
+| API key required | No | Yes |
+| Trial | — | **30 days free, no credit card** |
+
+[Get a free trial key →](https://modpackqt.com/nodered)
+
+When the daily cap is hit, master read/write nodes return a clear error pointing at the upgrade link. **Traffic events, slave register reads/writes, and decode/encode operations don't count.**
 
 ---
 
-## API Endpoints Used
+## Importing the example flow
 
-| Node | Gateway Endpoint |
-|---|---|
-| `modpackqt-master-read` | `POST /api/modbus/tcp/read` |
-| `modpackqt-master-write` | `POST /api/modbus/tcp/write` |
-| `modpackqt-slave-read` | `GET /api/slaves/:id/registers` |
-| `modpackqt-slave-write` | `PATCH /api/slaves/:id/registers` |
+This package ships with a complete demo flow under `examples/basic-flow.json` showing every node combined with the bytes palette (master read → decode-float32, encode-float32 → master write, status bitmask, traffic monitor, slave loop).
+
+Node-RED → Menu → Import → Examples → **node-red-contrib-modbus-modpackqt** → basic-flow.
+
+Make sure `node-red-contrib-bytes-modpackqt` is also installed before importing — the example uses both.
 
 ---
 
@@ -233,25 +205,42 @@ Add one `modpackqt-config` node per gateway instance. All other nodes reference
 
 | Issue | Solution |
 |---|---|
-| `connect ECONNREFUSED localhost:8502` | The ModPackQT Gateway app is not running. Start it first. |
-| `401 Unauthorized` | Missing or invalid API key — check `modpackqt-config`. |
-| `403 Forbidden` on slave nodes | Your plan does not include the Slave Simulator. [Upgrade your plan →](https://modpackqt.com/#pricing) |
-| `slave not found — check Slave ID` | The Slave ID is wrong or that slave was deleted. Check in ModPackQT → Slave Simulator. |
-| `gateway not running` on slave nodes | The Gateway app is stopped. Open ModPackQT and click Start Gateway. |
-| `Cannot find module 'axios'` | Run `npm install` in `~/.node-red`. |
-| Nodes not appearing after install | Restart Node-RED completely after `npm install`. |
-| Node-RED version error | Requires Node-RED ≥ 2.0.0 and Node.js ≥ 14. |
+| `ModPackQT free tier limit reached` | Either wait until midnight or [get a free trial key](https://modpackqt.com/nodered) |
+| Decoded float looks like garbage | Try a different word order (`BE` ↔ `LE_SWAP`) — Schneider uses ABCD, Siemens often uses CDAB |
+| `Serial port not configured for RTU mode` | Open runtime config → set Serial Port (e.g. `/dev/ttyUSB0` or `COM3`) |
+| `EADDRINUSE` on slave port | Another process already uses that port. Pick a different one (e.g. `1502`). |
+| `connect ECONNREFUSED` | Target Modbus device is unreachable. Check IP / port / firewall. |
+| `Embedded slave is disabled` | Open runtime config → check **Enable embedded slave server** |
+| Nodes don't appear after install | Fully restart Node-RED. |
+
+---
+
+## Reporting bugs & getting updates
+
+- **Bugs / feature requests:** open a GitHub issue at the repository linked in
+  `package.json`, or email **support@modpackqt.com**.
+- **Security issues:** see [`SECURITY.md`](./SECURITY.md) — please report
+  privately to **support@modpackqt.com**.
+- **Updates are never automatic.** Node-RED's palette manager will show
+  "update available" when we publish a new version — you choose when to
+  upgrade. Pin a major version (`^2.0.0`) in production.
+- **Changelog:** see [`CHANGELOG.md`](./CHANGELOG.md). We follow
+  [semver](https://semver.org/) — patch releases for bug fixes only.
+- **Paid customers** get email notice for security and breaking-change
+  releases.
 
 ---
 
 ## Links
 
-- [ModPackQT Homepage](https://modpackqt.com)
-- [Download ModPackQT Gateway](https://modpackqt.com/download)
-- [Free Modbus Tutorial](https://modpackqt.com/resources/tutorial)
-- [Modbus Resources Hub](https://modpackqt.com/resources)
-- [Node-RED Docs](https://nodered.org/docs/)
-- [Contact / Report an Issue](https://modpackqt.com/contact)
+- [ModPackQT homepage](https://modpackqt.com)
+- [Node-RED + ModPackQT docs](https://modpackqt.com/nodered)
+- [Bytes palette (decoders/encoders)](https://www.npmjs.com/package/node-red-contrib-bytes-modpackqt)
+- [Modbus tutorials](https://modpackqt.com/resources/tutorial)
+- [Disclaimer & safe-use checklist](./DISCLAIMER.md)
+- [Changelog](./CHANGELOG.md)
+- [Security policy](./SECURITY.md)
+- [Contributing guide](./CONTRIBUTING.md)
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you discover a security issue in this package, **please report it
+privately** so we can fix it before it's exploited.
+
+- **Email:** support@modpackqt.com
+- **Response time:** we aim to acknowledge within **2 business days** and
+  publish a fix or mitigation within **90 days** of the report.
+
+Please include:
+
+- Affected version(s)
+- A short description of the impact
+- Steps or a proof-of-concept to reproduce
+- Your preferred name for credit (or anonymous)
+
+We follow [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure):
+we will not publish the issue until you've had a chance to verify the fix or
+the 90-day window has elapsed.
+
+## Supported versions
+
+| Version | Status |
+|---|---|
+| `2.x`   | ✅ Active — security fixes within 90 days |
+| `1.x`   | ❌ End of life — please migrate to 2.x |
+
+## What is in scope
+
+- The Node-RED nodes shipped in this package
+- The embedded Modbus TCP slave server
+- The traffic event bus
+- Authentication and rate-limiting code paths
+
+## What is out of scope
+
+- Vulnerabilities in our dependencies (please report those upstream — for
+  example to [`modbus-serial`](https://github.com/yaacov/node-modbus-serial))
+  — but tell us too so we can pin a safe version
+- Issues that require an attacker to already have control of the Node-RED
+  runtime (Node-RED is not a sandbox)
+- Denial-of-service caused by the free-tier rate limit (this is by design)
+
+## Hall of fame
+
+We credit security reporters in this section unless they request anonymity.
+
+_(none yet)_