Node-RED Raspberry Pi: Complete Flow Automation Guide

Q: Do I need Node-RED if I already have Home Assistant?

Not necessarily. Home Assistant covers most home automation logic directly. Node-RED is better for complex multi-step flows, data transformation before logging to InfluxDB, and standalone dashboards. Many users run both.

Q: Can Node-RED run on a Pi Zero 2 W?

Yes, with the memory flag: node-red-pi --max-old-space-size=128. Simple MQTT and InfluxDB flows run well. Pi 4 is the practical choice for setups with 20 or more active flows.

Q: What is the difference between Dashboard 2 and the original dashboard?

The original node-red-dashboard v1 is in maintenance mode. Dashboard 2 (@flowfuse/node-red-dashboard) is the actively maintained replacement with a Vue 3 frontend, more widget types, and better mobile support. All new projects should use Dashboard 2.

Q: How do I back up my flows?

The entire Node-RED state lives in ~/.node-red/ and contains flows.json, settings.js, and installed palette nodes. Copying this directory is a complete backup. Individual flows can be exported as JSON from Menu > Export in the editor.

Node-RED Raspberry Pi turns a Pi 4 into a visual flow automation engine that connects MQTT devices, HTTP APIs, sensors, and databases without writing application code. Flows are built by wiring nodes together in a browser-based editor: an MQTT input node subscribes to a Zigbee2MQTT topic, a function node filters the payload, and an InfluxDB node logs the result. All of this is configured through a drag-and-drop interface. This guide covers installation using the official script, security hardening, practical flows for MQTT and ESPHome device data, Dashboard 2 for sensor display, InfluxDB logging, and HTTPS access via Caddy.

Key Takeaways

The Node-RED editor is unauthenticated by default. Anyone on your network can open http://<pi-ip>:1880 and modify your flows. Add adminAuth to settings.js immediately after installation.
Use the official install script rather than npm install -g node-red or installing from the Debian repos. The script installs Node.js 22 LTS via NodeSource, sets up the systemd service with Pi-appropriate memory limits, and provides the node-red-start, node-red-stop, and node-red-log convenience commands.
Dashboard 2 (@flowfuse/node-red-dashboard) is the current dashboard package. The older node-red-dashboard v1 is in maintenance mode. Install Dashboard 2 from the palette manager for current features and active maintenance.

Node-RED Raspberry Pi: How It Works

Node-RED is a flow-based programming environment where logic is expressed as connected nodes rather than written code. A flow is a sequence of nodes: input nodes receive data (from MQTT topics, HTTP requests, timers, or GPIO pins), processing nodes transform or filter it, and output nodes send it somewhere (to a database, another MQTT topic, a dashboard, or an HTTP endpoint). Flows are defined in the browser-based editor and deployed to the Node-RED runtime running on the Pi with a single click.

This architecture makes Node-RED well suited for home automation glue work: subscribing to Zigbee2MQTT sensor readings and logging them to InfluxDB, triggering actions when ESPHome devices report state changes, or aggregating data from multiple sources into a single dashboard. The MQTT nodes are built in, the InfluxDB and dashboard nodes install from the palette manager in two clicks, and the flows survive Pi reboots automatically.

Installation

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. In the advanced settings, set hostname, enable SSH, and configure credentials. After first boot:

sudo apt update && sudo apt full-upgrade -y
sudo apt install build-essential git curl -y

Run the official Node-RED install script. This installs Node.js 22 LTS via NodeSource and Node-RED, sets up the systemd service, and optionally installs Pi-specific nodes:

bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-nodered-deb)

The script prompts whether to install Pi-specific nodes (GPIO, Pi camera) and whether to initialise the settings file. Answer yes to both. When complete, enable the service to start at boot and start it now:

sudo systemctl enable nodered.service
node-red-start

Expected result: The node-red-start output shows the Node-RED version, Node.js version, and the URL the editor is listening on. Navigate to http://<pi-ip>:1880 and the Node-RED editor loads with an empty flow canvas.

Security: Locking Down the Editor

Before building any flows, add authentication to the editor. Open the settings file:

nano ~/.node-red/settings.js

Find the adminAuth section (it is commented out by default) and replace it with:

adminAuth: {
    type: "credentials",
    users: [{
        username: "admin",
        password: "$2b$08$...",
        permissions: "*"
    }]
},

Generate the bcrypt password hash using the Node-RED built-in tool:

