diff --git a/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md b/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md deleted file mode 100644 index e45aab49cc..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md +++ /dev/null @@ -1,29 +0,0 @@ -This configuration section contains settings of the connection to broker, such as: - -| **Parameter** | **Default value** | **Description** | -|:--------------|:-------------------------|-------------------------------------------------------------------- -| name | **Default Local Broker** | Broker name for logs and saving to persistent devices. | -| host | **127.0.0.1** | MQTT broker hostname or ip address. | -| port | **1883** | MQTT port on the broker. | -| version | **5** | MQTT protocol version may be 3 (3.1), 4(3.11) or 5(5) | -| clientId | **tb_gw_li06e** | This is the client ID. It must be unique for each session. | -| security | **anonymous** | This is the configuration for client authorization at MQTT Broker. | -| --- - -Example: - -```json -"broker": { - "name": "Default Local Broker", - "host": "127.0.0.1", - "port": 1883, - "version": 5, - "clientId": "tb_gw_li06e", - "security": { - "type": "anonymous" - } -}, -``` -{: .copy-code} - -![image](/images/gateway/mqtt-connector/connection-to-broker-advanced-section-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md b/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md deleted file mode 100644 index b9efb48b2e..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md +++ /dev/null @@ -1,9 +0,0 @@ -This configuration section contains settings of the connection to broker, such as: - -- Host - MQTT broker hostname or ip address; -- Port - MQTT port on the broker; -- MQTT version - MQTT protocol version; -- Client ID - this is the client ID. It must be unique for each session; -- Security - configuration for client authorization at MQTT Broker (anonymous, basic, or certificates). - -![image](/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/mqtt-basic-section.md b/_includes/templates/iot-gateway/mqtt-connector/mqtt-basic-section.md new file mode 100644 index 0000000000..57c501e139 --- /dev/null +++ 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/_includes/templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md b/_includes/templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md deleted file mode 100644 index 899bed9533..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md +++ /dev/null @@ -1,3 +0,0 @@ -Anonymous auth is the most simple option. It is useful for testing on public MQTT brokers, like test.mosquitto.org. - -![image](/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png) \ No newline at end of file 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 deleted file mode 100644 index 49fd171370..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-basic-basic-subsection.md +++ /dev/null @@ -1,3 +0,0 @@ -One type of security configuration is basic. For authorization, a combination of username and password provided in this section, in config will be used. - -![image](/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-anonymous.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-anonymous.md deleted file mode 100644 index 09c384fb6a..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-config-anonymous.md +++ /dev/null @@ -1,17 +0,0 @@ -Anonymous auth is the most simple option. It is useful for testing on public MQTT brokers, like test.mosquitto.org. - - -|**Parameter**|**Default value**|**Description**| -|:-|:-|- -| type | **anonymous** | Type of authorization. | -|--- - -Security subsection in configuration file will look like this: - -```json - "security": { - "type": "anonymous" - } -``` - -![image](/images/gateway/mqtt-connector/security-advanced-anonymous-subsection-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-basic.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-basic.md deleted file mode 100644 index ce58cd214a..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-config-basic.md +++ /dev/null @@ -1,22 +0,0 @@ -One type of security configuration is basic. -For authorization, a combination of username and password provided in this section, in config will be used. - - -| **Parameter** | **Default value** | **Description** | -|:--------------|:------------------|-----------------------------| -| type | **basic** | Type of authorization. | -| username | **username** | Username for authorization. | -| password | **password** | Password for authorization. | -| --- - -Security subsection in configuration file will look like this: - -```json - "security": { - "type": "basic", - "username": "username", - "password": "password" - } -``` - -![image](/images/gateway/mqtt-connector/security-advanced-basic-subsection-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-config-certificates.md b/_includes/templates/iot-gateway/mqtt-connector/security-config-certificates.md deleted file mode 100644 index c212ee11c0..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-config-certificates.md +++ /dev/null @@ -1,22 +0,0 @@ -The table below describes the parameters required to configure authorization on MQTT broker. - -| **Parameter** | **Default value** | **Description** | -|:------------------|:---------------------------------------------|---------------------------- -| type | **certificates** | Type of authorization. | -| pathToCACert | **/etc/thingsboard-gateway/ca.pem** | Path to CA file. | -| pathToPrivateKey | **/etc/thingsboard-gateway/privateKey.pem** | Path to private key file. | -| pathToClientCert | **/etc/thingsboard-gateway/certificate.pem** | Path to certificate file. | -| --- - -Security subsection in configuration file will look like this: - -```json -"security":{ - "type": "certificates", - "pathToCACert": "/etc/thingsboard-gateway/ca.pem", - "pathToPrivateKey": "/etc/thingsboard-gateway/privateKey.pem", - "pathToClientCert": "/etc/thingsboard-gateway/certificate.pem" -} -``` - -![image](/images/gateway/mqtt-connector/security-advanced-certificates-subsection-1-ce.png) \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-advanced.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-advanced.md deleted file mode 100644 index 70a6dc9959..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-advanced.md +++ /dev/null @@ -1,8 +0,0 @@ -Now select the security type: - -{% capture mqttsecurityadvancedsubsection %} -AnonymousNo security%,%anonymous%,%templates/iot-gateway/mqtt-connector/security-config-anonymous.md%br% -BasicRecommended%,%basic%,%templates/iot-gateway/mqtt-connector/security-config-basic.md%br% -CertificatesFor advanced security%,%certificates%,%templates/iot-gateway/mqtt-connector/security-config-certificates.md{% endcapture %} - -{% include content-toggle.liquid content-toggle-id="mqttsecurityadvancedsubsection" toggle-spec=mqttsecurityadvancedsubsection %} \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-anonymous.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-anonymous.md new file mode 100644 index 0000000000..34b83c0d22 --- /dev/null +++ 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
(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 %} \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-basic.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-basic.md index d050591ff2..013c36fe44 100644 --- 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 %} -AnonymousNo security%,%anonymous%,%templates/iot-gateway/mqtt-connector/security-basic-anonymous-subsection.md%br% -BasicRecommended%,%basic%,%templates/iot-gateway/mqtt-connector/security-basic-basic-subsection.md%br% -CertificatesFor advanced security%,%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 %} \ No newline at end of file +{% include images-gallery.liquid showListImageTitles="true" imageCollection=securityBasic %} \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/security-subsection-certificates.md b/_includes/templates/iot-gateway/mqtt-connector/security-subsection-certificates.md new file mode 100644 index 0000000000..d38056c21b --- /dev/null +++ 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 %} \ No newline at end of file diff --git a/_includes/templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md b/_includes/templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md deleted file mode 100644 index e9fe8ca5b1..0000000000 --- a/_includes/templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md +++ /dev/null @@ -1,4 +0,0 @@ -![image](/images/gateway/mqtt-connector/workers-settings-advanced-1-ce.png) - -- **maxNumberOfWorkers** is a maximal number of workers thread for converters (amount of workers changes dynamically, depending on load). Recommended amount 50-100; -- **maxMessageNumberPerWorker** is a maximal messages count that will be in queue for each converter worker. \ No newline at end of file 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 index 4f70ab5c2f..a4dd1d32c8 100644 --- 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**
+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. \ No newline at end of file +2. **Max number of workers**
+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. \ No newline at end of file diff --git a/docs/iot-gateway/config/mqtt.md b/docs/iot-gateway/config/mqtt.md index 87ac34ef46..1863fb9e63 100644 --- a/docs/iot-gateway/config/mqtt.md +++ b/docs/iot-gateway/config/mqtt.md @@ -11,68 +11,91 @@ redirect_from: * TOC {:toc} -This guide will help you to get familiar with MQTT Connector configuration for ThingsBoard IoT Gateway. -Use [general configuration](/docs/iot-gateway/configuration/) to enable this Connector. -The purpose of this Connector is to connect to an external MQTT broker and subscribe to data feed from devices. -The connector is also able to push data to MQTT brokers based on the updates/commands from ThingsBoard. +## Overview -This connector is useful when you have local MQTT broker in your facility or corporate network, and you would like to push data from this broker to ThingsBoard. +This documentation will help you set up the MQTT connector for the ThingsBoard IoT Gateway. We'll explain the configuration +parameters in simple terms to make it easy for you to understand and follow. The MQTT(Message Queuing Telemetry Transport) +is a lightweight publish-subscribe, machine-to-machine network protocol that is widely used for connections with remote +locations with devices that have resource constraints or network transfer rate. +Use [general configuration](/docs/iot-gateway/configuration/){:target="_blank"} to enable this connector. -We will describe connector configuration file below. +Also, if you are new to ThingsBoard IoT Gateway, we recommend you to read the [Getting Started](/docs/iot-gateway/getting-started/?connectorsCreation=mqtt){:target="_blank"} +guide to understand the basic concepts of ThingsBoard IoT Gateway and how it works with MQTT protocol. + +The connector can be configured via the user interface form, which helps you set up a connection to an MQTT broker and +read/write data by subscribing/publishing to MQTT topics, that can be defined statically or generated on the fly. +Let's look at all the available settings and explain each one clearly. +This will help you understand how everything works. {% capture difference %} **Please note:** -If you are new to IoT Gateway, use the "Basic" configuration mode. If you are familiar with configuring IoT Gateway, you can use the "Advanced" configuration mode. +To access the actual UI for the gateway - you need to a have connected gateway before adding a connector. Otherwise, you will see the old UI. {% endcapture %} {% include templates/info-banner.md content=difference %} -## Connector configuration +## Configuration modes + +The MQTT connector can be configured in two modes: **Basic** and **Advanced**. +- **Basic** mode is designed for users who are new to ThingsBoard IoT Gateway and want to quickly set up the connector with minimal configuration. It provides a simplified interface with essential settings. +- **Advanced** mode is intended for experienced users who need more control over the configuration. It offers additional options and flexibility for advanced use cases. + +{% capture difference %} +**Please note:** +If you are new to IoT Gateway, use the "Basic" configuration mode. If you are familiar with configuring IoT Gateway, +you can use the "Advanced" configuration mode. +{% endcapture %} +{% include templates/info-banner.md content=difference %} -Connector configuration is a UI form that contains information about how to connect to external MQTT broker, what topics to use when subscribing to data feed and how to process the data. -Let's take a comprehensive look at all the possible settings. We will go through each option in detail to ensure that we thoroughly understand their functions and implications. -By doing so, we can make well-informed decisions about which settings will best suit our needs and preferences. +You can switch between these modes using the toggle button at the top of the configuration page: -## Section "General" +![image.png](/images/gateway/mqtt-connector/mqtt-modes-toggle.png) -This configuration section contains general connector settings, such as: +## General settings -- Name - connector name for logs and saving to persistent devices; -- Logs configuration: - - Enable remote logging - enabling remote logging for connector; - - Logging level - logging level for local and remote logs: INFO, DEBUG, WARNING, ERROR, CRITICAL, NONE; -- Send data only on change - sending only if data changed from last check, if not – data will be sent after every check. +{% include /templates/iot-gateway/connector-commons/general-settings.md %} ![image](/images/gateway/mqtt-connector/general-basic-section-1-ce.png) {% capture difference %} -The settings are the same for both the basic and advanced configurations. +The General tab in settings is the same for both the basic and advanced configurations. {% endcapture %} {% include templates/info-banner.md content=difference %} -## Section "Connection to broker" +## Connection settings -Section "Connection to broker" offers detailed connection configuration options and contains several important fields, including host, port, MQTT version, client ID, and security settings. -The host field specifies the address of the broker, while the port field indicates the communication port. -The MQTT version field ensures compatibility with the protocol version being used. -The client ID uniquely identifies the client, and the security settings provides configuration for client authorization at MQTT Broker. +Connection settings how the MQTT connector establishes and maintains communication with the MQTT broker. +These settings cover the basic connection parameters, mqtt version protocol that will be used for security configuration, and +authentication modes. -{% capture mqttconnectiontobrokersection %} -Basic%,%basic%,%templates/iot-gateway/mqtt-connector/connection-to-broker-basic-section.md%br% -Advanced%,%advanced%,%templates/iot-gateway/mqtt-connector/connection-to-broker-advanced-section.md{% endcapture %} +### Connection to broker -{% include content-toggle.liquid content-toggle-id="mqttconnectiontobrokersection" toggle-spec=mqttconnectiontobrokersection %} +This subsection specifies the target MQTT broker and how the gateway interacts with it. It includes the broker's host, +port, mqtt version protocol, client id. -### Subsection "Security" +{% include /templates/iot-gateway/mqtt-connector/mqtt-basic-section.md %} -Subsection "Security" provides configuration for client authorization at MQTT Broker. +### Security -Firstly, select basic or advanced MQTT configuration: +MQTT broker connections offer three distinct security types: [Anonymous](/docs/iot-gateway/config/mqtt/#anonymous), +[Basic](/docs/iot-gateway/config/mqtt/#basic), [Certificates](/docs/iot-gateway/config/mqtt/#certificates). + +#### Anonymous + +{% include /templates/iot-gateway/mqtt-connector/security-subsection-anonymous.md %} -{% capture mqttsecuritysubsection %} -Basic%,%basic%,%templates/iot-gateway/mqtt-connector/security-subsection-basic.md%br% -Advanced%,%advanced%,%templates/iot-gateway/mqtt-connector/security-subsection-advanced.md{% endcapture %} +#### Basic -{% include content-toggle.liquid content-toggle-id="mqttsecuritysubsection" toggle-spec=mqttsecuritysubsection %} +{% include /templates/iot-gateway/mqtt-connector/security-subsection-basic.md %} + +#### Certificates + +{% include /templates/iot-gateway/mqtt-connector/security-subsection-certificates.md%} + +{% capture difference %} +All configuration parameters list for each authentication mode, 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 %} ## Section "Data mapping" @@ -354,242 +377,160 @@ Advanced%,%advanced%,%templates/iot-gateway/mqtt-connector/server {% include content-toggle.liquid content-toggle-id="mqttattributerequestsubsection" toggle-spec=mqttattributerequestsubsection %} -## Workers settings +## Advanced configuration -This configuration settings provides fields for configuring connector performance and message reading/formatting speed: +The advanced configuration section provides a detailed overview of all available parameters for the MQTT connector. -Select basic or advanced MQTT configuration: +### Connection to broker -{% capture mqttattributerequestsubsection %} -Basic%,%basic%,%templates/iot-gateway/mqtt-connector/workers-settings-section-basic.md%br% -Advanced%,%advanced%,%templates/iot-gateway/mqtt-connector/workers-settings-section-advanced.md{% endcapture %} +The broker section defines the target MQTT broker and how the gateway interacts with it. -{% include content-toggle.liquid content-toggle-id="mqttattributerequestsubsection" toggle-spec=mqttattributerequestsubsection %} -## Configuration file +| **Parameter** | **Default value** | **Description** | +|:------------------------------------------|:------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| broker | | The broker object specifies the target mqtt broker and how the gateway interacts with it. | +| broker.host | | Hostname or ip address that will be used for establishing connection to MQTT broker. | +| broker.port | **1883** | Listening MQTT port on the broker that will accept connection from a client. | +| broker.version | **5** | MQTT protocol version (there are three versions currently supported by gateway - **3.1**, **3.11**, **5**). | +| broker.clientId ** | **ThingsBoard_gateway** | Unique identifier for each client’s session on the broker. | +| broker.maxMessageNumberPerWorker | **10** | (Optional) Maximum number of MQTT messages a single worker (a background helper that processes queued messages)
handles in one pass before letting other workers run. You may read more about this in the [Workers settings](/docs/iot-gateway/config/mqtt/#workers-settings). | +| broker.maxNumberOfWorkers | **100** | (Optional) Maximum number of workers (background helpers that process queued messages)
the gateway can run in parallel to handle MQTT traffic. You may read more about this in the [Workers settings](/docs/iot-gateway/config/mqtt/#workers-settings). | +| broker.keepAlive (in seconds) | **60** | (Optional) Seconds between pings; e.g., default is 60s, the broker expects traffic within the given interval * 1.5 or it closes the connection. | +| broker.cleanSession | **true** | (Optional) Tells the broker whether to start fresh or keep your previous session, Use `false`, if you want offline message queueing; use `true` if you always reconnect cleanly and don’t need persistence(Only for 3.1, 3.11 see details here - [MQTT Parameter Version Differences](/docs/iot-gateway/config/mqtt/#mqtt-parameter-version-differences). | +| broker.cleanStart | **true** | (Optional) Simular to **broker.cleanSession**, but unlike it, only decides what happens **at the start** of a connection; use `true`, if you want discard an old session; use `false` if you want to try to resume it (For MQTT 5.0 only see details here - [MQTT Parameter Version Differences](/docs/iot-gateway/config/mqtt/#mqtt-parameter-version-differences). | +| broker.sessionExpiryInterval (in seconds) | **0** | (Optional) How long the broker should keep your session after you disconnect (For MQTT 5.0 only see details here - [MQTT Parameter Version Differences](/docs/iot-gateway/config/mqtt/#mqtt-parameter-version-differences). | +| --- | | | -Example of MQTT Connector configuration file: +{% capture difference %} +**Please note:** +\** -- The broker (or broker cluster) does not allow two simultaneous sessions with the same **broker.clientId**. 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 [Connection to broker](/docs/iot-gateway/config/mqtt/#connection-to-broker) subsection. +{% endcapture %} +{% include templates/info-banner.md content=difference %} + +Example of the server configuration: ```json -{ - "broker": { - "host": "127.0.0.1", - "port": 1883, - "clientId": "ThingsBoard_gateway", - "version": 5, - "maxMessageNumberPerWorker": 10, - "maxNumberOfWorkers": 100, - "sendDataOnlyOnChange": false, - "security": { - "type": "anonymous" - } - }, - "mapping": [ - { - "topicFilter": "sensor/data", - "subscriptionQos": 1, - "converter": { - "type": "json", - "deviceInfo": { - "deviceNameExpressionSource": "message", - "deviceNameExpression": "${serialNumber}", - "deviceProfileExpressionSource": "message", - "deviceProfileExpression": "${sensorType}" - }, - "sendDataOnlyOnChange": false, - "timeout": 60000, - "attributes": [ - { - "type": "string", - "key": "model", - "value": "${sensorModel}" - }, - { - "type": "string", - "key": "${sensorModel}", - "value": "on" - } - ], - "timeseries": [ - { - "type": "string", - "key": "temperature", - "value": "${temp}" - }, - { - "type": "double", - "key": "humidity", - "value": "${hum}" - }, - { - "type": "string", - "key": "combine", - "value": "${hum}:${temp}" - } - ] - } - }, - { - "topicFilter": "sensor/+/data", - "subscriptionQos": 1, - "converter": { - "type": "json", - "deviceInfo": { - "deviceNameExpressionSource": "topic", - "deviceNameExpression": "(?<=sensor/)(.*?)(?=/data)", - "deviceProfileExpressionSource": "constant", - "deviceProfileExpression": "Thermometer" - }, - "sendDataOnlyOnChange": false, - "timeout": 60000, - "attributes": [ - { - "type": "string", - "key": "model", - "value": "${sensorModel}" - } - ], - "timeseries": [ - { - "type": "double", - "key": "temperature", - "value": "${temp}" - }, - { - "type": "string", - "key": "humidity", - "value": "${hum}" - } - ] - } - }, - { - "topicFilter": "sensor/raw_data", - "subscriptionQos": 1, - "converter": { - "type": "bytes", - "deviceInfo": { - "deviceNameExpressionSource": "message", - "deviceNameExpression": "[0:4]", - "deviceProfileExpressionSource": "constant", - "deviceProfileExpression": "default" - }, - "sendDataOnlyOnChange": false, - "timeout": 60000, - "attributes": [ - { - "type": "raw", - "key": "rawData", - "value": "[:]" - } - ], - "timeseries": [ - { - "type": "raw", - "key": "temp", - "value": "[4:]" - } - ] - } - }, - { - "topicFilter": "custom/sensors/+", - "subscriptionQos": 1, - "converter": { - "type": "custom", - "extension": "CustomMqttUplinkConverter", - "cached": true, - "extensionConfig": { - "temperature": 2, - "humidity": 2, - "batteryLevel": 1 - } - } - } - ], - "requestsMapping": { - "connectRequests": [ - { - "topicFilter": "sensor/connect", - "deviceInfo": { - "deviceNameExpressionSource": "message", - "deviceNameExpression": "${serialNumber}", - "deviceProfileExpressionSource": "constant", - "deviceProfileExpression": "Thermometer" - } - }, - { - "topicFilter": "sensor/+/connect", - "deviceInfo": { - "deviceNameExpressionSource": "topic", - "deviceNameExpression": "(?<=sensor/)(.*?)(?=/connect)", - "deviceProfileExpressionSource": "constant", - "deviceProfileExpression": "Thermometer" - } - } - ], - "disconnectRequests": [ - { - "topicFilter": "sensor/disconnect", - "deviceInfo": { - "deviceNameExpressionSource": "message", - "deviceNameExpression": "${serialNumber}" - } - }, - { - "topicFilter": "sensor/+/disconnect", - "deviceInfo": { - "deviceNameExpressionSource": "topic", - "deviceNameExpression": "(?<=sensor/)(.*?)(?=/connect)" - } - } - ], - "attributeRequests": [ - { - "retain": false, - "topicFilter": "v1/devices/me/attributes/request", - "deviceInfo": { - "deviceNameExpressionSource": "message", - "deviceNameExpression": "${serialNumber}" - }, - "attributeNameExpressionSource": "message", - "attributeNameExpression": "${versionAttribute}, ${pduAttribute}", - "topicExpression": "devices/${deviceName}/attrs", - "valueExpression": "${attributeKey}: ${attributeValue}" - } - ], - "attributeUpdates": [ - { - "retain": true, - "deviceNameFilter": ".*", - "attributeFilter": "firmwareVersion", - "topicExpression": "sensor/${deviceName}/${attributeKey}", - "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}" - } - ], - "serverSideRpc": [ - { - "type": "twoWay", - "deviceNameFilter": ".*", - "methodFilter": "echo", - "requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}", - "responseTopicExpression": "sensor/${deviceName}/response/${methodName}/${requestId}", - "responseTopicQoS": 1, - "responseTimeout": 10000, - "valueExpression": "${params}" - }, - { - "type": "oneWay", - "deviceNameFilter": ".*", - "methodFilter": "no-reply", - "requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}", - "valueExpression": "${params}" - } - ] +"broker": { + "host": "127.0.0.1", + "port": 1883, + "version": 5, + "clientId": "ThingsBoard_gateway", + "maxMessageNumberPerWorker": 10, + "maxNumberOfWorkers": 100, + "keepAlive": 60, + "cleanSession": true, + "cleanStart": true, + "sessionExpiryInterval": 0, + "security": { + "type": "anonymous" } } ``` -{:.copy-code.expandable-15} +{: .copy-code} + +### Security + +MQTT broker connections offer three distinct security types: [Anonymous](/docs/iot-gateway/config/mqtt/#anonymous-1), +[Basic](/docs/iot-gateway/config/mqtt/#basic-1), [Certificates](/docs/iot-gateway/config/mqtt/#certificates-1). + +#### Anonymous + +**Anonymous** is the simplest option: no credentials are required to publish/subscribe on the MQTT broker. +*not recommended for production*, because it allows unattended access. + + +| **Parameter** | **Default value** | **Description** | +|:---------------------|:------------------------|------------------------------------------------------------------------------------------------------| +| broker.security | | The broker security object specifies authentication type for establishing connection to MQTT broker. | +| broker.security.type | **anonymous** | Type of authentication. | +| --- | | | + + +Example of the security configuration for **anonymous** authentication option. + +```json +"security": { + "type": "anonymous" +} +``` +{: .copy-code} + +#### Basic + +**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. + + +| **Parameter** | **Default value** | **Description** | +|:--------------------------------|:------------------|---------------------------------------------------------------------------------------------------| +| broker.security | | The broker security object specifies authentication type for establishing connection to MQTT broker.| +| broker.security.type | **basic** | Type of authentication. | +| broker.security.username | **username** | Username that will be used for establishing connection with MQTT broker. | +| broker.security.password | **password** | Password that will be used for establishing connection with MQTT broker. | +| --- | | | + + +Example of the security configuration for **basic** authentication option: + +```json +"security": { + "type": "basic", + "username": "username", + "password": "password" +} +``` +{: .copy-code} + +#### Certificates + +**Certificate-based authentication** uses TLS certificates so the gateway and broker verify each other. +The safest authentication mode, setting up use the broker’s TLS port (typically 8883) for encrypted, production-grade security. + + + +| **Parameter** | **Default value** | **Description** | +|:---------------------------------|:---------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| broker.security | | The broker security object specifies authentication type for establishing connection to MQTT broker. | +| broker.security.type | **certificates** | Type of authentication. | +| broker.security.pathToCACert | **/etc/thingsboard-gateway/ca.pem** | Path to the **pathToCACert** your CA certificate your MQTT client uses it to check the broker’s certificate during TLS, ensuring you’re connecting to a trusted server. | +| broker.security.pathToPrivateKey | **/etc/thingsboard-gateway/privateKey.pem** | Path to the **pathToPrivateKey** the key that proves the client’s identity and enables secure TLS handshakes. | +| broker.security.pathToClientCert | **/etc/thingsboard-gateway/certificate.pem** | Path to the **pathToClientCert** your certificate that identifies the gateway to the MQTT broker during TLS handshake. It’s paired with the gateway’s private key and is usually signed by a trusted CA. | + + +Example of the security configuration for **certificates** authentication option: + +```json +"security": { + "type": "certificates", + "pathToCACert": "/etc/thingsboard-gateway/ca.pem", + "pathToPrivateKey": "/etc/thingsboard-gateway/privateKey.pem", + "pathToClientCert": "/etc/thingsboard-gateway/certificate.pem" +} +``` +{: .copy-code} + +## Workers settings + +This configuration settings provides fields for configuring connector performance and message reading/formatting speed: + +{% include /templates/iot-gateway/mqtt-connector/workers-settings-section-basic.md %} + +## Additional information + +## Troubleshooting + +### MQTT Parameter Version Differences + +1. **broker.cleanSession** +*MQTT 3.1, 3.11 only*; in *MQTT 5.0* it’s replaced by **broker.cleanStart** (on connect behavior) plus **broker.sessionExpiryInterval** (how long the session is kept after disconnect). + +2. **broker.sessionExpiryInterval** +*MQTT 5.0 only*; if it is `0` drop session on disconnect, if it is bigger than `0` keep it for that many seconds. + +3. **broker.cleanStart** +*MQTT 5.0 only*; controls what happens at connect: `true` discards any previous session, `false` tries to resume it. ## Next steps diff --git a/images/gateway/mqtt-connector/connection-to-broker-advanced-section-1-ce.png b/images/gateway/mqtt-connector/connection-to-broker-advanced-section-1-ce.png deleted file mode 100644 index 6adcba2659..0000000000 Binary files a/images/gateway/mqtt-connector/connection-to-broker-advanced-section-1-ce.png and /dev/null differ diff --git a/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png b/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png old mode 100755 new mode 100644 index 16a700f29a..521f2c6090 Binary files a/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png and b/images/gateway/mqtt-connector/connection-to-broker-basic-section-1-ce.png differ diff --git a/images/gateway/mqtt-connector/general-basic-section-1-ce.png b/images/gateway/mqtt-connector/general-basic-section-1-ce.png old mode 100755 new mode 100644 index a6f9781b68..3adb9500d7 Binary files a/images/gateway/mqtt-connector/general-basic-section-1-ce.png and b/images/gateway/mqtt-connector/general-basic-section-1-ce.png differ diff --git a/images/gateway/mqtt-connector/generate-clientID-from-UI.png b/images/gateway/mqtt-connector/generate-clientID-from-UI.png new file mode 100644 index 0000000000..44cf3cda82 Binary files /dev/null and b/images/gateway/mqtt-connector/generate-clientID-from-UI.png differ diff --git a/images/gateway/mqtt-connector/generated-clientID-from-UI.png b/images/gateway/mqtt-connector/generated-clientID-from-UI.png new file mode 100644 index 0000000000..7197c6af44 Binary files /dev/null and b/images/gateway/mqtt-connector/generated-clientID-from-UI.png differ diff --git a/images/gateway/mqtt-connector/mqtt-modes-toggle.png b/images/gateway/mqtt-connector/mqtt-modes-toggle.png new file mode 100644 index 0000000000..24f60df856 Binary files /dev/null and b/images/gateway/mqtt-connector/mqtt-modes-toggle.png differ diff --git a/images/gateway/mqtt-connector/security-advanced-anonymous-subsection-1-ce.png b/images/gateway/mqtt-connector/security-advanced-anonymous-subsection-1-ce.png deleted file mode 100755 index e57e676f4d..0000000000 Binary files a/images/gateway/mqtt-connector/security-advanced-anonymous-subsection-1-ce.png and /dev/null differ diff --git a/images/gateway/mqtt-connector/security-advanced-basic-subsection-1-ce.png b/images/gateway/mqtt-connector/security-advanced-basic-subsection-1-ce.png deleted file mode 100755 index e0f7628c40..0000000000 Binary files a/images/gateway/mqtt-connector/security-advanced-basic-subsection-1-ce.png and /dev/null differ diff --git a/images/gateway/mqtt-connector/security-advanced-certificates-subsection-1-ce.png b/images/gateway/mqtt-connector/security-advanced-certificates-subsection-1-ce.png deleted file mode 100755 index 3af38572f7..0000000000 Binary files a/images/gateway/mqtt-connector/security-advanced-certificates-subsection-1-ce.png and /dev/null differ diff --git a/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce-preview.png b/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce-preview.png new file mode 100644 index 0000000000..1e8e8cbcd1 Binary files /dev/null and b/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce-preview.png differ diff --git a/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png b/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png old mode 100755 new mode 100644 index 5cda9d9279..1dee435675 Binary files a/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png and b/images/gateway/mqtt-connector/security-basic-anonymous-subsection-1-ce.png differ diff --git a/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce-preview.png b/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce-preview.png new file mode 100644 index 0000000000..058234fb63 Binary files /dev/null and b/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce-preview.png differ diff --git a/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png b/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png old mode 100755 new mode 100644 index c1cc59fbf1..c67e310438 Binary files a/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png and b/images/gateway/mqtt-connector/security-basic-basic-subsection-1-ce.png differ diff --git a/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce-preview.png b/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce-preview.png new file mode 100644 index 0000000000..7343015216 Binary files /dev/null and b/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce-preview.png differ diff --git a/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce.png b/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce.png old mode 100755 new mode 100644 index 75c534694a..663d000378 Binary files a/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce.png and b/images/gateway/mqtt-connector/security-basic-certificates-subsection-1-ce.png differ diff --git a/images/gateway/mqtt-connector/workers-settings-1-ce.png b/images/gateway/mqtt-connector/workers-settings-1-ce.png old mode 100755 new mode 100644 index 118b10973e..2634d0aa14 Binary files a/images/gateway/mqtt-connector/workers-settings-1-ce.png and b/images/gateway/mqtt-connector/workers-settings-1-ce.png differ diff --git a/images/gateway/mqtt-connector/workers-settings-advanced-1-ce.png b/images/gateway/mqtt-connector/workers-settings-advanced-1-ce.png deleted file mode 100755 index cfaffc8836..0000000000 Binary files a/images/gateway/mqtt-connector/workers-settings-advanced-1-ce.png and /dev/null differ