Pairing mechanism in 2Smart Cloud
For the full performance of the IoT device, it is necessary to ensure its Internet connection and set up a connection with the platform's MQTT broker. The standard method used in the IoT industry is the pairing mechanism. This procedure is started when the device is first connected or when the Internet connection parameters are changed (for example, connecting to another Wi-Fi network or changing the password of an existing one).
A mobile application is most often used to transmit the necessary parameters to the device. Still, other methods are also possible — for example, manual configuration using the built-in web interface.
Pairing in 2Smart Cloud
2Smart Cloud devices can use three communication types:
- Wi-Fi – Internet connection via local networks;
- No Wi-Fi – alternative connections: GSM, Ethernet, etc.;
- Others – Internet connection via hubs (Zigbee, LoRaWAN protocols, etc.) and virtual devices hosted on a server with Internet access.
The following describes the pairing procedure for devices connected to the Internet using Wi-Fi. For No Wi-Fi and Other devices, the pairing is simpler and shorter:
- for No Wi-Fi devices, the step with the transfer of Wi-Fi network credentials is irrelevant;
- for Other devices, data transfer is not performed; the end-user should be offered instructions on connecting the device.
Pairing via admin panel
Technically, the simplest way to pair a device with a platform and a mobile application is to use the built-in admin panel. The admin panel web interface is one of the standard features for any 2Smart Cloud device created using the platform SDK.
How is the pairing initiated via the admin panel:
1 - When the device is first turned on, it launches a Wi-Fi hotspot.
2 - When connecting to this hotspot from any device, the consumer uses the browser to access the admin panel.
3 - The user fills in the appropriate fields in the admin panel with the data required to pair the device:
- Wi-Fi network credentials;
- the vendor's email and token for connecting to the MQTT broker (the parameters are available in the mobile application or vendor panel).
4 - After saving the data, the device is connected to the platform and is available for user control.
All or part of the parameters can be pre-specified in the device firmware. The device will start immediately after switching on, or the user will only need to transfer his Wi-Fi credentials.
The disadvantage of this pairing method is an inconvenience for the end-user. This method appears outdated, and for consumer devices, pairing via mobile application is the preferable method.
Pairing via mobile app
Pairing via the 2Smart Cloud mobile app is performed using the step-by-step assistant interface. It includes several simple steps that the user needs to go through to connect the device to the platform. The 2Smart Cloud vendors can configure this wizard relatively flexibly for each product.
The step-by-step assistant consists of five steps:
1 - A product card in the catalog includes a photo and a description of the device. This information is specified by the vendor when creating the product.
2 - Instructions for the user to connect the device. The vendor can offer their instructions instead of the default one, while hyperlinks and simple text formatting are supported.
3 - Entering parameters for connecting to a local network (Wi-Fi SSID and password).
4 - Connecting to the Wi-Fi hotspot started by the device.
5 - Transferring to the device the parameters to access the Internet and connect to the MQTT broker. Waiting for device connection.
Pairing device implementation and firmware requirements
For the end-user to use pairing via a mobile application, a local web server must be set up on the device. With it, the device receives from the mobile application all parameters required for pairing.
The local web server must also respond to connection status verification requests from the mobile application.
Example of a request sent by a mobile application to verify connectivity:
curl http://192.168.4.1/healthcheck
The device should return the following status in response to the HTTP request:
200 OK
Example of a request sent by a mobile application to the device server with connection parameters (for a device using Wi-Fi):
curl http://192.168.4.1/pair?psk=123&ssid=test&wsp=test@test.com&token=qwerty&host=cloud.2smart.com&brport=1883
The device should return the following status in response to the HTTP request:
200 OK
Example of a request sent by a mobile application to the device server with connection parameters (for No Wi-Fi device):
http://192.168.4.1/pair?wsp=test@test.com&token=qwerty&host=cloud.2smart.com&brport=1883
The device should return the following status in response to the HTTP request:
200 OK
After successfully receiving the necessary parameters, the device should automatically connect to the MQTT broker. Only after that a message appears in the step-by-step assistant of the mobile application about the successful completion of pairing.
Description of the device requirements for pairing in the 2Smart Cloud GitHub: https://github.com/2SmartCloud/2smart-cloud-docs/blob/master/Device_pairing.md