node-red admin hash-pw

Enter your chosen password when prompted. Copy the full $2b$... hash output into the password field in settings.js. Restart Node-RED:

node-red-restart

Expected result: Navigating to http://<pi-ip>:1880 now shows a login screen. The editor loads only after entering the username and password set above.

Node-RED Raspberry Pi flow architecture diagram showing MQTT input function node InfluxDB output and Dashboard 2 display

Installing Additional Nodes

In the editor, go to Menu (top right) > Manage Palette > Install tab. Search for and install:

@flowfuse/node-red-dashboard: Dashboard 2, the current dashboard package for building sensor displays and controls
node-red-contrib-influxdb: InfluxDB v1 and v2 output and input nodes for logging and querying the monitoring stack

The MQTT nodes (mqtt in, mqtt out) are built into Node-RED and require no additional installation.

Practical Flows

Flow 1: Zigbee2MQTT sensor to InfluxDB

This flow subscribes to all Zigbee2MQTT device topics, extracts temperature and humidity readings, and logs them to InfluxDB. It requires a running Mosquitto broker and Zigbee2MQTT instance. See Zigbee2MQTT Raspberry Pi for the broker and coordinator setup.

Build the flow by wiring these nodes in sequence:

mqtt in node: Server localhost:1883, Topic zigbee2mqtt/+, QoS 0, Output: parsed JSON object
function node named “Extract sensor data”: filters for temperature readings and formats the payload for InfluxDB
influxdb out node: Version 2.x, URL http://localhost:8086, Token from your InfluxDB setup, Organisation home, Bucket metrics, Measurement zigbee_sensor

Function node code:

// Only pass through messages that have temperature data
if (msg.payload.temperature === undefined) {
    return null;
}

// Extract the device name from the topic
// Topic format: zigbee2mqtt/device_name
const device = msg.topic.split('/')[1];

msg.payload = [
    {
        temperature: msg.payload.temperature,
        humidity: msg.payload.humidity || 0,
        battery: msg.payload.battery || 100
    },
    {
        device: device,
        location: device
    }
];

return msg;

Expected result: After deploying the flow, open the InfluxDB data explorer at http://<pi-ip>:8086. Within 60 seconds of a Zigbee sensor reporting, measurements appear in the metrics bucket under measurement zigbee_sensor with fields temperature, humidity, and battery, tagged with the device name.

Flow 2: ESPHome device state and control

ESPHome devices using the MQTT component publish state to esphome/device_name/sensor/sensor_name/state and accept commands on esphome/device_name/switch/switch_name/command. Wire a flow that logs the state and provides a toggle:

mqtt in node: Topic esphome/#, Output: string
switch node named “Route by type”: routes motion sensor messages to one branch, temperature to another
debug node on each branch during development. Replace with influxdb out or dashboard nodes once the routing is verified.

To send a command back to an ESPHome relay, use an mqtt out node with topic esphome/device_name/switch/relay1/command and payload ON or OFF. Wire a Dashboard 2 toggle switch to the mqtt out node for manual control from the dashboard.

For ESPHome device setup including MQTT component configuration, see ESPHome Raspberry Pi.

Flow 3: Pi system health alert

This flow reads Pi CPU temperature every 60 seconds and sends a notification if it exceeds 75°C. It uses the built-in exec node to read the thermal zone directly:

inject node: Repeat every 60 seconds
exec node: Command cat /sys/class/thermal/thermal_zone0/temp, Append msg.payload: unchecked
function node named “Check threshold”: converts millidegrees to Celsius and routes high temperatures to an alert branch
mqtt out node or http request node for the alert (Pushover, Gotify, Home Assistant webhook)

// Convert millidegrees to Celsius
const tempC = parseInt(msg.payload) / 1000;
msg.payload = { temperature: tempC };

if (tempC > 75) {
    msg.alert = true;
    msg.topic = "Pi temperature warning: " + tempC.toFixed(1) + "C";
}

return msg;

Dashboard 2 Setup

After installing @flowfuse/node-red-dashboard, a Dashboard 2 tab appears in the editor sidebar. Create a page and a group, then add dashboard nodes to your flows.

To display a Zigbee temperature sensor on a dashboard:

Add a ui-gauge node after the function node in Flow 1
Set the group to your dashboard group, label to the device name, and range to 0-40°C
Wire it alongside the influxdb out node (both nodes can receive the same message)

