IoT Platform:Establish MQTT over WebSocket connections

Procedure

1. Prepare a certificate.

   You can use WebSocket for unencrypted connections or WebSocket Secure for encrypted connections. Transport Layer Security (TLS) is used to encrypt WebSocket Secure connections. A WebSocket Secure connection requires a root certificate, which is also required for a TLS connection.

2. Develop a client.

   IoT Platform provides MQTT SDK for Java. You can use the SDK to develop your client, but you need to replace the URL in the SDK with a URL that is used by WebSocket. For information about how to obtain MQTT SDKs for other programming languages or how to use custom MQTT SDKs, see libraries. Before you use MQTT SDKs, read the instructions and check whether WebSocket is supported.

3. Establish a connection to IoT Platform.

   Compared with an MQTT over TCP connection, an MQTT over WebSocket connection has a different protocol and port number in the URL. An MQTT over WebSocket connection has the same parameters as an MQTT over TCP connection except for the securemode parameter. If you use WebSocket Secure, set this parameter to 2. If you use WebSocket, set this parameter to 3.

   • Endpoint format: wss://${MQTT endpoint} or ws://${MQTT endpoint}. For information about the MQTT endpoints of public instances and Enterprise Edition instances, see View the endpoint of an instance.
   • Port number: 443.
   • Variable header: Keep Alive.

     You must include the Keep Alive parameter in the CONNECT message. Valid values of the keep-alive period: 30 to 1,200. Unit: seconds. If the value of the Keep Alive parameter is not within this range, IoT Platform rejects the connection. We recommend that you specify a value that is greater than 300 seconds. If the network connection is unstable, we recommend that you set the keep-alive period to a large value.

     In a keep-alive period, the device must send at least one message. The message can be a ping request.

     If IoT Platform does not receive messages within the keep-alive period, the device is disconnected from IoT Platform. You must reconnect the device to the server.

   • An MQTT Connect message contains the following parameters:

     mqttClientId: clientId+"|securemode=3,signmethod=hmacsha1,timestamp=132323232|"
     mqttUsername: deviceName+"&"+productKey
     mqttPassword: sign_hmac(deviceSecret,content)

     The description of the parameters is as follows:

     • mqttClientId: Extended parameters are placed between vertical bars (| |).
     • clientId: the ID of the client. You can specify a client ID based on your business requirements. The client ID cannot exceed 64 characters in length. We recommend that you use the MAC address or serial number (SN) of the device as the client ID.
     • securemode: the secure mode. Valid values: 2 (WebSocket Secure) and 3 (WebSocket).
     • signmethod: the signature algorithm. Valid values: hmacmd5, hmacsha1, and hmacsha256. Default value: hmacmd5.
     • timestamp: the current time, in milliseconds. This parameter is optional.
     • mqttPassword: the password. Calculation method: Sort the parameters that are submitted to the server in alphabetical order and encrypt the parameters based on the specified signature algorithm. For more information about the signature calculation example, see Examples of creating signatures for MQTT connections.
     • content: a concatenated string consisting of the parameters that are submitted to the server. These parameters include productKey, deviceName, timestamp, and clientId. The parameters are sorted in alphabetical order and concatenated without delimiters.
       Important productKey and deviceName are required. timestamp and clientId are optional. If you configure the timestamp or clientId parameter, the parameter value must be the same as the value that is specified for the mqttClientId parameter.

   In this example, a device under the Enterprise Edition instance whose ID is iot-06****9 is used. You must specify the following parameters before you can establish the connection.

   clientId = 12345, deviceName = device, productKey = pk, timestamp = 789, signmethod=hmacsha1, deviceSecret=secret

   Specify the following connection parameters.

   • To establish a WebSocket connection:
     • Endpoint:

       ws://iot-06****9.mqtt.iothub.aliyuncs.com:443

     • Connection parameters:

       mqttclientId=12345|securemode=3,signmethod=hmacsha1,timestamp=789|
       mqttUsername=device&pk
       mqttPasswrod=hmacsha1("secret","clientId12345deviceNamedeviceproductKeypktimestamp789").toHexString(); 

   • To establish a WebSocket Secure connection:
     • Endpoint:

       wss://iot-06****9.mqtt.iothub.aliyuncs.com:443

     • Connection parameters:

       mqttclientId=12345|securemode=2,signmethod=hmacsha1,timestamp=789|
       mqttUsername=device&pk
       mqttPasswrod=hmacsha1("secret","clientId12345deviceNamedeviceproductKeypktimestamp789").toHexString();

   We recommend that you use Link SDK to connect devices to IoT Platform. For information about how to develop a custom device SDK for connection, see Examples of creating signatures for MQTT connections.