Dynamic device registration over MQTT

Dynamic registration flow

1. The device sends a CONNECT message that contains dynamic registration parameters to request a connection.

   Note

   Dynamic registration requires TLS. Direct TCP connections are not supported. IoT Platform does not verify the MQTT keepalive interval during dynamic registration, so you do not need to set it.

   • MQTT connection domain name: MQTT endpoints for public and Enterprise instances are listed in View and configure instance endpoints.

     Note

     For unique-certificate-per-product authentication without pre-registration, ${YourRegionId} is cn-shanghai.

   • Dynamic registration parameters in the CONNECT message:

     • When a device belongs to a new public instance or an Enterprise instance, the dynamic registration parameters are as follows:

       mqttClientId:clientId+"|securemode=-2,authType=xxxx,random=xxxx,signmethod=xxxx,instanceId=xxxx|"
       mqttUserName: deviceName+"&"+productKey
       mqttPassword:sign_hmac(productSecret,content)

     • When a device belongs to a legacy public instance, the dynamic registration parameters are as follows:

       mqttClientId:clientId+"|securemode=2,authType=xxxx,random=xxxx,signmethod=xxxx|"
       mqttUserName: deviceName+"&"+productKey
       mqttPassword:sign_hmac(productSecret,content)

     Note

     For more information, see Instance overview.

     Parameter description:

     • mqttClientId

       Parameters in the value:

       Parameter	Description
       clientId	The client ID. Custom value, up to 64 characters. Use the MAC address or serial number (SN) for easy identification.
       securemode	The security mode. For unique-certificate-per-product authentication with pre-registration, the value is fixed at 2. For unique-certificate-per-product authentication without pre-registration, the value is fixed at -2.
       authType	The authentication method. Each method returns different parameters: register: For unique-certificate-per-product authentication with pre-registration, this method returns the DeviceSecret. regnwl: For unique-certificate-per-product authentication without pre-registration, this method returns the DeviceToken and ClientID.
       random	A custom random number.
       signMethod	The signature algorithm. Supported values: hmacmd5, hmacsha1, and hmacsha256.
       instanceId	The instance ID. Find it on the Instance Overview page of the IoT Platform console.

     • mqttUserName

       Structure: deviceName+"&"+productKey

       Example: device1&al123456789

     • mqttPassword

       Calculation method: sign_hmac(productSecret,content)

       Concatenate deviceName, productKey, and random in alphabetical order without delimiters to form the content string. Sign it using the algorithm specified by signMethod in mqttClientId, with the ProductSecret as the key.

       Example: hmac_sha1(h1nQFYPZS0mW****, deviceNamedevice1productKeyal123456789random123)

2. IoT Platform returns a CONNECT ACK message.

   • A return value of 0 indicates that the device is successfully registered.

   • Other values indicate that the dynamic registration failed. You can identify the cause of the failure based on the returned error code.

   IoT Platform returns one of the following status codes:

   Result code	Message	Description
   0	CONNECTION_ACCEPTED	The dynamic registration is successful.
   2	IDENTIFIER_REJECTED	Invalid parameters. Possible causes: A required parameter is missing or in an invalid format. A direct TCP connection was used. Dynamic registration requires TLS.
   3	SERVER_UNAVAILABLE	A server error occurred. Try again later.
   4	BAD_USERNAME_OR_PASSWORD	Authentication failed. Verify the mqttUserName and mqttPassword values.

3. IoT Platform pushes authentication parameters to a topic based on the authType in the CONNECT message.

   Note

   The device does not need to subscribe to this topic.

   • With pre-registration (authType=register), the topic is /ext/register. The message contains the DeviceSecret.

     Payload format:

     {
       "productKey" : "***",
       "deviceName" : "***",
       "deviceSecret" : "***"
     }

   • Without pre-registration (authType=regnwl), the topic is /ext/regnwl. The message contains the ClientID and DeviceToken.

     Payload format:

     {
       "productKey" : "***",
       "deviceName" : "***",
       "clientId" : "***",
       "deviceToken" : "***"
     }

4. The device receives and saves the DeviceSecret, or the ClientID and DeviceToken. Then, it disconnects the current MQTT connection.

   Disconnect by sending a DISCONNECT message or closing the TCP connection.

   If the device does not disconnect, IoT Platform closes the connection after 15 seconds.

   If you use the Eclipse Paho MQTT client, set MqttConnectOptions.setAutomaticReconnect(false). Otherwise, the client automatically re-initiates dynamic registration after the connection closes.

5. The device reconnects using the DeviceSecret (with pre-registration) or the DeviceToken and ClientID as mqttClientId (without pre-registration). MQTT-TLS connection.

FAQ

• Failed to obtain the DeviceSecret during dynamic registration over MQTT using unique-certificate-per-product authentication

• What do I do if a device is denied registration after five registration attempts using unique-certificate-per-product authentication without pre-registration?

• Can a DeviceName be registered only once when I use unique-certificate-per-product authentication with pre-registration?

• How do I set the device heartbeat in IoT Platform?

• Can I configure MQTT connection parameters in IoT Platform?

• Which regions and instances support unique-certificate-per-product authentication without pre-registration?

• How do I determine why a device went offline?

• How do I check for network issues?