Forward to and from HiveMQ

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

Abstract

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

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 Explorer tool 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.

This tutorial assumes you are running both brokers on the same computer, and has you configure them to use different ports.

Requirements:

Ensure FairCom MQ is downloaded and installed.
Confirm server access by running the FairCom API Explorer (see API Explorer to learn about the user interface).
Ensure HiveMQ is downloaded and installed.

Set up the HiveMQ broker

Complete the tutorial requirements before this procedure.

Set up the HiveMQ broker to send and receive payloads from the FairCom MQ broker:

Important

HiveMQ and FairCom MQ must be on different ports.

The default port for both FairCom MQ and HiveMQ is 1883.

In this procedure, HiveMQ will be listening on port 1884, and FairCom MQ will be on 1883. The port number does not matter as long as they are open ports. Similarly, the configuration file name does not matter.

Navigate to the configure folder typically named conf, in the unpacked HiveMQ folder.
Locate and open the Config XML file inside the conf folder with your preferred text editor.
Verify the listening port is <port>1884</port>.

Verify that anonymous-usage-statistics is set to true.

<anonymous-usage-statistics>
        <enabled>true</enabled>
 </anonymous-usage-statistics>

Start the HiveMQ broker.
1. Navigate back to the parent directory where the bin folder is located.
2. Run the run.bat file.

Configure the FairCom broker

Prerequisites

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

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

Select MQ API from the Select API dropdown menu.
Select the "configureBrokerConnection" action from the JSON Actions dropdown menu.

Replace the JSON in the API Request editor with the following JSON:

{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "00000015",
  "authToken": "aAuthTokenProvidedByTheServer",
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "HiveMQConnection",
    "brokerHostname": "127.0.0.1",
    "brokerPort": "1884"
  }
}

Click Apply defaults to JSON request () to replace the "authToken" value with the valid one from your session.
Click Send request ().

Observe the response and ensure the action completed successfully.

Note

"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": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
  "result": {},
  "requestId": "00000015",
  "debugInfo": {
    "request": {
      "authToken": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
      "api": "mq",
      "action": "configureBrokerConnection",
      "params": {
        "brokerConnectionName": "HiveMQConnection",
        "brokerHostname": "127.0.0.1",
        "brokerPort": "1884"
      },
      "apiVersion": "1.0",
      "requestId": "00000016",
      "debug": "max"
    }
  },
  "errorCode": 0,
  "errorMessage": ""
}

Select the "listBrokerConnection" action from the JSON Actions dropdown menu.
Click Send request ().

Observe the list of "brokerConnectionNames" in the response to verify "HiveMQConnection" was created.

{
  "authToken": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
  "result": {
    "brokerConnectionNames": [
      "HiveMQConnection",
      "MosqBroker"
    ]
  },
  "requestId": "00000018",
  "debugInfo": {
    "request": {
      "authToken": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
      "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.

Prerequisites

Enable HiveMQ payloads to send to the FairCom MQ broker:

Select the "configureTopic" action from the JSON Actions dropdown menu.

Replace the JSON in the API Request editor with the following JSON:

Note

The "params.topic" value is the MQTT topic that receives inbound messages.
The "params.forwardToExternalBroker.[].topic" value is the topic on the target broker that will receive the MQTT topic messages.

{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "00000001",
  "authToken": "anAuthTokenProvidedByServer",
  "action": "configureTopic",
  "params": {
    "topic": "house",
    "forwardToExternalBroker": [
      {
        "brokerConnectionName": "HiveMQConnection",
        "topic": "house"
      }
    ]
  }
}

Click Apply defaults to JSON request () to replace the "authToken" value with the valid one from your session.
Click Send request ().

Observe the response and ensure the action completed successfully.

Note

"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": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
  "result": {},
  "requestId": "00000019",
  "debugInfo": {
    "request": {
      "authToken": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
      "api": "mq",
      "action": "configureTopic",
      "params": {
        "topic": "house",
        "forwardToExternalBroker": [
          {
            "brokerConnectionName": "HiveMQConnection",
            "topic": "house"
          }
        ]
      },
      "apiVersion": "1.0",
      "requestId": "00000019",
      "debug": "max"
    }
  },
  "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.

Prerequisites

Enable a subscriber to receive payloads from the FairCom MQ broker:

Select the "configureTopic" action from the JSON Actions dropdown menu.

Replace the JSON in the API Request editor with the following JSON:

{
  "authToken": "authTokenHere",
  "api": "mq",
  "action": "configureTopic",
  "params": {
    "topic": "house",
    "subscribeToExternalBroker": "HiveMQConnection"
  }
}

Click Apply defaults to JSON request () to replace the "authToken" value with the valid one from your session.
Click Send request ().

Observe the response and ensure the action completed successfully.

Note

"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": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
  "result": {},
  "requestId": "00000020",
  "debugInfo": {
    "request": {
      "authToken": "PqxlwypHN8h7KHL2yVotMjCEj7dl0MdCyFRu6LEs59bsJy6EH6XEOaOHHxKVyyOp",
      "api": "mq",
      "action": "configureTopic",
      "params": {
        "topic": "house",
        "subscribeToExternalBroker": "HiveMQConnection"
      },
      "requestId": "00000020",
      "debug": "max"
    }
  },
  "errorCode": 0,
  "errorMessage": ""
}

Create a subscriber client

Prerequisites

Create a subscriber client that will receive all the messages a HiveMQ broker receives:

This procedure will subscribe you to all messages on a topic house, on port 1884, the port that HiveMQ is listening on.

Navigate to the python.mqtt directory in <faircom>/drivers/python.mqtt/PythonMQTTTutorial1/subscribe to use one of FairCom's drivers.
Run the python subscribe.py -t house -s 127.0.0.1:1884 command.

Publish a message to the FairCom MQ broker

Prerequisites

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.

Navigate to and open the python.mqtt directory through <faircom>/drivers/python.mqtt/PythonMQTTTutorial1/publish to use one of FairCom's drivers.
Run the python publish.py -t house -f data.json command, to publish a JSON object to port 1883.
Observe that the published JSON sample, contained in the driver package, has been successfully received by the HiveMQ subscriber client.