MQTT Architecture in R-COM Gateway Gateway

This article explains the MQTT communication paths used by R-COM Gateway Gateway. It is for developers, system integrators, administrators, and support engineers who need to configure, secure, and troubleshoot MQTT integrations.

The Gateway has three separately configured MQTT roles:

1. Integration MQTT: used for inbound integration events, outbound MQTT messages from workflows, and live data delivered to Custom UIs. For Custom UI MQTT communication, the Custom UI subscribes through a WSS-enabled Integration MQTT connection.
2. UI MQTT Broker: a browser-facing connection used by the standard Gateway UI for live updates. Agent status is one example.
3. Agent MQTT Broker: a shared connection used by R-COM Agents and the Gateway for Agent management and edge communication.

These are logical roles, not a statement that every deployment must run three broker servers. A deployment may point multiple roles at one broker service when that broker exposes the required transports and access controls. They remain separate Gateway configurations with separate purposes. Do not assume that a setting in one role automatically configures either of the others.

Choose the Correct MQTT Configuration

Requirement	Configure	Why
Receive a device or external-system message and start Gateway processing	Integration MQTT	The Gateway subscribes to the registered topic, creates an event, and an Event Rule starts the workflow.
Publish a workflow result, command, or integration message	Integration MQTT	MQTTPublisher and MQTTChallengeResponse select a named Integration MQTT connection through MQTT_CLIENT.
Show live data in a Custom UI	Integration MQTT	The Custom UI subscribes through the selected named connection. That connection must expose WSS.
Show live data in the standard Gateway UI	UI MQTT Broker	This is the browser-facing live-update environment for the standard Gateway UI.
Exchange heartbeat, status, logs, commands, or configuration with an Agent	Agent MQTT Broker	This is the shared Agent ↔ Gateway communication environment.

Terminology: broker versus client configuration

An MQTT broker accepts MQTT connections and routes publications to subscribers. The Gateway screens described in this article store the details that let a Gateway component—or, for browser scenarios, a Custom UI—connect to a broker. The Integration MQTT screen therefore configures Gateway MQTT client connections; it does not create or administer the broker itself.

Architecture at a Glance

Integration MQTT

UI MQTT Broker

Agent MQTT Broker

Configuration Boundaries

Configuration	UI location	Purpose	MQTT clients that use it	Typical publishers	Typical subscribers	Supported direction	Example use cases	Security and authentication
Integration MQTT	Integrations > MQTT	Shared MQTT configuration for inbound external events, outbound workflow messages, and live data subscriptions in Custom UIs.	Gateway integration client; workflows by MQTT_CLIENT; Custom UIs through a WSS-enabled configuration	External devices/systems; Gateway workflows	Gateway inbound topic processor; external systems; Custom UIs using WSS	External system → Gateway; Gateway workflow → external system or Custom UI; broker → Custom UI	RFID/sensor ingestion, cloud integration, workflow notification, Custom UI live data	Username/password, TLS setting, broker-side ACLs. Custom UI MQTT subscriptions require a WSS-enabled connection; see Custom UI MQTT Communication.
UI MQTT Broker	Administration > System Config > Client Settings	Delivers live updates to the standard Gateway UI. Agent status is one example, not its only use.	Standard Gateway UI in a browser; Gateway services that provide live UI data	Gateway services providing live UI data	Standard Gateway UI	Gateway → UI via broker	Live Agent status, runtime changes, notifications, and other dynamic UI data	Browser-facing connection must use WSS when the UI is served over HTTPS. The topic prefix scopes the UI live-update messages.
Agent MQTT Broker	Agents → Manage Agents → MQTT Settings	Shared Agent ↔ Gateway communication environment.	Registered Agents and Gateway Agent-management services	Agents; Gateway Agent-management services	Gateway Agent-management services; Agents	Agent → Gateway and Gateway → Agent	Heartbeats, vitals, status, logs, process data, configuration and command updates	Username/password and TLS. Per Agent credentials, TLS choice, and certificates can be overridden; host, port, and root topic are inherited from the shared configuration.

info

The UI MQTT Broker and Agent MQTT Broker must not be treated as aliases. If the UI broker is absent or unavailable, live Gateway UI updates stop until a refresh; the Agents Dashboard is one affected view. Agent-to-Gateway MQTT communication is unaffected. Conversely, configuring the Agent broker does not configure browser connectivity.

1. UI MQTT Broker for the Standard Gateway UI

The standard Gateway UI uses the UI MQTT Broker setting to receive live updates. The UI automatically subscribes below the configured Topic Prefix. Agent connectivity, health, and runtime state are examples of dynamically updated UI data; the same UI MQTT environment supports other live Gateway UI updates.

