You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
MQTT module for the [OpenDAQ SDK](https://github.com/openDAQ/openDAQ).
6
-
5
+
MQTT module for the [OpenDAQ SDK](https://github.com/openDAQ/openDAQ). The module is designed for software communication via the *MQTT 3.1.1* protocol using an external broker. It allows publishing and subscribing to openDAQ signal data over MQTT. The module consists of four key openDAQ components: the *MQTT device* and its nested function blocks — the *publisher* (**@publisherMqttFb**), the *raw subscriber* (**@rawMqttFb**), and the *JSON subscriber* (**@jsonMqttFb**).
6
+
7
+
### Functional
8
+
- Connecting to an MQTT broker;
9
+
- Publishing openDAQ signals as MQTT messages (*publisher FB*);
10
+
- Subscribing to MQTT topics and converting incoming messages into openDAQ signals (*raw FB and JSON FB*);
11
+
- Support for multiple message types and formats for both publishing and subscribing;
12
+
- A set of examples and *gtests* for verifying functionality.
-**Purpose**: Represents the MQTT broker as an openDAQ device - the connection point through which function blocks are created.
18
+
-**Main properties:**
19
+
-*MqttBrokerAddress* (string) - MQTT broker address. It can be an IP address or a hostname. By default, it is set to *"127.0.0.1"*.
20
+
-*MqttBrokerPort* (integer) - Port number for the MQTT broker connection. By default, it is set to *1883*.
21
+
-*MqttUsername* (string) — Username for MQTT broker authentication. By default, it is empty.
22
+
-*MqttPassword* (string) — Password for MQTT broker authentication. By default, it is empty.
23
+
-*ConnectTimeout* (integer) — Timeout in milliseconds for the initial connection to the MQTT broker. If the connection fails, an exception is thrown. By default, it is set to *3000 ms*.
24
+
2)**Publisher MQTT Function Block (@publisherMqttFb)**:
-**Purpose**: Publishes openDAQ signal data to MQTT topics. There are **four** general data publishing schemes:
27
+
1) One MQTT message per signal / one message per sample / one topic per signal / one timestamp for each sample. Example: *{"AI0": 1.1, "timestamp": 1763716736100000}*
28
+
29
+
2) One MQTT message per signal / one message containing several samples / one topic per signal / one timestamp per sample (array of samples). Example: *{"AI0": [1.1, 2.2, 3.3], "timestamps": [1763716736100000, 1763716736200000, 1763716736300000]}*
30
+
31
+
3) One MQTT message for several signals (from 1 to N) / one message per sample for each signal / one topic for all signals / separate timestamps for each signal. Example: *[{"AI0": 1.1, "timestamp": 1763716736100000}, {"AI1": 2, "timestamp": 1763716736700000}]*
32
+
33
+
4) One MQTT message for all signals / one message per sample containing all signals / one topic for all signals / one shared timestamp for all signals. Example: *{"AI0": 1.1, "AI1": 2, "timestamp": 1763716736100000}*
34
+
35
+
The schemes are configured through combinations of properties.
36
+
37
+
-**Main properties**:
38
+
-*TopicMode* (list) — Selects whether to publish all signals to separate MQTT topics (one per signal, *single-topic mode*) or to a single topic (*multiple-topic mode*), one for all signals. Choose *0* for *single-topic* mode and *1* for *multiple-topic* mode. By default, it is set to *single-topic* mode.
39
+
-*MqttQoS* (integer) — MQTT Quality of Service level. It can be *0* (at most once), *1* (at least once), or *2* (exactly once). By default, it is set to *1*.
40
+
-*SharedTimestamp* (bool) — Enables the use of a shared timestamp for all signals when publishing in *multiple-topic* mode. By default, it is set to *false*.
41
+
-*GroupValues* (bool) — Enables the use of a sample pack for a signal when publishing in *single-topic* mode. By default, it is set to *false*.
42
+
-*UseSignalNames* (bool) — Uses signal names as JSON field names instead of Global IDs. By default, it is set to *false*.
43
+
-*GroupValuesPackSize* (integer) — Sets the size of the sample pack when publishing grouped values in *single-topic* mode. By default, it is set to *1*.
44
+
-*ReaderPeriod* (integer) — Polling period in milliseconds, specifying how often the server collects and publishes the connected signals’ data to an MQTT broker. By default, it is set to *20 ms*.
45
+
46
+
To configure the publishing schemes, set the properties as follows:
-**Purpose**: Subscribes to raw MQTT messages and converts them into openDAQ signals (binary data) without any parsing — suitable for binary/unstructured messages or simple numeric values.
57
+
-**Main properties**:
58
+
-*SignalList* (list of strings) — List of MQTT topics to subscribe to for receiving raw binary data.
-**Purpose**: Subscribes to MQTT topics, extracts values and timestamps from MQTT JSON messages, and converts them into openDAQ signal data samples.
63
+
-**Main properties**:
64
+
-*SignalList* (string) — **JSON configuration string** that defines the list of MQTT topics and the corresponding signals to subscribe to. A typical string structure:
The *‘Timestamp’* and *‘Unit’* fields may be omitted. The fields inside *‘Unit’* may also be omitted. Example:
86
+
```json
87
+
{
88
+
"/mirip/UNet3AC2/sensor/data":[
89
+
{
90
+
"temp":{
91
+
"Value":"temp",
92
+
"Timestamp":"ts",
93
+
"Unit":[
94
+
"°C"
95
+
]
96
+
}
97
+
},
98
+
{
99
+
"humidity":{
100
+
"Value":"humi",
101
+
"Timestamp":"ts"
102
+
}
103
+
},
104
+
{
105
+
"tds":{
106
+
"Value":"tds_value",
107
+
"Unit":[
108
+
"ppm", "parts per million", "Total dissolved solids"
109
+
]
110
+
}
111
+
}
112
+
]
113
+
}
114
+
```
115
+
In this example, the *JSON MQTT Function Block* creates 3 signals, subscribes to the *"/mirip/UNet3AC2/sensor/data"* topic, and extracts 3 signal samples from each message (one sample per signal). The signals are named *“temp”*, *“humidity”*, and *“tds”*. The *“temp”* signal is created with a domain signal because the *“Timestamp”* field is present. Each domain-signal sample is extracted from the *“ts”* field of the JSON MQTT message. The value of the *“ts”* field (the timestamp field) may be in **ISO8601** format or **Unix epoch time** in seconds, milliseconds, or microseconds. The value of the *“temp”* signal sample is extracted from the *“temp”* field of the JSON message. The unit of the values is “°C”.
116
+
Example of JSON MQTT message for this configuration:
-**custom-mqtt-sub** - demonstrates how to work with the *JSON MQTT FB*. The application creates an *MQTT device* and a *JSON MQTT FB* to receive JSON MQTT messages, parse them, and create openDAQ signals to send the parsed data. The application also creates *packet readers* for all FB signals and prints the samples to standard output. The *SignalList* property of the JSON MQTT FB is set to the value read from a file whose path is provided as a command-line argument when the application starts (see the **Key components** section). Usage:
-**ref-dev-mqtt-raw-sub** - demonstrates how to work with the raw MQTT FB. The application creates an MQTT device and a raw MQTT FB to receive MQTT messages and create openDAQ signals to send the data as binary packets. The application also creates packet readers for all FB signals and prints the binary packets as strings to standard output. The SignalList property of the raw MQTT FB is filled from the application arguments. Usage:
-**ref-dev-mqtt-fb-pub** - demonstrates how to work with the *publisher MQTT FB*. The application creates an *openDAQ ref-device* with four channels, an *MQTT device*, and a *publisher MQTT FB* to publish JSON MQTT messages with the channels’ data. The properties of the *publisher MQTT FB* are set according to the selected mode, which can be specified via the *--mode* option. Posible values are:
176
+
- 0 - One MQTT message per signal / one message per sample / one topic per signal / one timestamp for each sample;
177
+
- 1 - One MQTT message per signal / one message containing several samples / one topic per signal / one timestamp per sample (array of samples);
178
+
- 2 - One MQTT message for several signals (from 1 to N) / one message per sample for each signal / one topic for all signals / separate timestamps for each signal;
179
+
- 3 - One MQTT message for all signals / one message per sample containing all signals / one topic for all signals / one shared timestamp for all signals.
> ***Note:****Using the applications involves using a third-party broker. It must be started before example applications. See a **External MQTT tools** section for more details*
191
+
192
+
> ***Note:****The **ref-dev-mqtt-fb-pub** application depends on [**RefDeviceModule**](https://github.com/openDAQ/openDAQ/tree/main/examples/modules/ref_device_module).*
51
193
52
-
There are several example applications in the *"examples"* folder. These examples are based on OpenDAQ SDK and allow testing of *MQTTStreamingModule* client/server sides with each other and with third-party MQTT tools.
53
194
54
-
> ***Note:****Using the applications involves using a third-party broker. It must be started before example applications. See a **External MQTT tools** section for more details*
195
+
## External MQTT tools
55
196
56
-
> ***Note:****The applications depend on **MQTTStreamingModule** and [**RefDeviceModule**](https://github.com/openDAQ/openDAQ/tree/main/examples/modules/ref_device_module).*
197
+
It is suggested to use [***Eclipse Mosquitto***](https://github.com/eclipse-mosquitto/mosquitto) as a third-party MQTT tool set. It includes MQTT broker and MQTT publisher/subscriber clients.
198
+
Utilities could be installed on **Ubuntu**:
57
199
58
-
#### ref-dev-mqtt-pub
200
+
```shell
201
+
sudo apt install mosquitto mosquitto-clients
202
+
```
59
203
60
-
The *ref-dev-mqtt-pub* application is a console example which publishes *ref-device Signal* samples via the *MQTTStreamingModule* server.
204
+
The MQTT broker will be run automatically after installing. For simple testing run a subscriber with the following options:
61
205
62
-
#### ref-dev-mqtt-sub
206
+
```shell
207
+
mosquitto_sub -h 127.0.0.1 -t "#" -v
208
+
```
209
+
The subscriber will wait for incoming data and then print it. Then run a publisher with the following options:
0 commit comments