ModPackQT Modbus for Node-RED

Read, write and simulate Modbus devices for testing and commissioning. Use the Modbus palette on its own for raw registers, or add the companion Bytes palette for drop-in float, integer, string and bitmask conversion.

Free to use under proprietary terms. Normal configuration and your own flows are permitted; modification and redistribution are restricted. No account, activation, Gateway Key or paid plan is needed for local Modbus operations. Optional cloud features have their own setup and account requirements.

Start here: Setup, examples and both palettes · Flow Library · ModPackQT web console · ModPackQT Desktop

Choose one palette or use both

| Palette | Use it for | Install independently? | | --- | --- | --- | | This Modbus palette | TCP/RTU master reads/writes, local slave stores and commissioning probes | Yes — raw register arrays and coils need no decoder | | ModPackQT Bytes | Decode/encode int16/uint16, int32/uint32, float32/float64, strings, bitmasks and byte/word order | Yes — also works with MQTT, TCP/UDP, BLE and other Buffer/array sources |

The pairing is optional, not a hidden dependency. For engineering values:

Modbus Master Read → decode-float32 → Debug / MQTT Out
Inject number → encode-float32 → Modbus Master Write

Install or update

Use Node-RED → Manage palette → Install and search the complete package names, or run the following in your Node-RED user directory (usually ~/.node-red on macOS/Linux; use your actual --userDir if different).

Modbus only:

cd ~/.node-red
npm install node-red-contrib-modbus-modpackqt@latest

Both palettes:

cd ~/.node-red
npm install node-red-contrib-modbus-modpackqt@latest node-red-contrib-bytes-modpackqt@latest

Restart Node-RED using the method you normally use to start it. Updating does not require uninstalling first. Node.js >=14 and Node-RED >=2.0 are the declared package minimums; use a Node.js release supported by your Node-RED version. RTU requires a supported serial adapter, driver and permission to open its port. Modbus runs in the Node-RED process; no separate gateway service is required.

Try an example without hardware

Menu → Import → Examples → node-red-contrib-modbus-modpackqt. The same flow JSON is available to copy/download from the example guide.

| Shipped example | Palettes needed | What to click / expected result | | --- | --- | --- | | modbus-only-loopback.json | Modbus only | Click Send [123,456]. A local Slave Write seeds holding registers and a real TCP Master Read returns [123,456]; a Slave Read inspects the same store directly. | | dynamic-coil-address.json | Modbus only | Use three Inject buttons to address coils 12 and 20 through one FC5 Write node. FC1 reads coils 12..27: array index 0 is coil 12 and index 8 is coil 20. | | basic-flow.json | Modbus + Bytes | Click Inject 23.5 for encode → slave store → TCP read → decode. Debug shows [16828,0] and 23.5. A second path writes 42.5 with FC16 and reads it back. |

Deploy first, wait for listening status, then click an Inject. These demos bind to 127.0.0.1, use separate high TCP ports (15020–15022), and have no automatic polling or startup writes. If a port is occupied, change both the Slave Server port and the Target Device port. The Slave Server also registers with the local probe runtime described below.

For a decoder-only demo, install only Bytes and import its decoder-recipes.json or binary-payloads.json. No Modbus device or broker is needed.

Published nodes

| Node | Input / output | | --- | --- | | modpackqt-config | Shared Target Device configuration: TCP/RTU, host/port/unit, serial settings and timeout; optional saved-cloud-profile picker | | modpackqt-probe-config | Shared probe HTTP runtime configuration used by commissioning probes | | modpackqt-master-read | Any input triggers FC1/2/3/4 read; msg.payload is the raw array, not a {values:…} wrapper. Optional polling interval. | | modpackqt-master-write | Scalar/array payload → FC5/6/15/16; passes the original message with success, valuesWritten and addressWritten on success | | modpackqt-slave-server | Standalone simulator/server with its own register store; emits external client read/write events and connects to the web console | | modpackqt-slave-write | Updates the selected Slave Server's store from msg.payload; references it using slaveServerId | | modpackqt-slave-read | Reads the selected Slave Server's store directly; msg.payload is a raw array | | modpackqt-master-probe | Commissioning connection to a configured target; Open in Console attaches the web tester |

