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
The *mqtt_client* package provides a ROS nodelet that enables connected ROS-based devices or robots to exchange ROS messages via an MQTT broker using the [MQTT](http://mqtt.org) protocol. This works generically for arbitrary ROS message types. The *mqtt_client* can also exchange primitive messages with MQTT clients running on devices not based on ROS.
11
+
The *mqtt_client* package provides a ROS nodelet or ROS 2 node that enables connected ROS-based devices or robots to exchange ROS messages via an MQTT broker using the [MQTT](http://mqtt.org) protocol. This works generically for arbitrary ROS message types. The *mqtt_client* can also exchange primitive messages with MQTT clients running on devices not based on ROS.
12
12
13
13
-[Installation](#installation)
14
14
-[Usage](#usage)
@@ -26,7 +26,11 @@ The *mqtt_client* package provides a ROS nodelet that enables connected ROS-base
26
26
The *mqtt_client* package is released as an official ROS Noetic package and can easily be installed via a package manager.
27
27
28
28
```bash
29
+
# ROS 1
29
30
sudo apt install ros-noetic-mqtt-client
31
+
32
+
# ROS 2
33
+
sudo apt install ros-humble-mqtt-client
30
34
```
31
35
32
36
If you would like to install *mqtt_client* from source, simply clone this repository into your ROS workspace. All dependencies that are listed in the ROS [`package.xml`](package.xml) can be installed using [*rosdep*](http://wiki.ros.org/rosdep).
The *mqtt_client* is best configured with a ROS parameter *yaml* file. The configuration shown below (also see [`params.yaml`](launch/params.yaml)) allows an exchange of messages as follows:
63
+
The *mqtt_client* is best configured with a ROS parameter *yaml* file. The configuration shown below (also see [`params.yaml`](mqtt_client/config/params.yaml) / [`params.ros2.yaml`](mqtt_client/config/params.ros2.yaml)) allows an exchange of messages as follows:
60
64
61
65
- ROS messages received locally on ROS topic `/ping/ros` are sent to the broker on MQTT topic `pingpong/ros`;
62
66
- MQTT messages received from the broker on MQTT topic `pingpong/ros` are published locally on ROS topic `/pong/ros`;
63
-
- primitive ROS messages received locally on ROS topic `/ping/primitive` are sent as primitive (string) messages to the broker on MQTT topic `pingpong/primitive`;
64
-
- MQTT messages received from the broker on MQTT topic `pingpong/primitive` are published locally as primitive ROS messages on ROS topic `/pong/primitive`.
65
67
66
68
```yaml
67
69
broker:
68
70
host: localhost
69
71
port: 1883
70
72
bridge:
71
73
ros2mqtt:
72
-
- ros_topic: /ping/ros
73
-
mqtt_topic: pingpong/ros
74
-
- ros_topic: /ping/primitive
75
-
mqtt_topic: pingpong/primitive
76
-
primitive: true
74
+
- ros_topic: /ping
75
+
mqtt_topic: pingpong
77
76
mqtt2ros:
78
-
- mqtt_topic: pingpong/ros
79
-
ros_topic: /pong/ros
80
-
- mqtt_topic: pingpong/primitive
81
-
ros_topic: /pong/primitive
82
-
primitive: true
77
+
- mqtt_topic: pingpong
78
+
ros_topic: /pong
83
79
```
84
80
85
81
#### Demo Client Launch
86
82
87
83
After building your ROS workspace, launch the *mqtt_client* nodelet with the pre-configured demo parameters using *roslaunch*, which should yield the following output.
[ INFO] [1665575657.362153083]: Connecting to broker at 'tcp://localhost:1883' ...
105
103
[ INFO] [1665575657.462622065]: Connected to broker at 'tcp://localhost:1883'
106
104
```
@@ -110,55 +108,83 @@ Note that the *mqtt_client* successfully connected to the broker and also echoed
110
108
In order to test the communication among *mqtt_clients*, publish any ROS message on ROS topic `/ping/ros` and wait for a response on ROS topic `/pong/ros`.
111
109
112
110
```bash
113
-
# 1st terminal: listen for ROS messages on /pong/ros
In order to test the communication between *mqtt_client* and other MQTT clients, publish a primitive ROS message on ROS topic `/ping/primitive`, directly publish a primitive MQTT message on MQTT topic `pingpong/primitive` and wait for responses on ROS topic `/pong/primitive`.
130
+
In order to test the communication between *mqtt_client* and other MQTT clients, publish a primitive ROS message on ROS topic `/ping/primitive`, directly publish a primitive MQTT message on MQTT topic `pingpong/primitive` and wait for responses on ROS topic `/pong/primitive`. Note that you need to restart the ROS 2 *mqtt_client* with a different config file.
123
131
124
132
```bash
125
-
# 3rd terminal: listen for primitive ROS messages on /pong/primitive
If everything works as expected, the second terminal should print a message at 1Hz, while the third terminal should print two different messages at 1Hz.
163
+
If everything works as expected, the second terminal should print a message at 1Hz, while the fourth terminal should print two different messages at 1Hz.
140
164
141
165
### Launch
142
166
143
167
You can start the *mqtt_client* nodelet in a standalone nodelet manager with:
This will automatically load the provided demo [params.yaml](launch/params.yaml)to the ROS parameter server. If you wish to load your custom configuration file, simply pass `params_file`.
177
+
This will automatically load the provided demo [`params.yaml`](mqtt_client/config/params.yaml)/ [`params.ros2.yaml`](mqtt_client/config/params.ros2.yaml). If you wish to load your custom configuration file, simply pass `params_file`.
You can also disable parameter loading altogether by passing `load_params:=false`. In this case, make sure to populate the ROS parameter server accordingly with other means.
In order to exploit the benefits of *mqtt_client* being a nodelet, load the nodelet to your own nodelet manager shared with other nodelets.
187
+
In order to exploit the benefits of *mqtt_client* being a ROS 1 nodelet, load the nodelet to your own nodelet manager shared with other nodelets.
162
188
163
189
### Configuration
164
190
@@ -201,9 +227,11 @@ client:
201
227
202
228
#### Bridge Parameters
203
229
230
+
> :warning: The ROS 2 version of *mqtt_client* is currently only capable of running one ROS-to-MQTT and one MQTT-to-ROS transmission at a time. The parameters `brige/ros2mqtt` and `bridge/mqtt2ros` therefore are not lists of dictionaries, but nested dictionaries without list index instead, see [`params.ros2.yaml`](mqtt_client/config/params.ros2.yaml). If you need to bridge multiple topics, you can run multiple instances of *mqtt_client* simultaneously.
231
+
204
232
```yaml
205
233
bridge:
206
-
ros2mqtt: # array specifying which ROS topics to map to which MQTT topics
234
+
ros2mqtt: # array specifying which ROS topics to map to which MQTT topics (not an array in ROS 2 version)
207
235
- ros_topic: # ROS topic whose messages are transformed to MQTT messages
208
236
mqtt_topic: # MQTT topic on which the corresponding ROS messages are sent to the broker
209
237
primitive: # [false] whether to publish as primitive message
@@ -214,7 +242,7 @@ bridge:
214
242
mqtt:
215
243
qos: # [0] MQTT QoS value
216
244
retained: # [false] whether to retain MQTT message
217
-
mqtt2ros: # array specifying which MQTT topics to map to which ROS topics
245
+
mqtt2ros: # array specifying which MQTT topics to map to which ROS topics (not an array in ROS 2 version)
218
246
- mqtt_topic: # MQTT topic on which messages are received from the broker
219
247
ros_topic: # ROS topic on which corresponding MQTT messages are published
220
248
primitive: # [false] whether to publish as primitive message (if coming from non-ROS MQTT client)
@@ -243,48 +271,89 @@ In order to inject the current timestamp into outgoing MQTT messages, the parame
243
271
These latencies can be printed easily with *rostopic echo*
Latencies measured on the message transfer to `<bridge/mqtt2ros[*]/ros_topic>` are published here, if the received messages have a timestamp injected (see [Latency Computation](#latency-computation)).
Latencies measured on the message transfer to `<bridge/mqtt2ros/ros_topic>` are published here, if the received messages have a timestamp injected (see [Latency Computation](#latency-computation)).
Returns whether the client is connected to the MQTT broker.
281
348
282
-
##### Parameters
349
+
###### Parameters
283
350
284
351
See [Configuration](#configuration).
285
352
286
353
## How It Works
287
354
355
+
### ROS 1
356
+
288
357
The *mqtt_client* is able to bridge ROS messages of arbitrary message type to an MQTT broker. To this end, it needs to employ generic ROS subscribers and publishers, which only take shape at runtime.
289
358
290
359
These generic ROS subscribers and publishers are realized through [topic_tools::ShapeShifter](http://docs.ros.org/diamondback/api/topic_tools/html/classtopic__tools_1_1ShapeShifter.html). For each pair of `ros_topic` and `mqtt_topic` specified under `bridge/ros2mqtt/`, a ROS subscriber is setup with the following callback signature:
0 commit comments