The Dashboard 2 UI is available at http://<pi-ip>:1880/dashboard. It is a separate page from the editor and does not require editor login credentials by default. Configure separate dashboard authentication in settings.js under ui if needed.

HTTPS Access with Caddy

Node-RED serves on HTTP by default. For secure remote access, put Caddy in front as a reverse proxy. The Caddyfile entry:

nodered.yourdomain.duckdns.org {
    reverse_proxy localhost:1880
}

For the full Caddy installation and DuckDNS setup, see Caddy Reverse Proxy Raspberry Pi. With HTTPS in place, the editor and Dashboard 2 are both accessible securely over the same domain.

Maintenance

Update Node-RED by re-running the install script:

bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-nodered-deb)

The script preserves existing flows and settings. Back up the ~/.node-red/ directory before major updates:

cp -r ~/.node-red ~/node-red-backup-$(date +%Y%m%d)

Export individual flows from the editor using Menu > Export > Download. Store the exported JSON files in version control alongside your other Pi configuration files. A flow export is all that is needed to restore a working setup on a fresh Node-RED install.

Troubleshooting

Editor not loading after restart

node-red-log

The most common causes after a settings change are a syntax error in settings.js (JavaScript, not JSON. Trailing commas in JS objects are valid but missing commas are not.) or an invalid bcrypt hash in adminAuth. The log shows the exact line number and error. Fix the settings file and run node-red-restart.

MQTT node shows disconnected

# Confirm Mosquitto is running
sudo systemctl status mosquitto

# Test the broker from the Pi
mosquitto_sub -h localhost -p 1883 -t '#' -v

Double-check the broker address in the MQTT node configuration. If Mosquitto requires authentication, add the username and password in the MQTT node’s broker settings. The node shows a green dot when connected and red when not.

InfluxDB node returns write errors

Open the debug panel (bug icon in the editor sidebar) and enable the debug output on the influxdb node. Common causes: wrong token, wrong organisation name, or the bucket does not exist. The error message from InfluxDB is passed through to the debug panel and identifies the exact problem. See Grafana InfluxDB Raspberry Pi for the full InfluxDB 2.x setup including token generation.

Flows not surviving reboot

# Confirm the service is enabled
sudo systemctl is-enabled nodered.service

# Enable if not already
sudo systemctl enable nodered.service

FAQ

Do I need Node-RED if I already have Home Assistant?

Not necessarily. Home Assistant’s automation engine covers most home automation logic directly. Node-RED is better suited for complex multi-step flows, data transformation before logging to InfluxDB, integrating non-Home-Assistant data sources, or building standalone dashboards that work without Home Assistant. Many users run both: Home Assistant handles device automations and Node-RED handles data pipelines and monitoring flows. See Home Assistant Raspberry Pi 5 for the HA setup.

Can Node-RED run on a Pi Zero 2 W?

Yes with the memory flag. Use node-red-pi --max-old-space-size=128 instead of node-red-start to limit Node.js heap size. Simple flows with a handful of MQTT subscriptions and an InfluxDB output run well on a Pi Zero 2 W. Complex flows with many nodes or heavy JavaScript in function nodes will be noticeably slower. Pi 4 is the practical choice for setups with 20 or more active flows.

What is the difference between Dashboard 2 and the original dashboard?

The original node-red-dashboard v1 is in maintenance mode with no new features. Dashboard 2 (@flowfuse/node-red-dashboard) is the actively maintained replacement with a Vue 3-based frontend, more widget types, better mobile support, and multi-page layouts. All new projects should use Dashboard 2. Existing v1 dashboards can continue to run but migrating to Dashboard 2 requires rebuilding the UI nodes.

Can I run multiple Node-RED instances on the same Pi?

Yes. Each instance needs its own port and user directory. Start additional instances with node-red --port 1881 --userDir ~/.node-red-2. The systemd service manages the primary instance; additional instances need their own service files or can run in Docker containers for isolation.

How do I back up my flows?

The entire Node-RED state lives in ~/.node-red/. This directory contains flows.json (all your flows), settings.js (configuration including credentials), and installed palette nodes. Copying this directory to another location is a complete backup. For individual flow export, use Menu > Export > Download in the editor to get a JSON file that imports cleanly on any Node-RED instance.

References

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB). Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. Node-RED 4.1, Node.js 22 LTS, Dashboard 2.x.

Was this helpful?

Yes

Thanks for your feedback!