IoT MQTT Panel User Guide

The purpose of this article is to provide detailed user guide of IoT MQTT Panel or IoT Controller application. MQTT is very lightweight protocol primarily designed for communication with constrained devices with low-bandwidth using publish subscribe pattern. This application provides better visualization and control of IoT application based on MQTT protocol.

You can download the app from google play store.

Pro version: IoT MQTT Panel Pro

Free version: IoT MQTT Panel

Please note that this article assumes that you have good understanding about MQTT protocol and its basic components e.g broker, client, message / payload, topic, QoS etc. You can find more information about MQTT at: http://mqtt.org/

For simplicity, all messages subscribed or published are string type.

How all devices are organized?

When we make a Smart Home ideally, we generally use multiple devices. Each device contains multiple sensors and transducers which have their own topic and messages. IoT Controller application is not only designed to visualize the various IoT states but also organize these connections, devices, messages etc. Before we start we need to familiar about the building blocks of this application. The below figure represents basic architecture of a Smart Home application.

IoT MQTT Panel User Guide

Connections: The IoT Controller app can manage multiple connections. Each connection can be connected to a configured broker. For an instance, you have a local broker hosted in Raspberry Pi and another one in a public broker in internet. When you are outside of home public broker is used to and inside home you use local broker for faster response. To manage this two connection efficiently you should create two connections with appropriate configuration.

Devices: Every connection contains multiple devices. This provides visual separation when you are using multiple IoT devices. For example, you have a Raspberry Pi in your drawing room and a ESP 8266 in kitchen. For this you should add two separate devices under a connection.

Panel: In most cases, you connect multiple sensor and transducers to an IoT device. Suppose you have a temperature sensor connected to Raspberry Pi in drawing room. Additionally, the Raspberry Pi is connected to light switch and fan speed controller. So, you should create a Log (for monitoring temperature), a Switch (to turn on or off light) and a Slider (to control fan speed manually) panel under the Raspberry Pi device.

The following section will guide you to create, select, edit and delete these connections, devices and panels. This application contains number of advanced features. But remember that all these features do not supported by every broker and you might not get expected behavior. So please verify the features if it supported by the broker before using it.

Creating a new connection: To create a connection press add button on connection page. This will bring you to Add Connection Form.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Connection Name: This is for friendly connection name. You can give any name of your choice to identify the connection uniquely.

Client ID: Most of the MQTT broker identify client by unique client id. If your broker provides client id you can mention it here. Or else you can leave it blank. The application will create a random string as client id.

Broker Web/IP address: You can use any private, public and locally hosted broker. If you have domain name of the broker you can use it. Alternatively, you can also use IP address (e.g. 192.168.1.5) of the broker.

Port number and Network protocol: Usually MQTT works on TCP or Websocket network protocol. The standard ports are 1883 for TCP and 8080 for Websocket. But some broker uses different ports. You should use the port accordingly. In some network the 1883 port is blocked by firewall. Websocket can be used inside this network as these ports are generally kept open. Before use Websocket make sure your broker supports it.

Device list: You can add one or more devices under each connection. While creating connection you need to add at least one device. You always can edit this device or add more at latter point of time.

IoT MQTT Panel User Guide

Device name: Friendly name for the device. This name must be unique, though you can use same name for the device under different connection.

Set as connection home: This option will make the device as home device of the connection, i.e. this device will be open by default when you select a connection.

Advanced options: This will allow you to add advanced option of the MQTT connection like Connection timeout, Keep alive, Username, Password etc.

IoT MQTT Panel User Guide

Connection timeout: The application will stop trying to connect the broker after the mentioned seconds. If you leave it blank it will be set to default 30 sec.

Keep alive: The connection will be closed automatically after the mentioned second if no message is transferred. If you leave it blank it will be set to default 60 sec.

Username and Password: If broker provided the username and password you need to mention it here. Remember all communications will take place over http connection. There is no secure connection is available for now. However, the application doesn’t share username and password to anyone including the app developer. It will be stored in locally and it will be send to broker each time of connection initiated.

Will message: Will message get automatically published by the broker if the connection between the app and broker unexpectedly get terminated.

IoT MQTT Panel User Guide

Topic: Topic for will message.

Payload: Payload for will message.

Retain: If checked, the last message will be retained by the broker.

QoS: Select the will message QoS. If not selected it will be set to 0 by default.

Connect automatically: If this option is checked, the app will automatically try to establish a connection to the broker when you select a connection. You need not to press connect button at the top (Refer device page). However, you need to connect manually if the connection breaks.

