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, device id, and device type. The activation code and device id codes can be found on the newly installed device in the form two numbers or QR code.
In response to the request, SH-GW enables the Guest Wi-Fi with SSID MQTT2GO 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 (_mqtt._tcp.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 fingerprint 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, login, and password 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 the acquired credentials.
Further MQTT end device connects to the MQTT broker with a certificate and credentials obtained in step 6 and subscribes to <dev_id>/topic.
In the next step, the MQTT end device publishes GET_DEVICE_TOPIC 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 topic with device id information to distinguish individual devices.
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 device topic to the <home_id>/<gw_id><dev_id>/topic.
In what follows, the MQTT end device subscribes to its topic, 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. They again follow the general structure from MQTT Reports, and they are labeled with numbers that correspond 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":  {
		"cert": "device_certificate",
		"user": "mqtt_login",
		"password": "mqtt_password"
	}
}

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": "wifi_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 topic name to which the devices has to be subscribed.

<dev_id>/topic

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, device_id, and device_type of the newly added device.

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

Get Device Topic

Get device topic command (6) is used to get device topic from the SH-GW. This command has value of GET_DEVICE_TOPIC.

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "topic",
	"value": "GET_DEVICE_TOPIC"
}

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

{
	"type": "command",
	"timestamp": "timestamp_value",
	"command_type": "rename_device",
	"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 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_id": "device_id",
		"setup_result": "setup_result"
	}
}

Device Topic

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

{
	"type": "report",
	"report_type":"command_response",
	"timestamp": "timestamp_value",
	"report_name": "topic",
	"value": "topic"
}

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 Topic

Rename Device

MQTT Reports

Rename Device

Device Topic