IoT Platform:Establish MQTT over WebSocket connections

Procedure

1. Prepare a certificate.

   WebSocket supports two protocols: ws (unencrypted) and wss (TLS-encrypted). For wss connections, use the same root certificate as for direct TLS connections.

2. Select a client.

   You can use the ApsaraMQ for MQTT client and replace the connection URL. For other languages, choose from Open-source MQTT clients. Verify that your client supports WebSocket.

3. Connect to IoT Platform.

   The WebSocket MQTT connection URL uses a different protocol and port from a direct TCP connection. Other MQTT parameters remain the same. Set securemode=2 for wss connections and securemode=3 for ws connections.

   • Endpoint: wss://${MQTT_Endpoint} or ws://${MQTT_Endpoint}. MQTT endpoints for public and Enterprise instances are listed in View and configure instance endpoint information (Endpoint).

   • Port: 443.

   • Variable header: Keep Alive.

     The Connect message must include Keep Alive, which specifies the keepalive interval in seconds. Valid range: 30 to 1200. IoT Platform rejects connections outside this range. Set the interval to 300 seconds or more. Use a longer interval for unstable networks.

     The client must send at least one message, such as a PING request, within each keepalive interval.

     If IoT Platform receives no messages from the client within a keepalive interval, it disconnects the client. The client must then reconnect.

   • MQTT Connect message parameters:

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

     Where:

     • 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 security mode. Valid values are 2 (for the wss protocol) and 3 (for the ws protocol).

     • signmethod: the signature algorithm. Valid values: hmacmd5, hmacsha1, hmacsha256, and sha256. 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.

   Connection exampleThis example uses a device in Enterprise instance iot-06****9.

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

   Connection parameters:

   • Using ws:

     • Endpoint:

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

     • Connection parameters:

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

   • Using wss:

     • Endpoint:

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

     • Connection parameters:

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

   Use a device-side SDK to connect to IoT Platform. For custom integrations, the MQTT connection signature example provides implementation details.