Home About us Support Partners SIGN UP NOW
Text Copied

CrystalMQ Broker Tutorial – Build IoT Application better

Quick Overview
Bevywise CrystalMQ Broker Overview

Bevywise CrystalMQ Broker is a complete IoT Application Suite with an inbuilt MQTT Broker. It acts as a central MQTT server, that facilitates communication among MQTT-enabled edge devices / Internet of Things (IoT) devices and collects data that can be stored for data analytics and visualization.

CrystalMQ Broker uses Message Queuing Telemetry Transport (MQTT) protocol as its standard messaging protocol/communication protocol. MQTT works based on the publish-subscribe model. It provides you a fully extendable framework which helps you build powerful IoT/IIoT Application for any industrial use cases.

MQTT Versions Supported :
  • MQTT 3.1
  • MQTT 3.1.1
  • MQTT 5
Note: MQTT Broker supports MQTT sparkplug B for industrial communication.

MQTT Sparkplug B - Please check ' MQTT Sparkplug B support' section to know more.
Key Functions

Topic-based Messaging: CrystalMQ uses a topic-based messaging model where messages are published to specific topics, allowing subscribers to receive only relevant data based on their subscriptions.

QoS Handling: CrystalMQ supports different Quality of Service (QoS) levels (0, 1, 2) to ensure message delivery reliability and guarantee, based on the requirements of the communication scenario.

Connection Management: It manages client connections, including establishing, maintaining, and terminating MQTT connections, as well as handling connection retries and timeouts.

Security: It provides security features such as TLS encryption, authentication mechanisms (username/password, client certificates), and access control to ensure secure and authorized communication.

Persistence: It offers message persistence options to store and manage messages, ensuring message delivery even in case of temporary network disruptions or client unavailability.

Scalability: With its ability to scale to support millions of concurrent connections, it stands out as the most scalable and high-performing MQTT Broker available.

Get Started

This section offers a comprehensive guide on downloading and installing the on-premise or self-hosted version of Bevywise CrystalMQ Broker on your chosen machines or servers. Additionally, it covers instructions on connecting devices and testing messaging scenarios (publishing and subscribing) with the broker.

Note: Apart from the deployment methods detailed in this section, if you're interested in exploring a cloud-hosted version of the MQTT Broker, simply sign up for an account. This allows you to connect your devices directly without the hassle of server maintenance.
Select your Plan

We've various plans fitting for various use cases, namely :

  • Developer Plan
  • Lite Plan
  • Starter Plan
  • Enterprise Plan
Developer Lite Starter Enterprise
Fully FREE MQTT Broker Premium Premium Premium
Upto 10 device connections Upto 100 device connections Connections based on custom requirement Connections based on custom requirement
Complete protocol support - 3.1, 3.1.1 and 5.0 Complete protocol support - 3.1, 3.1.1 and 5.0 Complete protocol support - 3.1, 3.1.1 and 5.0 Complete protocol support - 3.1, 3.1.1 and 5.0
No Feature restrictions Custom Storage Multi-tenanacy - White Labelling
Clustering Included and more and more and more
Download Buy Now Contact Us Contact Us

For Developer Plan (FREE version), you can directly get your free package using the download link.

For Premium plans, please contact support to get your license & build.

Install CrystalMQ Broker

CrystalMQ can run on any private / local machine / physical server in an on-premise environment or can also be run in docker.

It is cloud agnostic and can be hosted on any cloud platform.

The following operation systems are currently supported to run the downloadable package.

  • Windows 10 or Higher
  • Ubuntu 20 or higher
  • RHEL 9.x

You also have the option to deploy the MQTT Broker with just one click from the AWS and Azure Marketplace.

To run MQTT Broker as a docker, please use the link below to get started with: Run as a docker.

Install CrystalMQ with downloadable file

Windows

  • Run the executable file (Bevywise_CrystalMQ_5.0.exe).
  • Double click the “runbroker.bat” file inside the Bevywise/CrystalMQ/bin folder.

Or

  • Open cmd as administrator and go to Bevywise/CrystalMQ/bin folder.
  • Next, type “runbroker.bat” and hit enter.
cd ./Bevywise/CrystalMQ/bin

runbroker.bat

Linux

Open terminal window. Go to the path where the downloaded MQTT Broker package is located & unzip the archive.

unzip Bevywise_CrystalMQ_Linux.zip
  • Open bin folder in the unzipped package. Typical location can be Downloads/Bevywise/CrystalMQ/bin
  • Now run sh runbroker.sh
cd ./Downloads/Bevywise/CrystalMQ/bin

sh runbroker.sh

By default, broker starts on localhost IP address (127.0.0.1) / machine IP and listens on port 1883.

Open your web browser and navigate to http://localhost:8080/ (replace "localhost" with your IP address) in the address bar to access the MQTT Broker Dashboard.

Other ways to start MQTT Broker

The other method through which you can start the message broker is by running it as a service. Running broker as a service helps you start broker automatically when the machine starts. You can avoid running it every time from the terminal or command prompt.

For Windows

To start CrystalMQ service,

  • Open command prompt in administrator mode. Go to ./Bevywise/CrystalMQ/bin and run CreateCrystalMQSvc.bat. This will create the CrystalMQ service and start the same.

cd ./Bevywise/CrystalMQ/bin

CreateCrystalMQSvc.bat

To stop CrystalMQ service,

  • Open command prompt in administrator mode. Go to ./Bevywise/CrystalMQ/bin and run RemoveCrystalMQSvc.bat. This will stop the broker and remove it from services.

cd ./Bevywise/CrystalMQ/bin

RemoveCrystalMQSvc.bat

For Linux

The bin folder (Bevywise/CrystalMQ/bin) contains RunAsService.sh file. Run this file to enable ‘set up the service file’ and ‘path’ (set as a symbolic link redirect to “/opt/Bevywise” folder).

cd ./Bevywise/CrystalMQ/bin

sh RunAsService.sh

Now, to start the service, use

sudo systemctl start crystalmq.service

To check status, use

sudo systemctl status crystalmq.service

To stop service, use

sudo systemctl stop crystalmq.service

Note : Please note that before trying to run broker as a service make sure that you stopped it from running manually.
Testing the connection with Bevywise IoT Simulator

The Bevywise IoT Simulator is an MQTT data simulation tool that allows you to create and simulate multiple devices simultaneously. This enables you to conduct load testing and test connectivity efficiently.

MQTT Protocol Supported - MQTT 3.1, & 3.1.1

Prerequisites

Make sure that you have downloaded IoT Simulator in your machine before you proceed. If not, download it using the link below.

IoT Simulator Free Download
  • Open your web browser and navigate to http://localhost:9000/ (replace "localhost" with your IP address) in the address bar to access the IoT Simulator Dashboard.
  • Create a New Network and configure broker settings as below.
