Setup new MQTT2GO Controller

The MQTT2GO controllers are vital part of any MQTT2GO-enabled installation. They are the entry points for users that want to interact with the whole MQTT2GO ecosystem. This is true for all the MQTT2GO installations no matter if there is or is not the local MQTT2GO broker. It is worth mentioning, that the controllers can be also utilized as a "sniffers" for data mining applications. From the perspective of the whole MQTT2GO communication infrastructure, the setup of the Controller brings one new element that have to be utilized. It is the Management Server, which has to be operated by the MQTT2GO adopter (service provider) and which contains all the necessary information about the MQTT brokers (ip addresses, names) and users. These users have to be created by the adopter authority as it is the only way how to maintain the security. This section defines how the creation of a new MQTT2GO account and addition of a new MQTT2GO controller is done.

Creation of new MQTT2GO account

The new MQTT2GO account creation process utilizes credentials provided by the MQTT2GO standard adopter entity. They are meant to be provided after the initial client registration process into the adopter's system (e.g., network operator's accounting system). The creation process steps are following:

The MQTT2GO App / Web Interface connects to the management server via HTTPS: /admin_login using the provided credentials (Username and Password).
The MQTT2GO App / Web Interface sends a request containing the Username, Password, Phone Number, Home ID, and GW ID to the Management server on the HTTPS: /add_user.
Management server forwards this information to the correct MQTT2GO cloud broker, which then creates the user.

Process of creating new MQTT2GO account

Fig. 1: Process of creating new MQTT2GO account.

Creation of new MQTT2GO controller

The MQTT2GO controller creation process can be initialized only if at least one MQTT2GO account creation was successful. If this requirement is satisfied, created user is able to add a new MQTT2GO controllers and users to the system. It is also worthwhile to be noted, that in theory users can use the same username for multiple logins, but to deal with this problem is not in scope of the MQTT2GO standard. The MQTT2GO creation process is again utilizing the Management Server for user authentication. The reason to utilize it together with the MQTT2GO cloud broker is mainly the security. The process itself can be described in following steps:

The MQTT2GO app tries to connect to HTTPS: /user_login using the user credentials (username and password).
If the credentials are valid, the management server forwards this request to the HTTPS: / login_user of the MQTT2GO cloud broker and initializes the login login process.
The MQTT2GO cloud broker then sends activation code via the SMS for client verification.
User enters this code into the MQTT2GO app, which then sends it into the HTTPS: /get_credentials of the management server.
The management server forwards the activation code to the HTTPS: /get_credentials of MQTT2GO cloud broker.
The MQTT2GO cloud broker then sends the certificate to the HTTPS: /post_credentials of the management server.
The management server then sends a response with user ID, broker IP, and certificate to the HTTPS: /get_credentials from which the MQTT2GO app saves it.
The MQTT2GO app connects to the MQTT2GO cloud broker using the provided certificate, user ID, login, password, and broker IP.
The MQTT2GO app subscribes to the <user_id>/topics and publishes a GET_USER_TOPICS message.
The MQTT2GO cloud broker publishes to the <user_id>/topics message with all topics the MQTT2GO app has to subscribe to.
From now on, the MQTT communication follows the MQTT2GO standard.

Process of login into MQTT2GO account

Fig. 2: Process of login into MQTT2GO account (adding new MQTT2GO controller).

This procedure is presented as the ideal implementation of the controller creation. If the user wants to utilize third party MQTT client, the green part (Authentication) that is exploited for, broker IP and certificate obtaining has to be implemented or used separately (i.e., using the web browser).

User authentication

The user authentication operation inside MQTT2GO controller creation is utilizing the HTTPS API and therefore does not follow the MQTT2GO topic naming convention. The reason for this is to simplify the access process of a service, which will be utilized only several times.

HTTPS API message structure

Even though the HTTPS API is not adhering to the topic naming convention, it still utilizes the JSON data structure of the messages. This section provides examples of all utilized messages.

user_login

This message contains information about the user credentials. Its structure is following:

{	
	"username": "username",
	"password": "pwd"
}

Configuration

This section is utilizing the standard MQTT2GO topic naming structure together with standard MQTT2GO messages. They are described in following section.

MQTT Commands

In this specific implementation, there is only one MQTT2GO command and its primary goal is to request all device topics to which the controller have to subscribe. This secures the controller to be able to control all devices, to which the selected user has access. The command structure is based on the structure from MQTT Commands. The numbering in this section is coherent with the numbering in Fig. 2.

Get Entities

<home_id>/<gw_id>/in

{
    "timestamp": "timestamp_value",
    "type": "user_entities",
    "value": "user_id"
}

MQTT Reports

The MQTT reports presented here are designed as “responses” to aforementioned commands. Their structure is also coherent with the general structure from MQTT Reports and the numbering is matching the one in Fig. 2.

Get entities

This report is utilized for requesting all necessary information from the smarthome gateway. The report contains topics and information about all devices, configured scenes and security features, as well as alerts and home layout.

<home_id>/<gw_id>/id/out

{
    "timestamp": "timestamp_value",
    "type": "command_response",
    "base_topic": "baseline_topic_value",
    "value": {
        "scenes":[
            {
                "id": "id_value",
                "name": "name_value",
                "icon": "icon_value",
                "active": "active_state_value"
            }, ...
        ],
        "alert":[
            {
                "event_name": "event_name_value",
                "message": "message_value",
                "status":"status_value",
                "timestamp": "timestamp_value"
            }, ...
        ],
        "security":[
             {
                "id":"id_value",
                "type":"type_value",
                "name":"name_value",
                "icon":"icon_value",
                "active": "active_state_value"
             }, ...
         ],
         "activities":[
         
        ],
        "rooms":[
         {
            "id":"room_id_value",
            "devices":[
               {
                  "id":"id_value",
                  "name":"name_value",
                  "type":"type_value",
                  "image":"image_location",
                  "events":{
                     "message":"message_value",
                     "timestamp":"timestamp_value"
                  }
               }
            ], ...
        }, ...
    }
}

Back

MQTT2GO Convention

An agreement on positions, definitions and specifications for the use of MQTT in harmonised form for service platforms, IoT devices, control nodes and user applications.