Use ordinary Debug, Catch and Status nodes for flow diagnostics. Slave Server events can be wired to Debug. There is no separate traffic node in this release. Master Pro and Slave Pro are not included in the public palette.

The Slave Server editor offers TCP and RTU transports; serial behavior depends on the installed transport library and adapter. The included runnable examples exercise TCP. Validate RTU support and framing on your hardware before relying on it; installing this palette is not a guarantee of compatibility with every serial platform.

Configure reads and writes

Use zero-based addresses: 0 is not a 40001-style reference label. Select the device in the shared Target Device config. Multiple master nodes may reference that target; use one shared runtime per physical RTU port.

• FC1/FC2 read booleans; FC3/FC4 read 16-bit register words.
• FC5 accepts a coil value; FC6 accepts one register word.
• FC15/FC16 accept arrays. Set Quantity explicitly: longer payloads are truncated and shorter ones are padded with the last value.
• A float32 occupies two registers: use Quantity 2 for FC16 and FC3.
• Incoming triggers and configured polling determine timing; dynamic addressing does not create a timer or combine requests.

Dynamic Start Address remains free

Enable Use msg.address when present in Master Write, choose FC5, and send:

msg.address = 12;
msg.payload = true;
return msg;

The next message can target coil 20 using the same node. The override is per-message and does not modify the saved address. It is off by default; missing msg.address falls back to the configured address. Supplied addresses must be zero-based integers 0..65535 (decimal integer strings are accepted); invalid addresses/ranges are rejected before I/O and reported to Catch. Device, unit, function code and Quantity stay configured.

Connect your flow to ModPackQT

• Web console: explore registers and byte orders, test device maps and use optional profile/AI features.
• Desktop: use ModPackQT's desktop experience for local testing and commissioning.
• Saved profiles: a Cloud Gateway Key from Settings → Cloud Gateways lets optional My Connections / My Slaves pickers load account-specific saved configuration. A key is not needed for local nodes and is not a Pro license or local Modbus authentication.
• Live console: use Open in Console on Master Probe or Slave Server from a browser that can reach that Node-RED machine.

The first probe/server starts an HTTP runtime, normally on 127.0.0.1:8502 with fallback ports 8503–8506. It stops after the last probe is removed.

| Local probe API | Purpose | | --- | --- | | GET /api/health, GET /api/probes, GET /api/probes/:id | Runtime status and probe details | | POST /api/probes/:id/read, POST /api/probes/:id/write | Master operations | | GET /api/probes/:id/store, PUT /api/probes/:id/store | Slave store access |

Keep the default loopback bind unless you deliberately need LAN access. MODPACKQT_PROBE_HOST / MODPACKQT_PROBE_PORT can change it, but editor restrictions and a Gateway Key do not secure the separate local HTTP API or the Modbus listener. Protect exposed endpoints with appropriate network and access controls; Modbus TCP has no built-in authentication.

Troubleshooting

| Symptom | Check | | --- | --- | | Missing node on import | Install the palette(s) stated in the example, then restart Node-RED | | Port already in use | Change the local Slave Server and matching Target Device port together | | Wrong float | Check register width and BE/LE/BE_SWAP/LE_SWAP; use Bytes for conversion | | Only one word written | Set FC16 Quantity to 2 for a float32 | | Cloud picker says deploy first | Deploy the config, set its optional key, then refresh; local operations do not require it | | Cannot reach a real device | Check host, port, unit, address convention, transport and permissions |

Release and license notes

Current release: 4.0.3. This documentation update clarifies the current release's license terms. Runtime behavior, registered nodes and examples are unchanged. See CHANGELOG.md for the full release history.

This release is free-to-use proprietary, not open source. See the installed LICENSE; the 4.0.3 license text is also available online. Third-party permissions remain applicable. Legal restrictions are not technical copy protection or payment enforcement.

Provided as is, without warranty. Test in an isolated environment and verify targets, addresses and safe values before writing to equipment. These tools must not be the sole safety/protection mechanism.

Report a bug · Security contact · More examples and companion palettes