Version boundaries and Node-RED’s role in Home Assistant

Why this matters

When you select OPEN WEB UI in Home Assistant, you see the Node-RED editor. However, Home Assistant Community App: Node-RED handles installation, startup, Ingress, data mounts, and permissions. The editor contains both Node-RED core nodes and Home Assistant WebSocket nodes. Calling all of this “Node-RED 22” can lead you to check the wrong version, apply the wrong settings, or assume that one layer’s authentication protects an unrelated network entry point.

The examples gradually build toward automations such as hallway lighting, away-from-home reminders, and temperature monitoring. The first flow controls no devices. Later, you will use Home Assistant’s Action node only after verifying the entity, trigger conditions, and recovery plan. Older documentation and existing flows may use the legacy name Call Service for this Action node; this guide uses its current UI name, Action.

Core concepts

Four layers, four sets of responsibilities

The Add-on’s pinned node-red/package.json explicitly lists node-red 5.0.2 and node-red-contrib-home-assistant-websocket 0.80.3. It also lists theme collection 5.0.1, but not @flowfuse/node-red-dashboard. The dashboard is therefore an optional extension. “Dashboard 2” in the package name identifies the product generation; it does not mean that this guide must pin npm major version 2.

A five-step version inventory before you begin

1. Confirm what you installed.

   On the Home Assistant Add-on details page, confirm that you are using the Node-RED Add-on rather than a separate Node-RED installation on another host. Record the displayed Add-on version; this guide verifies only 22.0.1.

2. Verify the runtime in the startup log.

   Read the Add-on log first and confirm that the service starts normally. Never post logs containing a token, URL, entity ID, or complete message content publicly. This guide’s runtime baseline is Node-RED 5.0.2.

3. Check the boundaries of the Home Assistant node package.

   The Add-on comes with HA WebSocket 0.80.3 preinstalled. You do not need to install the same package again for the first exercise, and you should not alter the default server connection. Wait until Chapter 8 to inspect the connection node.

4. Begin with a side-effect-free exercise.

   Read this chapter, followed by the installation and editor chapters, before creating Inject → Change → Debug. This flow produces only an in-memory message and Debug output. It does not call Action, write files, or control lights.

5. Keep a change record for future maintenance.

   Record the versions, purpose of the change, Deploy scope, and observations, but remove private locations, real IDs, credentials, and internal addresses. If your versions differ, check the release notes first. Do not assume that every UI detail in this chapter remains unchanged.

Version scope and two Home Assistant thresholds

The Add-on 22.0.1 manifest declares homeassistant: 2023.3.0. This is the threshold the Supervisor uses to determine whether the Add-on can be installed; it is not the complete compatibility requirement for HA WebSocket 0.80.3. The latter’s pinned README lists Home Assistant 2024.3+, Node-RED 3.1.1+, and Node.js 18.2.0+. In this guide’s pinned configuration, the bundled Node-RED 5.0.2 is above the Node-RED minimum. You should nevertheless treat Home Assistant 2024.3+ as a prerequisite for using HA WebSocket 0.80.3.

init: false is a container-manifest flag. It is separate from the safe_mode setting, which starts Node-RED with --safe. Do not combine internal package constants, the Add-on installation threshold, and user-facing prerequisites from a README into one “minimum Home Assistant version.”

System roles in a home-automation scenario

Consider a light that should turn on at night when someone passes through the entrance. Home Assistant integrations represent the motion sensor and light as entities and maintain their states. HA WebSocket nodes can subscribe to state events, query other entities, and ask Home Assistant to turn on the light through an Action node. The Node-RED runtime routes messages through nodes and wires, evaluates conditions, and manages the flow lifecycle. The Add-on starts and persists that runtime within Home Assistant’s managed environment and exposes its editor through Ingress.

• Home Assistant: The authority for device and service semantics. Writing a name on the Node-RED canvas does not automatically create a real device.
• HA WebSocket 0.80.3: The communication bridge. It includes server config, state/event, Action, and companion entity nodes. Each node has its own rules for input overrides and output.
• Node-RED 5.0.2: The graphical-programming runtime. Each msg is a JavaScript object that can contain payload, topic, _msgid, and other fields; it is not just a single piece of text.
• Add-on 22.0.1: The deployment package. It provides data paths, proxies, permissions, and a package collection, but it cannot determine whether an automation is safe for your environment.

