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.

Setup 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. In the following sections, two login procedure options are described. ### SMS login process of MQTT2GO controller The process of the SMS login 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 process.
The MQTT2GO cloud broker then sends activation code via the SMS for client verification.
User enters this code into the third party platform, which then sends it into the HTTPS: /get_platform_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, certificate, login, and password 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 <home_id>/<gw_id>/out and publishes a QUERY_GUI_DEV message to <home_id>/<gw_id>/in.
The MQTT2GO cloud broker publishes to the <home_id>/<gw_id>/out message with all available MQTT2GO entities and its language. Based on the entities, the controller subscribes to all their topics.
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).

If the adopter prefer a novelty way of the login, a QR code option is available. The necessary steps for this login procedure are described in following text.

The MQTT2GO Controller initializes the login procedure by contacting the management server and establishing WebSocket connection.
The MQTT2GO Controller sends get_qr_code over the WebSocket connection on which the Management server replies with generated QR code that contains a login token in qr_code message.
The MQTT2GO Mobile App scans the QR code on the MQTT2GO Controller and sends back to it the user’s phone number and encrypted token to the Management Server. To obtain the encrypted_token the MQTT2GO Mobile App utilizes user certificate that is tied to currently logged-in user account. The MQTT2GO Controller then resends these values together with the original token and user_id to the MQTT2GO Cloud Broker.
The MQTT2GO Cloud Broker verifies if the token is correct (decrypts it with the public key of the respective user) and the User ID is valid.
The MQTT2GO Cloud Broker sends the UserID, Certificate, Login, and Password back to the Management server, which then sends it via the WebSocket to the MQTT2GO Controller application.
The WebSocket Connection is closed, and the procedure is continuing with the configuration as in the previous example.

Process of login into MQTT2GO account with QR code

Fig. 3: Process of login into MQTT2GO account with QR code.

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. The whole user authentication process can be substituted by any similar procedure that securely exchanges the necessary information (certificate, broker IP/address, user ID, login and password). If the authentication procedure is changed to custom implementation, all involved parties HAS TO BE NOTIFIED about it.

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 (request)

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

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

get_credentials (request)

This request contains SMS activation code. Its structure is following:

{ 
  "code": "SMS activation code"
}

get_credentials (response)

This message contains User ID, Broker IP/URL, Certificate, Login, Password. Its structure is following:

{ 
  "user_id": "user id",
  "broker": "broker IP/URL",
  "certificate": "client certificate",
  "login": "user login",
  "password": "user password"
}

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",
    "home_prefix": "baseline_topic_value",
    "language": "language",
    "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.

Setup new MQTT2GO Controller

Creation of new MQTT2GO account

Setup of new MQTT2GO controller

User authentication

HTTPS API message structure

user_login (request)

get_credentials (request)

get_credentials (response)

Configuration

MQTT Commands

Get Entities

MQTT Reports

Get entities

Setup new MQTT2GO Controller

Creation of new MQTT2GO account

Setup of new MQTT2GO controller

QR code login process of MQTT2GO controller

User authentication

HTTPS API message structure

user_login (request)

get_credentials (request)

get_credentials (response)

Configuration

MQTT Commands

Get Entities

MQTT Reports

Get entities