Manager Applications : Others
Broker IP Address :
TLS / SSL : Enabled / Disabled (Based on the configuration set in broker.conf).
Broker port : 1883 (It automatically changes to 8883 if TLS enabled).
Root-Certificate : Leave it empty if TLS is disabled.
Clean Session : 0 (0-False, 1-True).
  • Create a new device.
  • There can be different of IoT event configuration. Select anyone from the list and define topic, data format, & variant based on the need.
  • Now click 'Red' button to connect the device with MQTT Broker. You can create & simulate multiple devices following the same method.
  • You can check the MQTT Broker dashboard for device activity.

MQTT Clients

We do have comprehensive documentations to assist you in connecting various MQTT clients to our CrystalMQ broker. Those guides will provide detailed instructions and insights, ensuring a seamless integration experience with CrystalMQ. Click on the below link to get started with our instant MQTT Clients.

MQTT Clients Documentations

Technical Details & Support

This section explains about the hardware requirements and files & directories for high level configurations.

Hardware Requirements

Hardware requirements vary based on the message rate and size.

However, please find the minimal requirements below for your reference.

  • CPU - 1 core or higher
  • RAM – 2 GB or higher
  • Hard Disk – 50 GB or higher

Introducing MQTT Broker Folders

After completing the installation process, you will discover the following files and folders located at the specified path.

Folder Description Files
bin Contains executable files 1. runbroker.bat / runbroker.sh - To start broker
2. stopbroker.bat / stopbroker.sh - To stop broker
3. crystalmq.service - systemd linux service file
4. RunAsService.sh - To run broker as a service in linux
5. install_mysql_connector.sh /
install_mysql_connector.bat - To install mysql connector & other dependencies.
Certificate
./root
./server
./client
Certificates for TLS / SSL communication .root/root.crt - Self-signed CA.
.server/server.crt - server based CA signed certificate
.server/server.key - server based private key
.client/client.crt - client based CA signed certificate
.client/client.key - client based private key
conf Contains configurable files mqtt.conf
MQTT Authentication
TLS configuration
UTF Support
ACL
Clustering

application.conf
UI Configuration
Log Handling

datastore.conf
Database related configurations
extensions extendable python hooks custom_auth.py - To customize authentication
custom_scheduler.py - To add AI / ML algorithms
custom_store.py - To integrate third party applications
custom_ui_server.py - To customize UI as needed
lib library files essential for functioning of the broker
license Contains Broker license license.dat - premium license file
logs Error logs broker.log - Captures latest error logs
ui Complete list of front end html files, css, jss of MQTT Broker
data SQLite Database bevywise - Database which stores data received and sent by broker (if SQLITE is selected as data storage option)

Technical Support

For any technical queries regarding MQTT Broker or need to discuss your requirements, you can always reach us at

Email : [email protected]
Message : https://www.bevywise.com/contact-us.html
Phone : India - +91 8072398868 / US - +1 707 879 8999

MQTT 5 Broker Properties

This section provides the detailed view on MQTT 5 properties and the configurations you can set to play with this protocol version.

Session Expiry

MQTT 5 introduces the concept of session and message expiry. Clients can set session expiry intervals, allowing the broker to clean up disconnected client sessions after a specified period.

You can configure and set the session expiry interval in broker.conf

SESSION_EXPIRY_INTERVAL = -1

#If set to (-1) value from CONNECT packet is used for each client

You can define a specific time frame for session expiry. Once configured, disconnected client sessions will be automatically removed after the specified duration.

You have the option to set a universal session expiry interval for all devices.

Additionally, you can set individual session expiry intervals for each client by setting the value to -1. In this case, the broker will check the CONNECT packet of each client for the session expiry interval value, and it will use these values to manage session cleanup accordingly.

Receive Maximum

The RECEIVE MAXIMUM property is used to indicate the maximum number of QoS 1 and QoS 2 messages that the client can process concurrently. This enhances the flexibility and efficiency of message delivery for concurrent message processing, enabling better resource utilization and improved message handling dynamics between clients and broker.

You can configure and set the numbers in broker.conf under property SERVER_RECEIVE_MAXIMUM.

#Default: 65535

SERVER_RECEIVE_MAXIMUM = 65535

The value of SERVER_RECEIVE_MAXIMUM can range from 1 to 65,535.

A value of 0 indicates that the client can not process any QoS 1 or QoS 2 messages concurrently, effectively disabling these QoS levels for the client.

Maximum QoS

MQTT Broker can inform the client about the highest QoS level it supports by including the Maximum QoS in the CONNACK packet during connection establishment.

Upon receiving the Maximum QoS from the broker in the CONNACK packet, the client must adhere to this maximum QoS level when sending PUBLISH packets.

However, the broker can still accept SUBSCRIBE packets from clients containing a Requested QoS of 0, 1, or 2, regardless of its support for QoS 1 or QoS 2 PUBLISH packets.

You can define Maximum QoS in broker.conf

#Default: 2

MAXIMUM_QOS = 2

Maximum Packet Size

The Maximum Packet Size property is used by the broker to notify the client about the maximum allowed size for packets. The client is required not to send packets larger than this limit to the server. If the server receives a packet that exceeds this size limit, it's considered a Protocol Error, and the server will disconnect the client using DISCONNECT packet.

You can set the maximum packet size in broker.conf as below.

#Default: 268435460

SERVER_MAXIMUM_PACKET_SIZE = 268435460

#Maximum 5 Bytes for Fixed Header + maximum remaining length 268435455

Topic Alias Maximum

The "Topic Alias Maximum" is a property used to specify the maximum number of topic aliases that a client can use during MQTT communication with the broker. This allows the broker to inform the client about the maximum number of topic aliases it can use.

Topic aliases are shorthand references to topics that help reduce the size of MQTT control packets by replacing the topic name with a shorter identifier (alias).

You can set Maximum Topic Alias in broker.conf.

#Default: 0

SERVER_TOPIC_ALIAS_MAXIMUM = 99

A value of 0 indicates that the broker does not support topic aliases, and the client should not use topic aliases in its messages.

Server Keep Alive

The "Server Keep Alive" mechanism refers to a feature that allows the MQTT broker (server) to notify clients about the maximum time interval allowed for maintaining an active connection.

During the connection establishment phase (CONNACK packet), the MQTT broker informs the client about the "Server Keep Alive" interval. The "Server Keep Alive" interval specifies the maximum time duration (in seconds) that the client can remain idle without sending any control packets (e.g., PINGREQ) to the broker.

You can define this in mqtt.conf

SERVER_KEEP_ALIVE = 90

#If set to (-1) value from CONNECT packet is used for each client

If you specify the keep alive here, the client will use this value instead of the keep-alive value provided in its CONNECT packet.

However, if the value is set to -1, which means the broker does not send the Server Keep Alive property, and the broker will use the keep-alive value set by the client in its CONNECT packet.

Retain Available

The "Retain Available" feature refers to the capability of an MQTT broker to support retained messages. Retained messages are special MQTT messages that are stored on the broker and delivered to new subscribers when they subscribe to a topic.

You can enable / disable Retain in mqtt.conf

#Default:1

