Tutorial: Forward to and from HiveMQ

Configure FairCom's MQTT broker to forward and subscribe to messages from a HiveMQ broker

 

Note You can chain together MQTT brokers by forwarding messages from one broker to another. This is a great way to move information across data centers, factories, and clouds. (See Broker forwarding.)

The MQTT broker in FairCom MQ and FairCom Edge can act as a bridge to another MQTT broker. You can use the API Consoletool to configure FairCom's MQTT broker engine.

This tutorial contains instructions for configuring FairCom's MQTT broker to forward messages to a HiveMQ broker. It also shows how to subscribe to messages from HiveMQ.

Messages published to FairCom's MQTT broker are forwarded automatically to the HiveMQ broker. HiveMQ broker subscribers receive the messages sent to FairCom's MQTT broker.

Messages published to the HiveMQ broker are forwarded automatically to FairCom's MQTT broker which publishes them to its subscribers.

 

Requirements:

  • Ensure FairCom MQ or FairCom Edge is downloaded and installed. 
  • Confirm server access by running the FairCom Control Center. The typical URL is https://localhost:8443/ .
  • Ensure public HiveMQ is available through mqtt://broker.hivemq.com:1883.

 

Configure the FairCom broker

Configure the FairCom MQ broker to forward and receive a newly started HiveMQ broker:

In this procedure, the FairCom GUI is used to configure a broker connection and configure a topic, in that order.

  1. Navigate to the Code tab.
  2. Select API Console from the Code menu.
  3. Paste this code into the API Console and click the Run button:
    1. {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "action": "configureBrokerConnection",
        "params": {
          "brokerConnectionName": "HiveMQConnection",
          "brokerHostname": "broker.hivemq.com",
          "brokerPort": "1883"
        }
      }
  4. Observe the response and ensure the action completed successfully.
    1. "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.
      {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {},
        "requestId": "00000015",
        "debugInfo": {
          "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "api": "mq",
            "action": "configureBrokerConnection",
            "params": {
              "brokerConnectionName": "HiveMQConnection",
              "brokerHostname": "broker.hivemq.com",
              "brokerPort": "1883"
            },
            "apiVersion": "1.0",
            "requestId": "00000016",
            "debug": "max"
          },
          "executionMicroseconds": 1951,
          "totalMicroseconds": 5263
        },
        "errorCode": 0,
        "errorMessage": ""
      }
      
  5. Run the minimal example of the "listBrokerConnections" action from the JSON Actions dropdown menu.
  6. Observe the list of broker connections in the response to verify that "HiveMQConnection" was created.
    {
      "authToken": "replaceWithAuthTokenFromCreateSession",
      "result": {
        "brokerConnectionNames": [
          "HiveMQConnection"
        ]
      },
      "requestId": "00000018",
      "debugInfo": {
        "request": {
          "authToken": "replaceWithAuthTokenFromCreateSession",
          "api": "mq",
          "action": "listBrokerConnections",
          "apiVersion": "1.0",
          "requestId": "00000018",
          "debug": "max"
        }
      },
      "errorCode": 0,
      "errorMessage": ""
    }

 

Forward to HiveMQ

This quick tutorial shows you how to configure FairCom's MQTT broker to forward messages to a HiveMQ broker. Subscribers to topics on the HiveMQ broker automatically receive messages published to those topics on FairCom's MQTT broker.

Enable HiveMQ payloads to send to the FairCom MQ broker:
  1. Navigate to the Code tab.
  2. Select API Console from the Code menu.
  3. Paste this code into the API Console and click the Run button:
    1. The "params.topic" value is the MQTT topic that receives inbound messages
    2. The "params.forwardToExternalBroker.[].topic" value is the topic on the target broker that will receive the MQTT topic messages. 
      {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "action": "configureTopic",
        "params": {
          "topic": "house",
          "forwardToExternalBroker": [
            {
              "brokerConnectionName": "HiveMQConnection",
              "topic": "house_external"
            }
          ]
        },
        "debug": "max"
      }
  4. Observe the response and ensure the action completed successfully.
    1. "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.
      {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {},
        "requestId": "00000019",
        "debugInfo": {
          "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "api": "mq",
            "action": "configureTopic",
            "params": {
              "topic": "house",
              "forwardToExternalBroker": [
                {
                  "brokerConnectionName": "HiveMQConnection",
                  "topic": "house_external"
                }
              ]
            },
            "apiVersion": "1.0",
            "requestId": "00000019",
            "debug": "max"
          },
          "executionMicroseconds": 263214,
          "totalMicroseconds": 263414
        },
        "errorCode": 0,
        "errorMessage": ""
      }
      

 

Subscribe to HiveMQ

This quick tutorial shows you how to configure the FairCom MQTT broker to subscribe to topics on a HiveMQ broker. Subscribers to those topics on FairCom's MQTT broker automatically receive messages published to HiveMQ.

Enable a subscriber to receive payloads from the FairCom MQ broker:
  1. Navigate to the Code tab.
  2. Select API Console from the Code menu.
  3. Paste this code into the API Console and click the Run button:
    {
      "authToken": "replaceWithAuthTokenFromCreateSession",
      "action": "configureTopic",
      "params": {
        "topic": "house",
        "subscribeToExternalBrokers": [
          {
            "brokerConnectionName": "HiveMQConnection",
            "topic": "house_external"
          }
        ]
      },
      "debug": "max"
    }
  4. Observe the response and ensure the action completed successfully.
    1. "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure, see Errors and contact FairCom with any questions.
      {
        "authToken": "replaceWithAuthTokenFromCreateSession",
        "result": {},
        "requestId": "00000020",
        "debugInfo": {
          "request": {
            "authToken": "replaceWithAuthTokenFromCreateSession",
            "api": "mq",
            "action": "configureTopic",
            "params": {
              "topic": "house",
              "subscribeToExternalBrokers": [
                {
                  "brokerConnectionName": "HiveMQConnection",
                  "topic": "house_external"
                }
              ]
            },
            "requestId": "00000020",
            "debug": "max"
          }
        },
        "errorCode": 0,
        "errorMessage": ""
      }
      

 

Create a subscriber client

Subscribe to the "house_external" topic in the local FairCom instance:

In this procedure, you will use the FairCom Control Center to subscribe to the "house_external" topic, which is subscribed to the topic with the same name in HiveMQ.

  1. Navigate to the MQ tab.
  2. Select Messages from the MQ menu.
  3. Click on the Add Subscription button.
  4. Select "house_external" in the Topic filter.
  5. Click on the Subscribe button:

 

Publish a message to the FairCom MQ broker

Publish a message to the FairCom MQ broker, to verify that the message is forwarded to the running HiveMQ broker, and then received by the subscriber:

This tutorial uses the python.mqtt driver. For more information on this driver, see MQTT client for Python.

  1. Navigate to the MQ tab.
  2. Select Messages from the MQ menu.
  3. Click on the Publish button.
  4. Select "house" from the Topic field.
  5. Enter a message like {"temp":25}.
  6. Click on the Publish button.
  7. Certify the subscriber received the message.

Note this message was originally published on the local "house" topic, then forwarded to the HiveMQ publish broker, the forwarded to the local "house_external" topic.