Quick Start: Create an MQTT over TCP Bridge

This guide demonstrates how to create an MQTT over TCP bridge using a free public MQTT broker. The bridge forwards MQTT messages between EMQX Edge and a remote broker. You can configure it via the Dashboard or using the configuration file.

Create an MQTT Bridge via the Dashboard

Follow the steps below to configure an MQTT over TCP bridge using the EMQX Edge Dashboard.

Step 1: Open the Bridge Creation Wizard

1. In the Dashboard, navigate to Bridges.
2. On the Bridges page, click Add in the upper right corner.
3. The bridge configuration form will appear with three tabs: Connector, Forwards, and Subscriptions.

Step 2: Set Up the Connector

This tab defines how EMQX Edge connects to the remote MQTT broker.

Configure the connection settings for the bridge:

• Name: Specify a unique name for the bridge, for example, emqx1.

• Bridge status: Toggle to enable or disable the bridge. When disabled, the bridge will not connect or exchange data, and no metrics will be shown on the Bridges page.

• Max parallel processes: Number of concurrent connections the bridge uses. Default is 2. Increase to improve throughput if needed.

• Server: The remote broker address. EMQX Edge supports a decoupled protocol and transport design, where the URL prefix defines the transport layer for MQTT. You can use different prefixes to indicate whether to connect via TCP, TLS over TCP, or QUIC. Supported protocols:

  • mqtt-tcp
  • tls+mqtt-tcp
  • mqtt-quic

  In this demonstration, set the address as mqtt-tcp://broker.emqx.io:1883.

• Protocol version: MQTT protocol version. 5 for MQTT 5.0, 4 for 3.1.1, 3 for 3.1.

• Client ID: Unique identifier for this bridge connection, for example, bridge_client. If omitted, a random ID is generated.

• Clean start: Boolean flag. Some platforms require this. When enabled, the bridge always starts a new session each time it connects; when disabled, it tries to resume previous sessions.

• Username/Password: Credentials used for authenticating with the remote broker. In this example, set to username/password.

• Keepalive: Optional keepalive interval in seconds. Helps maintain the connection.

TLS Settings (Optional)

