Tutorial: Configuration

MQTT Gateway (beta) Configuration

This web page is about the configuration tool for Webcom MQTT Gateway. It is strongly recommended to read this page before using this tool.

Table of contents:

Where is the configuration tool ?

For now, you can access this configuration tool through the "labs zone" tab on Webcom management page.

tabs

Once logged in, choose your favorite Webcom application, also known as "namespace", click on the "manage" button, then on "labs zone" tab. On the page, you should see something like this:

empty main form

In chapters below, we will show how to write Webcom MQTT Gateway settings for an application called "mqtt-demo".

Notice: Appearance of different forms may change in the future, or look a little different on your browser.

The main form

What you see above is called the "main form" and allows you to:

  • handle Subscribe to MQTT -> Put/Push to Datasync configurations,
  • handle Listen to Datasync -> Publish to MQTT configurations,
  • display running configurations,
  • search for running configurations,
  • access this documentation :-)

At the top of the form, click on little "doc" icon to access the top page of this documentation.

Authentication key

Below, you have to provide an "Authentication key" shared by all Webcom MQTT Gateway settings for this Webcom application. For now, this key is one of the secrets keys of your Webcom application, that should be replaced in the future by some more secured type of key...

So, back to the top of the page, choose the "authentication" tab and create there a secret key (we strongly recommend not to use the default one, as it is easier to create/revoke your own ones) through the "add a secret" button at the bottom of the page. Click on "show" button and copy the key.

Back to our main form, paste the key in "Authentication key" input text box and reload the page. Oops, the key disappeared ! This is because we forgot to hit the "Save" button. So, paste the key again, click on "Save" button and reload the page.

Congratulations, you just successfully started to configure Webcom MQTT Gateway for your Webcom application.

Save and Reload

At the right top of the main form, you can find both "Save" and "Reload" buttons.

You can change anything you want in any settings, including the shared "Authentication key", but as long as you do not click on "Save" button, nothing happens. So, we strongly recommend to hit that button as soon as you change something, somewhere in some settings.

You have to know that, as soon as you hit that button, the entire set of configurations is parsed by Webcom MQTT Gateway. Any configuration, presenting even a tiny change in its settings, is stopped and start again. So, if you wait to change lots of things in many configurations before hitting the "Save" button, this process may take a while...

The "Reload" button is used as a roll back, as long as you have not hit the "Save" button !

Say that you have changed some settings and you want to start from fresh again. You can go back to the previous state of your configurations by hitting that button. Actually, when you click on the "Reload" button, Webcom MQTT Gateway is requested for your settings, exactly as it is when the main form is first loaded.

You can even use that button, after hitting the "Save" button, just to be sure what you just saved was really stored to the Webcom MQTT Gateway.

Configurations

Below the "Authentication key" input text, you can find "Subscribe to MQTT -> Put/Push to Datasync" and "Listen to Datasync -> Publish to MQTT" links, each of which purpose is to navigate through configurations in order to change them (or not)

The third link, "Running MQTT configurations (read only)", is bound to configurations that are actually running. It allows to read them, and may be used along with the "Search for running MQTT configurations sub form" that will be described in a specific chapter below.

Handling configurations

Let us create our first configuration, say a Subscribe to MQTT -> Put/Push to Datasync one. On the main form, click on "Subscribe to MQTT -> Put/Push to Datasync" link, the main form turns to the following:

main form - new configuration

Then, click on the "New..." link and you should see the following form:

empty main configuration form

General settings

A new form pops up in front of the main form, which is now unreachable, until you close this form. Closing such a form can be done either with the little cross in its top right or simply by clicking outside of it.

Let us call this new form the "main configuration form".

The main form, however, has changed. Below the "Subscribe to MQTT -> Put/Push to Datasync" link, you can see that there is some kind of a new line, just above the "New..." link. It contains nothing for now, but let us type a "Title" and a little "Description" in corresponding input text boxes.

main configuration form with title and description

