Node-RED Serial Port Communication Nodes

2.0.3 verified Sat Apr 25 auth: no javascript

node-red-node-serialport provides a set of nodes for Node-RED, enabling communication with hardware serial ports (e.g., RS232, RS485, USB-to-serial adapters). It integrates the widely used `serialport` library to offer Input, Output, Request, and Control nodes directly within the Node-RED visual programming environment. The current stable version is 2.0.3, released in late 2023. This package is actively maintained, with significant updates in major versions to align with Node.js and underlying `serialport` library advancements. Its primary differentiator is seamless integration into Node-RED flows, allowing developers to manage serial communications visually and programmatically without writing custom boilerplate code for port management.

Common errors

error Error: The module '/path/to/node_modules/serialport/build/Release/serialport.node' was compiled against a different Node.js version using NODE_MODULE_VERSION XX. This version of Node.js requires NODE_MODULE_VERSION YY. ↓

cause Mismatch between the Node.js version installed in your environment and the version against which the native `serialport` module was compiled.

fix

Ensure your Node.js version meets the package requirements (>=16.0.0 for node-red-node-serialport v2.x). If Node.js was recently updated or downgraded, reinstall node-red-node-serialport to recompile its native dependencies for the current Node.js version: npm rebuild node-red-node-serialport or npm install node-red-node-serialport in your Node-RED user directory.

error Error: Cannot open serial port '/dev/ttyUSB0': Permission denied ↓

cause The Node-RED process does not have sufficient permissions to access the specified serial port device.

fix

On Linux, add the Node-RED user to the dialout or uucp group: sudo usermod -a -G dialout $USER (replace $USER with the user running Node-RED, or pi if on Raspberry Pi). A reboot or logging out and back in may be required for group changes to take effect. Ensure the device path is correct.

error TypeError: Cannot read properties of undefined (reading 'split') ↓

cause This error often occurs in 'Function' nodes or other processing nodes when `msg.payload` is not a string, but the code expects it to be (e.g., when trying to call `.split()` on a Buffer or `undefined` payload).

fix

Ensure that the Serial In node's output type is configured correctly (e.g., 'UTF8 string' if you expect string data for .split()). Use a 'Change' or 'Function' node upstream to convert msg.payload to a string using msg.payload.toString() if it might be a Buffer, or add checks like if (typeof msg.payload === 'string') { ... }.

Warnings

gotcha During installation via `npm i node-red-node-serialport`, there may be messages about optional compilation failures. These often appear as errors but are typically warnings for optional dependencies and the node will still install and function correctly. Only be concerned if the install process explicitly fails at the end. ↓

fix Verify successful installation by checking the Node-RED palette for the serial nodes. If they appear, the 'failures' were likely benign compilation warnings. If problems persist, ensure you have necessary build tools installed (e.g., `build-essential` on Linux, Visual Studio build tools on Windows).

breaking The 'Split char' option in the 'Serial In' node now defaults to `\n` (newline) instead of being empty. If you previously relied on an empty split character to stream single characters, you must explicitly set the split character field to an empty string. ↓

fix For existing flows, review 'Serial In' nodes and explicitly set the 'Split char' to an empty string if streaming single characters is the desired behavior. For new flows, be aware of the new default split behavior.

breaking The `serialport` configuration node (which defines the port settings) no longer supports `timeout`, `delimiter`, or `length` properties. These parsing-related options are now configured directly within the 'Serial In' node itself. ↓

fix Migrate parsing configurations (timeout, delimiter, length) from the shared serialport configuration node to the individual 'Serial In' nodes where they are used. Review and update all 'Serial In' nodes after upgrading.

breaking The `msg.port` property is no longer automatically added to messages output by the 'Serial In' node. It is still added by the 'Serial Request' node for consistency. ↓

fix If your flows relied on `msg.port` from 'Serial In' nodes, you will need to manually add this information (e.g., using a 'Change' node) or refactor to use 'Serial Request' nodes if applicable, or retrieve the port name from the node configuration directly if needed downstream.

breaking Node.js 16.0.0 or higher is now required. Running with older Node.js versions will result in errors or prevent the node from loading. ↓

fix Upgrade your Node.js installation to version 16.0.0 or newer. Check your Node-RED environment's Node.js version (`node -v`) and update if necessary.

Install

npm install node-red-node-serialport

yarn add node-red-node-serialport

pnpm add node-red-node-serialport

Imports

Serial In Node
wrong
```
import { SerialInNode } from 'node-red-node-serialport'
```
correct
```
Drag 'Serial In' node from Node-RED palette onto canvas.
```
Node-RED packages are installed via the 'Manage palette' interface or npm, then configured visually in the Node-RED editor, not imported directly into user JavaScript code.
Serial Out Node
wrong
```
const SerialOutNode = require('node-red-node-serialport')
```
correct
```
Drag 'Serial Out' node from Node-RED palette onto canvas.
```
Interaction with Node-RED nodes is entirely within the visual flow editor; there are no direct programmatic imports for end-user flows.
Serial Control Node
wrong
```
import type { SerialControlConfig } from 'node-red-node-serialport'
```
correct
```
Drag 'Serial Control' node from Node-RED palette onto canvas.
```
Configuration of Node-RED nodes is handled through their respective dialogs in the editor, and their behavior is defined by messages passed within the flow, not via TypeScript types in user code.

Quickstart

Illustrates how to install the Node-RED package and provides a JavaScript object representing a message payload to programmatically configure and control a serial port using the 'Serial Control' node in a Node-RED flow.

/*
  To install node-red-node-serialport, run this command in your Node-RED user directory (typically ~/.node-red):
*/
npm i node-red-node-serialport

/*
  After installation, the nodes will appear in your Node-RED palette.
  To dynamically control a serial port, configure a 'Serial Control' node
  and send it a message like the following (e.g., from an 'Inject' node
  or 'Function' node):
*/

// Example message to configure and enable a serial port via a 'Serial Control' node
const controlMessage = {
    "payload": {
        "serialport": "/dev/ttyUSB0", // Or "COM1" on Windows
        "serialbaud": 115200,
        "databits": 8,
        "parity": "none",
        "stopbits": 1,
        "enabled": true
    }
};

// In a Node-RED Function node, you would typically return msg like this:
// return controlMessage;

console.log("Node-RED Serial Control Message Example:", controlMessage);
// In a real Node-RED flow, this message would be wired into a 'Serial Control' node.