@flowfuse/nr-mqtt-nodes 0.1.0

package/nodes/icons/ff-logo.svg

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="90" height="135" version="1.1" viewBox="0 0 90 135" xmlns="http://www.w3.org/2000/svg">
+ <g transform="matrix(1.0078 0 0 1.0078 -67.007 -65.914)">
+  <path d="m77.77 92.7c-3.497 0-6.311 2.816-6.311 6.313-0.0052 11.55-0.01316 23.11-0.01499 34.66 7.5 0.0444 15.01 0.217 22.49-0.3183 10.43-0.9511 19.61-6.552 29.22-10.23 8.742-3.697 18.13-5.941 27.66-5.741l-1e-3 -18.38c4e-3 -3.498-2.815-6.313-6.311-6.313zm73.05 37.19c-1.055 0.0169-2.111 0.0457-3.166 0.0889-11.64-0.0448-21.96 5.974-32.46 10.19 8.115 3.283 15.95 7.454 24.55 9.389 3.675 0.5576 7.372 0.8292 11.08 0.9085zm-71.13 16.57c-2.747 6e-3 -5.494 0.0346-8.239 0.0486 0.0024 6.416 0.0072 12.83 0.01757 19.25 0.0037 3.498 2.815 6.313 6.311 6.313h66.73c3.497 0 6.311-2.816 6.311-6.313v-2.778c-8.203-0.0537-16.4-1.304-24.04-4.374-11.82-4.124-22.85-11.45-35.68-11.94-3.798-0.1794-7.602-0.2147-11.41-0.2062z" fill="#fff"/>
+ </g>
+</svg>

package/nodes/lib/TeamBrokerApi.js

@@ -0,0 +1,83 @@
+/**
+ * @typedef {Object} LinkResult
+ * @property {string} id - The ID of the broker client
+ * @property {string} username - The username for the broker client
+ * @property {Array} acls - The access control lists for the broker client
+ * @property {Object} owner - The owner of the broker client
+ * @property {string} owner.instanceType - The type of instance (e.g., 'hosted')
+ * @property {string} owner.id - The ID of the owner instance
+ * @property {string} owner.name - The name of the owner instance
+ * @property {string} password - The password for the broker client
+ */
+
+/**
+ * Creates an API for interacting with the FlowFuse platform
+ * @param {Object} RED - The Node-RED runtime object
+ * @param {import('got').Got} gotClient - The got client to use for making HTTP requests
+ * @param {Object} options - Configuration parameters
+ * @param {string} options.forgeURL - The Forge URL
+ * @param {string} options.teamId - The team ID
+ * @param {string} options.token - The authentication token
+ * @param {string} [options.API_VERSION='v1'] - The API version to use
+ * @example
+ * const { TeamBrokerApi } = require('./lib/TeamBrokerApi.js');
+ * const got = require('got').default;
+ * const forgeURL = 'https://example.com/forge';
+ * const teamBrokerApi = TeamBrokerApi(RED, got, { forgeURL, teamId: "abcdef", token: "your-token" });
+ */
+function TeamBrokerApi (gotClient, { forgeURL, teamId, instanceType, instanceId, token, API_VERSION = 'v1', API_TIMEOUT = 5000 } = {}) {
+    const teamClientUserId = `${instanceType}:${instanceId}`
+    const baseURL = `${forgeURL}/api/${API_VERSION}/teams/${teamId}/broker/client`
+    const got = gotClient.extend({
+        headers: {
+            Authorization: `Bearer ${token}`
+        },
+        timeout: {
+            request: API_TIMEOUT
+        }
+    })
+
+    /**
+     * Get the broker client user information
+     * @returns {Promise<Object>} - The broker client information
+     */
+    async function getClient () {
+        const url = `${baseURL}/${teamClientUserId}`
+        const res = await got.get(url)
+        if (res.statusCode !== 200) {
+            throw new Error(`Failed to fetch client: ${res.statusCode} ${res.statusMessage}`)
+        }
+        const data = JSON.parse(res.body)
+        return data
+    }
+
+    /**
+     * Link this instance to a broker client
+     * @param {string} password - The password to use for linking
+     * @returns {Promise<LinkResult>} - Returns broker settings
+     * @throws {Error} - Throws an error if the request fails
+     */
+    async function link (password) {
+        const url = `${baseURL}/${teamClientUserId}/link`
+        console.debug(`Linking instance to broker client via URL: ${url}`)
+        const res = await got.post(url, {
+            json: {
+                password
+            }
+        })
+        if (res.statusCode !== 200 && res.statusCode !== 201) {
+            throw new Error(`Failed to link instances: ${res.statusCode} ${res.statusMessage}`)
+        }
+        const data = JSON.parse(res.body)
+        return data
+    }
+
+    return {
+        getClient,
+        link
+    }
+}
+
+module.exports = {
+    TeamBrokerApi
+}

