文档

基于MQTT协议的设备动态注册

更新时间:

在物联网平台控制台为产品开启动态注册功能后,直连设备可使用一型一密安全认证方式完成动态注册,通过MQTT通信协议连接物联网平台。设备先基于TLS建立与物联网平台的连接,获取MQTT连接所需的设备证书,再断开连接,然后使用设备证书重新建立MQTT连接进行通信。本文介绍设备的动态注册流程。

前提条件

一型一密认证支持两种使用方式:一型一密免预注册、一型一密预注册,对比说明(地域限制、实例限制)和操作流程,请参见一型一密

设备动态注册认证前,需已完成一型一密文档中的以下步骤:

  1. 创建产品。

  2. 开启动态注册。

  3. 如果是一型一密预注册,需要添加设备。

  4. 产线烧录。

动态注册流程

流程

  1. 设备发送CONNECT报文,报文中包含动态注册参数,请求建立连接。

    说明

    目前,动态注册只支持使用TLS建立连接,不支持TCP直连。动态注册时,物联网平台不会校验MQTT连接的Keep Alive(保活时间),因此可以不用设置Keep Alive时间。

    • MQTT连接域名说明:公共实例和企业版实例中,MQTT的接入域名,请参见查看和配置实例终端节点信息(Endpoint)

      说明

      若直连设备使用一型一密免预注册认证方式,则${YourRegionId}值为cn-shanghai

    • CONNECT报文的动态注册参数:

      • 当设备属于新版公共实例或企业版实例时,动态注册参数如下:

        mqttClientId:clientId+"|securemode=-2,authType=xxxx,random=xxxx,signmethod=xxxx,instanceId=xxxx|"
        mqttUserName: deviceName+"&"+productKey
        mqttPassword:sign_hmac(productSecret,content)
      • 当设备属于旧版公共实例时,动态注册参数如下:

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

      实例的详细说明,请参见实例概述

      参数说明:

      • mqttClientId

        参数取值中包含的详细参数如下表所示。

        参数

        说明

        clientId

        客户端ID,可自定义,长度在64个字符内。建议使用设备的MAC地址或SN码,方便您识别区分不同的客户端。

        securemode

        安全模式。

        authType

        一型一密认证方式,不同类型将返回不同的认证参数:

        • register:一型一密预注册认证方式,返回DeviceSecret。

        • regnwl:一型一密免预注册认证方式,返回DeviceToken、ClientID。

        random

        随机数。您自定义随机数。

        signMethod

        签名算法。目前支持hmacmd5、hmacsha1、hmacsha256。

        instanceId

        实例ID。请登录物联网平台控制台,在实例概览页面查看。

      • mqttUserName

        组成结构:deviceName+"&"+productKey

        示例:device1&al123456789

      • mqttPassword

        计算方法:sign_hmac(productSecret,content)

        其中,content的值是提交给服务器的必需参数和值(deviceName、productKey、random)按照字母顺序排序、拼接(无拼接符号)的字符串。然后,将content的值通过mqttClientId中的signMethod指定的算法,使用产品的ProductSecret进行签名计算。

        示例:hmac_sha1(h1nQFYPZS0mW****, deviceNamedevice1productKeyal123456789random123)

  2. 物联网平台返回CONNECT ACK。

    • 返回0,表示设备动态注册成功。

    • 返回其他值,表示设备动态注册失败。请根据返回的错误码,确定错误原因。

    设备发送连接请求后,物联网平台返回的结果状态码和说明如下表。

    结果码

    消息

    说明

    0

    CONNECTION_ACCEPTED

    动态注册成功。

    2

    IDENTIFIER_REJECTED

    参数错误。原因可能是:

    • 必填参数缺失或格式错误。

    • 您使用了TCP直连注册。动态注册只能使用TLS通道。

    3

    SERVER_UNAVAILABLE

    云端错误。请稍后再试。

    4

    BAD_USERNAME_OR_PASSWORD

    动态注册失败,鉴权未通过。

    请检查传入的mqttUserNamemqttPassword取值是否正确。

  3. 建立连接后,物联网平台通过推送证书的Topic,根据CONNECT报文中的authType,返回不同的认证参数。

    说明

    设备无需订阅推送证书的Topic。

    • 一型一密预注册认证方式:Topic为/ext/registerauthType取值为register,返回DeviceSecret。

      物联网平台推送的消息Payload格式如下:

      {
        "productKey" : "***",
        "deviceName" : "***",
        "deviceSecret" : "***"
      }
    • 一型一密免预注册认证方式:Topic为/ext/regnwlauthType取值为regnwl,返回ClientID、DeviceToken。

      物联网平台推送的消息Payload格式如下:

      {
        "productKey" : "***",
        "deviceName" : "***",
        "clientId" : "***",
        "deviceToken" : "***"
      }
  4. 设备收到并保存DeviceSecret,或ClientID和DeviceToken的组合,断开当前MQTT连接。

    设备可以通过发送DISCONNECT报文或直接断开TCP连接,断开当前连接。

    如果设备未断开此连接,15秒之后,物联网平台会主动断开连接。

    如果您使用Eclipse Paho MQTT客户端,需设置MqttConnectOptions.setAutomaticReconnect(false)关闭自动重连。否则,注册成功且TCP断连后,重连逻辑会发起新的动态注册请求。

  5. 设备使用DeviceSecret(一型一密预注册),或将ClientID转化为mqttClientId后和DeviceToken组合(一型一密免预注册),再次发起MQTT连接请求,建立设备与物联网平台的连接,进行消息通信。具体操作,请参见MQTT-TLS连接通信

操作样例

直连设备的动态注册示例,请参见一型一密动态注册(MQTT通道)

常见问题

  • 本页导读 (1)
文档反馈