Node-RED Complete Guide: From First Flow to Home Automation

Node-RED connects devices, APIs and services by arranging small building blocks into visual flows. Begin with one message, inspect it, add a condition, and gradually connect sensors, dashboards and automations.

This is SolderHub's roadmap for learning Node-RED. It starts with the editor and message model, moves into MQTT and real ESP32 hardware, then introduces dashboards, data storage, notifications, security and maintainable flows. Follow it in order or jump to the section that matches your project.

An important distinction: Node-RED is normally the automation runtime running on a computer, server or Raspberry Pi. It is not firmware that runs directly on an ESP32. The ESP32 reads physical inputs and controls its pins; Node-RED receives messages and coordinates the larger workflow.

What Node-RED does—and where it runs

A node performs a task, such as creating a message, subscribing to a topic, converting a value or sending an HTTP request. A flow is the connected sequence of nodes. A message carries data between them; its main payload is commonly stored in the property msg.payload.

A temperature workflow might receive a reading from an ESP32, convert the payload to a number, compare it with a threshold, display it on a dashboard and send an alert only when needed. Each stage is visible and can be tested separately.

Node-RED is useful for prototyping and integration, but a visually simple flow can still become unreliable if it ignores reconnects, malformed data, permissions or error handling. Learn the message model first, then build complexity in small steps.

Step 1: understand nodes, flows and messages

Start with Node-RED Tutorial for Beginners: Nodes, Flows & msg.payload. It explains how nodes pass JavaScript message objects, why the payload may be a string, number, Boolean or object, and how to use Inject and Debug to inspect each step.

Your first flow can be Inject → Function → Debug. Inject creates a known input. Function transforms the message and returns it. Debug lets you confirm what the next node receives. Deploy after editing, and change one thing at a time so a failed flow is easy to diagnose.

Step 2: run Node-RED reliably on Raspberry Pi 5

A Raspberry Pi is a practical host for a small home-automation server. Follow Install Node-RED on Raspberry Pi 5: Autostart & Remote Editor to install Node-RED, run it as a systemd service, enable autostart and access the editor from another computer on your local network.

Treat the Pi as the always-on automation host. Confirm that the service starts after reboot, that you can reach the editor using the Pi's actual LAN address, and that a flow still behaves correctly after a restart. Node.js requirements and installer behavior can change, so use the current Node-RED getting-started documentation rather than pinning an old version from a dated tutorial.

Step 3: connect devices with MQTT

MQTT is a publish/subscribe messaging protocol often used to connect constrained devices and automation systems. A device publishes a message to a topic; a broker routes it to subscribers. Node-RED can publish with MQTT Out nodes and receive messages through MQTT In nodes.

Follow Node-RED with MQTT: Connect Mosquitto, Publish & Subscribe to connect the editor to an existing broker and test messages before adding hardware. Then use Install Mosquitto on Raspberry Pi 5 if you want to host your own broker.

Use clear topic names, distinguish commands from reported state, and decide whether a message should be retained. A retained command such as ON can be replayed to a reconnecting device; that may be wrong for a physical actuator. Retained state is often safer than a retained one-shot action.

Step 4: take the flow to real ESP32 hardware

Once the broker path works, connect a real board. Control an ESP32 LED with Node-RED and MQTT sends explicit ON and OFF commands through MQTT and reports device state back. It is a useful first hardware integration because it makes the whole command path visible without requiring a sensor.

A reliable design separates command and reported-state topics. Do not assume publishing an ON command proves the pin changed. Wait for state feedback or a meaningful acknowledgement, and show connection status separately from the output's last reported state.

For sensors, validate incoming payloads before converting them to numbers. Reject empty strings, unexpected JSON shapes and out-of-range values rather than silently turning them into zero. For relay and mains projects, hardware safety and appropriate isolation matter regardless of whether the command came from a dashboard or an automation.

Step 5: build a modern dashboard

For new dashboard work, use FlowFuse Dashboard, often called Dashboard 2.0, package @flowfuse/node-red-dashboard. The legacy node-red-dashboard package is deprecated. Install the modern package from Palette Manager and build the interface with its own UI nodes; do not assume legacy nodes and settings will transfer unchanged.

Start with Node-RED Dashboard 2.0: Install Buttons, Switches & Gauges. Build a button, a switch and a gauge, and connect each widget to a flow that validates inputs and reports its result. For real hardware, update displayed state from device feedback rather than trusting the browser widget's last click.

Read the official Dashboard 2.0 getting-started guide and migration guide before upgrading an existing interface.

Step 6: add sensors, serial data and HTTP APIs

Data can reach Node-RED in several ways:

• MQTT: a good fit for Wi-Fi devices such as ESP32 boards that publish structured measurements.
• Serial: useful when an Arduino Uno or Nano sends newline-delimited readings over USB. Select the correct port and baud rate; keep debugging text separate from machine-readable data.
• HTTP: useful when a device sends JSON to an endpoint or a flow calls an external API. Validate method, body shape, authentication and response codes.
• Camera snapshots: an ESP32-CAM can expose or send an image, but browser access, network routing and authentication should be designed explicitly.

