MQTT, the preinstalled node matrix, Palette management, and the FlowFuse Dashboard 2 extension (optional and not bundled)

First Distinguish Core Protocol Features, Preinstalled Packages, and Optional Packages

Add-on 22.0.1 embeds Node-RED 5.0.2 and HA WebSocket nodes 0.80.3. MQTT In, MQTT Out, and mqtt-broker are part of Node-RED core; the package matrix lists the Add-on image's direct dependencies; Palette Manager and npm_packages add third-party server code; and FlowFuse Dashboard 2 1.30.2 is optional and not bundled. Do not conflate these four layers.

The Add-on has host_network: true and uart: true grants and mounts media:rw and share:rw storage. These settings indicate potential reachability or read/write access; they do not mean that MQTT, serial, File, File In, or Watch is in use. For every external connection or file node, pin the destination, topic, device, and path individually. See Chapter 21 for backup and secret-handling guidance.

Make Each MQTT Choice Independently

The broker connection configuration determines the transport, protocol version, and session. MQTT In determines the subscription filter, subscription QoS, and output data type. MQTT Out determines the publication topic, QoS, retained-message setting, and MQTT 5 properties. Selecting a TLS checkbox does not create a topic ACL, and choosing QoS 2 does not make downstream business operations execute “exactly once.”

MQTT 5 adds properties and subscription flags. When you select MQTT 3.1 or 3.1.1, you cannot rely on MQTT 5 features such as response topic, correlation data, content type, message expiry, user properties, no local, retain as published, retain handling, or session expiry. Pin the version supported by the broker before configuring nodes; do not rely on the client to guess.

For high-frequency MQTT and large-payload testing, follow the approach in Chapter 18: debug only allowlisted fields and limit the number of cases. See Chapter 5 for message-shape and data-type fundamentals.

Six Offline Checks Without Establishing a Broker Connection

1. Create a topic contract.

   For each direction of data flow, record a placeholder topic, publisher, subscriber, payload schema, maximum byte size, permitted frequency, QoS, retained-message setting, and duplicate-handling strategy. Do not enter a real broker, client ID, or credentials.

2. Select the protocol and session behavior.

   Explicitly record MQTT 3.1, 3.1.1, or 5. Then decide on clean session/clean start, client ID, automatic unsubscription, and MQTT 5 session expiry. Leave fields unsupported by the selected protocol blank.

3. Read the example JSON offline.

   Open 14-mqtt-in-out.json. Confirm that both MQTT In and MQTT Out have d:true, that the broker configuration has autoConnect:false, and that the host, client ID, and topics are complete placeholders with no credentials.

4. Check TLS and ACLs.

   In the written specification, require a controlled TLS configuration, server-certificate verification, separate client credentials, and least-privilege publish/subscribe topic ACLs. Never put secrets in a broker URL, Function node, flow export, or Debug output.

5. Conditional: inventory package sources.

   Only when auditing preinstalled nodes or evaluating an installation, compare against this chapter's 25-entry bundled matrix. Record the exact npm package and pinned version, maintenance status, license, transitive dependencies, permissions, and removal procedure. This chapter does not install anything; MQTT-only readers may skip this step.

6. Conditional: document package or Dashboard failures and recovery.

   Only when packages or Dashboard are involved, document package startup failures, route/Socket.IO problems, and recovery procedures. Record broker unreachability, certificate errors, ACL denials, duplicates, stale retained messages, and session recovery in the MQTT topic contract. Keep the relevant nodes disabled and perform no I/O.

Offline MQTT contract (not connection configuration)
broker: PLACEHOLDER_MQTT_BROKER_HOST
client id: PLACEHOLDER_MQTT_CLIENT_ID
subscribe: PLACEHOLDER_MQTT_INPUT_TOPIC
publish: PLACEHOLDER_MQTT_OUTPUT_TOPIC
protocol: PLACEHOLDER_MQTT_VERSION
max payload: PLACEHOLDER_LIMIT
credentials: store only in the controlled credentials store
network action: do not execute

End-of-Chapter Offline Acceptance Check

Node-RED 5.0.2 MQTT In, MQTT Out, and Broker Fields

MQTT In: Subscriptions and Output Data Types

MQTT In output includes at least msg.topic, msg.payload, msg.qos, and msg.retain. An MQTT 5 packet may also expose responseTopic, correlationData, contentType, messageExpiryInterval, payloadFormatIndicator, reasonString, and userProperties. Treat all of these as untrusted broker/message metadata; never use them directly to select a Home Assistant Action, file path, or HTTP URL.

