Getting Started Guide

Shared FREE Plan

When you select the Shared FREE plan, your 'Free Forever' MQTT server will be ready within a minute or two.

Once it's set up, you'll see a page with the following details:

1. MQTT Server Name - Shared MQTT platform

2. MQTT Dashboard - The link to access your shared free instance

3. Plan - FREE (as you have chosen)

4. Created On - The date and time your account was created

Click on the link to access your CrystalMQ Dashboard.

When you click, you'll be taken to the 'Connect Page', which provides essential details such as the host address, TCP port, and WebSocket port. Additionally, we offer a list of ready-to-use MQTT client applications that you can use to connect to our cloud broker.

Connect your clients/devices

Begin provisioning and monitoring your devices.

Under the Clients tab, click on the + icon to add a new client.

'Add a Client' window will appear.

Provide a unique client ID and name for the client/device you are adding. The MQTT username and password for that client will be automatically generated. Once added, the authentication token (which serves as the password) will be shown only once before being encrypted for security reasons. Be sure to note it down for future use.

Include a brief description of the client.

Then fill in the 'Can' tab which is nothing but the permissions tab.

There are 3 types of permissions. They're :

• Send and Receive Messages – Grant both subscribe and publish permission for the device.
• Send Messages – Grant only publish permission.
• Receive Messages – Grant only subscription permission.

After filling in all the details, click the 'Add' button to provision your client/device.

Once completed, the newly created device, along with its authentication key and token, will be displayed.

Note: The auth key and token will only be visible during the initial client addition process. After that, they will be encrypted. Please make sure to save them for future reference.

You also have the ability to control your clients' or devices' access to publishing and subscribing topics. In the 'Access Control List' section, enter the topic or multiple topics (separated by commas) and choose whether to allow or deny the device/client from publishing to those topics. Similarly, enter the subscription topics and set whether to allow or deny subscription to them.

Data - Dashboard

The dashboard provides a quick overview of the most recent activity on the platform. It displays the following information:

• Total & Active Clients: The total number of clients/devices along with the count of active ones.
• Messages Received & Sent: The total number of messages received and sent.
• Recent Events: A log of recently published messages, including the client ID, the topic, the data, and the timestamp of the publication.
• Recent Connections & Disconnections: Information about clients/devices that have recently connected or disconnected.

Clients

This tab displays the complete list of devices (both active and inactive). It provides you with a high level view on each connected device. With the help of Devices tab, you can get the complete list of events published, commands received if it is a subscriber and send an instant command to the devices. To make optimum use of devices tab, follow the below steps.

• Go to ‘Devices/Clients’ tab.
• Click anyone from the devices listed.

Activity

This is nothing but a list of recent activities.

Events

The list of messages published by that devices along with its associated topic and the time at which the data is published.

Commands

The list of messages received from other devices from a topic this device is subscribed to along with the time at which the data is received.

Subscriptions

This is nothing but the list of topics subscribed by that particular device.

Send

Users can send a message or data to the subscribed topic manually with the help of ‘Send Command’. Users can use this feature for testing. This can be done at the device level or for a group of devices. To send an instant command :

• Go to the ‘Send’ tab.
• Select the active subscribed topic from the list below ‘Command Topic’ to which you want to send the message.
• After selecting, those devices that are subscribed to the selected topic will be listed on the left panel.
• In the 'Data’, type the message which is to be sent to the topic.
• Then click the ‘Send’ button to send the data to the specified topic.

Dashboard

This is the custom dashboard page where you can create widgets to visualize your data using your preferred charts or graphs.

Widgets

You can create more than 8 different types of widgets here. Below is the list of available widget types:

• Text
• Colour
• Table
• Line Chart
• Bar Chart
• Gauge Chart
• Half Gauge
• LED Light
• Switch

Widget Creation

To create a widget, follow the below steps :

Click on the + symbol in the top right corner. In the 'Widget type' window that appears, select anyone type of widget.

1. Text Widget

Select ‘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.