package/nodes/lib/proxyHelper.js

@@ -0,0 +1,301 @@
+/*
+This is a fork of the MQTT nodes from Node-RED.
+The original code can be found at:
+https://github.com/node-red/node-red/blob/283f7f5992b139200825f57234faddb409d7fcc9/packages/node_modules/@node-red/nodes/core/network/lib/proxyHelper.js
+Below is the copyright notice for the original code.
+The copyright notice for this fork is the same as the original.
+### Changes:
+- Hide advanced features
+- Remove the config node for MQTT broker
+- Remove the dynamic connection control
+- lint errors fixed up
+*/
+/*
+The MIT License
+
+Copyright (C) 2016-2018 Rob Wu <rob@robwu.nl>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+*/
+
+/*
+This proxy helper is heavily based on the proxy helper from Rob Wu as detailed above.
+It has been modified to work with the Node-RED runtime environment.
+The license for the original code is reproduced above.
+*/
+
+/**
+ * Parse a URL into its components.
+ * @param {String} url The URL to parse
+ * @returns {URL}
+ */
+const parseUrl = (url) => {
+    let parsedUrl = {
+        protocol: null,
+        host: null,
+        port: null,
+        hostname: null,
+        query: null,
+        href: null
+    }
+    try {
+        if (!url) { return parsedUrl }
+        parsedUrl = new URL(url)
+    } catch (error) {
+        // dont throw error
+    }
+    return parsedUrl
+}
+
+const DEFAULT_PORTS = {
+    ftp: 21,
+    gopher: 70,
+    http: 80,
+    https: 443,
+    ws: 80,
+    wss: 443,
+    mqtt: 1880,
+    mqtts: 8883
+}
+
+const modeOverride = getEnv('NR_PROXY_MODE', {})
+
+/**
+ * @typedef {Object} ProxyOptions
+ * @property {'strict'|'legacy'} [mode] - Legacy mode is for non-strict previous proxy determination logic (for node-red <= v3.1 compatibility) (default 'strict')
+ * @property {boolean} [favourUpperCase] - Favour UPPER_CASE *_PROXY env vars (default false)
+ * @property {boolean} [lowerCaseOnly] - Prevent UPPER_CASE *_PROXY env vars being used. (default false)
+ * @property {boolean} [excludeNpm] - Prevent npm_config_*_proxy env vars being used. (default false)
+ * @property {object} [env] - The environment object to use (defaults to process.env)
+ */
+
+/**
+ * Get the proxy URL for a given URL.
+ * @param {string|URL} url - The URL, or the result from url.parse.
+ * @param {ProxyOptions} [options] - The options object (optional)
+ * @return {string} The URL of the proxy that should handle the request to the
+ *  given URL. If no proxy is set, this will be an empty string.
+ */
+function getProxyForUrl (url, options) {
+    url = url || ''
+    const defaultOptions = {
+        mode: 'strict',
+        lowerCaseOnly: false,
+        favourUpperCase: false,
+        excludeNpm: false
+    }
+    options = Object.assign({}, defaultOptions, options)
+
+    if (modeOverride === 'legacy' || modeOverride === 'strict') {
+        options.mode = modeOverride
+    }
+
+    if (options.mode === 'legacy') {
+        return legacyGetProxyForUrl(url, options.env || process.env)
+    }
+
+    const parsedUrl = typeof url === 'string' ? parseUrl(url) : url || {}
+    let proto = parsedUrl.protocol
+    let hostname = parsedUrl.host
+    let port = parsedUrl.port
+    if (typeof hostname !== 'string' || !hostname || typeof proto !== 'string') {
+        return '' // Don't proxy URLs without a valid scheme or host.
+    }
+
+    proto = proto.split(':', 1)[0]
+    // Stripping ports in this way instead of using parsedUrl.hostname to make
+    // sure that the brackets around IPv6 addresses are kept.
+    hostname = hostname.replace(/:\d*$/, '')
+    port = parseInt(port) || DEFAULT_PORTS[proto] || 0
+    if (!shouldProxy(hostname, port, options)) {
+        return '' // Don't proxy URLs that match NO_PROXY.
+    }
+
+    let proxy =
+        getEnv('npm_config_' + proto + '_proxy', options) ||
+        getEnv(proto + '_proxy', options) ||
+        getEnv('npm_config_proxy', options) ||
+        getEnv('all_proxy', options)
+    if (proxy && proxy.indexOf('://') === -1) {
+        // Missing scheme in proxy, default to the requested URL's scheme.
+        proxy = proto + '://' + proxy
+    }
+    return proxy
+}
+
+/**
+ * Get the proxy URL for a given URL.
+ * For node-red < v3.1 or compatibility mode
+ * @param {string} url The URL to check for proxying
+ * @param {object} [env] The environment object to use (default process.env)
+ * @returns
+ */
+function legacyGetProxyForUrl (url, env) {
+    env = env || process.env
+    let prox, noprox
+    if (env.http_proxy) { prox = env.http_proxy }
+    if (env.HTTP_PROXY) { prox = env.HTTP_PROXY }
+    if (env.no_proxy) { noprox = env.no_proxy.split(',') }
+    if (env.NO_PROXY) { noprox = env.NO_PROXY.split(',') }
+
+    let noproxy = false
+    if (noprox) {
+        for (const i in noprox) {
+            if (url.indexOf(noprox[i].trim()) !== -1) { noproxy = true }
+        }
+    }
+    if (prox && !noproxy) {
+        return prox
+    }
+    return ''
+}
+
+/**
+ * Determines whether a given URL should be proxied.
+ *
+ * @param {string} hostname - The host name of the URL.
+ * @param {number} port - The effective port of the URL.
+ * @returns {boolean} Whether the given URL should be proxied.
+ * @private
+ */
+function shouldProxy (hostname, port, options) {
+    const NO_PROXY =
+        (getEnv('npm_config_no_proxy', options) || getEnv('no_proxy', options)).toLowerCase()
+    if (!NO_PROXY) {
+        return true // Always proxy if NO_PROXY is not set.
+    }
+    if (NO_PROXY === '*') {
+        return false // Never proxy if wildcard is set.
+    }
+
+    return NO_PROXY.split(/[,\s]/).every(function (proxy) {
+        if (!proxy) {
+            return true // Skip zero-length hosts.
+        }
+        const parsedProxy = proxy.match(/^(.+):(\d+)$/)
+        let parsedProxyHostname = parsedProxy ? parsedProxy[1] : proxy
+        const parsedProxyPort = parsedProxy ? parseInt(parsedProxy[2]) : 0
+        if (parsedProxyPort && parsedProxyPort !== port) {
+            return true // Skip if ports don't match.
+        }
+
+        if (!/^[.*]/.test(parsedProxyHostname)) {
+            // No wildcards, so stop proxying if there is an exact match.
+            return hostname !== parsedProxyHostname
+        }
+
+        if (parsedProxyHostname.charAt(0) === '*') {
+            // Remove leading wildcard.
+            parsedProxyHostname = parsedProxyHostname.slice(1)
+        }
+        // Stop proxying if the hostname ends with the no_proxy host.
+        return !hostname.endsWith(parsedProxyHostname)
+    })
+}
+
+/**
+ * Get the value for an environment constiable.
+ *
+ * @param {string} key - The name of the environment constiable.
+ * @param {ProxyOptions} options - The name of the environment constiable.
+ * @return {string} The value of the environment constiable.
+ * @private
+ */
+function getEnv (key, options) {
+    const env = (options && options.env) || process.env
+    if (options && options.excludeNpm === true) {
+        if (key.startsWith('npm_config_')) {
+            return ''
+        }
+    }
+    if (options && options.lowerCaseOnly === true) {
+        return env[key.toLowerCase()] || ''
+    } else if (options && options.favourUpperCase === true) {
+        return env[key.toUpperCase()] || env[key.toLowerCase()] || ''
+    }
+    return env[key.toLowerCase()] || env[key.toUpperCase()] || ''
+}
+
+/**
+ * Get a specific proxy agent for a WebSocket connection. This should be applied to the `wsOptions.agent` property
+ *
+ * NOTE: This utility function is specifically designed for the MQTT instances where the proxy is set based on the http based EndPoint
+ *       that the instance will use to make a connection. As such, the proxy URL is determined based on the `wsEndPoint` provided in
+ *       conjunction with env vars `http_proxy`, `https_proxy` and `no_proxy`.
+ *
+ * More Info:
+ *   `wsOptions.agent` is expected to be an HTTP or HTTPS agent based on the request protocol
+ *   http/ws requests use env var `http_proxy` and the HttpProxyAgent
+ *   https/wss requests use env var `https_proxy` and the HttpsProxyAgent
+ *   REF: https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent#maps-proxy-protocols-to-httpagent-implementations
+ *
+ * @param {String} url - WebSocket url
+ * @param {import('http').AgentOptions} proxyOptions - proxy options
+ * @returns {import('https-proxy-agent').HttpsProxyAgent | import('http-proxy-agent').HttpProxyAgent | null}
+ */
+function getWSProxyAgent (url, proxyOptions) {
+    if (!url) {
+        return null
+    }
+    const _url = new URL(url)
+    const isHTTPBased = _url.protocol === 'ws:' || _url.protocol === 'http:'
+    const isHTTPSBased = _url.protocol === 'wss:' || _url.protocol === 'https:'
+    if (!isHTTPBased && !isHTTPSBased) {
+        return null
+    }
+
+    // replace ^ws with http so that getProxyForUrl can return the correct http*_proxy for ws/wss
+    const proxyUrl = getProxyForUrl(url.replace(/^ws/, 'http'))
+
+    if (proxyUrl && isHTTPSBased) {
+        const HttpsAgent = require('https-proxy-agent').HttpsProxyAgent
+        return new HttpsAgent(proxyUrl, proxyOptions)
+    }
+    if (proxyUrl && isHTTPBased) {
+        const HttpAgent = require('http-proxy-agent').HttpProxyAgent
+        return new HttpAgent(proxyUrl, proxyOptions)
+    }
+    return null
+}
+
+/**
+ * Get proxy agent for HTTP or HTTPS got instance. This should be applied to the `agent` property of the got instance options
+ *
+ * NOTE: This utility function is specifically designed for the GOT instances where the proxy is set based on the `httpEndPoint`
+ *       that the instance will use to make requests. As such, the proxy URL is determined based on the `httpEndPoint` provided
+ *       in conjunction with env vars `http_proxy`, `https_proxy` and `no_proxy`.
+ * @param {String} url - http or https URL
+ * @param {import('http').AgentOptions} proxyOptions - proxy options
+ * @returns {{http: import('http-proxy-agent').HttpProxyAgent | undefined, https: import('https-proxy-agent').HttpsProxyAgent | undefined}}
+ */
+function getHTTPProxyAgent (url, proxyOptions) {
+    const agent = {}
+    if (url) {
+        const _url = new URL(url)
+        const proxyUrl = getProxyForUrl(url)
+        if (proxyUrl && _url.protocol === 'http:') {
+            const HttpAgent = require('http-proxy-agent').HttpProxyAgent
+            agent.http = new HttpAgent(proxyUrl, proxyOptions)
+        }
+        if (proxyUrl && _url.protocol === 'https:') {
+            const HttpsAgent = require('https-proxy-agent').HttpsProxyAgent
+            agent.https = new HttpsAgent(proxyUrl, proxyOptions)
+        }
+    }
+    return agent
+}
+
+module.exports = {
+    getProxyForUrl,
+    parseUrl,
+    getWSProxyAgent,
+    getHTTPProxyAgent
+}

