{"id":18048,"library":"node-red-node-serialport","title":"Node-RED Serial Port Communication Nodes","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/node-red/node-red-nodes","tags":["javascript","node-red","serial"],"install":[{"cmd":"npm install node-red-node-serialport","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-node-serialport","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-node-serialport","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for accessing serial ports. This Node-RED package is a wrapper around it.","package":"serialport","optional":false},{"reason":"Used by the Input node for parsing incoming data based on a readline delimiter.","package":"@serialport/parser-readline","optional":false}],"imports":[{"note":"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.","wrong":"import { SerialInNode } from 'node-red-node-serialport'","symbol":"Serial In Node","correct":"Drag 'Serial In' node from Node-RED palette onto canvas."},{"note":"Interaction with Node-RED nodes is entirely within the visual flow editor; there are no direct programmatic imports for end-user flows.","wrong":"const SerialOutNode = require('node-red-node-serialport')","symbol":"Serial Out Node","correct":"Drag 'Serial Out' node from Node-RED palette onto canvas."},{"note":"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.","wrong":"import type { SerialControlConfig } from 'node-red-node-serialport'","symbol":"Serial Control Node","correct":"Drag 'Serial Control' node from Node-RED palette onto canvas."}],"quickstart":{"code":"/*\n  To install node-red-node-serialport, run this command in your Node-RED user directory (typically ~/.node-red):\n*/\nnpm i node-red-node-serialport\n\n/*\n  After installation, the nodes will appear in your Node-RED palette.\n  To dynamically control a serial port, configure a 'Serial Control' node\n  and send it a message like the following (e.g., from an 'Inject' node\n  or 'Function' node):\n*/\n\n// Example message to configure and enable a serial port via a 'Serial Control' node\nconst controlMessage = {\n    \"payload\": {\n        \"serialport\": \"/dev/ttyUSB0\", // Or \"COM1\" on Windows\n        \"serialbaud\": 115200,\n        \"databits\": 8,\n        \"parity\": \"none\",\n        \"stopbits\": 1,\n        \"enabled\": true\n    }\n};\n\n// In a Node-RED Function node, you would typically return msg like this:\n// return controlMessage;\n\nconsole.log(\"Node-RED Serial Control Message Example:\", controlMessage);\n// In a real Node-RED flow, this message would be wired into a 'Serial Control' node.\n","lang":"javascript","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"Mismatch between the Node.js version installed in your environment and the version against which the native `serialport` module was compiled.","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."},{"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.","cause":"The Node-RED process does not have sufficient permissions to access the specified serial port device.","error":"Error: Cannot open serial port '/dev/ttyUSB0': Permission denied"},{"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') { ... }`.","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).","error":"TypeError: Cannot read properties of undefined (reading 'split')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}