...
IoT package is available with RouterOS version 6.48.3. You can get it from our download page - under "Extra packages".
| Property | Description |
|---|---|
| brokers | A list of configured MQTT brokers. |
| connect | A command that specifies, which broker to connect to. |
| disconnect | A command that specifies, which broker to disconnect from. |
| publish | A command that defines the MQTT message that needs to be published. |
subscribe | A command that defines MQTT topics to subscribe to. |
subscriptions | A list of subscribed topics and received messages. |
unsubscribe | A command that specifies, which topic to unsubscribe from. |
Brokers
To add a new MQTT broker (or an MQTT server), run the following command:
...
Configurable properties are shown below:
| Property | Description |
|---|---|
| address (IP|hostname; Default: ) | IP address or hostname of the broker. |
| auto-connect (yes | no; Default: no) | When enabled, after the connection with the MQTT broker goes down/gets interrupted, RouterOS will try to re-establish the connection over and over again. |
| certificate (string; Default: ) | The certificate that is going to be used for the SSL connection. |
client-id (string; Default: ) | A unique ID used for the connection. The broker uses this ID to identify the client. |
keep-alive (integer:30..64800; Default: 60) | A parameter that defines the time (in seconds), after which the client should "ping" the MQTT broker that it is "alive", to ensure the connection stays ongoing. This value should be set according to MQTT broker settings. |
name (string; Default: ) | Descriptive name of the broker. |
parallel-scripts-limit (integer:3..1000; Default: off) | A parameter that defines how many scripts the on-message feature for this broker is allowed to run at the exact same time. Can be useful to reduce CPU, in cases when a large number of messages are constantly published. |
password (string; Default: ) | Password for the broker (if required by the broker). |
port (integer:0..4294967295; Default: 1883) | Network port used by the broker. |
ssl (yes | no; Default: no) | Secure Socket Layer configuration. |
| username (string; Default: ) | Username for the broker (if required by the broker). |
An example of adding a broker:
...
Publish menu is used to send MQTT messages to the MQTT broker.
| Property | Description |
|---|---|
| broker (string; Default: ) | Select the broker, where to publish the message. |
| disconnect-after (yes | no; Default: no) | Parameter, that ensures that the connection with the broker will be automatically disconnected after the publish message is sent. |
| force (yes | no; Default: yes) | If set to "yes", when the connection with the broker is not yet established ("connected=no"), and the message is attempted to be published, RouterOS will try to establish an MQTT connection with the specified broker first and then publish the message. If set to "no", RouterOS will not be able to send the message, unless the connection is already established beforehand ("connected=yes"). |
message (string; Default: ) | The message that you wish to publish to the broker. |
qos (integer:0..4294967295; Default: 0) | Quality of service parameter, as defined by the broker. |
retain (yes | no; Default: no) | Whether to retain the message or to discard it if no one is subscribed to the topic. This parameter is defined by the broker. |
topic (string; Default: ) | Topic, as defined by the broker. |
An example of publishing the message:
...
This menu is used to subscribe to MQTT topics from the broker.
| Property | Description |
|---|---|
| broker (string; Default: ) | Select the broker, where to subscribe to. |
| force (yes | no; Default: yes) | If set to "yes", when the connection with the broker is not yet established ("connected=no"), and subscription is attempted, RouterOS will try to establish an MQTT connection with the specified broker first and then subscribe to the topic. If set to "no", RouterOS will not be able to subscribe to the topic, unless the connection is already established beforehand ("connected=yes"). |
qos (integer:0..4294967295; Default: 0) | Quality of service parameter, as defined by the broker. |
topic (string; Default: ) | Topic, as defined by the broker, where to subscribe to. |
An example of a subscription:
...
It has the same properties as the Subscribe section.
| Info |
|---|
| Since Starting with v7.12beta9, this menu allows you to add the "on-message" setting to your subscriptions. |
| Property | Description |
|---|---|
| on-message (string; Default: ) | Configure a script that will be automatically initiated/run whenever a new message is received in the subscribed topic. |
To check already subscribed topics, issue the command:
...
| Code Block | ||
|---|---|---|
| ||
/iot mqtt subscriptions recv print 0 broker=broker topic="my/test/topic" data="test-message" time=2023-05-22 16:57:00 |
| Info |
|---|
Received message list is limited to 1024 entries. After which, older entries will get overwritten with the new ones. |
To clear stored messages, issue the command:
...
To run a script (for example, a basic "log" script) whenever any new message appears in the subscribed topic, do the followingyou can use the on-message feature:
| Code Block | ||
|---|---|---|
| ||
/iot mqtt subscriptions set on-message={:log info "Got data {$msgData} from topic {$msgTopic}"} broker=broker 0 |
The script can use $msgData and $msgTopic variables. $msgData defines the MQTT message that was published and $msgTopic defines the MQTT topic, where the message was published. Both variables are automatically generated when a new message appears.
| Info |
|---|
|
After you publish a new MQTT message to the subscribed topic, a new log entry should appear:
...
A second example shows how to run a script whenever a specific message (keywords from the message) appears. To achieve a scenario, where we want to run a script only when the MQTT message has specific content or a keyword, we can utilize the the if condition statement:
| Code Block | ||
|---|---|---|
| ||
/iot mqtt subscriptions set 0 on-messag={:if ($msgData~"\\{\"test\":\"123\"\\}") do={:log info "Got data {$msgData} from topic {$msgTopic}"}} |
...
When you receive a message from a topic that falls under multiple subscriptions with with on-message configuration, only x1 on-message script will be run. RouterOS will choose which on-meesage script to run using the following logic/priority:
...
When you publish the data to some/thing/else, script 4 will be initiated → because it falls under the multi-level wildcard topic name (even though it is also matched by some/# wildcard, it is a level closer to some/thing/# entry).
Unsubscribe
| Property | Description |
|---|---|
| broker (string; Default: ) | Select the broker to unsubscribe from. |
topic (string; Default: ) | Select a topic, as defined by the broker, to unsubscribe from. |
An example of unsubscribing from the broker and the topic is shown below:
...