Back

Setup via WPS

The process of adding a new device using the WPS is very similar to the previous example. The only difference is that all the initial setup of the connection to the SH-GW is done via the WPS. The process of WPS is as follows: Both SH-GW and New Device has to activate the WPS at the same time. After the WPS is activated, the client-side device negotiates access with the access point and after the Wi-Fi connection is set up, the rest is the same as in the ideal example.

Setup Steps

1. 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.
2. The user is prompted to activate WPS by pressing buttons on both SH-GW and newly installed end device.
3. MQTT end device then connects to the Home Wi-Fi and further utilizes mDNS (multicast DNS) to resolve address MQTT2GO.local, which equals to the address of the MQTT broker.
4. 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.
5. When the TLS communication is established the MQTT end device subscribes to the _<activation_code>/activation topic and publishes GET_CREDENTIALS request.
6. 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.
7. When the MQTT end device receives the certificate, a connection with the initialization broker is closed.
8. Further MQTT end device connects to the MQTT broker with a certificate obtained in step 6 and subscribes to <device_id>/topics. 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.
9. In the next step, the MQTT end device publishes GET_DEVICE_TOPICS request.
10. As a result, MQTT broker publishes the message to <home_id>/<gw_id>/add_device topics with device type and device id information.
11. MQTT broker then expects a message from MQTT Controller with the end device name, group, and id.
12. 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.
13. In this step, the MQTT end device subscribes to its topics, and all ongoing communication happens according to the MQTT2GO standard.

Fig. 1: Process of adding a new WPS MQTT2GO device.

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 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 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"
}

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"
}

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 (4) 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 (6) 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 (5) 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 (7) 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