For a live sensor dashboard, label units and timestamps. A stale sensor value is not the same as a zero reading, and no incoming message should not be mistaken for a valid measurement.

Step 7: move from a demo to useful automation

A dashboard lets a person request an action. An automation decides when to act. Begin with a schedule or an LDR-based lighting rule, then add conditions such as occupancy, time window and a minimum interval between actions.

For motion alerts, use a state transition to detect the start of an event, then add a delay, rate limit or cooldown. Otherwise a PIR sensor held HIGH may create dozens of messages. Make notifications idempotent where possible: repeated input messages should not create repeated physical actions or a flood of alerts.

If you store measurements, give each record a timestamp and clear unit. InfluxDB is designed for time-series measurements; Grafana can query and visualize them. Decide a retention period early, and do not store unlimited debug messages as a substitute for a data model.

Step 8: make flows understandable and recoverable

As a flow grows, use subflows for reusable logic, Link In/Out nodes to separate areas of a workspace, and Catch nodes to route supported node errors to an explicit handler. Label nodes according to their purpose, validate messages at system boundaries, and handle empty or malformed data intentionally.

Keep operational state separate from the last measurement. A sensor may report 0 °C; that does not mean it has disconnected. Track last-seen time, device availability and timestamp alongside values. Decide what should survive a restart and configure context storage accordingly; in-memory context alone is not durable.

Export important flows regularly, store reviewed exports in Git, and document credentials as environment/configuration requirements rather than embedding secrets in shared flow JSON. A backup should be restorable; periodically prove you can restore it to a test instance.

Security before remote access

A default Node-RED editor is not a public-facing authenticated control panel. The official documentation warns that the editor is unsecured by default; anyone who can reach it may be able to modify flows. On a trusted LAN this may be acceptable for initial development, but it is not appropriate for direct internet exposure.

Before remote access, configure editor/admin authentication, HTTPS or a secure reverse-proxy setup, restrict network access, and secure HTTP endpoints and dashboards. Use MQTT authentication, topic access controls and TLS when traffic crosses networks you do not trust. Store tokens and passwords outside exported flows, redact secrets from screenshots, and keep Node.js, Node-RED and installed nodes updated.

Official reference: Securing Node-RED. Do not port-forward editor port 1880 straight to the public internet.

The SolderHub Node-RED learning path

The pillar should be published after the full set of linked guides has been written, reviewed and published.

Beginner

• Node-RED Tutorial for Beginners: Nodes, Flows & msg.payload
• Install Node-RED on Raspberry Pi 5: Autostart & Remote Editor
• Your First Node-RED Flow: Inject, Function & Debug
• Node-RED with MQTT: Connect Mosquitto, Publish & Subscribe
• Control an ESP32 LED with Node-RED and MQTT

Intermediate

• Node-RED Dashboard 2.0: Install Buttons, Switches & Gauges
• Live DHT11 and BMP280 Dashboard with ESP32 and MQTT
• Read Arduino Uno/Nano Sensors over Serial in Node-RED
• 8-Channel Relay Dashboard with MQTT State Feedback
• HTTP In Node-RED: Build an API and Receive ESP32 POST Data

Advanced

• PIR Motion Alerts to Telegram or Email without Notification Floods
• InfluxDB and Grafana: Store and Chart Node-RED Sensor Data
• Node-RED Automations: Schedules, LDR Lighting and Context
• ESP32-CAM Motion Snapshots in a Node-RED Dashboard
• Secure Node-RED: Login, HTTPS, MQTT TLS, Backups and Git
• Reliable Node-RED Flows: Subflows, Link Nodes and Catch

Frequently asked questions

Does Node-RED run on an ESP32? Normally no. Run the Node-RED runtime on a computer, Raspberry Pi or server and let the ESP32 execute its own firmware while exchanging data through MQTT, HTTP or another transport.

Should I use the old Dashboard package? For new work, start with @flowfuse/node-red-dashboard. The legacy package is deprecated; plan migration rather than mixing tutorials written for different node sets.

Can Node-RED control GPIO on Raspberry Pi 5? Raspberry Pi 5 uses the RP1 I/O controller and its GPIO software stack differs from older models. Do not copy a legacy GPIO-node tutorial without checking current Pi 5 support and testing the exact hardware/software combination. For a portable first hardware path, use an ESP32 over MQTT and keep the Pi as the server.

Can I expose the editor over the internet? Not without a deliberate security design. Add authentication, encrypted access and network restrictions; a public port-forward is not sufficient.

Official documentation

• Node-RED getting started
• Node-RED messages
• Node-RED Function node
• Node-RED on boot
• Node-RED security
• FlowFuse Dashboard 2.0

A useful learning path teaches readers to verify message shapes, separate commands from state, handle failures, secure access and understand which component owns each responsibility.