Installation & Setup

MQTTRoute is available for download for Windows/Windows servers (32 & 64 bit) , Linux, MAC and Raspbian. The binaries are available as zip archive for Linux, Mac and Raspbian and as self extracting exe for the windows OS.

Windows Setup

Double click the downloaded exe and follow the instruction in the wizard and install the MQTTRoute. By default the product will be installed inside the C:\Bevywise\MQTTRoute folder. You can change the folder during the installation. In addition, the shortcuts and the Start menus will be created for easily starting the MQTT Broker. For demo refer our installation video.

For Liunx, MAC and Raspberry:

For all other operating system, you can unzip the archive in the desired location and use the sh files present inside the /Bevywise/MQTTRoute/bin to start the broker.

Runing the Broker

For Windows

To start:

You can run the MQTTBroker with multiple ways

  • Double click the shortcut created in Desktop[Shortcut will be created, only when you enable the shortcut option while installing

  • Double click the “runbroker.bat” file inside the Bevywise/MQTTRoute/bin folder.

  • Open cmd and go to Bevywise/MQTTBroker/bin folder. Next type “runbroker.bat” and hit enter.

To stop:

  • Double click or run the “stopbroker.bat” via cmd which is inside the Bevywise/MQTTRoute/bin folder.

For Other Operating System

To start:

  • Open terminal and go to Bevywise/MQTTRoute/bin

  • Type “sh runbroker.sh” and hit enter.

To stop:

  • Open terminal and go to Bevywise/MQTTRoute/bin

  • Type “sh stopbroker.sh” and hit enter.

Configuring Bevywise MQTT broker

The MQTTRoute can be configured using the broker.conf file inside the conf folder.

broker.conf

[CONFIG]
PORT_NO = 1883
WS_PORT_NO = 10443

TLS_ENABLED = FALSE
# TLS_PORT must be 88xx.
TLS_PORT_NO = 8883
WSS_PORT_NO = 11443

########################Authentication Details######################

[AUTHENTICATION]
AUTHENTICATION_ENABLED = NO
# YES || NO

######################## UserInterface Details ######################

[UI]
UI_Http_Port = 8080
LIST_API_CLIENTS = FALSE

PORT_NO – Specify the port in which MQTTBroker start. By default it will start at 1883.

AUTHENTICATION – Used to enable Authentication. If it is enabled, you need to use the mqtt username and password when the edge device is connected. The username and the password should be specified in the Broker User interface.

TLS_PORT_NO – Specifies the port in which the broker runs when the TLS in enabled. It takes the default value as 8883.

TLS_ENABLED – Enable this field to run your product with SSL support. By default it takes the value as FALSE.

WS_PORT_NO – The port at which the broker will listen for the websocket connection. The default port is 80.

WS_PORT_NO – The port at which the broker will listen for the websocket connection. The default port is 80.

WSS_PORT_NO – The port at which the broker will listen for the secure websocket connection. The default port is 443. This port will be used when the TLS is enabled.SSL/ TLS Certificates

Running MQTT Broker with TLS/SSL enabled

By default, Bevywise MQTTBroker has a self signed root, server and client certificate inside the Certificate folder[Bevywise/MQTTRoute/Certificate]. For development purposes, if you don’t have certificates from authorized CA, you can use these default certificates. To connect your client with TLS/SSL, just copy/paste client certificate & root certificate in the client side or set the path of the client & root certificate. Client certificate is in Certificate/client folder and root certificate is in Certificate/root folder.

Other than default certificate, you can create your own self singed ones using openssl or you can create free certificates from Let’s Encrypt Once you created certificates, place the certificates in the following folder:

  • Broker or Server certificate and Key file MUST be present in ./Certificate/server folder.

  • Client certificate and Key file MUST be present in ./Certificate/client folder.

  • CA Certificate MUST present in ./Certificate/root folder.

  • Broker and Client certificates MUST be signed by same CA.

How to enable TLS/SSL in MQTT Broker

  • Open Bevywise/MQTTRoute/conf folder

  • In that, open broker.conf file.[ For windows user use notepad or sublime to open the file]

  • In broker.conf file, change

    • TLS_ENABLED = TRUE

  • Save the file and start the MQTT broker.


Bevywise MQTTBroker User Interface

Sign-in Page

This page helps users to login to the MQTT broker user interface securely. Below username and password are the default credentials to sign-in to the MQTT broker user interface.


  • Username – admin

  • Password – admin


Users can also change the username and password via user interface based on their need. To change the credentials, follow the below steps:

  • Login to MQTT broker user interface using the above default credentials.

  • Click the user icon on top left corner and select Change Password.

  • In change password window, give your old and new password and save it.

To logout

  • In MQTT broker user interface, click the user icon on top right corner and select Logout.


Dashboard

The dashboard provides a quick snapshot of the latest happenings in the Broker. It provides a quick status of the broker like count of messages in last 30 seconds, Active topics, currently connected devices and uptime, disconnected device details. The recent activity like, last 5 clients that connected and the time when it is connected, published messages, last 5 errors ocurred while connected the device and topic, disconnections and active subscribers will be shown.



Device details

This tab contains the list of devices that are connected to your MQTT Broker from the start of the broker. When a single device is chosen, the right side of the tab provides the details like device name, WILL topic & messages and the time when it is connected. You can also get the published topics & messages as well as the subscribed topics. The Message Logs lets you to know the list of messages from the clients & the topic discussed with the clients. Additionally, Subscribed device had a option called “Instant command” which is used to send a message or payload manually to the subscribed topic.


Topics

This tab provides details about all published and subscriber topics individually. It provides


  • Total published message count of individual topic

  • List of device which published or subscribed to that topic

  • Individual topic status and time stamp

Rule Engine

The Rules are the first step to building intelligence to the broker. You will be able to customize the broker to send different message to the different clients based on the messages received by the broker. The rules can be defined based on the following conditions.

  • Client & Topic – Rule data contains Client name & topic

  • Topic & Message – Rule data contains Topic & Message

  • Client & Topic & Message – Rule data contains Client name, topic & message

  • Timer Rule – Send message to the topic based on the give date and time


You can also add new rules and edit the existing rule. Based on rule type selected, provide the details accordingly.

The messages can be transformed based on conditions like greater than, less than, equal to and not equal to. The messages received will be compared against these operands. You can also send the message as received for another topic.












MQTT Clients

Now Bevywise MQTTBroker is ready to connect your edge devices. Based on your configuration you have either connect without or with authentication. You can connect any standard MQTT Client that supports MQTT V3.1. You can also download our prebuilt libraries for the different OS to connect.



The MQTTRoute also has some examples to connect to the Broker inside the Bevywise/MQTTRoute/examples folder.


AUTHENTICATION

Add and remove username and password for Authentication.

To add authentication:

  • Click the + icon on top left corner

  • Add Username & Password in the pop window and click save.

To delete authentication:

  • Click x icon next to the added username & password to delete authentication credentials.


Error Log

This tab contains list of errors that are occurred while connecting a device to Bevywise MQTTBroker. Below list help you to identity the reason for the errors.




Error Reason
Server busy Server busy, number of socket connection exceeded Server physical limit reached
Unknown Client Client details are not given properly. Invalid Client details provided
Clientid Null Client id Null, Connection entry restricted Client Identifier is NULL
Connection Refused Same client id already found, try to connect with another client id Reusing an existing Client Identifier not allowed
Invalid Credential Username or password wrong. Connect with correct user credential. Invalid Authentication Details Provided
Ping Response Failed Device went to offline. TCP Timeout occurred.
SSL Accept Error while establishing secure connection. Invalid SSL Certificate or Connection
Protocol Not Supported Invalid Protocol. Received message is not in proper MQTT Format
Socket Closed Server is busy
Device Disconnected Unexpectedly device disconnected

Advanced Data Storage

MQTTRoute supports storage of data in SQLite by default. But, for industrial production and developement SQLite is not efficient. For that case, you can change the storage configuration to MySQL. Also, for powerful visualization and analysis of data, you can store the data in Elastic Search or any other document based Big Data engine using custom implementation

The options can be configured using the data_store.conf file inside the conf folder.


data_store.conf

[PERSISTENCE]
PERSISTENCE_ENABLED = TRUE

[CONFIG]
DB_SERVER= SQLITE
# SQLITE || MYSQL || POSTGRES
# DB details for the SQLite

[SQLITE]
SQLITE_DB = bevywise

# DB details for the MYSQL. The DB will be created automatically in the Mysql Server

[MYSQL]
DBHOST =127.0.0.1
DBPORT = 3306
MYSQL_DB = bevywise
MYSQL_USER = root
MYSQL_PASSWORD =

PERSISTENCE_ENABLED – When set as TRUE, this will store the data either in SQLite or MySQL based on the DB_SERVER value. When set as false, it will not store data and the UI will not be accessible.

DB_SERVER – Specify whether the server need to store data in MySQL or SQLITE. when set as SQLLite, the data will be stored inside the data folder in the name of the file specified for SQLITE_DB

DBPORT – Port number of the mysql. The default port will be 3306.

MYSQL_DB – The db where you want to store the data inside MySQL.

MYSQL_USER – The username to be provided for the connection.

MYSQL_PASSWORD – The password to be provided for the connection.


MySQL configuration

To connect MQTTBroker and MySQL, follow the below steps:

For Linux and Mac user:

  • Open Terminal and go to ./Bevywise/MQTTRoute/bin

  • Run “sh installer.sh” , this file will install all dependence and mysql-connector

  • Install MySQL 5.7 server or higher.

  • Go to ./Bevywise/MQTTRoute/conf and data_store.conf

  • In data_stor.conf set DB_SERVER = MYSQL and give MYSQL username and password.

For Window/Windows server users:

  • Download and install WGET from [https://eternallybored.org/misc/wget/]. In that webpage download wget-1.20 zip and extract it.[version 1.20]



  • From the desktop, right click My Computer.

  • Choose Properties from the context menu.

  • Click the Advanced system settings link.




  • Click Environment Variables. In the section System Variables, find the PATH environment variable and select it. Click Edit. If the PATH environment variable does not exist, click New.






  • In the Edit System Variable (or New System Variable) window, specify path where wget.exe located. Click OK. Close all remaining windows by clicking OK.




  • Open cmd and go to ./Bevywise/MQTTRoute/bin

  • Type installer.bat and hit enter , this file will install all dependence which required to establish the connection between MQTTBroker and MySQL

    • Dependency installed after running “installer.bat” file

      • Python 2.7

      • Pip 2.7

      • Mysql-connector-python

    • Note: Above dependencies will skipped if it already installed in PC.

  • Install MySQL 5.7 server or higher and then set MYSQL username and password in data_store.conf file.

Note: Please don’t use XAMPP or MAMP for MySQL.

Python installation in windows

Once you run the installer.bat file, python2.7 will automatically download and the installation will start.[Python installation will skip, if it was already installed]

Follow the below steps to install python2.7:

  • At first you can see the following window will show up. In that, select first option and click next



  • The next window will ask you about the path where you want python to be installed. Please leave this as default[C:\Python27\] and click next.



  • Scroll down and click “Add python exe to path” and select “Will be installed on local hard drive”. This will automatically set python as a Environmental variable. Click next



  • Once the above step is completed, the installation of the Python 2.7 will start on your Windows 7 machine.



  • When the setup is close to the finish, just click the Finish button like shown below.



Custom Storge Configuration

MQTT Broker has an option called Custom storage to store data in elastic and other big data engine to store data


data_store.conf

[CUSTOM STORAGE]

[DATASTORE]
CUSTOMSTORAGE= DISABLED
# ENABLED || DISABLED
DATASTORE= CUSTOM
# ELASTIC || CUSTOM

[ELASTIC]
HOSTNAME = 127.0.0.1
PORT = 9200
INDEX_NAME = mqtt

[ELASTIC]
INTERCEPT_FILEPATH =./../extensions/custom_store.py

CUSTOMSTORAGE – If it is enabled, the data will be sent to the Document data store in addition to the MySQL/SQLite Storage.

DATASTORE – Choose the ELASTIC to store data in Elastic search. Choose CUSTOM to do a custom implementation.

HOSTNAME – Hostname of the Elastic Search if you are using Elastic as Custom data store.

PORT – The port of the Elastic server. The default port is 9200.

INDEX_NAME – The inde name in which you want to store data. It similar to db name in MySQL.

INTERCEPT_FILEPATH – The inde name in which you want to store data. It similar to db name in MySQL.

Note: Currently we have custom plugins to store data in Mongodb, elastic search and redis. We can also customize the MQTT broker to data or payload to any big data engines based on customer need. Contact us for other customization.

Custom Data Store

AI / ML plays a major role in any IoT Implementation. So the data received from the different sensors need to be modelled and stored to any BIG data engine for further analysis and decision making. MQTT Route provides an option called custom store to receive data at back end to be stored as needed.

Custom Store implementation is used to hook the received payload from MQTTBroker and store the payload in any of your analytics / big data engine. To configure, you must enable the CUSTOMSTORAGE in data_store.conf.

You need to enable CUSTOMSTORAGE to receive the data of the message received from the devices into a python call back handle_Received_Payload (data) . the method need to be implemented in the python file specified in the INTERCEPT_FILEPATH.

The data will be passed in a JSON format with the following keys – ‘sender’,’topic’, ‘message’, ‘unixtime’, ‘timestamp’

Your implementation should receive the data and store it and return the method. We advice you to just store the data or hand over the data to a stream analysis and return the method handle. Below is the custom_store.py file


extensions/custom_store.py


# Importing the custom class into the handler
from customimpl import DataReceiver
datasend = DataReceiver()

def handle_Received_Payload(data):
      # Write your code here. Use your connection object to
      # Send data to your data store

       print “print in the handle_received_payload” , data
       result = datasend.receive_data(data)
      # if result is none then write failed

RESTful API

The Custom data store help you receive, process and store data in your own big data store. This does not complete the cycle of Broker integration. RESTful API help you call the broker for managing any specific device or device as a whole. The restful API will also help in querying the connected devices list and related APIs to manage the broker as well as the edge devices.

Refer the API document for the details of the methods.

WILL and Retained Messages

MQTT broker supports WILL and Retained messages. The client can configure toWILL when connecting with the broker. You can receive Retain messages by configuring to the Retain bit. WILL message lets you to publish messages to clients in case of ungraceful disconnection. Retained messages are sent to new subscribers on particular topic. The broker will process the request and publish the messages to the configured clients.

QoS Support

MQTT broker supports multiple QoS levels. Clients can subscribe to any topic with any one of the QoS levels ‘0 – At most once’, ‘1 – At least once’ or ‘2 – Exactly once’. The broker will check for the QoS configuration when the client subscribes. Default QoS is ‘0’.

QoS 0 – At most once

Sender sends the message only once. The receiver of the message will not acknowledge it and the sender will not check for the delivery status of the message

QoS 1 – At least once

Sender guarantees message delivery. Sender sends a message once and will wait for the acknowledgement from the receiver. Sender will send the message till it receives the acknowledgement.

QoS 2 – Exactly once

Message sent will be acknowledged each time by the receiver. The sender will send the publish message. After receiving the acknowledgement from the receiver, The sender will send the instruction to release the published message. The receiver will send an acknowledgement for this message also.

Running Broker as Service

MQTTBroker as a Service in Linux

To run the MQTTBroker as service we need the Monit version 5.25 and it cannot be installed using the apt-get. The procedure to set up the monit is as follows. This application will ensure that the service will be started again when the server gets restarted.

  • Download the Monit for linux X64 or X86 based on your servers.

  • Extract the archive using tar -xzf < downloaded file >

  • Go to monit-5.25.2/bin

  • copy monit to /usr/bin folder – sudo cp monit /usr/bin

  • Go to monit-5.25.2/conf

  • copy the monitrc file to “/etc/” using below command – sudo cp monitrc /etc/

  • Modify the monit conf file. Uncomment the following lines in /etc/monitrc file. use sudo vi /etc/monitrc. Change the username and password as per your need.
        set httpd port 2812 and
          use address localhost # only accept connection from localhost (drop if you use M/Monit)
          allow localhost # allow localhost to connect to the server and
          allow admin:monit # require user ‘admin’ with password ‘monit’

  • Add the following at the end of the /etc/monitrc file
     check process MQTTRoute with pidfile < path to Bevywise/MQTTRoute >/Broker.pid
        start program = “< path to Bevywise/MQTTRoute >/bin/runbroker.sh” with timeout 2 seconds
        stop program = “< path to Bevywise/MQTTRoute >/bin/stopbroker.sh” with timeout 2 seconds

  • To reload the confiration changes, run sudo monit reload

  • Add MQTTRoute process to monitoring sudo monit start MQTTRoute

MQTTBroker as a Service in Windows/Windows server

  • Set the environmental variable for runbroker.bat and MQTTRoute.exe

    • Right click Mycomputer and select “Properties”.

    • Click “Advance System Variable” from left side panel.

    • In “System Properties” pop-up click “Advance” tab and click “Environmental Varibale” button on bottom.

    • In “Environmental Varibale”, select Path from system variables and click Edit.

    • In that add

      • runbroker.bat path[ installation path/Bevywise/MQTTRoute/bin]

      • MQTTRoute.exe path[ installation path/Bevywise/MQTTRoute]

      • Click Ok.

    • Next open the “Task Scheduler”

    • In Taskscheduler window, right click the “Task Scheduler” on the left pane and select “Create Basic Task..”.

    • In “Create Basic Task” wizard,

      • First give a Name and Discription for the Task and click next

      • Select “When the computer starts” and click next

      • Select “Start a program” and click next.

      • In Program/Script, click Browse and specify runbroker.bat path[ installation path/Bevywise/MQTTRoute/bin]. Click next

      • Select the “Open the Properties dialog box for this task” checkbox and click Finish.

      • Next the “In Properties” dialog box will open. In that select “General” tab and select “Run whether user is logged on or not”. Also enable “Run with highest privileges” checkbox.

      • Next select “Condition” and uncheck all the checkbox.

      • Select “Setting”, enable “If the task fails, start every:” checkbox and select the time interval [default min time is one min] and uncheck all other checkbox.

      • Next click ok to save the properties.

    • Once you install the MQTTBroker will set to “startup program”, which means it will start when the PC starts. So we must remove MQTTBroker form “Startup program”

      • For Windpws 7 or higher

        • Click start and search “System Configuration”

        • In that wizard, under “startup”, click ” Bevywise MQTTRoute” and disable it.

      • For Windows Server 2012R2 or higher:

        • Press “windowskey+r” to open run window

        • In that type “shell:common startup” and click OK

        • Now Startup window will open. In that Delete the Bevywise MQTTBroker and close the windows.

    • Next Restart the PC. Now the Broker will run as a service via Task scheduler.

    • To check:

      • In command prompt, type “netstat -a” and press enter.

      • In output, you can see 0.0.0.0:1883, 0.0.0.0:8080, 0.0.0.0:8081 port are running. [1883 -MQTTBroker, 8080 – MQTTBroker UI, 8081:Client connection].

MQTT Gateway

The MQTT Gateway acts as a intermediate agent between the Sensors and the MQTT Broker. The MQTT Gateway has an inbuilt functionality to discover all the sensors that runs around the gateway. The gateway advertises itself and the Clients will be able to search for the gateway in return.

The gateway can be started in two modes

Aggregated Gateway – The gateway will make only one connection with the central MQTT Broker and will aggregate all the messages from the individual sensors and send to the broker via the single connection. This will reduce the load on the Central Broker.

Transparent Gateway – This gateway will just act as a forwarding agent and each sensor will be individually connected to the central broker.

The gateway supports accumulation of messages when the client goes for a sleep state and sends all the messages when the client comes back.

Note: Without Bluetooth, MQTTGateway will not work. So, enable Bluetooth in your PC and follow the below steps.

To start MQTTGateway:

Without starting MQTTBroker, Gateway will not start. So, start the Gateway after along with the MQTBroker.


For windows:

  • Double click the “rungateway.bat” file inside the Bevywise/MQTTRoute/bin folder.
  • (or)
  • Thrid, Open cmd and go to Bevywise/MQTTBroker/bin folder. Next type “rungateway.bat” and hit enter.

To start:

  • Open terminal and go to Bevywise/MQTTRoute/bin

  • Type “sh runbroker.sh” and hit enter.

Configuring Bevywise MQTT Gateway

The Gateway can be configured using the gateway.conf file inside the conf folder.


conf/gateway.conf

[SERVER_CONFIG]
PGATEWAY_NAME = “gateway1”
SERVER_TLS_ENABLED = FALSE

# True to enable TLS and listen SERVER_TLS_PORT & False to disable TLS and listen SERVER_PORT.

SERVER_IP = 127.0.0.1
SERVER_PORT = 1883
SERVER_TLS_PORT = 8883

# TLS_PORT must be 88xx.
SERVER_AUTHENTICATION_ENABLED = FALSE
USERNAME = Hello
PASSWORD = hello

# Gateway config to MQTT Client.

[GW_MQTT_LISTEN_CONFIG]
GW_MQTT_ENABLED = TRUE

# True to listen MQTT Client & False to disable MQTT Client.
GW_TLS_ENABLED = FALSE

# True to listen MQTT Client in secured channel.
GW_MQTT_PORT = 1884

# Gateway config to MQTTSN Client.

[MQTT_SN_CONFIG]
GW_MQTT_SN_ENABLED = TRUE

# True to listen MQTTSN Client & False to disable MQTTSN Client.
GATEWAY_TYPE = TRANSPARENT

#AGGREGATED || TRANSPARENT

# multicast Address for Gateway
GW_GROUP_ADDR = 224.2.2.1
GW_GROUP_PORT = 1883

# multicast Address for SN Clients
SN_GROUP_PORT = 1884
SN_GROUP_ADDR = 224.3.3.1
GW_PATH_TO_PREDEF_TOPIC = ./conf/predefined_topics.txt
# set the predefined Topic name and id in the file.
# Format:

Localization

You can now make the MQTT Broker show details on the User Interface in your language for all your employees and technicians. We support a few languages by default. It is easy add your text to the localization.js file to make it easier for your team. The following steps help you do it.

  • Identify language code – Visit language codes page to understand the code used for your language.

  • Open the localization.js inside the folder Bevywise/MQTTRoute/web/build/js.

  • Copy the english text below the “en” code whiich is at the starting of the file and paste it at the end. Change the “en” code to your web browser language code. Provide a meaningful text in your language for the correspesponding english text on the right side of the : separator.

  • Once you done save the file and restart the broker. Now the UI will be changed to your language.

Feel free to send us the translated file, so that we can distribute the changes you have done to your national people in your name. Send to [email protected]

Package Structure

This gives you the details about MQTTRoute Product Package. When you unzip the file, a folder Bevywise will be created. The contents of the Broker are in Bevywise/MQTT_Broker location.

bin/

This folder contains the executable file required to run Bevywise MQTTBroker. The runbroker.sh file runs the broker using python executable file.

Certificate/

This folder contains the secure SSL/TLS certificate. The client and server contains a common CA certificate root.crt file which is the Certificate Authority to verify the clients and the server. client/ will have client.crt certificate file and client.key key file for the certificate. server/ will have server.crt certificate file and server.key key file for certificate.

conf/

In this folder the configuration file for the broker is stored. The properties like Broker Port, TLS Port, Enable/Disable TLS and Authentication of the user can be configured using the broker.conf file.

data/

This folder contains the SQLITE database that stores all the details of the broker. When the broker runs, the database is created.

lib/

This folder contains the core libraries of Bevywise MQTTBoker.

license/

This folder contains the open source license agreement and license file of the MQTTBroker libraries.

ui/

This folder contains the required files for the User Interface. You can see user interface from your browser using 127.0.0.1:8080.

README

Text file which guide the user step by step to run the Bevywise MQTTBroker.

Have more Questions?

We are with all ears waiting to hear from you. Post us with your questions and feedback.