All Products
Search
Document Center

IoT Platform:MQTT-based dynamic registration

最終更新日:Nov 24, 2023

If you enable dynamic registration in the IoT Platform console, you can verify a directly connected device by using the unique-certificate-per-product method. This way, the device can connect to IoT Platform over Message Queuing Telemetry Transport (MQTT). The device establishes a Transport Layer Security (TLS) connection to IoT Platform to obtain the DeviceSecret that is required for an MQTT connection. Then, the device closes the TLS connection and establishes the MQTT connection for communication. This topic describes the dynamic registration process.

Prerequisites

The following steps that are described in the Unique-certificate-per-product verification topic are performed:

Important

The preregistration-free unique-certificate-per-product verification method is available only in the China (Shanghai) region.

  1. Create a product.

  2. Enable dynamic registration.

  3. Add a device.

  4. Install the device certificates on the devices.

Dynamic registration process

流程

  1. The device sends a CONNECT message that includes dynamic registration parameters to establish a connection.

    Note

    Dynamic registration supports only TLS connections. During dynamic registration, IoT Platform does not verify the keep-alive time of the MQTT connection. Therefore, you do not need to specify the keep-alive time.

    • MQTT endpoints for public instances and Enterprise Edition instances: For more information, see Manage the endpoint of an instance.

      Note

      If you want to verify a directly connected device by using the preregistration-free unique-certificate-per-product method, replace ${YourRegionId} with cn-shanghai.

    • Dynamic registration parameters of the CONNECT message:

      • If the device is connected to a public instance of the new version or an Enterprise Edition instance, configure the following dynamic registration parameters:

        mqttClientId:clientId+"|securemode=-2,authType=xxxx,random=xxxx,signmethod=xxxx,instanceId=xxxx|"
        mqttUserName: deviceName+"&"+productKey
        mqttPassword:sign_hmac(productSecret,content)
      • If the device is connected to a public instance of the old version, configure the following dynamic registration parameters:

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

      For more information, see Overview of IoT Platform instances.

      Parameters:

      • mqttClientId

        The following table describes the parameters that are included in the mqttClientId parameter.

        Parameter

        Description

        clientId

        The ID of the client. The client ID must be 1 to 64 characters in length. We recommend that you use the Media Access Control (MAC) address or serial number (SN) of the device as the client ID.

        securemode

        The mode of security. Valid values:

        authType

        The verification method. The parameters that are returned vary based on the verification method. Valid values:

        • register: the pre-registration unique-certificate-per-product verification method. If you set the parameter to this value, a DeviceSecret is returned.

        • regnwl: the preregistration-free unique-certificate-per-product verification method. If you set the parameter to this value, a DeviceToken and a ClientID are returned.

        random

        The random number. You can specify a random number.

        signMethod

        The signature algorithm. Valid values: hmacmd5, hmacsha1, and hmacsha256.

        instanceId

        The ID of the IoT instance. You can log on to the IoT Platform console and view the instance ID on the Overview tab.

      • mqttUserName

        Format: deviceName+"&"+productKey

        Example: device1&al123456789

      • mqttPassword

        Calculation method: sign_hmac(productSecret,content)

        The value of the content parameter is a concatenated string of the parameters and the corresponding values that must be submitted to IoT Platform. The parameters include deviceName, productKey, and random. The parameters are sorted in alphabetical order and concatenated without using concatenation operators. Then, the value of the content parameter is encrypted based on the algorithm that is specified by signMethod in the mqttClientId parameter. The ProductSecret of the product is used as the secret key of the algorithm.

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

  2. IoT Platform returns a CONNECT ACK message.

    • The value 0 indicates that the dynamic registration is successful.

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

    The following table describes the response codes that may be returned after the device sends a connection request to IoT Platform.

    Response code

    Message

    Description

    0

    CONNECTION_ACCEPTED

    The dynamic registration is successful.

    2

    IDENTIFIER_REJECTED

    The parameters are invalid. This error may occur due to one of the following causes:

    • One or more required parameters are not specified or are in invalid formats.

    • You established a direct TCP connection for registration. Dynamic registration supports only TLS connections.

    3

    SERVER_UNAVAILABLE

    An error occurred in IoT Platform. Try again later.

    4

    BAD_USERNAME_OR_PASSWORD

    The dynamic registration failed. The device is not verified.

    Check whether the values of the mqttUserName and mqttPassword input parameters are valid.

  3. After the connection is established, IoT Platform uses the topic that is used to push device certificates to return verification parameters. The verification parameters vary based on the authType parameter in the CONNECT message.

    Note

    The device does not need to subscribe to the topic that is used to push the certificate.

    • If you use the pre-registration unique-certificate-per-product method, set the authType parameter to register. In this case, the /ext/register topic is used to return a DeviceSecret.

      The message payload that is pushed by IoT Platform is in the following format:

      {
        "productKey" : "***",
        "deviceName" : "***",
        "deviceSecret" : "***"
      }
    • If you use the preregistration-free unique-certificate-per-product method, set the authType parameter to regnwl. In this case, the /ext/regnwl topic is used to return a ClientID and a DeviceToken.

      The message payload that is pushed by IoT Platform is in the following format:

      {
        "productKey" : "***",
        "deviceName" : "***",
        "clientId" : "***",
        "deviceToken" : "***"
      }
  4. The device receives and saves the DeviceSecret or a combination of the ClientID and DeviceToken, and closes the current MQTT connection.

    The device can close the current connection by sending a DISCONNECT message or by closing the TCP connection.

    If the device does not close the connection, IoT Platform disconnects the device after 15 seconds.

    If you use the Eclipse Paho MQTT client, use the MqttConnectOptions.setAutomaticReconnect(false) function to disable automatic reconnection. Otherwise, a new request for dynamic registration is generated based on the reconnection logic after the registration is completed and the TCP connection is closed.

  5. If you use the pre-registration unique-certificate-per-product method, the device uses the DeviceSecret to re-initiate a request to establish an MQTT connection between the device and IoT Platform for message communication. If you use the preregistration-free unique-certificate-per-product method, the device converts the ClientID into the mqttClientId, and then uses the combination of the mqttClientId and DeviceToken to establish the MQTT connection. For more information, see Establish MQTT connections over TCP.

Example

For information about the example on how to dynamically register a directly connected device, see MQTT-based dynamic registration.