Setting Up HiveMQ for MQTT Device Brokering

Before you begin

Ensure you have the following:

  • Latest version of HiveMQ server
  • Installed SOTI Connect
  • MQTT Certificates
  • Text editor software (Notepad ++ or similar)
  • Keystore creation tool (Portecle or similar)
  • Java Runtime Environment (JRE) 8+
  • Java SE Development 11+
  • Open JDK11(GA) (https://jdk.java.net/archive/)
Note: SOTI recommends installing HiveMQ on a separate machine for optimal performance.
Note: Certificates used to setup HiveMQ are not tracked within SOTI Connect. Any certificates used for setting up HiveMQ must be manually tracked for when they expire.
Note: SOTI Connect installation does not include MQTT certificates.
Note: Devices must use QoS 1 or QoS 2. Devices using QoS 0 may result in dropped messages by the HiveMQ Broker.

About this task

HiveMQ is an enterprise-ready MQTT broker that acts as a connection tool between your MQTT devices and SOTI Connect. Other than the trial version, there are three versions of HiveMQ that users can download. For more information on HiveMQ, visit https://www.hivemq.com/hivemq/editions/. Contact sales for more information on installing an enterprise solution of HiveMQ.

We recommend using HiveMQ Professional edition for long-term use or using the HiveMQ Community edition if you want to test the broker first.

There are three security options that you leverage for communication between SOTI Connect, HiveMQ, and OEM Devices:

  • Insecure TCP: no security features
  • Server-side TLS: client only validates if the server certificate is correct. For SOTI Connect, the client validates the certificate signed by the Root CA provided when adding the MQTT PA.
    Important: The sample procedure documented in this topic demonstrates server-side TLS.
  • TLS with Client Certificates: the server certificate is validated, and the client must provide a valid certificate signed by the same authority as the server certificate.

Procedure

  1. Download and install HiveMQ.

    For manual installation, you can download HiveMQ files at https://github.com/hivemq/hivemq-community-edition. Scroll to the Quick Start section of the page and download the binary package:

    Binary package location.

    For installation as a Windows service, you can download HiveMQ files at https://hivemq.com/additional-software/hivemq-windows-service.zip.

  2. Navigate to your MQTT Certificates directory.
  3. Run Portecle as an Administrator.
    Running Portcele application as an administrator
  4. Select the New Keystore Type button and ensure you select JKS as the Keystore. Select OK.

    Creating a new keystore in PortceleSelecting JKS as the keystore type in Portcele

  5. Select the Import Key Pair button and select your server certificate in PFX format. Select Choose.
    Clicking the Import Key Pair button in Portcele
    Selecting the server-cert.pfx key pair file
  6. Enter the password for your MQTT certificate. You established this in the SOTI Connect install process, then select OK.

    Entering the key store password in Portcele

  7. Confirm the password and Key Pair.
  8. Enter an Alias for your Key Pair, then select OK.
    Entering a key pair alias in Portcele
  9. Enter a new password for this Key Pair.

    Changing key pair password

  10. Select the Key Pair and select the Keystore password. Write your desired password (this password will be used by the HiveMQ Server).

    Portcele save button

  11. Name the Keystore, then select Save.

    Portcele save as dialog box for Keystore

  12. Navigate to your MQTT Certificates directory. Find the Keystore file and copy it.
  13. Navigate to the HiveMQ directory and paste the copied file into the required sub-directory.
  14. Open the config.xml file in the conf directory with Notepad++ or a similar app that allows you to edit the XML. Inside the XML file, you will see the default configuration and the file that only contains the unsecured TCP listener on port 1883.

    Hive config XML showing default configuration

  15. Create a TLS Listener on Port 8883. This will use the Java Keystore you previously created.

    Confix XML file with new TLS Listener defined

    
    <tls-tcp-listener>
    	<port>8883</port>
    	<bind-address>0.0.0.0</bind-address>
    	<tls>
    		<keystore>
    			<path>.conf/HiveMQ_MQTT.jks</path>
    			<password>JKS_Password</password>
    			<private-key-password>PrivateKey_Password</private-key-password>
    		</keystore>
    		<truststore>
    			<path>.conf/HiveMQ_MQTT.jks</path>
    			<password>JKS_Password</password>
    		</truststore>
    		<client-authentication-mode>NONE</client-authentication-mode>
    	</tls>
    </tls-tcp-listener>
    							
  16. Ensure that the path is accurate. Enter the password for the Java Keystore and the password for the SOTI Connect servers’ Private Key. Client authentication mode should be set to None because this topic demonstrates server-side TLS. Save the config file.
  17. Navigate to the HiveMQ directory and open the bin sub-directory.

    Hive bin directory location for run.bat file

  18. Run the run.bat file as administrator to start the server.

    Run as administrator right-click Windows menu

Results

Your HiveMQ server is now connected to your SOTI Connect instance.

Batch file running to connect HiveMQ and Connect

See also:

Installing SOTI Connect

System Requirements

Updating the Software Version

Uninstalling SOTI Connect

Installing the Failover Instance

Installing and Setting Up SQL Server