Setup via WPS with Remote Broker

On top of the typical Smart-Home paradigm with a SH-GW acting as a centerpiece of all communication, MQTT2GO also offers to offload this functionality to the cloud. The local network then does not contain any local MQTT broker, but the whole communication is handled in the cloud. Nevertheless, none of the features of the local broker are missing, and the transition is seamless from the perspective of the end user / end device.

From the perspective of the whole communication infrastructure, one new element is required to be present. This element is called the Discovery server and allows end devices to discover the address of the cloud MQTT broker. Furthermore, an additional communication channel between the cloud broker and the Discovery server is needed, as it will be described in the following text.

The following steps cover the optimal case with WPS functionality. When the WPS is not present, the process is more complicated and requires additional user interaction. These steps mainly consist of delivering the SSID and password of home Wi-Fi.

Setup Steps

MQTT Controller (Mobile/Web App) initiates the process of adding a new device by subscribing to /<home_id>/<gw_id>/add_device/in. Then it publishes an activation request containing activation code, device_type and device id to /<home_id>/<gw_id>/add_device/out. These codes can be found on the newly installed device in the form of two unique numbers identifying the device or as QR code.
The cloud MQTT broker then contacts the Discovery server and adds the newly installed device into the database of devices waiting for activation. The communication is conducted via REST API over HTTPS protocol. All data including cloud MQTT broker IP, activation code and newly generated certificate, login, and password are delivered to the /activate_device endpoint. The device is not stored in the database permanently, but it is removed after 15 minutes. This approach limits the time window during which the device can be activated, but also adds an additional level of security.
In the meantime, the MQTT end device connects to the home Wi-Fi via WPS and looks for the network for the MQTT2GO.local (_mqtt._tcp.local.) activation server address.
When the MQTT broker is not found in the local network, end device (ED) contacts the Discovery server. The address of the server is pre-loaded in the device during the manufacturing process.
The ED utilizes the pre-loaded certificate together with the activation code to connect to the MQTT broker on the Discovery server. As in the case of other activation procedures, the certificate of the server must be issued by the same CA (Certification Authority). Otherwise, the TLS (Transport Layer Security) communication cannot be established.
Further, the end device subscribes to the <activation_code>/activation/in topic and publishes the GET_BROKER_DATA request to the <activation_code>/activation/out topic .
As a response, MQTT broker on the Discovery server delivers the cloud broker IP, login, password, and the new certificate obtained in the step 5. The end device further closes the connection to the MQTT broker on the Discovery server.
Then the end device connects to the remote MQTT broker with the certificate and credentials from the previous step and subscribes to <dev_id>/home/in.
In the next step, the MQTT ED publishes request of the home_prefix type to <dev_id>/home/out topic that contains all entities the ED provides with additional information on its data type and unit.
The SH-GW publishes home_id and gw_id to <dev_id>/home/in.
As a result, cloud MQTT broker publishes the message to <user_id>/<gw_id>/add_device/in topic with device id information to distinguish individual devices.
MQTT broker then expects a message from MQTT Controller with the end device device_name, group, and device_id in the <user_id>/<gw_id>/add_device/out topic .
In what follows, the MQTT end device subscribes to its topic, and all ongoing communication happens according to the MQTT2GO standard.

Process of adding a new MQTT2GO device

Fig. 1: Process of adding a new MQTT2GO device with remote (cloud) broker.

Network Join

In this phase, no MQTT communication takes place, and the whole process consists of network join via the WPS process.

MQTT Broker Discovery

The operation of adding a new device into the network / household is utilizing a special topics. These topics are only temporary and utilized only for this specific use-case. This means that, aside from one, they are not a part of the standard topic structure. This simplifies the implementation at the end devices as they have no idea of the current structure of the MQTT2GO household. The topics, commands, and reports needed for discovery of remote MQTT broker are described in this section.

MQTT Commands

The MQTT commands for the network join are again based on the general structure from MQTT Commands. And the most important change is in the value of the command, which can be further divided by the function of the message (the numbering here corresponds to the one in Fig. 1).

Get Remote Broker Data

This command (3) is utilized to get the address of remote broker together with a newly generated certificate for the end device. Its command value is in form of string with value GET_BROKER_DATA.

{
	"timestamp": "timestamp_value",
	"value": "GET_BROKER_DATA"
}

MQTT Reports

These reports are specifically designed for the initialization process of remote broker discovery. Again the process follows the general structure from MQTT Reports. They are again labeled with numbers that are corresponding to the Fig. 1.

Remote Broker Data

This report (4) is utilized to deliver a newly generated certificate from MQTT broker to the end device.

{
    "type": "broker_data",
	"timestamp": "timestamp_value",
	"value": {
		"broker_ip": "broker_ip",
		"device_certificate": "device_certificate",
		"user": "mqtt_login",
		"password": "mqtt_password"
	}
}

Device Configuration

The device configuration is happening over topics that are unique to this process. To secure that the configuration will be done to the intended device, a unique device_ids is utilized during the process.

Topics Structure

The topics for the device configuration presented in this section are for the initial device configuration only.

MQTT Commands

The MQTT Commands mentioned below are used in adding a new device process. The command structure is based on the structure from MQTT Commands. Again, the numbering in this section is coherent with the numbering in Fig. 1.

Add New Device

This command (1) is utilized to start the whole process of adding a new device. The command contains the activation_code, device_id, and device_type of the newly added device.

<home_id>/<gw_id>/add_device/out

{
	"timestamp": "timestamp_value",
	"value": {
		"activation_code": "activation_code",
		"device_id": "device_id",
		"device_type": "device_type"
	}
}

Get Home Prefix

In case of Get Home Prefix (5), which is used to obtain the home prefix, that consists of home_id and gateway_id. The command value consists of array of the available topic names of the current device, together with unit name and type.

<device_id>/home/out

{
    "timestamp": "timestamp_value",
    "type": "home_prefix",
    "value": [
      {"name": "topic_name",
       "unit": "unit_quantity",
       "type": "unit_datatype"
      }, ...   
    ]
}

Rename Device

This command (8) is utilized to finalize the process of adding a new device to the system. Via this report, the end device gains its name and inclusion to the groups.

<home_id>/<gw_id>/add_device/out

{
	"timestamp": "timestamp_value",
	"value": {
		"device_id": "device_id",
		"device_name": "device_name",
		"group_id": ["group_id_1", "group_id_2", ...]
	}
}

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. 1.

Home Prefix Report

The home prefix report (6) consists of home_id and gateway_id.

<device_id>/home/in

{
    "timestamp": "timestamp_value",
    "type": "home_prefix",
    "value": {
      "home_id": "home_id_value",
       "gateway_id": "gateway_id_value"
    }
}

Rename Device Report

This report (8) is utilized to request the user of the MQTT2GO Controller app for the name and group of the newly added device.

<home_id>/<gw_id>/add_device/in

{
	"timestamp": "timestamp_value",
	"value": {
		"device_id": "device_id",
		"setup_result": "setup_result"
	}
}

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 via WPS with Remote Broker

Setup Steps

Network Join

MQTT Broker Discovery

MQTT Commands

Get Remote Broker Data

MQTT Reports

Remote Broker Data

Device Configuration

Topics Structure

MQTT Commands

Add New Device

Get Home Prefix

Rename Device

MQTT Reports

Home Prefix Report

Rename Device Report