As you can see, title and description appear now on this new line. Actually, this new line is a link representing your new configuration. Clicking on it, when main form is reachable again, pops up the main configuration form again. Give it a try...

Additionally, you may have noticed that the title also appear on top left of the main configuration form.

There is also an "Available" check box, but we cannot check it yet, as some mandatory settings are not set.

On top right, you can find a "Remove" button. Let us try it:

delete confirmation pop up

Yet another pop up, asking you if you really want to remove this configuration. Let us keep our settings for now, so just hit the "No, cancel" button.

MQTT broker settings

In the main configuration form, now click on the "MQTT Config" button, a new form pops up again, that we could call the "MQTT broker form":

empty MQTT broker configuration form

As you can see, our three MANDATORY settings (see "MQTT broker settings" on Overview page) are highlighted in red. Let us populate these three settings and see what happen:

MQTT broker configuration form with mandatory parameters populated

As soon as the last input text box losts the focus, another pop up appears:

Not started warning pop up

Just close this pop up and go back to the main configuration form (click outside of the MQTT broker form or click on its upper right little cross) and check that the "Available" check box is now ready for checking. Let us click on it:

main configuration form with available check box

Now, if you go back to the MQTT broker form, remove one of the three mandatory settings and come back to the main configuration form, you should see that "Available" check box is no more checked and no more reachable again. Give it a try...

Let us complete the MQTT broker form:

complete MQTT broker configuration form

For this MQTT broker, please use the following as the "SSL Certificate":

-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow
PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD
Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O
rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq
OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b
xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw
7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD
aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG
SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69
ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr
AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz
R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5
JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo
Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
-----END CERTIFICATE-----

Webcom settings

Go back to the main configuration form and click on the "Datasync Config" button to access what we are going to call the "Datasync form":

empty Datasync form

Let us populate it according to our example #2 from the Overview page

complete Datasync form

Go back now to the main configuration form and be sure the "Available" check box is actually checked.

Save the new configuration

Back to the main form, hit the "Save" button. The main form now turns to:

main form - saved configuration

As you can see, there is now one running configuration, and if you click on the "Running MQTT configurations (read only)" link, you can navigate through main configuration form, MQTT broker form and Datasync form exactly as explained before, but without the ability to change anything. This is just a read-only way of navigating through your running configurations...

Create another configuration

From the main form, let us use the "Listen to Datasync -> Publish to MQTT" link to create another configuration. The only change is in the Datasync form that we could populate according to our example #1 from the Overview page

complete Datasync form

Let us use the following as MQTT broker settings (SSL Certificate is the same as in previous example)

complete MQTT broker configuration form

Do not forget to hit the "Save" button on the main form.

Running configurations

Let us click on the "Running MQTT configurations (read only)" link, both of our previously configurations appear:

main form showing running configurations

Notice that it is not only a matter of checking if configurations are properly set for running. Webcom MQTT Gateway is requested to check all configurations that are really running. Keep in mind however, that a running configuration may malfunction, in which case Webcom MQTT Gateway will start it again and again until there is no more failure. So, if you do not obtain results you are waiting for, you may check and possibly update your configurations...

Searching for running configurations

Now, let us imagine that we have dozens of configurations for our Webcom application, and that we only want to check the one with topic containing "myTopic". We can use the "searching form" at the bottom of the main form, and as soon as we hit the "Search" button we obtain the following:

main form showing "myTopic" running configurations

Now, say that we only seek for "Subscribe to MQTT -> Put/Push to Datasync" category of configurations:

main form showing "Subscribe to MQTT -> Put/Push to Datasync" running configurations

Notice that the "Path listened" input text box disappeared as it is useless for Subscribe to MQTT -> Put/Push to Datasync configurations. Its use is the same as "Topic" input text box, meaning that you do not need to type a strictly matching listen path or topic, but only a part of it.

Notice also that criteria use an AND operand, so that if you use all of them, you seek for configurations corresponding to "topic contains a certain string" AND "category is a certain category" AND (if available) "listen path contains a certain string".

From now on, the best way to understand that is giving it some try...