MQTT Client Configuration in R-COM Gateway
MQTT is a lightweight, publish-subscribe messaging protocol designed for low-bandwidth, high-frequency data transfer ideal for IoT and industrial devices. In R-COM Gateway, MQTT serves as a real-time event ingestion channel, connecting barcode/RFID readers, sensors, and visual systems with the automation core.
This guide walks you through configuring MQTT clients in R-COM Gateway to receive and route device data for real-time processing.
Where to Begin
From the R-COM Gateway dashboard, go to:
- Integrations > MQTT
Here you can:
- View existing MQTT configurations
- Edit or delete entries
- Create new MQTT clients
To create a connection, select Add MQTT Connection.
Avaialble MQTT Connections
Step 1: Create an MQTT Client
Each MQTT Client configuration establishes a connection with a remote broker and manages subscriptions for inbound data.
Configure new MQTT
Connection Details
| Field | Description |
|---|---|
| Name | Friendly name to identify the connection within the gateway (e.g., Test_MQTT, Sensor_Bridge). |
| MQTT client ID | A unique identifier for the client (e.g., mqtt_reader001). |
| Username / Password | Optional fields used for authenticating with the broker. |
| Broker host | Broker URL or IP address (e.g., test.mosquitto.org). |
| Broker port | Broker port number (1883 for unencrypted, 8883 for TLS). |
| TLS encryption | Connect using SSL/TLS. |
| Connect over WebSocket | Use a WebSocket transport; required when a browser-based Custom UI connects through this configuration. |
| Active Status | Enables or disables the MQTT connection. |
| Use shared subscriptions | Enables broker shared-subscription behavior. |
Test Connection
Click to verify broker connectivity with the entered parameters. On a successful test, a popup with “MQTT Connection is valid“ message will be shown.
Step 2: Define MQTT Topics
Use the Topics section to subscribe to incoming MQTT messages and associate them with internal R-COM Gateway events.
Define MQTT topic
Add a new topic:
Select Add Topic to open a topic configuration row.
Topic Configuration Fields
| Field | Description |
|---|---|
| Name | Internal label for this topic (e.g., TagEvents) |
| Topic | The full MQTT topic string (e.g., factory/sensors/+/temp) |
| QoS Level | Delivery guarantee level: AtMostOnce - 0, AtLeastOnce - 1, or ExactlyOnce - 2. |
| Event Type | Defines how R-COM Gateway processes the message (e.g., UHFTagRead, CustomTrigger, GhostData) |
| Payload Type | Specifies the expected payload format; it is normally selected from the event type. |
MQTT Wildcard Support
MQTT wildcards make it easy to subscribe to groups of related topics without creating a separate subscription for every topic. They can only be used in subscription filters—not when publishing messages.
+ — Single-level wildcard
The + wildcard matches exactly one topic level.
For example, subscribing to:
devices/+/data
matches:
devices/sensor-01/data
devices/sensor-02/data
devices/gateway-a/data
but does not match:
devices/sensor-01/status
devices/region-a/sensor-01/data
Use + when one part of a topic changes, such as a device ID, room name, or customer ID.
# — Multi-level wildcard
The # wildcard matches all remaining topic levels, including zero or more levels. It must appear at the end of a topic filter and occupy an entire level.
For example, subscribing to:
devices/#
matches:
devices/sensor-01/data
devices/sensor-01/status
devices/region-a/sensor-01/data
A subscription to:
devices/sensor-01/#
receives every message published beneath that specific device, such as telemetry, status updates, and configuration events.
Practical examples
home/+/temperature
Receives temperature readings from every room:
home/kitchen/temperature
home/bedroom/temperature
factory/line-1/#
Receives all messages for production line 1:
factory/line-1/machine-a/status
factory/line-1/machine-b/telemetry
Best practices
- Keep topic structures consistent so wildcard subscriptions remain predictable.
- Use
+when you only need one variable topic level. - Use
#carefully, since broad subscriptions can receive a large volume of messages. - Apply appropriate access controls: wildcard subscriptions should only be permitted where the client is authorized to read every matching topic.
For more info on wildcard support, refer to the official documentation.
Step 3: Save the Configuration
Once all fields are filled:
-
Select Save to save the MQTT connection and its topic subscriptions.
-
Your MQTT connection will appear in the management list with an Active status if successful.
How it works
Once submitted and tested, R-COM Gateway begins receiving tagread messages for real-time processing.
- Use any MQTT client to connect to your broker (e.g., tcp://test.mosquitto.org:1883)
- Ensure the connection is active
- Subscribe to the same topic that you just configured
- Set a QoS
- Publish to the topic
- The message will be captured by the associated R-COM Gateway Event Rules and forwarded to the selected workflow.
Troubleshooting
| Symptom | Possible Cause | Solution |
|---|---|---|
| Status remains Inactive | Incorrect broker address or authentication failure | Verify host, port, and credentials. Use Test Connection. |
| No events processed | Incorrect topic syntax or wrong event type | Ensure the topic matches the published topic. Check event type bindings. |
| Frequent disconnections | Client ID conflict or low keep-alive timeout | Use unique client IDs. Increase keep-alive settings on broker. |
| Payload not recognized | Event type mismatch | Ensure payload structure aligns with the selected Event Type. |
| Connection fails with TLS | Certificate issue | Make sure TLS is supported and proper certificates are configured if needed. |
Manage MQTT Configurations
The MQTT landing page lists the saved MQTT connections available to you. Use the list to review connection status and broker details, filter configurations by topic, and access row actions such as View Topics.
| Column | Description |
|---|---|
| MQTT Client ID | The configured MQTT client identifier. |
| Name | The name assigned to the MQTT configuration. |
| Status | Shows whether the MQTT connection is active or inactive. |
| Topic Count | The number of topics configured for the MQTT connection. |
| Broker Host | The configured MQTT broker host. |
| Broker Port | The configured MQTT broker port. |
| Username | The configured broker username, when one is set. |
| Actions | Provides controls for the MQTT configuration, including View Topics. |
Use the Topic filter to find MQTT configurations with a matching subscription topic. After filtering the list, use View Topics to review the subscriptions for a matching MQTT configuration.
- Select Add filter.
- Select Topic, choose the comparison, and enter the topic text. Use contains when you want to find a partial topic match.
- Select Done to apply the filter.
Filter the MQTT configuration list by subscription topic.
- In the filtered list, select View Topics for the MQTT configuration that you want to inspect.
Use View Topics to open the subscriptions for a matching MQTT configuration.
- Review the subscription list, which shows the subscription Name and Topic.
The subscriptions list shows the topics configured for the selected MQTT connection.
✅ Final Checklist
Before going live:
✅ Verify broker connectivity using the Test Connection button ✅ Use secure TLS settings in production environments ✅ Confirm topic names and wildcard usage match expected device topics ✅ Test message flow using MQTT tools like MQTT.fx or mosquitto ✅ Ensure Event Type and Payload are aligned with your business logic