Verified behavior

• Configure it under Administration > System Config > Client Settings. Select MQTT configuration, then Edit.
• Its fields are host, port, username, password, topic prefix, and TLS.
• The topic prefix scopes the messages used for live Gateway UI updates. Agent status is one example.
• The browser UI needs a broker WebSocket listener and, when the Gateway UI is HTTPS, WSS (wss://). A browser cannot use raw MQTT TCP ports such as 1883 or 8883.
• If the UI broker is unreachable or not configured, live Gateway UI data becomes stale until the user refreshes the page. This does not stop the Agent MQTT path.

Integration boundary

The UI MQTT Broker is reserved for live updates in the standard Gateway UI. Use Integration MQTT for external-system and Custom UI integrations.

The UI MQTT Broker is a separate Gateway configuration from the general Integration MQTT list. A deployment may use the same physical broker endpoint for both only if it is deliberately configured to do so and the broker provides WSS plus appropriate ACLs.

2. Integration MQTT Configuration

Integration MQTT, configured under Integrations > MQTT, creates named Gateway connections to external MQTT brokers. Each named connection contains broker details and its inbound topic subscriptions. The same connection is used for three core paths:

• Inbound integration events: external devices and systems publish to registered topics; the Gateway receives the messages and routes them into Event Rules and workflows.
• Outbound workflow messages: a workflow selects the configuration through MQTT_CLIENT and publishes to a destination topic.
• Custom UI live data: a Custom UI MQTT subscription selects the configuration by name and receives messages from its broker. The selected connection must be WSS-enabled because the Custom UI runs in a browser.

For workflow publishing, the destination topic is selected in the workflow action. It does not need to be added to the connection's inbound topic list unless the Gateway must also subscribe to that topic.

Connection configuration

Each named client includes:

Field	Verified purpose
MQTT Client ID	Unique identifier for the client connection.
Name	Gateway-facing name used to identify the configuration, for example Sensor_Bridge.
Username / Password	Broker authentication credentials when required.
Host / Port	The remote broker endpoint. The configuration guide gives 1883 for unencrypted MQTT and 8883 for TLS as server-side examples.
Use TLS	Enables encrypted MQTT transport.

Use Test Connection before saving. A saved connection reports Active when the Gateway can establish the configured connection. For Custom UI use, ensure that the selected broker connection also exposes a WSS listener; standard MQTT/TLS listeners alone are not sufficient for a browser.

tip

Integration MQTT Configuration in R-COM Gateway

Inbound topic registration and routing

The Gateway listens only to the topics registered as active under a Integration MQTT connection. A topic registration contains:

Field	Verified purpose
Name	Internal label for the topic, for example TagEvents.
Topic	Full MQTT topic filter, for example factory/sensors/+/temp.
QoS Level	Requested delivery level for the subscription: at-most-once, at-least-once, or exactly-once.
Event Type	How the Gateway interprets the received message, for example UHFTagRead, CustomTrigger, or GhostData.
Payload	Expected payload format; it is normally selected from the event type.
Active	Enables or disables the subscription.

After an external publisher sends a message to a matching active topic, the Gateway creates an event using the configured event type and payload definition. An Event Rule then maps the MQTT source to a workflow and passes mapped values into the workflow job.

The inbound message path is:

1. An external publisher sends a message to a registered topic.
2. The broker delivers it to the Gateway's matching active subscription.
3. Gateway interprets the payload using the topic's event type and payload definition, then creates an MQTT-source event.
4. The selected Event Rule maps the event values and starts the configured workflow/version.

An Event Rule identifies MQTT as its Event Source and selects an MQTT Source Name.

Broker ACLs are separate from Gateway registration

Registering a topic in Gateway tells the Gateway what to subscribe to; it does not create permissions in the MQTT broker. The broker must independently authorize the configured client to connect and subscribe to that filter. Likewise, an external publisher must be allowed to publish to it.

Outbound use of the same client configuration

Publishing from a workflow

MQTTPublisher or MQTTChallengeResponse sends a message through the selected MQTT connection.

Parameter	Use
MQTT_CLIENT	Identifier of the named Integration MQTT connection to use.
TOPIC	Destination MQTT topic.
QOS_LEVEL	Publish QoS 0, 1, or 2.
PAYLOAD	Message body, typically JSON or plain text.
AWAIT_RESPONSE	MQTTChallengeResponse option that controls whether the action waits for a broker response.
TIMEOUT_MILLIS	Timeout setting available to both MQTTPublisher and MQTTChallengeResponse.

Typical uses include sending device commands, publishing workflow results to an event bus, or delivering real-time data to a Custom UI or external system. The publishing workflow must choose a topic that the intended consumer is authorized to subscribe to.

Use MQTTChallengeResponse when a workflow must publish a request and wait for a response on a specific topic. Configure the request topic, response topic, timeout, and result variable in the action.

Request/response communication

MQTTChallengeResponse publishes a request to REQUEST_TOPIC, subscribes to RESPONSE_TOPIC, waits up to TIMEOUT_MILLIS, and stores the response payload in RESULT_VAR. It returns true when a valid response arrives within the timeout and false otherwise.

tip

• MQTTPublisher
• MQTTChallengeResponse

Isolation between configurations and environments

MQTT_CLIENT chooses a specific named Integration MQTT connection. It does not, by itself, provide isolation if two connections point to the same broker and use overlapping topics. Separate environments and clients with distinct broker endpoints, credentials, root prefixes, and ACLs. Avoid sharing broad topic filters across tenants or environments.

3. Custom UI MQTT Communication

A Custom UI is browser code served by the Gateway. For MQTT live data, it subscribes through a named Integration MQTT connection; it does not define a separate broker connection. The selected connection must expose WSS.

How a Custom UI obtains its connection

In the Custom UI editor, select MQTT Subscriptions, then + Add Subscription. Each subscription supplies:

Field	Use
MQTT client	Name of an existing, WSS-enabled Integration MQTT configuration.
Topic	Topic or wildcard filter to receive, for example factory/line1/quantity.
Message handler (JavaScript)	JavaScript executed for each received message.

There is no host field in the Custom UI subscription. The selected Integration MQTT connection supplies the broker address, port, and WSS transport. Every delivered payload is available as the predefined string variable message; JSON payloads can be parsed with JSON.parse(message).

The Custom UI message path is:

1. A workflow or external publisher sends a message to the selected broker topic.
2. The broker delivers the message over WSS to every matching Custom UI subscription.
3. Gateway populates the predefined message value and runs that subscription's Message handler (JavaScript).
4. The handler updates the page state or DOM.

Browser transport and lifecycle

• Browsers cannot use raw MQTT TCP listeners such as 1883 or 8883. A Custom UI subscription requires WSS (wss://), commonly exposed by a broker on 443 or 8084 depending on the deployment.
• Plain ws:// is not suitable for a Custom UI served over HTTPS because browsers block mixed content.
• A Custom UI MQTT subscription can use an exact topic or the + and # wildcards.

tip

• MQTT for real-time updates in Custom UI

Communication patterns

• Workflow → Custom UI: a workflow publishes through MQTTPublisher; every Custom UI subscribed to that topic receives the payload and runs its handler.
• External system → Custom UI: the external publisher sends to a broker topic to which the Custom UI is subscribed.
• External system → Gateway workflow: the external system publishes to a registered Integration MQTT topic; the Gateway creates an event and Event Rules start the workflow.
• Custom UI → Gateway workflow: use a Gateway REST endpoint or UI workflow trigger, then let the workflow publish MQTT when needed.

Workflows and Custom UIs use the same Integration MQTT environment: the workflow selects the named client to publish, and the Custom UI selects that same named client to subscribe. The connection must be WSS-enabled for the Custom UI and must have compatible topics and broker permissions.

4. Agent MQTT Configuration

The Agent MQTT Broker configuration at Agents → Manage Agents → MQTT Settings is a dedicated, shared Agent communication environment. It is not the Integration MQTT integration configuration.

Select MQTT Settings to view the shared configuration. The Agent MQTT Broker dialog opens in read-only mode; select Edit before changing its settings.

What moves over the Agent MQTT environment

• Agent heartbeat, vitals, connectivity, and runtime status
• Agent logs and process data
• Gateway configuration and command updates to Agents
• Agent responses and configuration-update confirmation

The Gateway uses this information for central management and monitoring. Agent status is then surfaced in the standard Gateway UI through the separate UI MQTT Broker path.

Shared and per-Agent settings

The shared configuration defines the broker Host, Port, Username, Password, Root Topic, and Use TLS. Every registered Agent inherits the shared Host, Port, and Root Topic; an individual Agent cannot change those three values.

An individual Agent can override its username, password, TLS setting, and certificate settings without changing other Agents. Agent MQTT settings include an option to trust all certificates, client-certificate path/password, CA certificate path, keep-alive interval, and reconnect interval.

How Agent MQTT differs from Integration MQTT

Agent MQTT	Integration MQTT
Shared by registered Agents and Gateway Agent-management services	Named general-purpose connection used for external integration, workflows, and Custom UI live data
Root topic is inherited by every Agent	Each connection has its own registered inbound topic list
Carries Agent management, telemetry, logs, commands, and configuration updates	Carries external device/system events, workflow MQTT publications, and Custom UI live-data subscriptions
Standard MQTT/TCP or TLS; it is server-side, not WSS	Server-side integrations can use MQTT/TLS; Custom UI use requires WSS
Supports per-Agent credential and certificate overrides	Configuration uses the connection's configured credentials and TLS option

5. Security

Controls

• Integration MQTT and Agent MQTT support username/password credentials and TLS.
• Agent configuration supports a CA certificate path and client certificate settings, enabling mutual-TLS deployments where the broker and certificates are configured accordingly.
• The Agent option Accept All Certificates accepts self-signed or untrusted certificates. Use it only for testing.
• Browser-based Gateway UI and Custom UI use require WSS when served through HTTPS.

Production recommendations

• Use TLS for every broker connection and WSS for browser clients. Do not expose an unauthenticated MQTT listener to the internet.
• Validate broker certificates. Do not enable Accept All Certificates outside isolated testing.
• Give each Gateway integration client and each Agent a least-privilege broker identity. Use ACLs that limit allowed publish and subscribe topic filters.
• Separate production, test, tenant, Agent, UI, and external-integration namespaces. A shared physical broker is acceptable only with strong ACL separation.
• Avoid broad # subscriptions; they are easy to misconfigure and can expose unrelated messages.
• Keep sensitive data out of payloads where possible. If it must be sent, encrypt in transit, restrict topic ACLs, and avoid placing secrets in topics or Custom UI JavaScript.
• Treat Integration MQTT broker credentials as privileged integration credentials. Gateway UI roles do not replace broker ACLs; configure broker access independently.

6. Monitoring and Troubleshooting

Where to look

Area	Evidence to inspect
Integration MQTT	Connection status, Test Connection result, host/port, client ID, credentials, TLS selection, and active topic registrations.
Gateway event processing	Events page: source, event type, raw/event data, and status.
Workflow execution	Workflow Jobs: action logs, workflow context, linked event, status, and any MQTTPublisher or challenge-response error.
Custom UI	Selected MQTT client name, topic filter, browser developer-console/network errors, WSS endpoint, and Message handler (JavaScript) parsing errors.
Agent communication	Agent Logs, Process Logs, heartbeat/status timing, and agent configuration synchronization state.
Broker and network	Broker connection/subscription logs, ACL denials, listener protocol/port, certificate chain, DNS, proxy, firewall, and TLS termination configuration.

Troubleshooting checklist

1. Identify the path. Decide whether the problem is Integration MQTT, UI MQTT Broker, Agent MQTT Broker, or Custom UI WSS. Do not troubleshoot one role with another role's configuration.
2. Check transport and endpoint. Verify hostname, port, DNS, firewall routes, and the expected protocol: MQTT/TLS for server-side clients; WSS for browsers.
3. Test authentication and TLS. Use Test Connection for Integration MQTT. Review broker logs for authentication or ACL denials. Validate the certificate chain and hostname; do not bypass validation in production.
4. Verify the publisher. Confirm the exact topic string, QoS, payload, and broker environment used by the publishing client.
5. Verify the subscriber. For Gateway ingress, confirm the Integration MQTT topic is active, has the exact matching filter, and has the correct event type and payload. For a Custom UI, confirm it references the intended WSS-enabled connection and topic.
6. Verify the Event Rule. Confirm Event Source = MQTT, source selection, trigger type, workflow version, and variable mapping. Inspect the Events page before assuming the workflow is at fault.
7. Inspect workflow evidence. Check the linked Workflow Job's Logs and Context. For challenge-response, confirm that the response is published to RESPONSE_TOPIC before TIMEOUT_MILLIS expires.
8. Check Agent-specific settings. Confirm the Agent uses MQTT mode, inherited host/port/root topic are correct, credential/certificate overrides are valid, and keep-alive/reconnect intervals suit the network. Review Agent and process logs.
9. Check browser constraints. A failure that affects only a Custom UI or standard Gateway UI is often a WSS listener, certificate, origin/mixed-content, or browser-network issue—not a raw MQTT 1883/8883 issue.
10. Look for duplicate or stale behavior. Review QoS, reconnects, and retained-message assumptions. Make the receiving workflow or UI handler safe for duplicate delivery and malformed JSON.

Related Articles

• Integration MQTT Configuration in R-COM Gateway
• Set Up Event Rules
• Workflow Actions
• Create Custom UI
• Register, Install, and Manage Agents
• Client Settings