package/nodes/lib/util.js

@@ -0,0 +1,112 @@
+/**
+ * Parses an nr-mqtt Node userId or clientId auth string into its components.
+ * @param {String} id - the ID to parse, expected format: `mq:hosted:teamId:instanceId[:haId]` or `mq:remote:teamId:deviceId[:projectId]`
+ * @param {'username'|'clientId'} [kind='username'] - the kind of ID to parse `'username'` or `'clientId'`
+ * @returns Parsed ID object
+ */
+function parseNrMqttId (id, kind = 'username') {
+    const validLengths = kind === 'clientId' ? [4, 5] : [4]
+    const result = {
+        teamId: null,
+        parentId: null,
+        parentType: null,
+        ownerId: null,
+        ownerType: null,
+        haId: null,
+        teamClientUsername: null
+    }
+    const parts = id.split(':')
+    if (!validLengths.includes(parts.length)) {
+        throw new Error(`Invalid ID format: ${id}`)
+    }
+
+    const [mq, instanceType, teamId, instanceId, part5] = parts
+    if (mq !== 'mq') {
+        throw new Error(`Invalid ID format: ${id}`)
+    }
+    result.teamId = teamId
+    result.ownerId = instanceId
+    if (instanceType === 'hosted') {
+        result.ownerType = 'instance'
+        result.parentType = 'application' // instances are treated as application owned
+        result.parentId = null // no application ID available at this point (or necessary)
+        result.teamClientUsername = `instance:${instanceId}`
+        if (kind === 'clientId' && parts.length === 4) {
+            // since a clientId can have a haId, we need to compute the teamClientUsername accordingly
+            result.haId = part5 || null
+        }
+    } else if (instanceType === 'remote') {
+        result.ownerType = 'device'
+        result.teamClientUsername = `device:${instanceId}`
+        result.parentType = 'application'
+        if (parts.length === 5) {
+            result.parentId = part5 // projectId
+            result.parentType = 'project'
+        } else {
+            result.parentId = null // no projectId for app owned devices
+        }
+    } else {
+        throw new Error('Invalid ID format')
+    }
+    return result
+}
+
+/**
+ * Creates an MQTT Auth ID for a team instance nr-mqtt client.
+ * Auth ID is used to identify the broker client by type, team, id and optionally haId.
+ *  - `mq:hosted:instanceId` for hosted instances
+ *  - `mq:hosted:instanceId:haId` for hosted High Availability instances
+ *  - `mq:remote:deviceId:projectId` for Instance Owned devices
+ *  - `mq:remote:deviceId` for Application Owned devices
+ * @param {string} teamId - team hash ID
+ * @param {'device'|'project'|'instance'} instanceType - the type of instance
+ * @param {string} instanceId - the ID of the instance or device
+ * @returns {string} - The created MQTT Auth ID e.g. `mq:hosted:instanceId`
+ */
+function createNrMqttId (teamId, instanceType, instanceId) {
+    let _type = instanceType
+    if (instanceType === 'remote' || instanceType === 'device') {
+        _type = 'remote' // remote devices
+    } else if (instanceType === 'hosted' || instanceType === 'instance' || instanceType === 'project') {
+        _type = 'hosted' // hosted instances
+    }
+
+    const parts = ['mq', _type, teamId, instanceId]
+    return parts.join(':')
+}
+
+/**
+ * Creates an MQTT Client ID for a team instance nr-mqtt client.
+ * Client ID is used to identify the broker client by type, team, id and optionally haId.
+ * @param {string} teamId - team hash ID
+ * @param {'device'|'instance'|'project'} instanceType - the type of instance (e.g., 'hosted', 'device')
+ * @param {string} instanceId - the ID of the instance or device
+ * @param {string} [haId=null] - optional High Availability instance ID
+ * @returns {string} - The created MQTT Client ID e.g. `mq:hosted:instanceId:haId`
+ */
+function createNrMqttClientId (teamId, instanceType, instanceId, haId = null) {
+    let mqttId = createNrMqttId(teamId, instanceType, instanceId)
+    if (haId && mqttId.startsWith('mq:hosted:')) {
+        mqttId += `:${haId}` // add haId for hosted instances
+    }
+    return mqttId
+}
+
+/**
+ * Helper function to test an object has a property
+ * @param {object} obj Object to test
+ * @param {string} propName Name of property to find
+ * @returns true if object has property `propName`
+ */
+function hasProperty (obj, propName) {
+    // JavaScript does not protect the property name hasOwnProperty
+    // Object.prototype.hasOwnProperty.call is the recommended/safer test
+    return Object.prototype.hasOwnProperty.call(obj, propName)
+}
+
+module.exports = {
+    parseNrMqttId,
+    createNrMqttId,
+    createNrMqttClientId,
+    hasProperty
+}