Editing a connection: You can edit any connection from connection page. First press option icon and then press edit icon. The options are similar to add connection.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Delete a connection: You can also delete any connection you want. Remember all configurations, devices and panels under this connection will be lost.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Device page explained: This is the page where you will spend most of the time. Select any connection and the app will navigate to device page.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Device Menu: To open device menu press menu button at the top left corner.

Switch Connection: On selecting this option you will be navigated to connections page and you can change current connection.

Device Settings: This will allow you to change advanced configuration of the current device. These configurations are like Adding Device configuration and we will discuss in detail there.

Device List: Bellow the Device Settings option you will find the device list of the current connection. You can select any device from this list.

Add a New Device: Add Device option will allow you to add a device under currently selected connection. Note that you can also add device from Add / Edit connection page. But here you will get privilege to add more advanced options. We will talk about this in detail in Add a Device section.

Connect / Disconnect: You can establish or stop connection by pressing connect / disconnect button available at top right corner. The icon and color of this button indicates the application state.

1. Disconnected: The application will try to establish a connection with broker on pressing this button. The following figure represents the disconnected status.

IoT MQTT Panel User Guide

2. Connecting: The application goes connecting state when it initiated connection but not completed yet.

IoT MQTT Panel User Guide

3. Connected: This state represents that the application is successfully connected with broker. You are ready to publish or subscribe any message. You can terminate this connection on pressing this button.

IoT MQTT Panel User Guide

Remote Status: This feature allows you to watch the status of IoT device, e.g. you can see if your ESP 8266 IoT module is connected with the broker or not. Remember this feature does not work out of the box. You must publish the status from the IoT device explicitly. The Remote Status feature is turned off by default. To turn it on you need to enable device status from device settings page and configure corresponding status topic and messages. This configuration has a sync topic and associated three status messages as described bellow.

1. Payload Online: The IoT device should publish this message when it establishes the connection with broker successfully. Whenever the mobile app receives this message it indicates the online status.

IoT MQTT Panel User Guide

2. Payload Offline: Before getting disconnected from broker the IoT device should publish payload offline. You also can add the same payload to the IoT device will message. This will allow broker automatically publish payload offline message if the IoT device lose internet connection or connection brakes unexpectedly. Upon receiving this message, the mobile app will indicate offline status.

IoT MQTT Panel User Guide

3. Sync Request: Some time you might need to ask IoT device to send its status manually. You can send the sync request by pressing the Payload Online / Payload Offline icon. The mobile app will publish sync request message and the IoT device must publish its status as response. Remember your mobile app will not wait for response. It only changes state when it receives either online or offline message.

Panels: All panels are listed in the device page. You can add any number of Panels under a device.

IoT MQTT Panel User Guide

Add Panel: You can add a panel by pressing add button at the bottom of the page. The available panels will be listed on the page. By selecting any specific type panel, it will navigate you to the respective add panel page.

IoT MQTT Panel User Guide

Panel Options: Every panel is associated with its menu which allows you edit, delete and move the panel.

IoT MQTT Panel User Guide

Delete Panel: On pressing delete icon of the options, the panel will be removed from the list.

Edit Panel: Edit panel will allow you to change the panel properties. We will discuss about it in detail in Add / Edit panel.

Move Up / Down: By pressing up or down arrow you can rearrange panel position.

Adding a new device: There are two places where you can add a new device. The first one is from add or edit connection page. This will allow you to add only mandatory configurations e.g. device name and default device. The second place where you can add a new device is device menu. Here you will get more advanced options to configure the device.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Device name: Friendly name for the device. This name must be unique, though you can use same name for the device of other connections.

Set as connection home: This option will make the device as home device of the connection, i.e. this device will be open by default when you select a connection.

Device prefix topic: When you add device prefix topic it automatically prepended to the topic of all panels under the same device. For example, you have a device ESP 8266 where device prefix topic is ‘/esp8266’.  This device has Button panel where configured topic is ‘/btnTopic. Now the effective topic of the Button panel will be ‘/esp8266/btnTopic’. This is helpful for many scenario.

1. If you have multiple devices with similar panels, there is a chance of topic collision if you are not careful enough. The device prefix topic gives hierarchical view of the topics.

2. If you use public broker with generic topic it might get conflict with another user’s topic. And adding topic prefix to every panel manually is very annoying. For this kind of situation, you can use your unique device prefix topic. For the above example, you can use device prefix topic as ‘someUniqueStirng/esp8266’ and effective topic for the button will be ‘someUniqueStirng/esp8266/ btnTopic’ which have very less chance of topic collision.

