configure generic mqtt integration with built-in network server

The Generic MQTT Integration allows your RAK gateway (running the Built-in LoRaWAN® Network Server) to publish device events directly to an MQTT broker, whether hosted locally or in the cloud.

With this integration, your LoRa® end devices can send data such as sensor readings, join notifications, acknowledgments, and status updates directly to an MQTT broker. Any MQTT-compatible platform or application (for example, ThingsBoard) can then subscribe to specific topics to receive and process this data in real time.

How It Works

When the Generic MQTT Integration is enabled, the RAK gateway begins forwarding device events to your MQTT broker following this process:

1. Device Communication
   End devices join the network or send uplink messages through the gateway.
2. Packet Processing
   The Built-in Network Server (LNS) decrypts, validates, and classifies packets into event types.
3. MQTT Message Construction
   The LNS converts each event into a structured JSON message.
4. Topic Mapping and Publishing
   Each message is published to a predefined MQTT topic based on its event type.
5. MQTT Broker Distribution
   The MQTT broker (local or cloud-based) distributes published messages to all subscribed clients.
6. Data Consumption by Applications
   Applications or platforms subscribed to the relevant topics process the data in real time.

Prepare Your MQTT Integration Platform

Before enabling the Generic MQTT Integration on your RAK gateway, ensure that your MQTT infrastructure is properly set up and accessible. This includes:

• An MQTT broker (either local or cloud-based), such as:
  • EMQX, Mosquitto, HiveMQ
  • MQTT-compatible services in platforms like ThingsBoard
• One or more subscribers (platforms or applications that consume data), such as:
  • ThingsBoard
  • Datacake
  • Custom Python/Java/Node.js applications
• The subscribers must listen to the predefined topic structure used by the gateway:

Enable Integration in Gateway

Before you begin, ensure the following prerequisites are met:

• The built-in LoRaWAN® Network Server is enabled on your WisGateOS 2 gateway
• At least one Application and its devices have been properly set up

To learn how to enable the built-in network server and add Applications/Devices, see:

LoRa Configuration – Built-in Network Server. 

1. Log in to the Web UI of the gateway.

2. Navigate to LoRa® > Configuration > Integration interface parameters.

3. Toggle Enable Integration Interface and select Generic MQTT .

4. Configure the following parameters: 

• MQTT Broker Address: The IP address of the MQTT broker.
• MQTT Broker Port: The port used by the broker (default: 1883).
• MQTT Version: MQTT protocol version .
• QoS: Quality of Service level
• Keepalive interval (s): Interval in seconds to keep the connection alive (default: 10).
• Clean session: When enabled, the broker does not store session data.
• Retain: If enabled, the last published message is retained.
• Client ID: ID used to associate with the topic (auto-generated if left empty).
• Enable User Authentication: Enable and provide MQTT username/password credentials.
• SSL/TLS Mode: Choose connection security
• TLS Version: Select TLS version.
• Join Topic / Uplink Topic / Downlink Topic / Downlink Acknowledge Topic / Status Topic: Predefined MQTT topics for uplink, downlink, and status updates.

5. Click Save changes to apply your settings.

Once configured, your gateway will begin publishing device messages to the specified topics.

Any MQTT-compatible platform or service subscribed to these topics can receive and process the data in real time.

Further Reading

For a practical step-by-step MQTT integration guide, read the ThingsBoard Integration Guide.

This tutorial walks you through configuring an MQTT broker and subscribing to topics to receive uplink data from the WisGateOS 2 gateway.

While it uses ThingsBoard as an example, the same principles apply to other platforms or any custom backend that supports MQTT topic subscriptions.

FAQs

1. Why can’t I receive data from the broker?
This issue usually occurs due to configuration errors or network connectivity problems. To resolve it, check the following:

• Verify that the MQTT broker address and port are correct and reachable.

• Ensure the broker is running and accepting connections from the gateway.

• Check firewall or NAT rules if the broker is external.

• Use an MQTT client (for example, MQTT Explorer) to subscribe to the wildcard topic # and confirm that messages are being published.

• If using authentication or TLS, verify that your credentials and certificates are correct.

2. Why isn’t my subscriber receiving messages for specific devices?
Confirm that the applicationName and deviceEUI in your client match the MQTT topic structure.

3. Can I modify the topic structure?
No. The topic structure is predefined by WisGateOS 2 and cannot be customized.

Updated November 07, 2025 03:57