MQTT Out: Publication Fields and Message Overrides

MQTT Out has Broker, Topic, QoS, and Retain fields. If Topic is blank, it may use msg.topic; if QoS or Retain is blank, it may use the corresponding message value. A topic, QoS, or retained-message setting fixed in the node takes precedence. This flexibility also means that an untrusted message can change publication behavior. Remove or validate msg.topic, msg.qos, and msg.retain on external input.

MQTT 5 also supports User Properties, Response Topic, Correlation Data, Content Type, and Message Expiry. A Response Topic is protocol metadata; it does not create a secure RPC mechanism. Design the reply-topic ACL, correlation uniqueness, timeout, duplicate handling, and late-reply handling separately. A publication topic cannot contain + or #.

mqtt-broker: Connection, Security, Sessions, and Messages

When importing an old broker configuration, also inspect the persisted verifyservercert value. The legacy default defined by the 5.0.2 editor is false; if the TLS configuration does not provide rejectUnauthorized, the runtime uses that value as a fallback. Migrate an old configuration to an approved TLS configuration and confirm that the resulting value is rejectUnauthorized=true. Enabling only the TLS toggle indicates encrypted transport; it does not prove that the broker's identity is verified.

Protocol value 3 is MQTT 3.1 compatibility, 4 is MQTT 3.1.1, and 5 is MQTT 5. When auto-connect is disabled, 5.0.2 allows a controlled action message to connect or disconnect. That capability is not an entry point for this chapter: never wire an external payload from MQTT In or HTTP In directly to broker control. Because the Add-on's host_network:true setting may make more local services reachable, a broker allowlist and ACLs are especially important.

Role Summary for the Direct Dependencies in Add-on 22.0.1

The pinned node-red/package.json contains 25 direct dependencies: 19 provide Palette/configuration nodes, 1 is the Node-RED runtime, 1 is an editor theme, and 4 are wrapper/runtime support libraries. This is not the complete transitive dependency tree. Preinstalled means available; it does not mean that any flow has run the package. Readers interested only in MQTT may skip the reference inventory below.

Cast, InfluxDB, Modbus, email, feedparser, ping, and serialport can perform network, database, or physical I/O. BigTimer, SunEvents, and suncalc-related nodes may generate messages autonomously based on time. Even apparently pure transformations such as Counter, moment, and smooth can pass an incorrect result to a downstream action. Follow Chapter 17 to separate computation from side effects; do not omit validation merely because a package is bundled.

Palette, npm_packages, and Startup Persistence

Palette Manager installs a node module, whose server-side JavaScript runs with the permissions of the Node-RED process; this is not merely a UI change that adds an editor icon. On every startup, the Add-on processes npm_packages by changing to /opt and running npm install --omit=dev --omit=optional. It first installs system_packages with the Alpine package manager, then processes npm packages, and finally runs eval on each line of init_commands. Any failure aborts initialization.

Do not record only a package name or a loose semver range. At minimum, retain the exact version, official registry identity, source repository, license, maintainer, publication date, known advisories, Node/Node-RED compatibility, a transitive-tree summary, and a rollback version. Pinning a direct version does not make every transitive dependency immutable. Generate a reproducible lock/inventory in an isolated environment, then update it through the formal process.

Add-on backups explicitly exclude node_modules, so restoration does not reproduce the installation tree byte for byte. Custom declarations, package metadata, and an available registry must be sufficient to reconstruct the same dependencies. Startup-time installation also adds an availability dependency. Do not manage the same package with both Palette Manager and npm_packages, which would make ownership and version ambiguous.

File/File In/Watch and Mounted Storage

Node-RED core also includes File, File In, and Watch. The Add-on's media:rw and share:rw grants give the container potential read/write access; they do not automatically authorize a flow to use any path. If a file name comes from MQTT, Dashboard, or HTTP input, it can enable path traversal, overwriting, or data exfiltration. Pin the base directory, allowlist file names, constrain byte size and frequency, and keep all writes disabled. The same principle applies to serial nodes: uart:true is a grant, not approval for arbitrary device commands.

FlowFuse Dashboard 2 1.30.2: Optional and Not Bundled

The 25-entry dependency list for Add-on 22.0.1 does not include @flowfuse/node-red-dashboard. Pinned package version 1.30.2 declares Node >=14 and Node-RED >=3.0.0. Node-RED 5.0.2 is within those declared ranges, but you must still test it in the target Add-on. The package registers 5 configuration nodes and 22 ui-* widgets—a total of 27 registrations—and adds server code, browser code, an HTTP route, and Socket.IO communication.

