Setup via Guest WiFi

The ideal process of adding new device should be considered as the right way how to go through this process. Keeping this in mind, some of the steps detailed below can be reduced using a specific technology that can provide the needed functionality (i.e., WPS). The idealprocess to add a new device is based on the following steps.

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.
In response to the request, SH-GW enables the Guest Wi-Fi and sets the password inputted as an activation code.
MQTT end device then connects to the Guest Wi-Fi and further utilizes mDNS (multicast DNS) to resolve address MQTT2GO.local, which equals to the address of the MQTT broker.
The MQTT end device then connects to the initialization MQTT broker. The MQTT end device contains a pre-loaded certificate of trustworthy CA (Certification Authority), which is used to establish TLS (Transport Layer Security) communication with the MQTT broker. The chain of trust must be on both sides. Thus, the SH-GW (MQTT broker) has to contain a certificate issued by the same CA as it is contained in the MQTT end-device. If these certificates do not match, the TLS communication cannot be established.
When the TLS communication is established the MQTT end device subscribes to the <activation_code>/activation topic and publishes GET_CREDENTIALS request.
As a response, SH-GW (MQTT broker) generates a new set of certificates that will be used for ongoing communication and publishes its CA certificate to the MQTT end device.
The MQTT end device further subscribes to <activation_code>/wifi and publishes GET_WIFI_CREDENTIALS request.
In response, the MQTT broker issues WiFi credentials (SSID, Password) for the home network.
When the MQTT end device receives the credentials, connection with the initialization broker is closed. The end device then connects to the home Wi-Fi with acquired credentials.
Further MQTT end device connects to the MQTT broker with a certificate obtained in step 6 and subscribes to <device_id>/topics.
In the next step, the MQTT end device publishes GET_DEVICE_TOPICS request. The certificate from step 6 is directly connected to the device id. Thus only the device with proper device id value can utilize this certificate. This approach brings additional security to the device configuration process.
As a result, 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 via guest WiFi.

Network Join

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. This topics and needed commands and reports 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 a unique topics for the initialization communication. They are:

<activation_code>/activation

utilized for certificate exchange,

<activation_code>/wifi

for the Wi-Fi credentials exchange.

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 Credentials

This command (2) is utilized to get a newly generated certificate for the end device. Its command value is in form of string with value GET_CREDENTIALS.

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "mqtt_credentials",
	"value": "GET_CREDENTIALS"
}

Get Wifi Credentials

Get Wifi credentials (4) which is used to obtain the Wi-Fi credentials, again the command value is GET_WIFI_CREDENTIALS string.

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "wifi",
	"value": "GET_WIFI_CREDENTIALS"
}

MQTT Reports

These reports are specifically designed for the initialization process of the network join. The again follow the general structure from MQTT Reports. The are again labeled with numbers that are corresponding to the Fig. 1.

Credentials

This report (3) 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": "device_certificate"
}

Wi-Fi Credentials

This report (5) is used to send the Wi-Fi credentials back to the end device.

{
	"type": "report",
	"report_type":"command_response",
	"timestamp": "timestamp_value",
	"report_name": "mqtt_credentials",
	"value": {
		"SSID": "wifi_ssid",
		"password": "password"
	}
}

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 (6) 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 (8) 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 (7) 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 (9) 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 Guest WiFi

Setup Steps

Network Join

Topics Structure

End device

MQTT Commands

Get Credentials

Get Wifi Credentials

MQTT Reports

Credentials

Wi-Fi Credentials

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