thingsboard · Andry925 · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025 · Oct 16, 2025
diff --git a/...s/templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md b/...s/templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md
diff --git a/...udes/templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md b/...udes/templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/mqtt-basic-section.md b/_includes/templates/iot-gateway/mqtt-connector/mqtt-basic-section.md
@@ -0,0 +1,40 @@
+This configuration section contains settings of the MQTT broker connection, such as:
+- **Host** - MQTT broker hostname or ip address;
+- **Port** - listening port on the MQTT broker that will be used for establishing connection;
+- **MQTT version** - MQTT protocol version (there are three versions currently supported by gateway - **3.1**, **3.11**, **5**);
+- **Client ID** ** - Unique identifier for each client’s session on the broker;
+- **Security** - configuration for client authorization at MQTT Broker (anonymous, basic, or certificates).
+
+{% capture difference %}
+**Please note:**
+\** -- The broker (or broker cluster) does not allow two simultaneous sessions with the same **Client ID**. If a second connection uses that ID, 
+the broker closes the existing session and accepts the new one (session takeover). The **Client ID** can be any valid UTF-8 string; 
+if you don’t have a descriptive one, you can generate it in the MQTT connector configuration UI—see the last screenshots under this subsection.
+{% endcapture %}
+{% include templates/info-banner.md content=difference %}
+
+{% capture difference %}
+All configuration parameters list, and their detailed description can be found in the 
+[Advanced configuration](/docs/iot-gateway/config/mqtt/#advanced-configuration) section.
+{% endcapture %}
+{% include templates/info-banner.md content=difference %}
+
+![image](/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png)
+
+If you want the UI to generate a **Client ID**, leave the **Client ID** field blank and click *Generate Client ID* (see the screenshot below). 
+The gateway will create a unique identifier.
+
+![image](/images/gateway/mqtt-connector/generate-clientID-from-UI.png)
+
+UI form with generated **Client ID** identifier e.g., *tb_gw_5ryl3* — this is just an example; your value will be different.
+
+![image](/images/gateway/mqtt-connector/generated-clientID-from-UI.png)
+
+
+
+
+
+
+
+
+
diff --git a/...des/templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md b/...des/templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-basic-basic-subsection.md b/_includes/templates/iot-gateway/mqtt-connector/security-basic-basic-subsection.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-anonymous.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-anonymous.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-basic.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-basic.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-certificates.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-certificates.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-advanced.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-advanced.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-anonymous.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-anonymous.md
@@ -0,0 +1,11 @@
+**Anonymous** is the simplest option: no credentials are required to publish/subscribe on the MQTT broker. 
+It can be useful for testing <br/> (e.g., public test brokers), 
+but not recommended for production because it allows unattended access.. 
+
+{% assign securityBasic = '
+    ===
+        image: /images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png,
+    '
+%}
+
+{% include images-gallery.liquid showListImageTitles="true" imageCollection=securityBasic %}
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-basic.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-basic.md
@@ -1,8 +1,11 @@
-Now select the security type:
+**Basic** authentication option uses a **username** and **password** configured on the MQTT broker. 
+It’s a good default for most setups—just use strong, unique credentials. For stronger identity and mutual verification, 
+consider certificate-based authentication; [Certificates](/docs/iot-gateway/config/mqtt/#certificates). 
 
-{% capture mqttsecuritybasicsubsection %}
-Anonymous<small>No security</small>%,%anonymous%,%templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md%br%
-Basic<small>Recommended</small>%,%basic%,%templates/iot-gateway/mqtt-connector/security-basic-basic-subsection.md%br%
-Certificates<small>For advanced security</small>%,%certificates%,%templates/iot-gateway/mqtt-connector/security-basic-certificates-subsection.md{% endcapture %}
+{% assign securityBasic = '
+    ===
+        image: /images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png,
+    '
+%}
 
-{% include content-toggle.liquid content-toggle-id="mqttsecuritybasicsubsection" toggle-spec=mqttsecuritybasicsubsection %}
+{% include images-gallery.liquid showListImageTitles="true" imageCollection=securityBasic %}
diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-certificates.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-certificates.md
@@ -0,0 +1,12 @@
+**Certificate-based authentication** uses TLS so the gateway and broker verify each other.
+Set the **pathToCACert** to your CA certificate (to trust the broker), **pathToClientCert** 
+to the gateway’s client certificate, and **pathToPrivateKey** to its private key (so the broker can authenticate the gateway). 
+Use the broker’s TLS port (typically 8883) for encrypted, production-grade security.
+
+{% assign securityBasic = '
+    ===
+        image: /images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce.png,
+    '
+%}
+
+{% include images-gallery.liquid showListImageTitles="true" imageCollection=securityBasic %}
diff --git a/...ludes/templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md b/...ludes/templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md
diff --git a/_includes/templates/iot-gateway/mqtt-connector/workers-settings-section-basic.md b/_includes/templates/iot-gateway/mqtt-connector/workers-settings-section-basic.md
@@ -1,5 +1,9 @@
 ![image](/images/gateway/mqtt-connector/workers-settings-1-ce.png)
 
-**Max number of workers** is a maximal number of workers thread for converters (amount of workers changes dynamically, depending on load). Recommended amount 50-100.
+1. **Max messages queue per worker**<br/>
+How many MQTT messages one worker handles in a single turn before letting others run. 
+Bigger number = higher throughput; smaller = lower latency. Example: ~100 for heavy telemetry, ~10–20 for fast RPC.
 
-**Max messages queue per worker** is a maximal messages count that will be in queue for each converter worker.
+2. **Max number of workers**<br/>
+How many workers run at the same time. More workers use more CPU cores but can cause contention if too high. 
+Start near your CPU core count and tweak based on backlog and CPU.