mirror of
https://github.com/node-red/node-red.git
synced 2023-10-10 13:36:53 +02:00
* 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>
161 lines
9.6 KiB
HTML
161 lines
9.6 KiB
HTML
<!--
|
|
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="mqtt in">
|
|
<p>Connects to a 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>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">
|
|
<p>Connects to a 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 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">
|
|
<p>Configuration for a connection to an MQTT broker.</p>
|
|
<p>This configuration will create a single connection to the broker which can
|
|
then be reused by <code>MQTT In</code> and <code>MQTT Out</code> nodes.</p>
|
|
<p>The node will generate a random Client ID if one is not set and the
|
|
node is configured to use a Clean Session connection. If a Client ID is set,
|
|
it must be unique to the broker you are connecting to.</p>
|
|
<h4>Birth Message</h4>
|
|
<p>This is a message that will be published on the configured topic whenever the
|
|
connection is established.</p>
|
|
<h4>Close Message</h4>
|
|
<p>This is a message that will be published on the configured topic before the
|
|
connection is closed normally, either by re-deploying the node, or by shutting down.</p>
|
|
<h4>Will Message</h4>
|
|
<p>This is a message that will be published by the broker in the event the node
|
|
unexpectedly loses its connection.</p>
|
|
<h4>WebSockets</h4>
|
|
<p>The node can be configured to use a WebSocket connection. To do so, the Server
|
|
field should be configured with a full URI for the connection. For example:</p>
|
|
<pre>ws://example.com:4000/mqtt</pre>
|
|
|
|
</script>
|