RETAIN_AVAILABLE = 1

# 0 || 1

A value of 0 means that retained messages are disabled. A value of 1 means retained messages are enabled.

Wild Card Subscription Available

A wildcard subscription refers to a subscription pattern that allows clients to subscribe to multiple topics using wildcard characters (+, #).

You have the option to configure the MQTT Broker to either enable or disable the wildcard feature based on your requirements.

#Default:1

WILDCARD_SUBSCRIPTION_AVAILABLE = 1

# 0 || 1

A value of 0 means that Wild Card Subscription is disabled. A value of 1 means that Wild Card Subscription is enabled.

Subscription Identifiers Available

Subscription identifiers are a feature that allows MQTT clients to assign identifiers to their subscriptions. Subscription identifiers are used to uniquely identify individual subscriptions made by MQTT clients to specific topics. Each subscription can be assigned a unique identifier.

#Default:1

SUBSCRIPTION_IDENTIFIERS_AVAILABLE = 1

# 0 || 1

A value of 0 means that subscription identifiers are disabled. A value of 1 means that subscription identifiers are enabled.

MQTT Shared Subscription

Our broker, by default, supports shared subscriptions, allowing data to be distributed among subscribed devices. When a publisher sends data to a topic, it is shared among all subscribed clients. For example, if two clients are subscribed to 'Topic 1', the broker will alternate sending messages between them.

Shared subscriptions follow the format below

$shared/subscriptionname/topic

You can enable / disable the same in mqtt.conf

#Default:1

SHARED_SUBSCRIPTION_AVAILABLE = 1

# 0 || 1

Note : Please be aware that while shared subscriptions function within nodes in a clustered environment, they do not extend across the entire cluster.

MQTT Broker User Interface & Dashboard

CrystalMQ UI enables you to monitor, visualise & manage your connected devices & data. This section provides a deep view on how to access the dashboard and to visualise MQTT data in a way you need.

Access to the UI / Dashboard

By default, the UI of the broker starts running in the port 8080. You can access it by navigating to the browser and entering

http://localhost:8080

Or

:8080
UI Configuration

This UI port can be changed by updating UI_HTTP_PORT in conf/application.conf

User Interface Configuration [UI]

UI_HTTP_PORT =8080
  • Restart the broker once
  • Now you can start accessing your UI in the defined port.
Note : UI port change may be required in scenarios where port 8080 is occupied by some other application running on your system. If you are not aware of some other application running, you will get [Error 98] while running MQTT Broker.
Overview

This page contains connection information of the Broker. TLS Encryption can be enabled or disabled from this page.

Overview

API Token to access CrystalMQ REST APIs can be generated in this page.

Dashboard

The dashboard provides a quick snapshot of the latest happenings in the Broker, where you can view the real time data coming from your devices. Along with raw data, you can expect the quick real time status of the broker.

dashboard
  • Active Devices – Devices that are currently active
  • Total Devices – Total number of devices connected so far to the broker
  • Events – Total number of messages / data published
  • Commands – Total number of messages / data received
  • Recent Events – The real-time view of recent data published.
  • Recent Device Log – The recent view on error occurred while connecting devices.
  • Recent Connections – The recent list of devices connected
  • Recent Disconnections – The recent list of devices disconnected

In addition to the default dashboard, MQTT Broker supports custom one which allows users to create multiple dashboards specific to their applications. Let us dig deeper to know how it can help your application.

Custom Dashboard

The usage of dashboards varies with use-case & application and it is not fair to provide static dashboards for all IoT implementations. Hence, CrystalMQ supports custom dashboards with set of pre-built widgets to help users have better visualisation specific to their application or industrial needs.

Unlike other MQTT Broker/servers you don’t need any third party plugin to visualise your data. You can create multiple dashboards with this functionality from the UI itself. Just lay out the widgets on the dashboard and provide a value-added visualization to your data.

List of widgets supported :

  • Text
  • Color
  • Line Chart
  • Bar Chart
  • Gauge Chart
  • Vertical Gauge
  • Horizontal Gauge
  • LED Light
  • Switch
How to create Custom Dashboards?

To create a Custom dashboard :

  • Click on '+' in the Dashboard Menu, Select “New Dashboard” and enter the Dashboard Name and description.
  • After completing, click the “Create” button to open the “Widgets” tab.
  • Then click the "+" icon at the top right corner of the widgets tab. 'Add Widget' window will appear along with the drop-down menu which lists the types of widgets.
custom dashboard

To create a Widget :

Widgets support JSON data and TEXT. Make sure you create widget only for numerical data.

widget

The steps to make 9 different types of widgets are listed below.

1. Text Widget
  • Select the ‘Text widget’ if you wish to display data in the form of plain text. This helps you highlight the values of specific parameters in a data.
text widget
  • Now provide a title and select a device from the device list.
  • The drop down menu will list all the clients (both active and inactive) connected to the platform.
  • Select the device which is active (your preferred device) from the list to view data flow in real-time.
  • Now you have to enter a topic for which your selected device is associated with.
  • If you have multiple topics for a particular device, all the topics will be listed in the drop-down menu.

Click to know more on MQTT Topics.

  • Then you have to select a key. Key refers to the parameters your JSON data has.

For example – JSON syntax will be like
{ “ KEY 1” : “ VALUE1 ” , “KEY2” : “ VALUE2 “ , “ KEY 3“ : “VALUE 3” }

Example for JSON data
{ “sensor” :”99″ , “temperature” : “90” , “status” : on” }

In the above data, sensor, temperature, status are referred to as keys and 99, 90 and ON are values for the keys.

For instance, if I want to display temperature data, I have to select the key as “temperature”. Then I have to enter unit for the data. As I have selected temperature as the key, I have given Celsius as unit. You can enter the right unit based on your data.

  • The color selection will allow you to select the color for the entire widget.
  • Then Minimum and Maximum refer to the range of your data. If I know that my data will reside in the range 0 to 100 or 40 to 80 etc., I can mention here.
  • Finally offset, it is an optional column. The effect of this parameter will vary based on the widget.
  • For example, in the case of Text widget, if the temperature is normal or low, I need to display that as a GREEN colored text. Similarly, if it is very high, I need to display that as RED colored text showing a Alert!! This is how offset helps in text widget. So I can enter the low temperature value as offset in the first column and will give green color for it. And then in the next column, I will enter the high temperature as offset and will give RED color.
  • Now, the inputs are given and you can view the text widget on submit.
text widget
2. Color Widget

Color widget helps you view data in a colored form. Also, you can set different colors for each optimum range of values.

The steps are the same as those of creating a TEXT widget.

add color widget
  • After providing the device details, topic & key selection & minimum & maximum range, you can proceed entering the offset values.
  • The usage of offset will vary here as you can make your desired MESSAGE to be displayed with selected background color.
  • For example, my device is publishing the speed data and the speed range is between 0 to 200. I want to get instant alert based on speed in three different formats like Normal, Medium & High speed in dashboard in colored format.

Let 0 to 50 be normal speed, 50 to 100 be medium speed and more than 100 be High speed. Now check the steps below.

  • Enter the first offset value as 50 and enter the subtitle as ‘Normal’ (as I want to display the text in a widget). Then you can select the preferred color (Background) to be displayed.
  • Enter the second offset value as 100 and enter the subtitle as ‘Medium’ (as I want to display the text in a widget). Then you can select the preferred color (Background) to be displayed.
  • Enter the third offset value as 100 and enter the subtitle as ‘Speed Alert’ (as I want to display the text in a widget). Then you can select the preferred color (Background) to be displayed.
  • Now you will be alerted with the speed in your preferred color
color widget
3. Line Widget

Line Widget allows you to create trend that is to view data that changes over time. This helps you create a series of values connected with a straight line. You can also compare changes over the same period for more than one value.

The steps are the same as those of creating a TEXT & Color widget. But there won’t be any option to set a minimum and maximum range & offset as this is a trend chart.

add line chart
  • Select Line chart from the widgets list.
  • Choose which kind of data you prefer : Live or Historical
  • Then, provide a title and select a device from the device list.
  • The drop down menu will list all the clients (both active and inactive) connected to the platform.
  • Select the device which is active (your preferred device) from the list to view data flow in real-time.
  • Now you have to enter a topic for which your selected device is associated with.
  • If you have multiple topics for a particular device, all the topics will be listed in the drop-down menu.
  • Then you have to select a key and provide a suitable sub-title & unit for the key.
line chart

As it is a trend chart, it displays data over time. Hence it is a chart of your data vs time. Data (value) will occupy y-axis and time will occupy x-axis. The subtitle & unit you provide will be displayed in y-axis.

  • Now you can provide your preferred color for the line which connects your data.
  • Click submit and your line chart will be created.

Note : When chosen Historical data, you can export the data for your preferable period of days.

To compare two or more values :

Comparing two or more values (data) of a single device can be done with line widget.

Follow the steps below to create a data comparison chart.

  • Use necessary steps in creating line widget as mentioned.
  • Before submitting the details, click + icon near color selection bar of first key.
  • Now proceed further by entering another key in a data, subtitle, unit and color.
  • You can add more keys based on how many keys the data of selected device has.
  • Now click submit and you can view the data comparison chart.
4. Bar Widget

The usage of Bar widget is the same as that of line widget and it represents data in rectangular bars with heights proportional to the values they represent.

add bar chart
  • Select Bar chart from the widgets list.
  • Choose which kind of data you prefer to get : Live or Historical
  • Then, provide a title and select a device from the device list.
  • The drop down menu will list all the clients (both active and inactive) connected to the platform.
  • Select the device which is active (your preferred device) from the list to view data flow in real time.
  • Now you have to enter a topic for which your selected device is associated with.
  • If you have multiple topics for a particular device, all the topics will be listed in the drop-down menu.
  • Then you have to select a key and provide a suitable sub-title & unit for the key.

As it is a trend chart, it displays data over time. Hence it is a chart of your data vs time, data (value) will occupy y-axis and time will occupy x-axis. The subtitle & unit you provide will be displayed in y-axis.

  • Now you can provide your preferred color for the bar which represents the key.
  • Click submit and your Bar chart will be created.
bar chart

Note : When choosing Historical data, you can export data for your preferable period of days.

To compare two or more values :

Comparing two or more values (data) of a single device can be done with bar widget.

Follow the steps below to create a data comparison chart.

  • Use necessary steps in creating bar widget as mentioned.
  • Before submitting the details, click + icon near the color selection bar of the first key.
  • Now proceed further by entering another key in a data, subtitle, unit and color.
  • You can add more keys based on how many keys the data of selected device has.
  • Now click submit and you can view the data comparison chart.
5. Gauge Widget

A gauge chart which visually illustrates a speedometer is used to represent progressive values.

The steps are the same as those of the TEXT & COLOR widget.

add gauge
  • After providing the device details, topic & key selection & minimum & maximum range, you can proceed entering the offset values.
  • The minimum & maximum value here depicts the starting and ending point in a dial.
  • The usage of offset will vary here as each offset represents the data range in a dial which is finally pointed by a needle. You can select different colors for different offsets.

Let us consider a pressure gauge and the data on pressure falls between the range 0 to 100. Now I can divide the dial into 5 different ranges.

  • 0 to 20
  • 20 to 40
  • 40 to 60
  • 60 to 80
  • 80 to 100

Each category represents each offset and I will assign different colors for the same. The needle will hove over & point out the pressure value based on the data received in dial.

gauge chart
6. Vertical Gauge & Horizontal Gauge

The usage of Vertical & Horizontal gauge is the same as that of Gauge but used to represent linear progressive values.

The steps for widget creation are exactly the same but you will have the linear scale (horizontal or vertical) instead of dial. You can set the offset based on this.

vertical gauge
horizontal gauge

For step by step procedure, please check Gauge widget.

7. LED Widget

It is a condition-based widget which works for random data. It can be used in a scenario of checking the status of the device either active or inactive.

Follow the steps below to create an LED widget.

  • Select LED from the widgets list.
  • Choose which kind of data you want : Live or Historical
  • Then, provide a title and select a device from the device list.
  • The drop down menu will list all the clients (both active and inactive) connected to the platform.
  • Select the device which is active (your preferred device) from the list to view data flow in real time.
  • Now you have to enter a topic for which your selected device is associated with.
  • If you have multiple topics for a particular device, all the topics will be listed in the drop-down menu.
  • Then you have to select a key.
add led light

Note : When choosing Historical data, you can export data for your preferable period of days.

Note : LED works only for the device which sends data in RANDOM. For example, On|Off or Open|Close

Now provide the value (ON) you receive when your device is active and (OFF) when the device is inactive in the respective space given. Choose your desired color. Based on the color chosen, the LED will blink representing the device status.

led light
8. Switch Widget

This is a user interactive widget where you can control the activity of device from the UI itself.

You can choose which kind of data you wish to get : Live or Historical. Based on the topic/event received by device, you can make your device ON/OFF or the action you need to perform with the subscribed data.

add switch widget

You can manually ON/OFF the device with the switch widget.

Note : When choosing Historical data, you can export data for your preferable period of days.

Note : Make sure the device you want to control is subscribed to the topic that has random data (ON / OFF or Open / Close).

switch widget
Clients

This menu displays the complete list of devices (both active & inactive) that are connected to the MQTT Broker. This provides you with a high level view on each device connected.

clients

Let us dig deeper to know how this can help.

Dashboard can provide the latest quick events of devices. But how can we get the complete list of events published and the commands received if it is a subscriber?

How can I send an instant command to the devices?

All these questions can be answered if you can make the optimum use of Clients Menu.

  • Go to Clients
  • Click any client
Events

The complete list of events published by the device selected. You can also get the list of messages published along with its associated topics by the selected device.

  • QoS level of each topic published. Read our blog to know more about Quality of Service (QoS) level.
  • The time at which the message was published.
events
Commands

The complete list of commands subscribed by the device selected. You can also get,

  • The list of messages received along with its associated topics by the selected device.
  • QoS level of each topic subscribed.
  • The time at which the message was received by the received.
commands
Subscribe Topics

This is a list of topic filters subscribed by the particular client.

topics
Send Command

‘Send Command’ helps you to send instant messages to client.

active subscriptions

Follow the steps to send an instant command :

  • Select topic name from the drop down menu.
  • Make sure the topic is subscribed by the device to which you are sending command.
  • Enter the command to be sent in the message tab.
Topics

The absolute list of topics published and subscribed by all devices connected to the broker.

Device Log

The connection of the device with the broker may be restricted/interrupted for so many reasons. The Device Log tab contains a list of errors that occurred while connecting a device to the broker. This helps you know the reason behind the failure.

The below list helps you to identify the reason for the error.

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
Client id 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 the correct user credential. Invalid Authentication Details Provided
Ping Response Failed Device went offline. TCP Timeout occurred.
SSL Accept Error while establishing a secure connection. Invalid SSL Certificate or Connection
Protocol Not Supported Invalid Protocol. The Received message is not in proper MQTT Format
Socket Closed Server is busy
Device Disconnected Unexpectedly Device disconnected
Rule Engine

Rules are the first step to build intelligence to the broker. It is an automation engine where you can create alerts based on the message received.

The rule engine comprises of Condition-based & Time based rules.

Condition based rule creation :

  • Client & Topic – Rule creation based on Client & topic
  • Topic & Message – Based on Topic & Message
  • Client & Topic & Message – Based on Client name, topic & message
rules type
Client & Topic

This rule type enables you to create rules based on the client & the topic it is associated with.

Let us consider the scenario. My publisher is publishing the data with the topic, pub/test in 2 minutes interval. And I want my subscriber with the topic sub/test subscribed to know that publisher is publishing the data or not.

So, I can create a rule that whenever the Publisher sends data, the subscriber will receive the message ‘Message Sent’.

Note : This is just an example scenario, you can create your own rule based on your need.

Steps to create Client & Topic rule type :

  • Go to the Rules tab & click + icon present at the top right corner.
  • The dialog box will be displayed to generate rules.
  • Now Select ‘Client & Topic’ in Rule type.
  • Provide the client ID of your publisher & Topic which the publisher is associated with.
client topic rule

If it has multiple topics, select the topic for which you are intended to generate a rule.

Now enter the topic which is about to receive the random message (yet to configure in rules)

Note : Device whichever is subscribed to this topic will receive the message configured.

Enter the message to be sent & click submit.

Alternatively, if you would like to send the message as it is from the publisher, click ‘forward’. This will forward the messages published as it are to the subscriber.

Topic & Message

This rule type enables you to send a response based on the message received and it is associated only with the topic & not with the device. (i.e) You can create rule specific to any publishing topic & it is not limited to the device associated with.

This rule type will be helpful for the below-mentioned scenario.

Let us consider my temperature sensor is publishing the temperature data in a range 0 to 50 and if it reaches the optimum value of 50, I have to send an alert message to the subscriber. So with topic & message rule type, I can set the condition that, if the data received is = 50, then send an alert message ‘Temperature High’.

Note : This is just an example scenario, you can create your own rule based on your need.

  • Go to the Rules tab & click + icon present at the top right corner.
  • The dialog box will be displayed to generate rules.
  • Now Select ‘Topic & Message’ in Rule type.
  • Provide Topic your preferred publishing topic.
  • Select the condition (=, <,>) and enter the value. (If the condition is = 50 then, you can select the condition as = and enter the value as 50).
topic message rule

Now enter the topic which is about to receive the random message (yet to configure in rules)

Note : Device whichever is subscribed to this topic will receive the message configured when the condition set is satisfied.

Enter the message to be sent & click submit.

Alternatively, If you would like to send the message as it is from the publisher, click ‘forward’. This will forward the messages published as it are to the subscriber on satisfying the condition set.

Client-Topic-Message

This rule type enables you to send a response based on the message received and it is associated with both topic & message (i.e) You can create rule specific to any publishing topic that is associated with the particular device.

The steps are the same as those of Client-Topic-Message rule type.

  • Go to Rules tab & click + icon present at the top right corner.
  • The dialog box will be displayed to generate rule.
  • Now Select ‘Client-Topic-Message’ in Rule type.
  • Provide the client ID of your publisher & Topic which the publisher is associated with. ( If it has multiple topics, select the topic for which you are intended to generate a rule.)
  • Select the condition (=, <,>) and enter the value. (If the condition is > 40 then, you can select the condition as > and enter the value as 40)
  • Now enter the topic which is about to receive the random message (yet to configure in rules)
client topic message

Note : Device whichever is subscribed to this topic will receive the message configured when the condition set is satisfied.

Enter the message to be sent & click submit.

Alternatively, if you would like to send the message as it is from the publisher, click ‘forward’. This will forward the messages published as it are to the subscriber on satisfying the condition set.

Timer based Rule creation

Timer Rule – Rule creation based on the given date and time.

Timer rule helps in scheduling the rule to execute it in a preferred date & time. (i.e) You can send an alert for the specified date & time.

  • Select ‘Timer’ in rule type.
  • Provide the client ID of the publisher.
  • Then enter the topic, which is subscribed by the above specified device, to which you are about to send the alert.
  • Enter the message to be sent.
  • Then the alert can be scheduled for :
    • Specific date
    • Date range
    • Day of the week
  • Select your preferred one and click create.
timer rule

Once done, the alert will be received by the subscriber client for the mentioned date & time.

rules
Security

Ensuring MQTT security is vital to protect sensitive data and maintain the integrity of messaging systems. By addressing the key aspects of MQTT security, organizations can establish a robust security posture for MQTT-based deployments, protect sensitive data, prevent unauthorized access, and maintain the integrity and confidentiality of MQTT communications.

Here are three levels of security employed in Bevywise MQTT Broker:

Device-Level Authentication

Device-level authentication involves validating the identity of devices connecting to the MQTT broker. This is crucial to prevent unauthorized devices from accessing the broker and ensures that only trusted devices can publish and subscribe to topics.

This enables you to connect your devices more securely with authentication credentials. This requires you to enable Authentication field in mqtt.conf file present in conf folder.

Enable Authentication :

  • Go to ./CrystalMQ/conf (Path may vary)
  • Open mqtt.conf
  • You can find AUTHENTICATION_ENABLED field is set to DISABLED. Change it to DEFAULT.
mqtt.conf

[DEVICE_AUTHENTICATION]
AUTHENTICATION = DEFAULT
# DEFAUT | DISABLED | CUSTOM

Save the file & restart the broker.

Now go to the UI of MQTT Broker. You will find the ‘Security’ Menu displayed. You can create your Authentication credentials for secure device connection.

security

Create Authentication Credentials :

Add MQTT Username (Access Key) and Password (Access Token) that can be used by specific ClientIds. 'Clients' - can be modified to a single ClientId, or a list of comma separated ClientIds (wildcards are supported). '*' means that Clients with any ClientId can connect.

add auth

These credentials can also be deleted.

MQTT Username (Access Token) can be either stored plain or as a digest in the database. Setting SECURE_MQTT_PASSWORD = TRUE in conf/datastore.conf will store MQTT Passwords as a digest and will not be displayed in the UI.

datastore.conf

SECURE_MQTT_PASSWORD = TRUE
# TRUE | FALSE

Save the file & restart the broker.

Please note that switching this configuration requires dropping the existing database.

Access Control Lists (ACLs)

ACLs are used to define granular permissions and control which devices or clients can perform specific actions (e.g., publish, subscribe) on MQTT topics. This level of security helps enforce fine-grained access control policies within the MQTT broker.

With ACL enabled, you can specify which topics the devices are allowed to publish or subscribe to, as well as which topics they are restricted from accessing.

Enable ACL

To enable ACL, go to 'mqtt.conf' file in the 'conf' folder. Then set as follows : TOPIC_ACL = TRUE. Save the file and restart the broker.

# This enables ClientId & Username based Access Control List to Topics

# If TRUE, all topics are allowed by default, unless topics are granted/denied access based on ClientId or Username.

TOPIC_ACL = TRUE

# TRUE | FALSE

MQTT Username based ACL

Enable Device Authentication to use MQTT Username based ACL.

Navigate to the 'Security' Menu

Under the Access Control List section, select MQTT Username

acl username

On creation of MQTT Username/Password, default ACL settings are automatically generated that allows PUBLISH/SUBSCRIBE of all Topics. This can be edited by clicking 'Edit' in the MQTT Username.

Comma Separated list of Topics can be configured to be allowed/denied for Publish and Subscribe of any Client connecting using this MQTT Username. Both the Publish and Subscribe Topics accept MQTT-like filters.

(eg. room/+/temperature)

Client based ACL

You can also set ACL based on the ClientId. ACL can be added only to already connected clients.

In the Security Menu, under the Access Control List Section, select 'Clients' and add ACL for a connected Client.

add acl for client
acl clients
TLS / SSL Encryption

Transport Layer Security (TLS) or Secure Sockets Layer (SSL) encryption adds a layer of security by encrypting MQTT communications between clients and the broker. This prevents eavesdropping, tampering, or unauthorized access to MQTT messages during transmission.

Enable TLS / SSL

To enable TLS, set TLS_ENCRYPTION = TRUE in conf/mqtt.conf :

TLS_ENCRYPTION = TRUE

[TLS]

# Used only when TLS_ENCRYPTION = TRUE

TLS_PORT = 8883

# TLS_PORT must be 88xx.

WSS_PORT = 11443

# Secure Websocket port of the Broker

SERVER_CERTIFICATE = ./../Certificate/server/server.crt

SERVER_KEY = ./../Certificate/server/server.key

CA_CERTIFICATE = ./../Certificate/root/root.crt

As TLS is enabled, broker will start running in the port 8883 instead of 1883.

Note : WSS_PORT_NO is to start the MQTT SSL version in Websocket.

By default, MQTTRoute comes with Self-Signed Certificate for Server. You can find the certificates inside CrystalMQ/Certificate

SERVER_CERTIFICATE = ./../Certificate/server/server.crt

SERVER_KEY = ./../Certificate/server/server.key

CA_CERTIFICATE = ./../Certificate/root/root.crt

Root certificate (root.crt) must be uploaded on the device / client side so the client can verify that the server's certificate (server.crt) was signed by its trusted root certificate.

If you need to create your own self-signed certificate, check below.

Self-signed Certificate Creation - Linux

Generate the Certificate Authority's signing key

$ openssl genrsa -des3 -out ca.key 2048

Enter pass phrase for the key and save it.

Result :

Generating RSA private key, 2048 bit long modulus (2 primes)

.......+++++

.+++++

e is 65537 (0x010001)

Enter pass phrase for ca.key:

Verifying - Enter pass phrase for ca.key:

Generate a certificate signing request for the CA

$ openssl req -new -key ca.key -out ca-cert-request.csr -sha256

Enter any organization name (Eg. Bevywise) and leave others empty.

Result :

Enter pass phrase for ca.key:

You are about to be asked to enter information that will be incorporated

into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [AU]:

State or Province Name (full name) [Some-State]:

Locality Name (eg, city) []:

Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bevywise

Organizational Unit Name (eg, section) []:

Common Name (e.g. server FQDN or YOUR name) []:

Email Address []:

Please enter the following 'extra' attributes

to be sent with your certificate request

A challenge password []:

An optional company name []:

Create the CA's root certificate

$ openssl x509 -req -in ca-cert-request.csr -signkey ca.key -out ca-root.crt -days 365 -sha256

Result :

Signature ok

subject=C = AU, ST = Some-State, O = Bevywise

Getting Private key

Enter pass phrase for ca.key:

Create the server / MQTT Broker's key pair

$ openssl genrsa -out server.key 2048

Result :

Generating RSA private key, 2048 bit long modulus (2 primes)

..............................+++++

.......................................+++++

e is 65537 (0x010001)

Create a certificate signing request

This can be done using the server key (server.key) to send it to the Certificate Authority for identity verification

$ openssl req -new -key server.key -out server-cert-request.csr -sha256

Provide any organization name (eg.Bevywise Inc) and enter the common name. Comman name (eg : tempmyaccount.mqttserver.com) should be the domain name of your server in which the MQTT Broker is running.

Or enter localhost if MQTT Broker is operating on a local machine.

Result :

You are about to be asked to enter information that will be incorporated

into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [AU]:

State or Province Name (full name) [Some-State]:

Locality Name (eg, city) []:

Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bevywise Inc

Organizational Unit Name (eg, section) []:

Common Name (e.g. server FQDN or YOUR name) []:tempmyaccount.mqttserver.com

Email Address []:

Please enter the following 'extra' attributes

to be sent with your certificate request

A challenge password []:

An optional company name []:

Creating and signing the server certificate

This step is to create a new server certificate and sign it with the power of Certificate Authority.

$ openssl x509 -req -in server-cert-request.csr -CA ca-root.crt -CAkey ca.key -CAcreateserial -out server.crt -days 360

Result :

Signature ok

subject=C = AU, ST = Some-State, O = Bevywise Inc, CN = tempmyaccount.mqttserver.com

Getting CA Private Key

Enter pass phrase for ca.key:

Now you have the below certificates and key in hand.

  • ca-root.crt (rename it to root.crt)
  • server.crt
  • server.key

Now, server.crt and server.key should be uploaded on the server ../MQTTRoute/Certificate/server, and root.crt should be provided on the client so the client can verify that the server's certificate (server.crt) was signed by its trusted root certificate.

root.crt - .../MQTTRoute/Certificate/root

server.crt - .../MQTTRoute/Certificate/server

server.key - .../MQTTRoute/Certificate/server

Self-signed Certificate Creation - Windows
  • Create CA certificate
  • Open Windows File Explorer.
  • Navigate to the OpenSSL bin directory.
  • Right-click the openssl.exe file and select Run as administrator.
  • Enter the following command to begin generating a certificate and private key:

req -new -x509 -sha256 -nodes -days365 -newkey rsa:2048 -keyout root.key -out root.crt

You will then be prompted to enter applicable Distinguished Name (DN) information, totalling seven fields :

Country Name (2 letter code) [AU]:.

State or Province Name (full name) [Some-State]:.

Locality Name (eg, city) []:.

Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bevywise

Organizational Unit Name (eg, section) []:.

Common Name (e.g. server FQDN or YOUR name) []:

Email Address []:[email protected]

You can modify the details based on your need.

Once completed, you will find the root.crt and root.key files created under the ..\\OpenSSL\\bin\\ directory

Create server key pair :

Again, navigate to the bin folder of openssl and enter the following commands:

genrsa -out server.key2048

req -new -out server.csr -key server.key

You will then be prompted to enter applicable Distinguished Name (DN) information, totalling seven fields :

Country Name (2 letter code) [AU]:.

State or Province Name (full name) [Some-State]:.

Locality Name (eg, city) []:.

Organization Name (eg, company) [Internet Widgits Pty Ltd]:Bevywise

Organizational Unit Name (eg, section) []:

Common Name (e.g. server FQDN or YOUR name) []:mqtt.server.com

Email Address []:[email protected]

Please enter the following ‘extra’ attributes to be sent with your certificate request.

A Challenge Password []:

An Optional Company Name []:

Enter the following command in the prompt

x509 -req -in server.csr -CA root.crt -CAkey root.key -CACreateserial -out server.crt

Upload the created certificates in the respective folders.

root.crt in ../MQTTRoute/Certificate/root

server.crt in ../MQTTRoute/Certificate/server

server.crt in ../MQTTRoute/Certificate/server

Trusted CA Certificate Creation - Linux

In this example, we will use certbot to generate LetsEncrypt Certificate and use that certificate to enable a secure TLS communication between MQTTRoute and its clients.

Install certbot:

$ sudo snap install -classic certbot

$ sudo ln -s/snap/bin/certbot/usr/bin/certbot/

Create Certificate :

$ sudo certbot certonly -standalone -d <your_domain>

The certificates will be created and saved in /etc/letsencrypt/live/<your_domain>

Set the paths of these generated certificates in Bevywise/MQTTRoute/conf/mqtt.conf

TLS_ENABLED = TRUE

SERVER_CERTIFICATE = /etc/letsencrypt/live/<your_domain>/fullchain.pem

SERVER_KEY = /etc/letsencrypt/live/<your_domain>/privkey.pem

CA_CERTIFICATE = /etc/letsencrypt/live/<your_domain>/chain.pem

Trusted CA Certificate Creation - Windows

In this example, we will use certbot to generate LetsEncrypt Certificate and use that certificate to enable a secure TLS communication between MQTTRoute and its clients.

Install certbot:

Download the latest version of the Certbot installer for Windows from the url, https://dl.eff.org/certbot-beta-installer-win_amd64.exe.

Create Certificate :

Open the Windows Start Menu and launch Windows PowerShell as an Administrator.

Enter the following commands to request a free Let’s Encrypt SSL certificate.

PS> certbot -d <your_domain>

The certificates will be created and saved in live folder of installation directory. Set the paths of these generated certificates in Bevywise/MQTTRoute/conf/mqtt.conf

TLS_ENABLED = TRUE

SERVER_CERTIFICATE = /etc/letsencrypt/live/<your_domain>/fullchain.pem

SERVER_KEY = /etc/letsencrypt/live/<your_domain>/privkey.pem

CA_CERTIFICATE = /etc/letsencrypt/live/<your_domain>/chain.pem

Database Configuration

The options to configure how data is stored by the Broker is set in Bevywise/CrystalMQ/conf/datastore.conf.

Device Information (Device IDs and Subscriptions) and MQTT Payload (Published/Received messages) are stored by the broker in one of the relational databases, by default. The relational databases supported by the Broker are: SQLite, MySQL, MSSQL & PostgreSQL. The UI uses this database.

However, if the data needs to be stored in some other database, outside the Broker, then it can be configured too.

Enabling / Disabling Storage in Relational Database

To store both Device Information (Device IDs, Subscriptions) and Payload (Published/Received messages) in database,

  • Go to Bevywise/CrystalMQ/conf/datastore.conf
  • Set, RELATIONAL_PERSISTENCE_ENABLED as True and enable PAYLOAD_TO_DB

RELATIONAL_PERSISTENCE_ENABLED = TRUE

PAYLOAD_TO_DB = ENABLED

If you don’t want to store both Device Information and Payload in database, then set

RELATIONAL_PERSISTENCE_ENABLED = FALSE

In this case, CrystalMQ UI is NOT available. Hence, PAYLOAD_TO_DB is assumed to be DISABLED.

To store only the Device Information in database and NOT the MQTT Payloads, set

RELATIONAL_PERSISTENCE_ENABLED = TRUE

PAYLOAD_TO_DB = DISABLED

In this case, only device information can be seen in the UI.

Let us see the Relational Database Configurations below.

Configuring SQLITE

SQLITE is the default storage option in MQTTRoute. And by default, Broker will store data in SQLITE.

You can check the configurations set in datastore.conf. DB_SERVER will be set in SQLITE.

[CONFIG]
DB_SERVER = SQLITE
# SQLITE || MYSQL || POSTGRES || MSSQL

Also, check SQLite Server information. A sample configuration is given below:

[SQLITE]
# SQLITE || MYSQL || POSTGRES || MSSQL

SQLite database will be stored in path Source/Bevywise/CrystalMQ/data.

Configuring MySQL

To configure MySQL Server as the relational database used by CrystalMQ, set in Bevywise/CrystalMQ/conf/data_store.conf

DB_SERVER = MYSQL

Also, set MySQL Server information. A sample configuration is given below.

[MYSQL]

DBHOST = 127.0.0.1

DBPORT = 3306

MYSQL_DB = bevywise

MYSQL_USER = root

MYSQL_PASSWORD = root

Note : The server configuration needs to be get from your MySQL server.

MYSQL Connector Installation :

Install the MYSQL connector and other dependencies by running the below command.

../MQTTRoute/bin

Windows

install_mysql_connector.bat

Linux

$ sh install_mysql_connector.sh

Configuring MSSQL

To configure MSSQL Server as the relational database used by CrystalMQ, set in Bevywise/CrystalMQ/conf/datastore.conf

DB_SERVER = MSSQL

Also, set MSSQL Server information. A sample configuration is given below

[MSSQL]

DRIVER = ODBC Driver 17 for SQL Server

SERVER_NAME =

DBPORT = 1434

MSSQL_DB = bevywise

MSSQL_USER = sa

MSSQL_PASSWORD =

In Linux, set SERVER_NAME as the value of ‘Description’ in file: /etc/odbcinst.ini

Configuring PostgreSQL

To configure PostgreSQL Server as the relational database used by CrystalMQ, set in Bevywise/CrystalMQ/conf/datastore.conf

DB_SERVER = POSTGRES

Also, set PostgreSQL Server information. A sample configuration is given below

[POSTGRES]

PSQLHOST = 127.0.0.1

PSQLPORT = 5432

PSQL_DB = bevywise

PSQL_USER = postgres

PSQL_PASSWORD = admin

MQTT Sparkplug B support

MQTT Sparkplug B relies on an MQTT broker to facilitate communication between industrial devices, sensors, and applications like, SCADA, Historians, etc. The MQTT broker serves as the underlying communication infrastructure that adheres to the MQTT protocol standards and handles the routing of Sparkplug B-compliant messages.

Sparkplug B-compliant devices and applications publish and subscribe to topics on the MQTT broker, following the structured data formats and guidelines specified by the Sparkplug B protocol.

The MQTT broker provides the communication backbone and protocol support, while MQTT Sparkplug B defines the standards and conventions for data exchange within industrial IoT ecosystems, leveraging the capabilities of the MQTT protocol for efficient, reliable, and scalable industrial automation and monitoring.

Our broker, by default, supports Sparkplug-enabled devices without requiring changes to the configuration file. However, it's essential to verify that the 'authentication' setting is enabled in the mqtt.conf file.

AUTHENTICATION = TRUE

MQTT Clustering

To ensure High Availability, more than 1 CrystalMQ Brokers can be used. Our CrystalMQ with the built-in Inter-Broker Communicator (IBC) enables all the brokers in the cluster to talk to each other ensuring continuous communication with the devices both ways irrespective of clients getting connecting to any broker in the cluster.

A load balancer can be set up at the device-facing edge to balance the load.

To learn more about the inter-broker communicator functionality, read our high availability blog.

To enable High Availability in CrystalMQ, you should activate the inter-broker communicator first.

Activate Inter-Broker Communicator

The built-in Inter-broker Communicator (IBC) feature ensures seamless communication among all brokers within a cluster. This guarantees continuous connectivity with devices in both directions, regardless of which broker clients connect to.

To enable IBC after installing MQTTRoute on broker machines, modify the configuration in Bevywise/MQTTRoute/conf/mqtt.conf as follows:

CLUSTERING_ENABLED = YES

The illustration below demonstrates the setup:

ibccluster

In this arrangement, two or more brokers with IBC enabled are grouped to form a cluster. A load balancer is then configured to distribute workloads evenly across these brokers. All MQTT brokers within the cluster remain active, and IBC within each broker ensures persistent communication by utilizing a shared database (DB). This means that brokers do not directly communicate with one another. Instead, they push data to the central database, allowing other brokers to access this data. As a result, every broker has access to client details and data.

Note: You have the flexibility to select any load balancer that suits your needs.

For a more comprehensive understanding of Nginx load balancer configuration, we recommend checking out our detailed blog on high availability.

If you've opted to use Azure as your load balancer, we suggest referring to our dedicated blog post on Azure load balancer configuration for enhanced clarity.

Refer : IoT Implementation on Azure blog

Process Supervision using Monit

To run the MQTT Broker as service, we need the Monit version 5.25. Monit is an open source dynamic monitoring tool for Linux systems which is used for monitoring and managing system processes. And also, it performs automatic maintenance or repair of a particular process (i.e., restarting the service) and execute significant informal actions in error conditions whenever necessary.

Download & Install Monit :

$ sudo apt install monit

$ sudo systemctl disable monit

$ wget https://monit.com/monit/dist/binary/5.25.2/monit-5.25.2-linux-x64.tar.gz

Extract the archive using the command below :

$ tar -xvzf < Download file> (For example -$ tar -xvzf monit-5.25.2-linux-x64.tar.gz

Copy monitrc file and paste in below location :

$ sudo cp monit-5.25.2/con/monitrc/etc/

$ sudo chmod 700 /etc/mmonitrc

Enable Monit HTTP interface :

Enable the HTTP interface by un commenting the following lines in /etc/monitrc file.

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’

If you want you can change admin:monit with username and password you want to use

Start Monit :

$ cd monit-5.25.2/bin/

$ sudo pkill -9 monit

$ sudo ./monit

Open Monit UI using the below URL in your web browser http://localhost:2812

Extensions

CrystalMQ has certain extensions to make it flexible for users. You can customize it based on your needs.

These custom extensions can be used individually or in combinations to fulfil your requirements beyond an MQTT Broker.

In CrystalMQ/extensions/extension_globals.py, there are objects that can be used to query the Internal Database, to send live updates to UI and to send messages to a connected client.

These objects can be used in the extensions to yield compelling customisations.

Custom Authentication

By default, the authentication of devices is done by the Broker. But, if authentication needs to be done outside the Broker, then this option can be used by setting in Bevywise/MQTTRoute/conf/mqtt.conf

  • Go to ./CrystalMQ/conf (Path may vary)
  • Open mqtt.conf
  • Make sure AUTHENTICATION is set to True

AUTHENTICATION = CUSTOM

[DEVICE_AUTHENTICATION]

In this case, the Username/Password sent by devices are received at the method custom_authenticate(username, password, clientid, ipaddress) in CrystalMQ/extensions/custom_authentication.py

This method can be updated to authenticate the devices, the way you require. (eg. HTTP Request to an external LDAP Server)

Custom Data Store

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

Custom Store implementation is used to hook the received payload from MQTT Broker and store the payload in any of your analytics / big data engine. To configure, in conf/datastore.conf

DATA_INTEGRATION = TRUE

In CrystalMQ/extensions/custom_store.py, there are two hooks method:
on_message_received_hook(data) - This method gets data every time a client publishes it.
on_message_sent_hook(data) - This method gets data every time it is sent to a client.
The data will be passed in a JSON format with the following keys:

data: { 'sender':, 'topic':, 'message':, 'unixtime':, 'datetime': } These methods can be used to push/store the data to other data sinks.

Custom UI server

UI custom server provides an option to customize the user interface. You can alter the code in CrystalMQ/extensions/custom_ui_server.py file as you need to customize it. You will be able to configure your dashboard to view device data as per your needs. You can add your own requirements, device details or notifications to the user interface as required. The UI custom server will help you customize the UI of the CrystalMQ by adding your own code on the server-side. Add your new functionality using the URL and the corresponding method. These URLs can be invoked from your User Interface for manipulating data.

Custom Scheduler

The Custom Scheduler will help you create your own scheduled jobs in CrystalMQ by adding your own code on the server-side.

Jobs and schedules added to CrystalMQ/extensions/custom_scheduler.py will be picked up by the Broker. To enable this, set in the method custom_schedules() enableCustomSchedules = True

Have More Questions?

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