package/nodes/locales/en-US/ff-mqtt.html

@@ -0,0 +1,121 @@
+<!-- 
+This is a fork of the MQTT nodes from Node-RED.
+The original code can be found at:
+https://github.com/node-red/node-red/blob/9bf9b7a635aab7190c51b76f7aa3ede443da8f91/packages/node_modules/@node-red/nodes/core/network/10-mqtt.html
+Below is the copyright notice for the original code.
+The copyright notice for this fork is the same as the original.
+### Changes:
+- Hide advanced features
+- Remove the config node for MQTT broker
+- Remove the dynamic connection control
+-->
+<!--
+  Copyright JS Foundation and other contributors, http://js.foundation
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<script type="text/html" data-help-name="ff-mqtt-in">
+<p>Automatically connects to the FlowFuse MQTT broker and subscribes to messages from the specified topic.</p>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+       <dt>payload <span class="property-type">string | buffer</span></dt>
+       <dd>a string unless detected as a binary buffer.</dd>
+       <dt>topic <span class="property-type">string</span></dt>
+       <dd>the MQTT topic, uses / as a hierarchy separator.</dd>
+       <dt>qos <span class="property-type">number</span> </dt>
+       <dd>0, fire and forget - 1, at least once - 2, once and once only.</dd>
+       <dt>retain <span class="property-type">boolean</span></dt>
+       <dd>true indicates the message was retained and may be old.</dd>
+
+       <dt class="optional">responseTopic <span class="property-type">string</span></dt>
+       <dd><b>MQTTv5</b>: the MQTT response topic for the message</dd>
+       <dt class="optional">correlationData <span class="property-type">Buffer</span></dt>
+       <dd><b>MQTTv5</b>: the correlation data for the message</dd>
+       <dt class="optional">contentType <span class="property-type">string</span></dt>
+       <dd><b>MQTTv5</b>: the content-type of the payload</dd>
+       <dt class="optional">userProperties <span class="property-type">object</span></dt>
+       <dd><b>MQTTv5</b>: any user properties of the message</dd>
+       <dt class="optional">messageExpiryInterval <span class="property-type">number</span></dt>
+       <dd><b>MQTTv5</b>: the expiry time, in seconds, of the message</dd>
+    </dl>
+    <h3>Details</h3>
+    The subscription topic can include MQTT wildcards, + for one level, # for multiple levels.</p>
+    <p>All FlowFuse MQTT nodes (in or out) share the same broker connection.</p>
+    <h4>Dynamic Subscription</h4>
+    The node can be configured to dynamically control the MQTT connection and its subscriptions. When
+    enabled, the node will have an input and can be controlled by passing it messages.
+    <h3>Inputs</h3>
+    <p>These only apply when the node has been configured for dynamic subscriptions.</p>
+    <dl class="message-properties">
+       <dt>action <span class="property-type">string</span></dt>
+       <dd>the name of the action the node should perform. Available actions are: <code>"connect"</code>,
+       <code>"disconnect"</code>, <code>"getSubscriptions"</code>, <code>"subscribe"</code> and 
+       <code>"unsubscribe"</code>.</dd>
+       <dt class="optional">topic <span class="property-type">string|object|array</span></dt>
+       <dd>For the <code>"subscribe"</code> and <code>"unsubscribe"</code> actions, this property
+           provides the topic. It can be set as either:<ul>
+           <li>a String containing the topic filter</li>
+           <li>an Object containing <code>topic</code> and <code>qos</code> properties</li>
+           <li>an array of either strings or objects to handle multiple topics in one</li>
+            </ul>
+        </dd>
+        <i>NOTE: By default, the MQTT connection will be established using the settings provided by
+            the platform. These cannot be overridden by the node.</i>
+    </dl>
+
+</script>
+
+<script type="text/html" data-help-name="ff-mqtt-out">
+    <p>Automatically connects to the FlowFuse MQTT broker and publishes messages.</p>
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+       <dt>payload <span class="property-type">string | buffer</span></dt>
+       <dd> the payload to publish. If this property is not set, no message will be sent. To send a blank message, set this property to an empty String.</dd>
+       <dt class="optional">topic <span class="property-type">string</span></dt>
+       <dd> the MQTT topic to publish to.</dd>
+       <dt class="optional">qos <span class="property-type">number</span></dt>
+       <dd>0, fire and forget - 1, at least once - 2, once and once only. Default 0.</dd>
+       <dt class="optional">retain <span class="property-type">boolean</span></dt>
+       <dd>set to true to retain the message on the broker. Default false.</dd>
+       <dt class="optional">responseTopic <span class="property-type">string</span></dt>
+       <dd><b>MQTTv5</b>: the MQTT response topic for the message</dd>
+       <dt class="optional">correlationData <span class="property-type">Buffer</span></dt>
+       <dd><b>MQTTv5</b>: the correlation data for the message</dd>
+       <dt class="optional">contentType <span class="property-type">string</span></dt>
+       <dd><b>MQTTv5</b>: the content-type of the payload</dd>
+       <dt class="optional">userProperties <span class="property-type">object</span></dt>
+       <dd><b>MQTTv5</b>: any user properties of the message</dd>
+       <dt class="optional">messageExpiryInterval <span class="property-type">number</span></dt>
+       <dd><b>MQTTv5</b>: the expiry time, in seconds, of the message</dd>
+       <dt class="optional">topicAlias <span class="property-type">number</span></dt>
+       <dd><b>MQTTv5</b>: the MQTT topic alias to use</dd>
+    </dl>
+    <h3>Details</h3>
+    <code>msg.payload</code> is used as the payload of the published message.
+    If it contains an Object it will be converted to a JSON string before being sent.
+    If it contains a binary Buffer the message will be published as-is.</p>
+    <p>The topic used can be configured in the node or, if left blank, can be set by <code>msg.topic</code>.</p>
+    <p>Likewise the QoS and retain values can be configured in the node or, if left
+    blank, set by <code>msg.qos</code> and <code>msg.retain</code> respectively. To clear a previously
+    retained topic from the broker, send a blank message to that topic with the retain flag set.</p>
+    <p>This node requires the connection to the FlowFuse broker to be configured.</p>
+    <p>All FlowFuse MQTT nodes (in or out) share the same broker connection.</p>
+    <h4>Dynamic Control</h4>
+    The connection shared by the node can be controlled dynamically. If the node receives
+    one of the following control messages, it will not publish the message payload as well.
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+       <dt>action <span class="property-type">string</span></dt>
+       <dd>the name of the action the node should perform. Available actions are: <code>"connect"</code>,
+       and <code>"disconnect"</code>.</dd>
+    </dl>
+
+</script>