Your First Node-RED Flow: Inject, Function and Debug

This tutorial builds a tiny flow that produces a visible result, changes a message and shows the output in Node-RED's Debug sidebar. No Raspberry Pi GPIO, sensor or MQTT broker is needed for this first exercise. The point is to learn how messages move through the editor before adding external systems.

A Node-RED flow is a series of connected nodes. Each node performs a task, and the runtime passes message objects between them. The standard property msg.payload commonly holds the main value, but it can be a string, number, Boolean, array or object. Inspect the actual message rather than guessing its type.

1. Open the editor and create a flow

Open your Node-RED editor in a browser. If Node-RED is on Raspberry Pi 5, use the Pi's LAN address and configured editor port; the browser and runtime are separate parts of the setup. See Install Node-RED on Raspberry Pi 5 if you need the server first.

Create a new flow tab and add three nodes: Inject, Function and Debug. Connect Inject to Function, then Function to Debug. A wire represents a message route—not an electrical wire.

2. Configure Inject

Open Inject. Set its payload type to string and value to hello. Give the node a clear label such as “Send hello”. Keep other settings at their defaults for this test, then click Done.

Inject can be triggered manually or scheduled. For now, use the small button beside the node to send one message on demand. That makes it easier to repeat a test and know exactly when the flow runs.

3. Configure the Function node

Open Function, give it a name and replace the starter code with this:

The Function node receives a message as msg. This code reads the incoming payload, converts it to text, adds a prefix and suffix, and returns the message object. Returning msg is important: returning a string by itself is not the normal Function-node contract. Keeping the message object also preserves other properties that upstream nodes may have added.

This first example uses a known Inject value. When data arrives from a sensor or network, validate its type and shape before using it.

4. Configure Debug and deploy

Open Debug and select msg.payload as its output. Click Done, then click Deploy in the editor. If you forget to deploy after editing, the runtime continues using the previous deployed version.

Click Inject once. The Debug sidebar should show:

SolderHub says: hello!

If nothing appears, confirm the Debug sidebar is enabled, the three nodes are wired together and the latest flow was deployed. Showing the complete message is useful while learning; showing only the payload keeps regular output concise.

5. Experiment safely

Change Inject's payload to Raspberry Pi 5 and deploy again. The output should become SolderHub says: Raspberry Pi 5!

Next, try a numeric payload. For external data, remember that strings such as “24.5” need explicit conversion before arithmetic, and inputs such as an empty string must not silently become a valid zero. In a production flow, route invalid data to a warning or error handler rather than presenting it as a measurement.

Common beginner mistakes

No output: click Deploy, then trigger Inject. A connected canvas does not mean the latest configuration is active.

Debug shows the whole object: configure Debug for the complete message or just msg.payload depending on what you need to inspect.

A value becomes NaN: check whether the payload is text or numeric and validate before conversion.

Function output disappears: verify the function returns a message. Returning null deliberately stops a message; returning a plain string is not the same as returning a message object.

Too much Debug output: disable noisy Debug nodes after testing, especially for fast sensor streams.

What to learn next

• Node-RED Tutorial for Beginners: Nodes, Flows & msg.payload explains the message model in more detail.
• Node-RED with MQTT: Connect Mosquitto, Publish & Subscribe brings messages in from a broker.
• Node-RED Dashboard 2.0: Install Buttons, Switches and Gauges turns flow outputs into a visual interface.

Official references: Working with messages and Writing Functions.