Dynamic MQTT connections (#3189)

* add mqtt-control
- adds auto-connect option to broker
- add new node mqtt-control
- adds i18n messages
- adds documentation

* documentation tweaks

* built in documentation improvements

* fix tip layout causing oversized editor

* remove unused requires

* add missing `unsubscribe` dropdown option
- oddly forgotten - now added

* ensure clientid is updated dynamically

* [rewrite] move mqtt-control login into mqtt-in

* Remove dynamic label

* remove redundant mqtt-control code left overs

* Callback for brokerConn.connect (improve done())
- done is now called on connect callback

* fix race condition if connect/disconnect too fast
- node.connected and node.client.connected getting out of sync

* fix connection fail when switching protocol 3 ~ 5
- ensure protocolId is correct for protocolVersion

* change msg.subscribe prop to `msg.topic`

* unsub all topics if msg.topic is `true`

* delete temprary debugger statements

* Final rework of dynamic mqtt connections

Co-authored-by: Steve-Mcl <sdmclaughlin@gmail.com>

packages/node_modules/@node-red/nodes/locales/en-US/messages.json

@@ -416,7 +416,11 @@
             "maximumPacketSize": "Max Packet Size",
             "receiveMaximum": "Receive Max",
             "session": "Session",
-            "delay": "Delay"
+            "delay": "Delay",
+            "action": "Action",
+            "staticTopic": "Subscribe to single topic",
+            "dynamicTopic": "Dynamic subscription",
+            "auto-connect": "Connect automatically"
         },
         "sections-label":{
             "birth-message": "Message sent on connection (birth message)",
@@ -457,7 +461,10 @@
             "invalid-topic": "Invalid topic specified",
             "nonclean-missingclientid": "No client ID set, using clean session",
             "invalid-json-string": "Invalid JSON string",
-            "invalid-json-parse": "Failed to parse JSON string"
+            "invalid-json-parse": "Failed to parse JSON string",
+            "invalid-action-action": "Invalid action specified",
+            "invalid-action-alreadyconnected": "Disconnect from broker before connecting",
+            "invalid-action-badsubscription": "msg.topic is missing or invalid"
         }
     },
     "httpin": {

packages/node_modules/@node-red/nodes/locales/en-US/network/10-mqtt.html

@@ -40,6 +40,38 @@
     <p>This node requires a connection to a MQTT broker to be configured. This is configured by clicking
     the pencil icon.</p>
     <p>Several MQTT nodes (in or out) can share the same broker connection if required.</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>"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 continaing 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>
+       <dt class="optional">broker <span class="property-type">broker</span> </dt>
+       <dd>For the <code>"connect"</code> action, this property can override any
+           of the individual broker configuration settings, including: <ul>
+               <li><code>broker</code></li>
+               <li><code>port</code></li>
+               <li><code>url</code> - overrides broker/port to provide a complete connection url</li>
+               <li><code>username</code></li>
+               <li><code>password</code></li>
+           </ul>
+           <p>If this property is set and the broker is already connected an error
+              will be logged unless it has the <code>force</code> property set - in which case it will
+              disconnect from the broker, apply the new settings and reconnect.</p>
+       </dd>
+    </dl>
+
 </script>
 
 <script type="text/html" data-help-name="mqtt out">
@@ -78,6 +110,30 @@
     <p>This node requires a connection to a MQTT broker to be configured. This is configured by clicking
     the pencil icon.</p>
     <p>Several MQTT nodes (in or out) can share the same broker connection if required.</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>
+       <dt class="optional">broker <span class="property-type">broker</span> </dt>
+       <dd>For the <code>"connect"</code> action, this property can override any
+           of the individual broker configuration settings, including: <ul>
+               <li><code>broker</code></li>
+               <li><code>port</code></li>
+               <li><code>url</code> - overrides broker/port to provide a complete connection url</li>
+               <li><code>username</code></li>
+               <li><code>password</code></li>
+           </ul>
+           <p>If this property is set and the broker is already connected an error
+              will be logged unless it has the <code>force</code> property set - in which case it will
+              disconnect from the broker, apply the new settings and reconnect.</p>
+       </dd>
+    </dl>
+
 </script>
 
 <script type="text/html" data-help-name="mqtt-broker">