The Add-on's direct NGINX /endpoint/ path does not pass through the editor's Supervisor auth_request. Ingress accepts only the Supervisor ingress source, but that does not imply that every Dashboard user has widget authorization. Verify whether http_node Basic Auth protects your route and Socket.IO session over the actual proxy path. With a custom Dashboard path, test the custom route and the hard-coded /dashboard/manifest.webmanifest separately for path and authentication behavior. Never assume that the Dashboard page, manifest, assets, and real-time channel are secure merely because the editor requires login.

Legacy Migration, Not a Drop-In Replacement

The old, unscoped node-red-dashboard is based on Angular v1 and is considered legacy; this chapter does not teach a fresh installation. The former scoped name @flowforge/node-red-dashboard is deprecated and no longer updated. FlowFuse Dashboard 2 is a rewrite. Do not claim that existing ui_* nodes, themes, layouts, custom templates, browser scripts, URLs, authentication, or client state will migrate automatically and unchanged.

First inventory the existing legacy flow's pages/groups/widgets, template code, routes, authentication, CSS, browser dependencies, and message contracts. Then rebuild and compare it page by page in an isolated copy. Running the legacy and new Dashboards in parallel also requires preventing conflicts in routes, Socket.IO, credentials, and duplicate side effects. Do not remove the old package first, and do not connect a new widget to a production action.

Troubleshooting

• MQTT node remains disconnected: Keep In/Out disabled and check, in order, the placeholder, DNS, port, protocol version, TLS chain, server hostname, client ID, credentials, and broker ACL. Do not begin by disabling certificate validation or switching to anonymous access.
• Duplicate messages arrive: QoS 1, reconnection, or a subscriber restart may cause redelivery. Use a stable message ID/business key for bounded deduplication and record the retention period. Do not assume that QoS 2 provides end-to-end exactly-once side effects for HA, email, or a database.
• A new subscription immediately receives an old command: Inspect the packet's retain flag and the broker's retained state. Do not use this chapter's example to publish a clearing message; first have the broker administration process confirm the topic, permissions, and scope of impact.
• Subscriptions behave unexpectedly after a non-clean session: Confirm that the client ID is unique and stable, and check session expiry, automatic unsubscription, broker queue limits, and whether an old client remains online. Never share a client ID across multiple instances.
• JSON output reports a parse error: Confirm the content type, encoding, and publisher schema. Do not switch unparseable bytes to auto-detect and then treat the result as a trusted object. Limit payload byte size and route errors to a bounded Catch path.
• The Add-on fails to start after a custom package is added: Check the exact package, architecture, registry availability, and the fail-fast system_packages → npm_packages → init_commands sequence. Use the recorded rollback version; do not repeatedly try unpinned versions.
• A package appears in the Palette inventory, but the expected node does not: Check the package's role first. bcryptjs, js-yaml, line-by-line, source-map-support, the Node-RED runtime, and the theme collection are not ordinary runtime Palette nodes. Then inspect the package's actual registrations and startup log.
• The Dashboard page opens, but real-time data does not update: Check the external route rewrite, Socket.IO path, HTTP and Socket.IO middleware, proxy streaming/upgrade, same-origin policy, and session separately. Do not expose the direct endpoint or remove authentication for troubleshooting.
• A migrated legacy Dashboard flow has a different layout/template: Dashboard 2 is not a drop-in replacement. Rebuild configuration nodes, widgets, layouts, CSS, templates, and message contracts page by page. Do not freshly install the legacy package or directly interchange the two sets of node names.

Pinned Versions and Official Documentation

This chapter uses exact commits to verify MQTT fields, the 25 direct dependencies, startup installation order, and Dashboard 2 boundaries. External brokers and organizational ACLs are environment-specific policies; this source code does not provide them automatically.

• Home Assistant Community App: Node-RED 22.0.1 pinned commit: 25 direct dependencies, grants, maps, system_packages, npm_packages, and startup order.
• Node-RED 5.0.2 pinned commit: MQTT In/Out/broker, TLS, WebSocket/TCP/UDP, and File/File In/Watch.
• FlowFuse Dashboard 2 1.30.2 pinned commit: package identity, compatibility, 27 registrations, routes, and Socket.IO.
• Official Node-RED documentation: Core nodes.
• Official Node-RED documentation: Adding nodes.
• Official Node-RED documentation: Securing Node-RED.
• Official FlowFuse Dashboard 2 documentation.
• Disabled example on this site: 14-mqtt-in-out.json. Read the safe example guidance before importing.

Frequently Asked Questions