---
title: "node-red-contrib-modbus • FlowFuse Integrations"
description: "FlowFuse builds your first industrial solution with your team, proves it at one plant, then helps you roll it out to every plant, faster each time."
canonical_url: "https://flowfuse.com/integrations/node-red-contrib-modbus/"
meta:
  "og:description": "FlowFuse builds your first industrial solution with your team, proves it at one plant, then helps you roll it out to every plant, faster each time."
  "og:title": "node-red-contrib-modbus • FlowFuse Integrations"
---

> Index of every page on this site: [llms.txt](https://flowfuse.com/llms.txt)

# **node-red-contrib-modbus**

FlowFuse Recommended

The all in one Modbus TCP, UDP and Serial contribution long term supported package for Node-RED.

**Version:** 5.62.1**Weekly Downloads:** 3,677**Author:**Klaus Landsdorf**Updated:** Oct 25, 2026

## **FlowFuse Recommended Node **

FlowFuse recommends this node as a well-maintained, dependable choice for production Node-RED projects.

![Platform Node-RED](https://img.shields.io/badge/Platform-Node--RED-red.png) ![Contribution Modbus](https://img.shields.io/badge/Contribution-Modbus-orange.png) [![Financial Contributors on Open Collective](https://opencollective.com/node-red-contrib-modbus/all/badge.svg?label=financial+contributors)](https://opencollective.com/node-red-contrib-modbus) [![NPM version](https://badge.fury.io/js/node-red-contrib-modbus.png)](https://www.npmjs.com/package/node-red-contrib-modbus) ![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.png) ![Node-RED](https://img.shields.io/badge/Node--RED-%3E%3D4-red.png) [![Standard - JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/) [![NPM download](https://img.shields.io/npm/dm/node-red-contrib-modbus.svg)](https://npm-stat.com/charts.html?package=node-red-contrib-modbus) [![Build and publish](https://github.com/BiancoRoyal/node-red-contrib-modbus/actions/workflows/build.yml/badge.svg)](https://github.com/BiancoRoyal/node-red-contrib-modbus/actions/workflows/build.yml) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/6cbeb40ab5604b3ab99e6badc9469e8a)](https://www.codacy.com/gh/BiancoRoyal/node-red-contrib-modbus) [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/BiancoRoyal/node-red-contrib-modbus) [![Supported with Claude Code Pro](https://img.shields.io/badge/Supported%20with-Claude%20Code%20Pro-d97706?logo=anthropic&logoColor=white)](https://claude.ai/code)

# node-red-contrib-modbus

### The all-in-one Modbus TCP and Serial contribution package for Node-RED

[![nodemodbus64](https://raw.githubusercontent.com/BiancoRoyal/node-red-contrib-modbus/master/images/modbus-icon64.png)](https://www.npmjs.com/package/node-red-contrib-modbus)

**Public LTS line:** **v5.x** (current: **5.60.2**) · License **BSD-3-Clause** · Repo: [GitHub](https://github.com/BiancoRoyal/node-red-contrib-modbus)

If you like this package, please **give us a star on [GitHub](https://github.com/BiancoRoyal/node-red-contrib-modbus)**.

> **AI-assisted maintenance:** This project is **actively developed and supported with [Claude Code Pro](https://claude.ai/code)** (Anthropic). Issue triage, specs, tests, and patches on the v5 LTS line are routinely done with Claude Code as part of the maintainer workflow — alongside human review before release.

---

## Requirements

|  | Minimum |
| --- | --- |
| **Node.js** | `>= 22` ([`package.json` engines](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/package.json)) |
| **Node-RED** | `>= 4` ([`node-red.version`](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/package.json)) |
| **Install** | Palette Manager or `npm install node-red-contrib-modbus` |

Older Node.js / Node-RED combinations: see historical notes in [HISTORY.md](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/HISTORY.md). Prefer staying on current LTS Node.js with this release line.

**Serial (RTU/ASCII):** supported and tested on Node.js **22** and **24**. Node.js **26** serial is a known risk (intermittent \~1 s delays / Queue full) until `@serialport/bindings-cpp` upstream improves — see [#585](https://github.com/BiancoRoyal/node-red-contrib-modbus/issues/585). TCP is unaffected.

---

## What’s in the package (v5)

TCP / serial Modbus **client** nodes plus an in-package **buffer Modbus TCP server** for demos and tests.

| Palette node | Role |
| --- | --- |
| **Modbus-Client** | Config: TCP or Serial, queue, reconnect (XState FSM) |
| **Modbus-Read** | Periodic FC1–4 poll |
| **Modbus-Getter** | On-demand FC1–4 read |
| **Modbus-Flex-Getter** | Payload-driven FC1–4 read |
| **Modbus-Write** | FC5 / 6 / 15 / 16 write |
| **Modbus-Flex-Write** | Payload-driven write |
| **Modbus-Flex-Sequencer** | Ordered multi-range reads |
| **Modbus-Flex-FC** | Custom FC maps (`extras/argumentMaps`) |
| **Modbus-Flex-Connector** | Runtime reconnect / endpoint switch |
| **Modbus-Queue-Info** | Client queue depth / reset |
| **Modbus-Response** | Status display for responses |
| **Modbus-IO-Config** | Named IO JSON mapping |
| **Modbus-Response-Filter** | Filter IO payload by name |
| **Modbus-Server** | Buffer-backed TCP slave (jsmodbus) |

**Not in v5:** TLS client (`Modbus-Client-TLS` is v6), flow-based dynamic request/response gateway ([#567](https://github.com/BiancoRoyal/node-red-contrib-modbus/issues/567) → separate package recommendation), `modbus-flex-server` (own package — see below).

### Highlights since 5.46 / in 5.50.0

- Client **FSM / reconnect / queue** hardening (from 5.46.x)
- Safer **unit ID** handling ( `unitId` / `unitid`, including unit `0`)
- Modbus address/quantity validation improvements
- Numbered **learning examples** `01`… `18` + [Learning Path docs](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/docs/LEARNING-PATH.md)
- **Requires Node-RED `>= 4`** and **Node.js `>= 22`**

See [CHANGELOG.md](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/CHANGELOG.md) for the full list.

---

## How to use / Learning Path

**Recommended:** use the in-package **numbered learning examples** (`01` … `15`).

1. Install this package and restart Node-RED.
2. Open **Menu → Import → Examples → `node-red-contrib-modbus`**.
3. Work through the flows in order (or jump to a single node tutorial).

| Doc | Content |
| --- | --- |
| [**Learning Path guide**](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/docs/LEARNING-PATH.md) | Stages, Modbus cheat sheet, node ↔ example map |
| [**Examples index**](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/examples/README.md) | Full file list, TCP ports, IO path, old→new mapping |
| [Docs hub](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/docs/README.md) | All documentation entry points |

Each example tab has an English **comment** node with run instructions. Node sidebar help points at the matching example filename.

| Learn… | Import example |
| --- | --- |
| Modbus registers & FCs | `01-Modbus-Basics-Registers-And-FCs` |
| First TCP client + server | `02-Getting-Started-Client-And-Server` |
| Polling / on-demand / flex read-write | `03` … `06` |
| Sequencer, Flex-FC, Connector, Queue, IO | `07` … `11` |
| Buffer server & patterns (HTTP, serial, gateway) | `12` … `15` |

Also: [Wiki / DEBUG](https://github.com/BiancoRoyal/node-red-contrib-modbus/wiki/DEBUG) · [YouTube Playlist](http://bit.ly/2jzwjqP) · [Leanpub Modbus book](https://leanpub.com/p4nr-contribution-modbus/) · optional older flow on [flows.nodered.org](https://flows.nodered.org/flow/bf06a87e84395e4bce276714c6f5f884)

![Flow Example](https://raw.githubusercontent.com/BiancoRoyal/node-red-contrib-modbus/master/images/Screenshot01V210.png)

---

## Install

In your Node-RED user directory (typically `~/.node-red`):

```bash
npm install node-red-contrib-modbus
```

Global (less common):

```bash
npm install -g node-red-contrib-modbus
```

If native modules fail to build:

```bash
npm install node-red-contrib-modbus --unsafe-perm --build-from-source
```

List published versions:

```bash
npm show node-red-contrib-modbus versions
```

Install a specific version (example):

```bash
npm install node-red-contrib-modbus@5.45.2
```

### Runtime libraries

| Package | Role in this contrib |
| --- | --- |
| [`@openp4nr/modbus-serial`](https://github.com/openp4nr/modbus-serial) | Modbus client I/O (TCP / serial / ASCII, etc.) |
| [`jsmodbus`](https://www.npmjs.com/package/jsmodbus) | In-package **Modbus-Server** (buffer slave) |
| [`@xstate/fsm`](https://www.npmjs.com/package/@xstate/fsm) | Client connection state machine |
| [`serialport`](https://www.npmjs.com/package/serialport) / `@serialport/list` | **Optional** — list serial ports in the UI (not the runtime Modbus stack) |

If TCP fails, verify connectivity with a plain Modbus client first. If serial fails, verify the port with [`serialport`](https://www.npmjs.com/package/serialport) first.

Logging uses the [`debug`](https://www.npmjs.com/package/debug) package (not winston — winston is a v6 direction):

```bash
DEBUG=contribModbus*,modbus-serial node-red -v
```

More options: [Wiki DEBUG](https://github.com/BiancoRoyal/node-red-contrib-modbus/wiki/DEBUG).

---

## Modbus Flex Server (separate package)

**Modbus-Flex-Server** was moved out of this package (vm2 / maintenance boundary). Install the dedicated contrib if you still need it. Further package splits (client vs server) remain a longer-term v6 architecture topic; **v5 keeps `Modbus-Server` in this package** as the buffer slave for demos and tests.

---

## P4NR B2B Community

The [P4NR B2B Community](https://plus4nodered.com/) (driven by [Iniationware](https://iniationware.com/)) supports development and commercial help around Modbus for Node-RED. Bianco Royal partners with P4NR.

- [PLUS for Node-RED International](https://plus4nodered.com/)
- [PLUS for Node-RED Germany](https://plus4nodered.com/de/)

### Leanpub live book

The [Online Leanpub Book](https://leanpub.com/p4nr-contribution-modbus/) (Edition 2 for **5.60+**, Node-RED 5 / Node.js 24) covers v5.x nodes and options in depth (“buy once, update forever”). For a free start in this repo, use the [**Learning Path**](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/docs/LEARNING-PATH.md) (examples `01`–`18`).

---

## Errors & status

From v5.22 onward, client and server nodes catch many network and protocol errors so Node-RED should not crash for those handled cases. Always watch **node status**, **Catch** nodes, and optional empty-msg-on-fail settings in your flows.

---

## Contributing

Contributors welcome. Fork the repo and open PRs against **`develop`** (or discuss via issues). For larger features, see the maintainer pipeline under [`docs/p4nr/`](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/docs/p4nr/README.md).

Useful scripts (see `package.json`):

```bash
npm run build          # lint + gulp → modbus/
npm test               # Mocha (parallel)
npm run test:units
npm run coverage
npm run dev-link       # local link into Node-RED
```

## Authors

Since April 2016 by [Klaus Landsdorf](https://github.com/biancode) and the community.

- Contribution since 2016: [Contributors](https://github.com/BiancoRoyal/node-red-contrib-modbus/graphs/contributors)
- License change 2016: [Jason D. Harper](https://github.com/jayharper)
- Started early 2015: [Mika Karaila](https://github.com/mikakaraila)

[Version history](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/HISTORY.md) · [CHANGELOG](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/CHANGELOG.md)

---

## Contributors

### Code Contributors

This project exists thanks to all the people who contribute. \[[Contribute](https://github.com/BiancoRoyal/node-red-contrib-modbus/blob/master/CONTRIBUTING.md)].

### Financial Contributors

Become a financial contributor and help us sustain our community. \[[Contribute](https://opencollective.com/node-red-contrib-modbus/contribute)]

#### Individuals

#### Organizations

Support this project with your organization. Your logo will show up here with a link to your website. \[[Contribute](https://opencollective.com/node-red-contrib-modbus/contribute)]

## **Installation **

Install in Node-RED via the [**palette manager**](https://flowfuse.com/docs/node-red/getting-started/library/#using-the-palette-manager).

![Node-RED Palette Manager dialog with the node selected and the Install button visible.](https://flowfuse.com/.netlify/images?w=707&h=376&fm=webp&q=80&url=%2Fimages%2Fintegrations%2Fpalette-manager-install.png)

## **Quick Stats**

Current Version**5.62.1**

Weekly Downloads**3,677**

First Published**Aug 27, 2015**

Last Updated**Oct 25, 2026**

## **GitHub Stats**

[Open Issues ![GitHub Issues](https://img.shields.io/github/issues/BiancoRoyal/node-red-contrib-modbus.svg?style=flat-square)](https://github.com/BiancoRoyal/node-red-contrib-modbus/issues) [ Stars ![GitHub Stars](https://img.shields.io/github/stars/BiancoRoyal/node-red-contrib-modbus.svg?style=flat-square)](https://github.com/BiancoRoyal/node-red-contrib-modbus/stargazers) [ Forks ![GitHub Forks](https://img.shields.io/github/forks/BiancoRoyal/node-red-contrib-modbus.svg?style=flat-square)](https://github.com/BiancoRoyal/node-red-contrib-modbus/network/members)

## **External Resources**

[View on NPM](https://www.npmjs.com/package/node-red-contrib-modbus) [ View Repository](https://github.com/BiancoRoyal/node-red-contrib-modbus)

## **Need Help?**

Get professional support for your Node-RED projects with FlowFuse.

[**Contact Us**](https://flowfuse.com/contact-us/)

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://flowfuse.com/#website","@type":"WebSite","description":"FlowFuse builds your first industrial solution with your team, proves it at one plant, then helps you roll it out to every plant, faster each time.","inLanguage":"en","name":"FlowFuse","url":"https://flowfuse.com/","alternateName":["FlowForge","Flow Fuse"],"publisher":{"@id":"https://flowfuse.com/#identity"}},{"@id":"https://flowfuse.com/integrations/node-red-contrib-modbus/#webpage","@type":"WebPage","description":"FlowFuse builds your first industrial solution with your team, proves it at one plant, then helps you roll it out to every plant, faster each time.","name":"node-red-contrib-modbus","url":"https://flowfuse.com/integrations/node-red-contrib-modbus/","isPartOf":{"@id":"https://flowfuse.com/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://flowfuse.com/integrations/node-red-contrib-modbus/"]}],"primaryImageOfPage":{"@id":"https://flowfuse.com/#logo"}},{"@id":"https://flowfuse.com/#identity","@type":"Organization","legalName":"FlowFuse Inc.","name":"FlowFuse","url":"https://flowfuse.com","alternateName":["FlowForge","Flow Fuse"],"logo":{"@id":"https://flowfuse.com/#logo"},"sameAs":["https://twitter.com/FlowFuseinc","https://github.com/FlowFuse","https://www.linkedin.com/company/flowfuse/","https://www.facebook.com/FlowFuse/","https://www.youtube.com/channel/UCbBzP8NZbv3WDtlt4UouA-g"]},{"@id":"https://flowfuse.com/#logo","@type":"ImageObject","caption":"FlowFuse","contentUrl":"https://flowfuse.com/handbook/images/logos/ff-logo--square--dark.png","inLanguage":"en","url":"https://flowfuse.com/handbook/images/logos/ff-logo--square--dark.png"}]}
```

## Sitemap

See the full [sitemap](https://flowfuse.com/sitemap.md) for all pages.