• Provide a title.
• Select a device from the devices listed in the drop-down menu.
• After selecting the device, the corresponding topics will be listed in the ‘Topic’ tab. Choose any one topic from the list.
• Enter ‘Key’, ‘Unit’ in the respective space provided and then pick a colour to display.
• Then enter ‘Minimum’ , ‘Maximum’, and ‘Offset’ values.
• Provide Subtitle and choose a ‘Colour’ to display.
• If you want to add more key values, then click the ‘Add’ ( + symbol) and repeat the previous steps.
• Click the ‘Create’ button to view your text widget.

2. Colour Widget

‘Colour widget’ helps you to view data in colored form. Also, you can set unique colour for each optimum range of values.

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

After providing the device details, topic, key selection, minimum & maximum range, you can proceed entering the offset values.

Give a subtitle if you wish and pick a colour to display. Finally, click ‘Create’ to view your colour widget.

3. Table Widget

Table widget allows you to view the data in the form of a table.

• Select ‘Table widget’ from the list of widgets.
• Provide a title.
• Choose a device from the device list.
• Enter a topic for which your selected device is associated with.
• Then you have to select a key and provide a sub-title & unit for the key.
• Enter Offset value, status and choose a colour to display.
• Hit the ‘Create’ button to view your table widget.

4. Line Chart

Line widget allows you to create trend that is to view data that changes over time. This helps you to create a series of values connected with a straight line.

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

5. Bar Chart

Bar chart has the same usage as that of Line chart and it represents data in rectangular bars with heights proportional to the values they represent.

• Choose Bar chart from the widgets list.
• Provide a title and select any device from the device list.
• After selecting the device, the corresponding topic will be listed in the ‘Topics’ tab. Select a topic.
• Enter ‘Key’ , ‘Subtitle’ , ‘Unit’ in the appropriate space provided and pick a colour to display.
• If you need to add more keys, then click the ‘Add’ button and repeat the previous steps.
• Press the ‘Create’ button to view the widget.

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 and unit you provide will be displayed in y-axis.

6. Gauge Chart

Gauge chart visually illustrates a speedometer, which is used to represent the progressive values.

The steps for creating a gauge chart are the same as those of a Text and Colour Widget.

Provide Title and select a device from the list of devices. Then choose a topic from the Topics tab and enter ‘Key’ , ‘Unit’ in the appropriate spaces allotted and pick a colour to display.

Proceed further by entering minimum, maximum and offset values. The minimum and maximum value here depicts the starting and ending point in a dial.

The usage of offset will vary here as each offset represents data range in a dial which is finally pointed by a needle. You can select different colours for different offsets.

Once you’re done, click ‘Create’ to view the gauge widget.

7. Half Gauage Chart

The process for creating a half-gauge chart is similar to that of a gauge chart. For more details, please refer to the steps for creating a gauge chart.

8. LED Light

LED widget 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.

• Select ‘LED light’ from the types of widgets.
• Give it a Title and choose a device from the listed devices.
• Now you have to enter a topic for which your selected device is associated with.
• Select a key value.

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 in active state and (OFF) when your device is in inactive state, in the respective space allotted. Choose your desired colour to represent both active and inactive states. Based on the colour chosen, the LED will blink representing the device’s status.

9. Switch Widget

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

• Select ‘Switch’ from the widgets list.
• Provide a Title and select a Device from the list of devices that appear on the drop-down menu.
• In the ‘Topics’ tab, select a suitable topic that your selected device is associated with.
• Enter ‘Subscribe Topic’.
• Select Active value and pick a colour to display it, Similarly, select Inactive value and choose a colour to display it.
• Hit the ‘Create’ button to view the widget.

Additionally, we've provided the facility of editing the layout of the widgets created. Upon enabling the 'Edit Layout' option in the top right corner, you will be able to adjust, rearrange, and personalize your widgets to match your unique workflow and comfort. After adjusting it, simply click on the 'Save Layout' option to get your changes saved.

Advanced Plan

When you choose the 'Advanced Plan,' you will be directed to the payment page where you'll need to enter your payment details.

If you have already provided your details on the 'Accounts' page, they will be displayed here for your review before you complete the payment.

Enter Your Details

Follow these steps to enter your necessary details under the 'Accounts' category beforehand:

