Setup via WPS with Remote Broker

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

From the perspective of the whole communication infrastructure, one new element is required to be presented. This element is called the Discovery server and allows end devices to discover the address of the cloud MQTT broker. Further, 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. Then it publishes an activation request containing activation code and device id. These codes can be found on the newly installed device in the form number or QR code.
The 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, 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 address.
When the MQTT broker is not founded in the local network, end device contacts the Discovery server. The address of the server is pre-loaded in the device during the manufacturing process.
The end device 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 topic and publishes the GET_BROKER_DATA request.
As a response MQTT broker on the Discovery server delivers the cloud broker IP address and the new certificate obtained in step 5. The end device further closes the connection to the MQTT broker on the Discovery server.
The end device connects to the remote MQTT broker with the certificate from the previous step and subscribes to <device_id>/topics.
In the next step, the MQTT end device publishes GET_DEVICE_TOPICS request.
As a result, the MQTT broker publishes the message to <home_id>/<gw_id>/add_device topics with device type and device id information.
MQTT broker then expects a message from MQTT Controller with the end device name, group, and id.
Based on the information from the previous step, the MQTT broker generates a topic structure for the end device and publishes the topics to the <dev_id>/topics.
In this step, the MQTT end device subscribes to its topics, and all ongoing communication happens according to the MQTT2GO standard.

Proccess of adding a new MQTT2GO device

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

Network Join

In this phase, no MQTT communication took place, and the shole process consist 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.

Topics Structure

As aforementioned, network join topics are unique inside the MTT2GO standard and are solely used for the initial connection of new devices.

End device

The end device itself utilizes an activation topic for certificate exchange.

<activation_code>/activation

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

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "mqtt_credentials",
	"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": "report",
	"report_type":"command_response",
	"timestamp": "timestamp_value",
	"report_name": "mqtt_credentials",
	"value": {
		"broker_ip": "broker_ip",
		"device_certificate": "device_certificate"
	}
}

Device Configuration

The device configuration is happening over topics that are unique to each device. This way it is secured that all the configuration will be done to the correct device. The only exception is the initialization process, where the topic is universal for the whole process, but in this case it is secured via the ability of adding only one device at a time.

Topics Structure

The topics for the device configuration presented in this section are for the initial device configuration only. The device update and similar topics are presented in MQTT Objects section. Here, the topics are divided into two parts depending on which device is utilizing them.

Controlling App / SH-GW

The controlling App / SH-GW utilizes a special topic for the addition of new devices. This topic is structured as follows:

<home_id>/<gw_id>/add_device

Its main purpose is to publish information that initialize and finalize the adding process.

End Device

The end device utilizes this channel to get the list of the topics to which the devices has to be subscribed.

<dev_id>/topics

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.

Activate Device

This command (1) is utilized to start the whole process of adding a new device. The command contains the activation code and id of the newly added device.

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "activate_device",
	"value": {
		"activation_code": "activation_code",
		"device_id": "device_id"
	}
}

Get Device Topics

Get device topics command (5) is used to get device topics from the SH-GW. This command has value of GET_DEVICE_TOPICS.

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "topics",
	"value": "GET_DEVICE_TOPICS"
}

Rename Device

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

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "rename_device",
	"value": {
		"device_id": "device_id",
		"device_name": "device_name",
		"group_id": "group_id"
	}
}

MQTT Reports

The MQTT reports presented here are designed as a “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.

Rename Device

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

{
	"type": "report",
	"report_type":"command_response",
	"timestamp": "timestamp_value",
	"report_name": "rename_device",
	"value": {
		"device_type": "device_type",
		"device_id": "device_id"
	}
}

Device Topics

This report (8) is used to deliver the requested topics, in which the new device is intended to subscribe.

{
	"type": "report",
	"report_type":"command_response",
	"timestamp": "timestamp_value",
	"report_name": "topics",
	"value": ["topic_1", "topic_2", "topic_3"]
}

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

Topics Structure

End device

MQTT Commands

Get Remote Broker Data

MQTT Reports

Remote Broker Data

Device Configuration

Topics Structure

Controlling App / SH-GW

End Device

MQTT Commands

Activate Device

Get Device Topics

Rename Device

MQTT Reports

Rename Device

Device Topics