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

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to **node-red-contrib-modbus-modpackqt** are documented
+here. This project follows [Semantic Versioning](https://semver.org/) — pin a
+major version (`^2.0.0`) in production.
+
+## [2.0.0] — Unreleased
+
+### ⚠️ Breaking changes
+
+- **Removed cloud gateway dependency.** Modbus communication now runs entirely
+  inside the Node-RED process via [`modbus-serial`](https://www.npmjs.com/package/modbus-serial).
+  No companion app required. Existing flows from `1.x` must be re-created — the
+  config node schema and node IDs have changed.
+- **Slave nodes no longer accept `slaveId`.** The embedded slave server is
+  single-unit (`unitID: 1`). Multi-unit support is on the roadmap.
+- **Master read/write nodes output raw register arrays only.** Type decoding
+  was removed in favour of the new
+  [`node-red-contrib-bytes-modpackqt`](https://www.npmjs.com/package/node-red-contrib-bytes-modpackqt)
+  palette — install both for the full experience.
+
+### Added
+
+- **Embedded Modbus TCP slave server** with a 65 536-register store per
+  register type (coils, discrete inputs, holding, input).
+- **`modpackqt-traffic` node** — free passive monitor that emits one message
+  per Modbus operation. Filters by direction, kind, function code, target.
+- **Local rate limit** (1 000 ops/day per Node-RED instance) for the free tier.
+- **Modbus spec quantity validation** — read/write requests exceeding the
+  protocol maximums (125 regs read, 123 regs write, 2 000 / 1 968 bits)
+  return a clear error before hitting the wire.
+- **Strict input validation on master writes** — non-integer or out-of-range
+  values now produce a helpful error pointing at the bytes palette instead of
+  silently truncating.
+- **Traffic events for external slave reads/writes** — Modbus masters writing
+  to the embedded slave server now appear in the traffic monitor with
+  `via: 'external'`.
+- **`DISCLAIMER.md`, `SECURITY.md`, `CONTRIBUTING.md`** documenting safe use,
+  vulnerability disclosure, and contribution guidelines.
+- **Bundled example flow** (`examples/basic-flow.json`) with six sections
+  combining this palette with the bytes palette.
+
+### Changed
+
+- Connection pooling per `(host, port, unitId)` for TCP and `(serial, unitId)`
+  for RTU — repeated reads/writes to the same target reuse a single client.
+- All master ops are serialised through a single promise queue to prevent
+  collisions on shared serial ports.
+
+### Security
+
+- Removed unauthenticated cloud gateway endpoints. Communication is local-only
+  unless you explicitly enable the embedded slave server (off by default).
+
+## [1.x] — Legacy
+
+Prior releases used a cloud gateway (`modsim`) for Modbus communication. They
+are deprecated; please migrate to 2.x.

package/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for your interest in improving **node-red-contrib-modbus-modpackqt**.
+This document explains how to report issues, suggest features, and submit code
+changes.
+
+## Reporting bugs
+
+Before opening an issue:
+
+1. Make sure you're on the **latest version** (`npm outdated` in `~/.node-red`).
+2. Check if the issue is reproducible against the [bundled example flow](./examples/basic-flow.json).
+3. Re-read [`DISCLAIMER.md`](./DISCLAIMER.md) — some "bugs" are actually
+   undocumented behaviour or known limitations.
+
+When you file an issue, please include:
+
+- Palette version (from `package.json` or the Node-RED palette manager)
+- Node.js version (`node --version`)
+- Node-RED version
+- Operating system
+- The smallest possible Node-RED flow that reproduces the issue (export from
+  Menu → Export → JSON)
+- Console / debug output, with timestamps if possible
+- A `modpackqt-traffic` node's output if the issue involves Modbus operations
+
+Where to file:
+
+- **Bugs and feature requests:** <https://modpackqt.com/contact> (or the
+  package's GitHub repo when listed in `package.json`)
+- **Security issues:** see [`SECURITY.md`](./SECURITY.md) — do not file
+  publicly
+
+## Suggesting features
+
+We're happy to consider new ideas. Before opening a request:
+
+- Describe the use case in plain language ("I want to read a 64-bit timestamp
+  from a Schneider device") — not the implementation ("add a new
+  decode-timestamp node").
+- Explain why the existing nodes can't already solve it (often they can —
+  composing `decode-uint32 BE_SWAP` + a `function` node solves a lot).
+
+## Submitting code changes
+
+1. **Open an issue first** for non-trivial changes so we can agree on the
+   approach before you spend time on a PR.
+2. **Keep changes small and focused** — one feature or fix per PR.
+3. **Preserve backward compatibility.** This package is shipped to many
+   production deployments; breaking changes require a major version bump and
+   a clear migration path.
+4. **Test against the example flow.** At minimum, importing `basic-flow.json`
+   and running each section should still work.
+5. **Update `CHANGELOG.md`** under "Unreleased".
+6. **Update the README** if you add or change a node's behaviour.
+7. **Bump versions only on release.** Maintainers handle the version bump
+   when publishing.
+
+## Code style
+
+- Vanilla Node.js — no TypeScript, no transpilation, no build step.
+- 2-space indent.
+- Prefer small, well-named helper functions over clever one-liners.
+- Wrap risky operations in `try/finally` and emit errors via `node.error()`
+  rather than throwing into Node-RED's runtime.
+
+## Licence
+
+By submitting a PR you agree to licence your contribution under the project's
+[MIT licence](./LICENSE).

package/DISCLAIMER.md

@@ -0,0 +1,92 @@
+# ⚠️ Industrial use disclaimer
+
+This software talks to industrial control systems (PLCs, RTUs, drives, meters).
+A Modbus write can move physical equipment — valves, motors, heaters, pumps —
+and a wrong write can damage equipment, ruin a batch, or cause a safety incident.
+
+**Read this before deploying in production.**
+
+## You are responsible for
+
+- **What your flows do.** Node-RED, this palette, and the bytes palette only
+  carry your bytes — they don't know whether `setpoint=200` means 200 °C or
+  200 RPM, or whether opening valve 7 floods the building.
+- **Testing.** Always test against the embedded slave server (or a simulator
+  like ModPackQT's own Modbus simulator) before pointing at a live device.
+- **Staging.** Have an air-gapped or read-only staging environment between
+  development and production. Never deploy a flow change directly to a system
+  controlling real assets.
+- **Backups.** Keep your Node-RED flows in version control. A flow recovery
+  is faster than a hardware recovery.
+- **Compliance.** If your installation is subject to safety regulations
+  (IEC 61508, ISO 13849, OSHA, FDA 21 CFR Part 11, etc.), this software is
+  **not certified** for safety-instrumented systems (SIS). Use it for
+  monitoring, supervisory control, and data acquisition — not for safety
+  interlocks.
+
+## Recommended safe-use workflow
+
+1. **Always start with reads.** Get the values flowing in before you wire any
+   write back out.
+2. **Use the embedded slave server as a sandbox.** Wire your flows to write
+   into the local slave first; verify the bytes are correct with `decode-…`
+   nodes; only then point them at a real device.
+3. **Add the `modpackqt-traffic` node** (free) to every config — it logs every
+   read and write with timing, value, and error info. If something goes wrong,
+   the trail is right there.
+4. **Test the worst case in the bytes palette.** Round-trip your values
+   through `encode-… → decode-…` to confirm the byte/word order matches the
+   target device. Wrong endianness on a setpoint write is a common cause of
+   damage.
+5. **Wrap critical writes in a guard.** A `function` node that rejects values
+   outside a safe range, or a `switch` node that blocks writes during
+   maintenance windows, costs you 30 seconds and saves you a service call.
+6. **Pin a major version in production** (`"node-red-contrib-modbus-modpackqt": "^2.0.0"`).
+   We follow semver — patch and minor releases are backward compatible; major
+   releases may not be.
+
+## What this software does NOT promise
+
+- It is **not** safety-rated.
+- It is **not** suitable for safety-instrumented systems (SIS / SIL-rated loops).
+- It is **not** a substitute for a real PLC's hardwired interlocks.
+- It does **not** guarantee delivery, ordering, or completeness of writes
+  beyond what the underlying `modbus-serial` library and the network/serial
+  link provide.
+- The free tier is rate-limited; if you exceed 1,000 ops/day, master read/write
+  nodes will return errors. **Do not rely on the free tier for production.**
+
+## Reporting issues
+
+- **Bugs / unexpected behavior:** open an issue at
+  <https://modpackqt.com/contact> (or the package's GitHub repo when listed).
+- **Security issues:** email **support@modpackqt.com** privately. Please
+  follow responsible disclosure — give us 90 days to fix before publishing.
+- **Paid customers:** include your customer ID for priority response.
+
+## Updates
+
+This package is distributed via npm. **Updates are never automatic.** Node-RED
+will show "update available" in the palette manager when a new version is
+published; you choose when to upgrade.
+
+We strongly recommend subscribing to release notifications:
+
+- **GitHub:** watch the repository (when listed in `package.json`)
+- **npm:** `npm view node-red-contrib-modbus-modpackqt versions`
+- **Email** (paid customers): security and breaking-change notices go to your
+  registered address.
+
+## Licence
+
+This software is provided under the MIT License — see `LICENSE`. Paid plans
+provide commercial support and remove the daily op cap. **Paid plans do not
+add a warranty** — the limitation of liability in the LICENSE applies to all
+users. See <https://modpackqt.com/nodered/terms> for the full terms.
+
+---
+
+If any of the above is unacceptable for your project, **do not use this
+software in production**. There is no shame in that — Modbus is a mature
+protocol with many alternative implementations, including hardware-based
+gateways with safety certifications.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ModPackQT
+
+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.