Toggle TLS to enable a secure, encrypted connection to the remote broker (e.g., tls+mqtt-tcp://broker.emqx.io:8883). When enabled, you can configure the following fields:

• Key Password: Password used to unlock your private key file.
• Key: Path to your private key file (e.g., /etc/certs/key.pem).
• Cert: Path to your certificate file (e.g., /etc/certs/cert.pem).
• Cacert: Path to the certificate authority file (e.g., /etc/certs/cacert.pem).
• Verify Peer: When enabled, the client will verify the server’s certificate for authenticity.
• Fail if No Peer Cert: When enabled, the connection fails if the server doesn't provide a certificate.

Step 3: Define Forwarding Rules

The Forwards tab defines how messages from EMQX Edge are forwarded to the remote MQTT broker.

To create a rule for message forwarding:

1. Click Add to create a new forward rule.
2. Fill in the fields:
   • Local Topic: The topic on your local EMQX Edge instance.
   • Remote Topic: The target topic on the remote broker.
   • QoS: Select the appropriate QoS level (0, 1, or 2).

Example Forward Rule Setting:

Local Topic	Remote Topic	QoS
topic1	fwd/topic1	1

You can edit or delete each rule later using the action buttons.

Step 4: Define Subscription Rules

The Subscriptions tab allows you to define how messages from the remote broker are received and routed to local topics in EMQX Edge. To create a subscription rule, specify which remote topics to subscribe to and where the incoming messages should be delivered locally.

1. Click Add to create a new subscription rule.

2. Provide the following details:

   • Remote Topic: The topic on the remote broker.

   • Local Topic: The corresponding topic on EMQX Edge.

   • QoS: Choose the appropriate QoS level (0, 1, or 2).

Example Subscription Rule Setting:

Remote Topic	Local Topic	QoS
cmd/topic3	topic3	1

You can edit or delete each rule later using the action buttons.

Step 5: Save and Apply the Bridge Configuration

1. Click Save to apply your bridge settings.

2. Restart the EMQX Edge to activate the new configuration. You can do this by running:

   nanomq start

3. Once EMQX Edge restarts, the new bridge will appear in the Bridges list.

Create an MQTT Bridge via Configuration File

This section demonstrates how to establish an MQTT-over-TCP data bridge between EMQX Edge and a free public MQTT broker through the configuration file to forward and receive messages.

Option 1: Add Configuration via the Dashboard (All configurations)

If you prefer working within the EMQX Edge Dashboard, you can directly paste the bridge configuration into the Settings -> All configurations page:

1. Navigate to Settings in the left-hand menu.

2. Click the All configurations tab.

3. Define the bridge configuration settings by adding the following configuration snippet into the editor:

   bridges.mqtt.emqx1 {
     server = "mqtt-tcp://broker.emqx.io:1883"
     proto_ver = 5
     clientid = "bridge_client"
     keepalive = 60s
     clean_start = false
     username = username
     password = passwd
   
     forwards = [
       {
         remote_topic = "fwd/topic1"
         local_topic = "topic1"
         qos = 1
       }
     ]
   
     subscription = [
       {
         remote_topic = "cmd/topic3"
         local_topic = "topic3"
         qos = 1
       }
     ]
   
     max_parallel_processes = 2
     max_send_queue_len = 32
     max_recv_queue_len = 128
   }

4. Click Save, then restart EMQX Edge to apply the changes.

Option 2: Edit the nanomq.conf File

1. Open the configuration file nanomq.conf under the directory /etc.
2. Define the bridge configuration settings by adding the following HOCON snippet to the configuration file:

bridges.mqtt.emqx1 {
  server = "mqtt-tcp://broker.emqx.io:1883"
  proto_ver = 5
  clientid = "bridge_client"
  keepalive = 60s
  clean_start = false
  username = username
  password = passwd

  forwards = [
    {
      remote_topic = "fwd/topic1"
      local_topic = "topic1"
      qos = 1
    }
  ]

  subscription = [
    {
      remote_topic = "cmd/topic3"
      local_topic = "topic3"
      qos = 1
    }
  ]

  max_parallel_processes = 2
  max_send_queue_len = 32
  max_recv_queue_len = 128
}

Start EMQX Edge with the Bridge Configuration

Run the following command to start EMQX Edge with your local configuration file:

nanomq start --conf /path/to/your/nanomq.conf --license /path/to/your/nanomq.lic

Replace /path/to/your/nanomq.conf with the actual path to your nanomq.conf file on your local machine.

For a complete list of configuration options, refer to the Data Bridge Configuration. The settings will take effect after EMQX Edge is restarted.

TIP

If you are using HOCON-format configuration items and EMQX Edge version 0.19 or later, you can either write the bridge-related configurations directly into the nanomq.conf file or place them in a separate file, such as nanomq_bridge.conf, and include it using HOCON’s include directive within nanomq.conf:

Example:

include "path/to/nanomq_bridge.conf"

To view more log data during runtime, you can set the log level log.level in the configuration file.

Test the MQTT Data Bridge

This section demonstrates how to use MQTTX to simulate clients and test the data bridge between EMQX Edge and the public MQTT broker. You will create two connections, one to EMQX Edge and another to the remote MQTT broker, to verify the bidirectional message forwarding.

Connect a Client to EMQX Edge

Create a client in MQTTX named NanoMQTest, connecting to localhost:1883.

Connect a Client to the MQTT Broker

Create another client in MQTTX named MQTTbridge, connecting to broker.emqx.io:1883.

Test Message Forwarding from EMQX Edge to Remote Broker

1. On the MQTTbridge client, subscribe to the topic fwd/#.
2. On the NanoMQTest client, publish a message to topic1, such as Hello from NanoMQ.
3. Confirm that the message appears on the MQTTbridge client, indicating successful forwarding.

Test Message Subscription from Remote Broker to EMQX Edge

1. On the NanoMQTest client, subscribe to the topic topic3.
2. On the MQTTbridge client, publish a message to cmd/topic3, such as Hello from broker.emqx.io.
3. Verify that the message is received by the NanoMQTest client, confirming successful subscription.

View Bridge Metrics and Status

After testing the message forwarding and receiving, you can monitor the bridge status and metrics on the Bridges page in the Dashboard.