• Click on the 'Account' button located at the top right corner.
• Under the 'Personal Info' section, provide your Name, phone number, address, country, and zip code.

• Click the 'Save' button after entering your personal information.
• Proceed to the 'Payment' section.

• Click on 'Add New Card' and enter your card details in the window that appears.

• Click 'Add Card' to add your card information.
• Go to the 'Security' section, where you can delete your account and associated data.

If you wish to delete your account from the CrystalMQ service, click on the 'Delete Account' button.

Back on the payment page, if you haven’t entered your details on the 'Account' page, you can do so here.

Begin by entering your personal information and selecting your membership type based on your needs. Next, proceed to the card details section and enter your card information accurately. Once completed, click the 'Checkout Now' button to process your payment.

After the payment is finalized, your instance will be ready within a few minutes. You'll be directed to a page with two options: 'Go to Broker Instance' and 'Go to Dashboard'. Selecting 'Go to Broker Instance' will take you to your instance page, where you can start using the broker. Choosing 'Go to Dashboard' will provide details about your created instance.

With the setup complete, you can now start enjoying the services.

Connecting Your Clients/Devices

You can begin provisioning your clients/devices to our CrystalMQ broker. For detailed instructions on how to connect your devices and proceed, please refer to the 'Connect your clients/devices' tab above.

Data Connectors

Our MQTT broker offers the capability to push the data streams to the set of connectors listed below.

• MySQL
• Mongodb
• Kafka
• Postgres
• Redis
• HTTP request
• MQTT Bridge
• InfluxDB
• Amazon Kinesis

By connecting to the data connectors, you can easily stream live data to your remote instances. This seamless integration guarantees real-time data delivery, boosting your operational efficiency.

1. MySQL Connector Configuration

To connect your broker to a MySQL connector, configure the following settings :

