Installation & Setup

MQTTRoute is available for download for Windows (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 Other Operating System

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

You can run the MQTTRoute from the Start Menu, command search tool or using the MQTTRoute.exe available inside the Installation Folder. You can also use the Startbroker.bat inside the Installation Folder /bin.

To Stop the MQTTRoute, run the stopbroker.bat inside the bin/ folder.

For Other Operating System

For all other operating system, you can use the runbroker.sh inside the bin/ folder from the console. To stop the broker, run the stopbroker.sh.

Configuring Bevywise MQTT broker

By default Bevywise MQTTBroker will run on Port 1883, without TLS/SSL, without Authentication and Websocket on port 10443. User can change the configuration via Bevywise MQTTBroker User Interface.

The User Interface will load on 8080 port. Type < ipaddress or localhost > : 8080 in your web browser to open MQTTbroker User Interface. In User Interface, click Settings tab and start your configuration.





Broker Port  – Specify the port at which you want to run the broker. If this value is not specified, the port will start in default port 1883.

WS Port – The port at which the broker will listen for the websocket connection. The default port is 10443.

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

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

WSS Port – The port at which the broker will listen for the secure websocket connection. The default port is 11443. This port will be used when the TLS is enabled.

AUTHENTICATION – If it is enabled, you need to use the mqtt username and password when the edge device is connected. By default username - highly secure and password - N4xnpPTru43T8Lmk are added and user can create multiple number of username and password by clicking + icon.

After configuration click Save button which will lead to pop-up menu. In that click "Save Changes" and restart the Broker manually to save all configurations.

SSL/ TLS Certificates

For development purpose, if you don't have certificates from authorized CA, you can create your own self singed ones..On other hand, you can try creating free certificates from Let's Encrypt.

Place the certificates in the following folder

  • Broker 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.

Custom Storge Configuration

For powerful visualization and analysis of data, you can store the data in Elastic Search or any other document based Big Data engine.Custom Store can be configured via User Interface.





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

DATASTORE – You can either choose the Elastic implementation done inside the Broker or do a custom implementation and specify CUSTOM here.

The Elastic Host name, Port number and Index name are available at data_store.conf file which is inside the conf folder (Bevywise/MQTTRoute/conf).

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.

Configuring Data Storage

Bevywise MQTTBroker supports storage of data in SQLite by default. MySQL can be used as an alternate option to store data instead of SQLite. 

MySQL configuration

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


conf/data_store.conf

[PERSISTENCE]
PERSISTENCE_ENABLED = TRUE

[CONFIG]
DB_SERVER= SQLITE
# SQLITE || MYSQL
# 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 =

#############################CUSTOM STORAGE###########################

[ELASTIC]
HOSTNAME =127.0.0.1
PORT = 9200
INDEX_NAME = mqtt
[CUSTOM] INTERCEPT_FILEPATH = ./lib/custom_store.py

 

INTERCEPT_FILEPATH – If you are using a custom data store implementation, you have to specify the python file path here. The template of the implementation is available at ./lib/custom_datastore.py.

External_Connection_Path

For Linux user, the mysql-connector-python should be installed along with mysql server 5.7 and mysql-connector path should be given in conf/data_store.conf file.

Mysql-connector Installation in Linux

  • Make Python 2.7 as default.

    • To test : type "python" in terminal and hit enter.

    • Output should be:
      Python 2.7.6 (default, Nov 23 2017, 15:49:48)  [GCC 4.8.4] on linux2  Type "help", "copyright", "credits" or "license" for more information.

  • Install pip for python 2.7(If pip installed skip this step. To test: type "pip -V" in terminal and hit enter )

  • Install mysql-connector-python by "pip install mysql-connector-python"

  • Mysql-connector-python should be installed in "/usr/local/lib/python2.7/dist-packages". Give this path in "EXTERNAL_CONNECTION_PATH ="

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

When the MySQL is used for the data storage, we need to specify the DB Parameters for the following fields.DBHOST - Machine name or the IP where the MySQL server is running.

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.

Connect Devices

The browser is now 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 lib/ folder.

MQTT 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 and Error logs. The recent activity like, last 5 clients that connected and the time when it is connected, published messages 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.


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 data contains Client name, topic, message, & specific date


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.












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

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 to receive data at back end to be stored as needed.

You need to enable CUSTOMSTORAGE to reveive 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.


lib/custom_store.py


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

      print "Custom_data_callback:" , data

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

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.

The Gateway can be started using the scripts in the bin/ folder.

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 technitians. 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 mqtt broker. 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/

configured using the broker.conf, data_store.conf, gateway.conf files.

data/

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

lib/

This folder contains the core library files which are required for connecting the clients with the broker and sample programs which can be used to work with the broker.

license/

This folder contains the license agreement and license file that represent the broker permissions and jQuery.

web/

This folder contains the required files for the User Interface. You can see user interface from your browser using < ipaddress or localhost > : 8080.

Have more Questions?

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