Setting Up HiveMQ

Before you begin

Ensure you have the following:

  • Latest version of HiveMQ
  • MQTT Certificates
  • Text editor software (Notepad or similar)
  • Keystore creation tool (Portecle or similar)
  • Java Runtime Environment (JRE) 8+
  • Java SE Development 11+

About this task

HiveMQ is an enterprise-ready MQTT broker you can use to test your SOTI Connect system.

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

Procedure

  1. Download and install HiveMQ.

    For manual installation, you can download HiveMQ files at https://www.hivemq.com/downloads/.

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

  2. Add your security certificate to a Java keystore repository (JKS).
    1. Open your keystore creation tool.
    2. Create a new keystore file. Ensure JKS is the selected type.
    3. Select Import Key Pair.
    4. Select server-cert.pfx from your SOTI Connect certificate folder. The default path is Program Files\SOTI\Connect\MQTT Certificates.
    5. Enter the password you created for the MQTT certificate when installing SOTI Connect.
    6. Enter an alias for the key pair.
    7. Enter and confirm a new password for the key pair.
    8. Select the key pair and click Set Keystore Password.
    9. Enter and confirm a password for the keystore.
      Note: This password will be used by the HiveMQ server.
    10. Enter a name for the keystore and click Save.
  3. Copy the JKS file to the HiveMQ configuration folder. The default location is Program Files\HiveMQ\conf.
    1. In the same folder, open the config.xml file using your text editor.
    2. Add the following inside the listeners tag, where HiveMQ_MQTT.jks is the JKS file you just created, JKS_Password is the password you created for it, and PrivateKey_Password is the private key you setup for SOTI Connect: 
      
<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>
    3. Save the config.xml file.
    4. In your Program Files\HiveMQ\bin folder, run run.bat.
  4. Register the MQTT PA in SOTI Connect.
    1. Login to SOTI Connect.
    2. Select Administration from the main menu.
    3. In the left pane, select System Management.
    4. Open the menu for Soti-Sdk-Mqtt and select Register.
    5. In the Register dialog, fill in the required fields:
      • Host address: MQTT server address
      • Port: 8883
      • PA Client Certificate: Client certificate in PFX format
      • PA Client Certificate Password: The password you entered in the MQTT certificate page during the installation
      • CA Certificate: root-cert.pem
    6. Click OK.
      Your HiveMQ server is now connected to your SOTI Connect instance.