Enable device status: This allows you to watch IoT device status. We have already discussed about it in the ‘Remote Status’ section. Once you enable this you can configure sync topic and messages for the remote status.

IoT MQTT Panel User Guide

Sync topic: This is topic for all remote status messages.

Payload sync request: This is the payload for asking IoT device status explicitly and this will be published when you press Remote Status icon.

Payload online: On receiving this message, the mobile app will indicate Remote device as online state.

Payload offline: On receiving this message, the mobile app will indicate Remote device as offline state.

Auto sync on connect: If you enable this, the app will publish Payload sync request once for every time the app successfully connects to broker.

QoS: QoS for Remote status messages.

Editing a device: You can edit currently selected device by selecting Device Settings from device menu. All options are similar like adding a device

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Deleting a device: You can delete a device from connection edit page. Remember you cannot delete the device which is assigned as connection home. You must assign another connection as home first. Then you can delete the previous one. Finally, press save button to update the device list.

IoT MQTT Panel User Guide

Adding a new panel: When you add a device, it does not contain any panel. You can add panel by pressing add button at the device page. The app has different panels for different purpose and you can add them as many time you want.

IoT MQTT Panel User Guide

Most of the devices has some common configuration along with some panel specific configuration. All this fields are self-explanatory. Here we are going to discuss common configurations.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Panel name: This is friendly name for the panel. It must be unique within the same device.

Topic: This is the topic used for subscribing or publishing the message for the panel. Remember that device prefix will be prepended automatically if you have configured it in device settings.

Retain: You can enable or disable the retain flag for the panel.

Qos: QoS for the panel. If you do not specify, it will be assigned to QoS 0 by default.

Edit a panel: To edit a panel first press option menu available on right side of the panel and then press edit icon. The fields options are same as add panel.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Delete a panel: Like edit panel you can delete a panel from panel options.

Panels Explained: In this application, you have flexibility to choose panel from several customizable panels according to your need.  This panel list will grow in future depending on user’s feedback.

Button Panel: This simple panel allows you to publish preconfigured message on pressing of the button. You can add more than one button to each panel with same topic but different payload.

IoT MQTT Panel User Guide

Switch Panel: You can use Switch panel for turning on or off any appliance. The mobile app also subscribes switch topic automatically. So, if you use another source (e.g. another mobile) to control the same appliance this switch state also get updated. You can add multiple switches to single panel as a group. Each switch must have their own topic.

IoT MQTT Panel User Guide

Slider Panel: To send analog value you can use Slider panel. Remember that the type of published value is String not Number. For example, if your slider’s min and max value is configured as 0 and 100, and you move slider to the middle, the value “50” will be published as string. This panel also subscribe its topic and it will be updated on receiving value from different source like switch panel.

IoT MQTT Panel User Guide

Color Picker Panel: Color picker will help you to send color code with different format (i.e. HEX, RGB and HSL). Press the preview icon on left side of the input to choose color using different palettes. You must press send button on right side of the input to publish the selected color. This panel subscribes its topic and preview icon color will change on receiving valid color code. You can use this panel to control color of RGB LED strip.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Time Picker Panel: This panel allow you to publish time with ease. You can send current time by pressing current time button or custom time by selecting from time picker. This panel always publish time with HH:MM:SS format.

IoT MQTT Panel User Guide

IoT MQTT Panel User Guide

Text Panel: This panel allow you to publish any custom message with preconfigure topic.

IoT MQTT Panel User Guide

Log Panel: Log panel will display received message for the configured topic. You can  enable or disable the received message timestamp and set max number of visible messages. This panel is useful to debug your application.

IoT MQTT Panel User Guide

 

I hope this tutorial is helpful. If you have any specific question please leave a comment. In case you find any bug or want a new feature please mention. Also please don’t forget to put positive feedback at play store.

 

Posted in IoT

2 thoughts on “IoT MQTT Panel User Guide

  1. Very Nice, looks promosing.
    What i’m missing is the possibility to export/import the settings to for example an other phone.
    Wife and son have also phone and i don’t like to enter everything 3 Times.

    1. Thank you Evert for your suggestion.

      Actually I am building this feature and it will be available very soon. The application is completely build on user’s settings which resides only on device memory. The exported file will be a human readable json file. If user modify it with invalid settings / syntax it might cause crash of the application in his mobile. So currently I am implementing proper validation before the settings can be imported.

Leave a Reply

Your email address will not be published. Required fields are marked *