A report that “the light failed to turn on” could therefore point to several layers: an unavailable entity, the Home Assistant connection, Action configuration, message conditions, runtime deployment, or Add-on startup. Identify the layer first and then read the relevant log; this is much more effective than repeatedly restarting the system.

Boundaries between data, control, and security responsibilities

Edit, deploy, and restart

Moving nodes in the workspace changes the editor state. Selecting Deploy sends the chosen scope to the runtime. After you modify Add-on settings, the official Add-on documentation instructs you to restart the Add-on. A deployment may restart affected nodes, while an Add-on restart rebuilds the surrounding services. These different scopes can produce different results for timers, event subscriptions, and nodes with external side effects.

Authentication boundaries are not interchangeable

Home Assistant Ingress, a direct listener, the editor route, flow-created HTTP endpoints, static content, and the optional dashboard all have different boundaries. Safely opening the editor from the Home Assistant sidebar does not mean that every direct endpoint automatically receives the same protection. Chapter 2 explains these distinctions.

Not every flow needs privileged capabilities

The Add-on manifest grants access to the Home Assistant API, Supervisor manager, host network, UART, and multiple mounts. These capabilities are available to the container, but that does not justify reading or writing Home Assistant settings, scanning the local network, or controlling serial devices without a specific need. Third-party nodes also run with the Node-RED process’s permissions, so review their source and necessity before installation.

A learning path from side-effect-free flows to home automation

1. Chapter 2: Set up the environment by following the Add-on documentation’s Install → Start → Logs → OPEN WEB UI sequence. Begin with Ingress, then learn the boundaries between direct ports, TLS, and the authentication layers.
2. Chapter 3: Tour only the workspace, Palette, sidebar, Help, and the three Deploy scopes. Do not select Deploy while taking screenshots or identifying parts of the interface.
3. Chapters 4 to 7: Use manual Inject nodes to explore msg, Change, Switch, time, and context. Send output only to Debug to avoid side effects on entities.
4. Chapters 8 to 12: After confirming the Home Assistant server connection, read events and states before learning Action. Always replace sample IDs with verified entities from your environment, and define stop and recovery conditions first.
5. Later exercises: Add debounce logic, availability handling, error paths, notifications, and maintenance practices. Test examples such as hallway lighting on targets that do not affect safety equipment.

Install the optional FlowFuse Dashboard 2 only when you need a user interface. It is not a prerequisite for Home Assistant automation. Learning messages, states, and error paths first reduces the risk of mistaking an attractive interface for reliable control.

Troubleshooting: identify the right layer first

• You see 22.0.1 but cannot find a “Node-RED 22” feature in the editor: 22.0.1 is the Add-on version. Consult the pinned editor and core sources for the bundled Node-RED 5.0.2.
• The Add-on installs, but a Home Assistant node behaves unexpectedly: Do not judge compatibility solely by 2023.3.0 in the manifest. Check the Home Assistant 2024.3+ prerequisite in the HA WebSocket 0.80.3 README, then review an Add-on log with all sensitive information removed.
• The tutorial mentions Dashboard, but it is absent from the Palette: FlowFuse Dashboard 2 1.30.2 is optional and not bundled; its absence does not mean the Add-on installation failed. Do not install it for the first four chapters.
• The Deploy or Action screens you found look different: Confirm that the material applies to Node-RED 5.0.2 and HA WebSocket 0.80.3. The current UI name is Action; the legacy name Call Service should be used only to identify existing material.
• You are unsure which layer is failing: Record, in order, whether the Add-on starts, whether the editor opens, whether a Node-RED core Inject/Debug flow works, whether the Home Assistant server is connected, and whether the specific Home Assistant node reports an error. Remove tokens, URLs, locations, and real IDs before reporting the issue publicly.

Pinned sources and verification boundaries

• Pinned Add-on 22.0.1 commit: manifest, node-red/package.json, packaging, and startup behavior. See also the official Add-on documentation at that commit.
• Pinned Node-RED 5.0.2 commit and the official Node-RED documentation.
• Pinned HA WebSocket 0.80.3 commit and the official integration documentation.
• Pinned FlowFuse Dashboard 2 1.30.2 commit and the official Dashboard documentation; these sources are used only to define the optional component.

Use the official documentation to understand concepts. If screens, defaults, or compatibility guidance differ, consult the pinned sources above first, then confirm the behavior with a side-effect-free test flow.

FAQ