Creating your first MyQttHub dashboards (panels) -- Walkthrough I

[francis.brosnan]

1. Introduction

The following article explains how to you can create integrated web panels that will help you show collected data by your MQTT devices connected to your HUB at MyQttHub.com (complete language reference here: MyQttHub dashboard markup language reference).

These panels are designed to provide a ready to use solution that integrates data with clean and attractive panels that are usable for end users to show relevant data and manipulate their environment through the panel.

This walthrough will create a very simple panel that shows latest temperature registered on a particular topic. Throughout the example, you will see:

1. How to create MyQttHub.com dashboards (panels)
2. What’s the language used, and how it integrates with your HUB.
3. What are the options to upgrade and modify your panel, how preview works, inline configuration or “go to code” option.

Once you finish this walkthrough, you will be able to expand your knowledge with the rest of options as they use similar mechanism (extending on what you already saw).

2. What we are going to create

We are going to create a panel using reference implementation from:

https://github.com/ASPLes/MyQttHub/blob/master/panels/reference/temperature.data.reference1.xml

That panel looks like:

You can use this as a template to show other data, change colors, icons, messages, etc.

3. Let’s start with your first MyQttHub Dashboard!

1. First, get into your MyQttHub account (with admin user), and click on Panels:

   

   …now click on menu option: Panels:

   

2. You will see the list of panels you already have created. Empty list if you don’t (right!). Now click to add a new panel:

   

3. Now, enter an initial description for your panel. You can change it later, don’t worry:

   

4. That will give you access to full panel workbench where you have different options you will be using while you create your panels. Here is an initial brief description:

   

5. Now, go to the Source tab and place the content found at the link:

   • https://github.com/ASPLes/MyQttHub/blob/master/panels/reference/temperature.data.reference1.xml

   …you should see something like:

   

6. After that, you have a full working panel! Now see results by clicking on preview. You will see the whole thing moving:

   

   IMPORTANT NOTE: regularly save your panel code to avoid losing anything (click on Update panel).

   

4. Using topic attribute to extract and show data (key feature)

1. Because your HUB has no data available yet for topics used by this panel, you will see it is not showing anything that is useful.

2. This happens because panel source code is doing reference to some topics (topic=“some/topic”) but those topics have no registered data. If you go to “Source tab”, you will see several elements doing topic use declaration like these:

   

3. With this element identified, you need to update your HUB to have some data to show. You have several options:

   • Real MQTT device: Make some real MQTT device to publish information to those topics. Once in production, this will be the main form of topic updates.
   • Use a developer MQTT device: like MQTT-Spy, so you can use it to publish topic information to these topics.
   • MyQttHub dashboard inline update: but because we are prototyping, MyQttHub dashboards allows you to simulate this by sending updates (real MQTT PUBLISH messages) directly from the panel. Here is how.

4. Go to the Preview tab and right click on temperature message:

   

5. A publish to topic panel will show up. Enter a temperature and publish:

   

6. Right after that, your preview will automatically update, and this time, showing latest updated value:

   

7. Do the same for the battery and umbrella icon: move mouse over it, and right click over it to Publish to topic. After that, you should see something like:

   

5. Using topics used tab to update topic values

1. Remember you can update topics latest state on the “Topics used tab”, by double click on the value or on the icon:

   

2. After that, the publish to topic window will show up so you can push new values there:

   

3. Now click on “Preview tab” to show latest value:

   

6. Configuring elements with configuration wizard as complement to code

The following is a feature you will be able to use at “Source tab” and “Preview tab”. It allows you to easily configure several aspects for elements you are using at your panels.

1. To use it from “Preview tab”, just right click on any element that glows when you move mouse over like:

   

2. A new configuration dialog will show:

   

3. Change color (or any other setting) and then click on “Accept and preview changes”:

   

4. After applying changes, you will see them reloaded automatically:

   

5. Remember to “Save panel” if you are fine with current status:

   

7. Remember you have a source code editor (reference manual)

MyQttHub dashboard panels are designed in a way that should be easy to start with all dialogs and configuration windows you have already seen. At the same time, MyQttHub dashboard panels uses a very common and widely understood language: XML (without any extension).

This will allow you to configure all the details that needs your panel and that might not be covered by configuration windows and wizards.

Here is a quick review about options you will find at Source tab editor:

1. Remember that all these helpers and preview code is designed to help you start quickly. But also, take into account you can make changes directly into your panel source code:

   

2. As you can see, MyQttHub dashboard language is plain XML (nothing more). Here you will find complete reference for all features, attributes and options available for direct edition:

   MyQttHub dashboard markup language reference

3. You can launch “item configuration wizard” by just moving cursor to the element you want, and then click to configure:

   

4. After that the Item configuration wizard will be shown:

   

8. You can always indent your code after making changes

1. Because you might add a lot of code that needs indentation, to keep your panel clear and easy to maintain and debug, use the “Pretty” button. It will indent all your panel code:

   

2. Remember to save your panel content after doing code indentation:

   

9. Support for quick snippets at source code editor

You can always take a look at the MyQttHub dashboard language reference to know more about elements and options available.

At the same time, you have a "Quick snippets" option that will help you add known supported elements directly from the source code editor. Here is how it works:

1. Go to the “Source tab” and position cursor at the place you want to add the element:

   

2. Now select to add a column:

   

3. As you see, right after selecting “Column”, it is added. Now move cursor inside and click to “Add element” again:

   

4. Now add a button so you can see how your panel evolves:

   

5. After that, a button with some default configuration will be added:

   

6. Click on preview and click on the button several times:

   

7. Again, remember to save your panel content after doing code indentation:

   

10. Moving your panel to production

So you are happy with your current panel configuration and you want to move it to production so it can be shown in a web browser, a monitor or a tablet like this:

1. For that, click on “Panel link” option to make your browser launch your panel link that will activate everything without having all the developer options:

   

2. Now copy that URL and make a browser to load it to show your panel at the destination device.

   

3. If you want your panel to be loaded without asking a valid userName/password from your MQTT HUB, configure your panel to make it public here:

   

11. How panels consume messages and optimize collection

Any time any of your panels are accessed, they consume message quota using the following indications:

1. Panel definition: an amount of message quota because of loading your panel definition, that is, your panel definition is considered as a message that is relayed from your MQTT HUB to your browser. In that sense, any time your panel definition is downloaded, that will be considered as a single message consuming message quota using message measurer size as defined by your MyQttHub message measurer size.

2. See how MyQttHub message measurer size works at the following article: How messages are counted by MyQttHub

3. Data used by panel: Now, for the data loaded by the panel, MyQttHub collects all the data that will be used into a single optimized call (to avoid several or hundred of calls) and creates a single message. Then, that single message consumes quota using message measurer size as defined by your MyQttHub message measurer size.