• Host - Enter the hostname or IP address of the MySQL server.
• Port - Enter the port number on which the MySQL server is listening (By default, it's 3306)
• Username - Enter the username to authenticate with the MySQL server.
• Password - Enter the password associated with the MySQL username.
• Database - Specify the name of the database to which you want to connect.
• SSL - Enable SSL if you want your connection to be secure. If SSL is enabled, just upload the Certificate Authority (CA) certificate file and SSL key as well as SSL certificate if necessary.
• CA Certificate - Upload the Certificate Authority (CA) certificate if the server's certificate is self-signed or issued by a CA that is not widely recognized.
• Client Certificate & Client Key - Upload these files if the server requires mutual authentication, allowing both the client and server to verify each other's identity.

Once all required fields are completed, click the 'Edit' button to establish a connection to the MySQL connector.

2. MongoDB Connector Configuration

The steps for configuring the MongoDB connector are the same as those for the MySQL connector. For detailed instructions, refer to the MongoDB connector configuration section.

Note : The port number on which the MongoDB server listens by default is 27017

3. Kafka Connector Configuration

Follow the below steps to establish a connection to Kafka connector:

• Host - Enter the hostname or IP address of the Kafka server.
• Port - Enter the port number on which the Kafka server is listening (By default, it's 9092)
• SASL Mechanisms - There are 3 types of authentication mechanisms in KafKa. They're as follows :
• None - No authentication required
• PLAIN - Simple authentication with a username and password. After selecting the 'PLAIN' method, enter the username and password to establish a connection with the Kafka server
• SCRAM - Secure authentication using SHA-512
• MQTT topic - Specify the topic to which you want to push the data.

Note : You can use * if you wish to push the data to all the topics.

• SSL - Enable SSL if you want your connection to be secure. If SSL is enabled, just upload the Certificate Authority (CA) certificate file and SSL key as well as SSL certificate if necessary.
• CA Certificate - Upload the Certificate Authority (CA) certificate if the server's certificate is self-signed or issued by a CA that is not widely recognized.
• Client Certificate & Client Key - Upload these files if the server requires mutual authentication, allowing both the client and server to verify each other's identity.

Once all required fields are completed, click the 'Edit' button to establish a connection to the MongoDB connector.

4. Postgres Connector Configurations

The steps for configuring the Postgres connector are the same as those for the MySQL connector. For detailed instructions, refer to the MongoDB connector configuration section.

Note : The port number on which the Postgres server listens by default is 5432

5. Redis Connector Configurations

The steps for configuring the Redis connector are the same as those for the MySQL connector. For detailed instructions, refer to the MongoDB connector configuration section.

Note : The port number on which the Redis server listens by default is 6379

6. HTTP Request

Here are the necessary steps to configure and establish a connection with the HTTP request:

• Request URL - Specify the API URL to which the HTTP POST request will be sent.
• Authentication Type - Select the type of authentication required for the HTTP POST request. Following are the types of authentication :
• No Authentication - No authentication is required
• Basic - Specify the username & password for authenticating the requested URL
• API-KEY - Give the API-Key for authenticating the requested URL
• Token - Give token for authenticating the request URL
• Bearer Token - Give the bearer token for authenticating the URL
• SSL - Enable SSL if you want your connection to be secure. If SSL is enabled, just upload the Certificate Authority (CA) certificate file and SSL key as well as SSL certificate if necessary.
• CA Certificate - Upload the Certificate Authority (CA) certificate if the server's certificate is self-signed or issued by a CA that is not widely recognized.
• Client Certificate & Client Key - Upload these files if the server requires mutual authentication, allowing both the client and server to verify each other's identity.

Upon completing all these required fields, click on the 'Edit' button to establish a connection to the HTTP request.

7. MQTT Bridge Connector

In this method, our broker will connect to another broker (i.e., your remote broker) on a server to transfer data. Follow the steps below to configure the MQTT bridge connector.

• Broker URL - Specify the URL of the MQTT broker to which you want to connect.
• Port - Enter the port number on which the MQTT broker is listening (By default, it's 1883 for non-SSL and 8883 for SSL)
• Client ID - Specify the unique client ID of the device to connect with your remote MQTT broker.
• Protocol version - Specify the protocol version of the above mentioned client. (For instance, MQTT version 3 or 5)
• MQTT username - Provide the username for authenticating with the MQTT broker (if necessary).
• MQTT password - Provide the password associated with the above username for authenticating with the MQTT broker (if necessary).
• SSL - Enable SSL if you want your connection to be secure. If SSL is enabled, just upload the Certificate Authority (CA) certificate file and SSL key as well as SSL certificate if necessary.
• CA Certificate - Upload the Certificate Authority (CA) certificate if the server's certificate is self-signed or issued by a CA that is not widely recognized.
• Client Certificate & Client Key - Upload these files if the server requires mutual authentication, allowing both the client and server to verify each other's identity.

Upon completing all these required fields, click on the 'Edit' button to establish a connection to the MQTT bridge connector.

8. InfluxDB configurations

Follow the below instructions to connect to InfluxDB.

• Host - Enter the hostname or IP address of the InfluxDB server.
• Port - Enter the port number on which the InfluxDB server is listening (By default, it's 8086)
• Token - Provide the token used for authenticating with the InfluxDB server.
• Bucket name - Specify the name of the bucket (a named location where the data gets stored) to which the data will be written in InfluxDB.
• Organization name - Enter the organization name associated with the InfluxDB instance.
• SSL - Enable SSL if you want your connection to be secure. If SSL is enabled, just upload the Certificate Authority (CA) certificate file and SSL key as well as SSL certificate if necessary.
• CA Certificate - Upload the Certificate Authority (CA) certificate if the server's certificate is self-signed or issued by a CA that is not widely recognized.
• Client Certificate & Client Key - Upload these files if the server requires mutual authentication, allowing both the client and server to verify each other's identity.

After filling in all the required fields, click the 'Edit' button to establish a connection to InfluxDB.

9. Amazon Kinesis Configurations

To configure Amazon Kinesis, follow the below instructions:

• AWS stream name - Provide the name of the Kinesis stream where data will be sent.
• AWS Region - Enter the AWS region where your Kinesis stream is located.
• AWS Access Key - Provide the AWS access key for authenticating to the AWS services.
• AWS Secret Key - Specify the AWS secret key for authenticating to the AWS services.

Once you have completed all the required fields, click the 'Edit' button to connect to AWS Kinesis.