本文介绍如何初始化设备信息,并建立设备与云端的连接。

云端域名

设备可以接入物联网平台的公共实例或者企业实例,SDK初始化时需要根据实例类型来指定设备连接的域名:
  • 公共实例

    若设备接入公共实例,需要指定公共实例所在的阿里云站点。需要注意的是物联网平台这个服务并没有在所有的阿里云地域都进行了部署,因此开发者需要先查看自己创建的产品所在的物联网平台地域,然后再从“地域和可用区中查看对应的RegionID,比如“华东2(上海)”的RegionID为cn-shanghai。

  • 企业实例
    用户需要在企业实例中查看实例的接入域名,请参见文档“实例管理,下图圈选部分即是企业实例的接入域名:mqtt_url

设备认证

设备的身份认证支持两种方法,不同方法需填写不同信息。

  • 若使用一机一密认证方式,需要指定host_name、product_key、device_name和device_secret。

  • 若使用一型一密认证方式,需要指定host_name、product_key、device_name和product_secret,需要设置动态注册回调接口on_device_dynamic_register。

说明 若使用一型一密认证方式,初始化过程中需设置一型一密动态注册接口。 并在控制台开启动态注册。 host_name为region信息,各地域信息可查询 https://help.aliyun.com/document_detail/40654.html。
  • 一机一密

下面的示例代码配置设备的设备证书以及连接的公共示例的RegionID,其中RegionID以华东2(上海)为例:

from linkkit import linkkit

lk = linkkit.LinkKit(
    host_name="cn-shanghai",
    product_key="xxxxxxxxxxx",
    device_name="nnnnnnnn",
    device_secret="ssssssssssssssssssssssssssssssss")
            

如果需要改变MQTT连接的一些默认参数,可以通过config_mqtt 指定端口等连接参数,如下所示:

config_mqtt(self, port=1883, protocol="MQTTv311", transport="TCP",
            secure="TLS", keep_alive=60, clean_session=True,
            max_inflight_message=20, max_queued_message=0,
            auto_reconnect_min_sec=1,
            auto_reconnect_max_sec=60,
            cadata=None):
            

上面的代码示例中设置了端口号、安全协议、保活时间等参数。

  • 一型一密

若用户选用一型一密认证方式,首先需要动态注册过程根据ProductKey、DeviceName和ProductSecret去获取DeviceSecret,然后将DeviceSecret保存下来之后再使用一机一密方式进行设备连接。

说明 目前Python SDK只在华东2(上海)站点支持一型一密。

下面是动态注册的代码示例:

from linkkit import linkkit

lk = linkkit.LinkKit(
    host_name="cn-shanghai",
    product_key="xxxxxxxxxxx",
    device_name="nnnnnnnn",
    device_secret="",
    product_secret="yyyyyyyyyyyyyyyy")
lk.on_device_dynamic_register = on_device_dynamic_register
def on_device_dynamic_register(rc, value, userdata):
    if rc == 0:
        print("dynamic register device success, rc:%d, value:%s" % (rc, value))
    else:
        print("dynamic register device fail,rc:%d, value:%s" % (rc, value))
            

当rc值为0时,动态注册成功, value 为从云端收到的deviceSecret, 需要用户将收到的device_secret存储下来。

注:

  • 如果设备已经通过动态注册方式获取到了deviceSecret,后续不能再继续使用动态注册方式去获取deviceSecret,而必须使用已获取到的deviceSecret使用一机一密方式连接阿里云IoT物联网。因此开发者需要保证deviceSecret存储的持久化,不能因为设备重启、重新安装导致deviceSecret丢失。

回调函数

设备连接云端成功后会通过on_connect回调函数通知用户,连接成功以后如果连接断开会通过on_disconnect 回调通知用户,用户可以在回调中加入自己的业务处理逻辑。

lk.on_connect = on_connect
lk.on_disconnect = on_disconnect
def on_connect(session_flag, rc, userdata):
    print("on_connect:%d,rc:%d,userdata:" % (session_flag, rc))
    pass
def on_disconnect(rc, userdata):
    print("on_disconnect:rc:%d,userdata:" % rc)
            

注:

  • 当设备连接到阿里云IoT物联网后,如果因为网络原因连接断开,SDK会自动尝试连接阿里云IoT物联网,用户无需调用API。

配置网络接口信息

如果产品生产时错误地将一个三元组烧写到了多个设备,多个设备将会被物联网平台认为是同一个设备,从而出现一个设备上线将另外一个设备的连接断开的情况。用户可以将自己的接口信息上传到云端,那么云端可以通过接口的信息来进行问题定位。

lk.config_device_info("Eth|03ACDEFF0032|Eth|03ACDEFF0031")
            

其中接口可取值:

  • WiFi
  • Eth
  • Cellular

如果设备的上行网络接口是WiFi或者Eth(以太网),那么接口会有MAC地址,MAC地址的格式为全大写;

如果是Cellular(即2G、3G、4G蜂窝网接口),那么需要填入的接口数据为:

  • IMEI:string
  • ICCID: string
  • IMSI:string
  • MSISDN:string

填入信息格式举例:"Cellular|imei_001122|iccid_22334455|imsi_234241|msisdn_53212"。

企业实例域名配置的更改

针对企业实例,需要调用config_mqtt接口,填入企业实例域名。以 examples/mqtt_connect_TCP.py为例:

在原有的lk.config_mqtt(secure="")的基础上, 加上企业实例域名的信息,调整为lk.config_mqtt(secure="", endpoint="${instance-endpoint}"),其中${instance-endpoint}为前面章节描述的企业实例域名。

# 修改如下所示:# - 标识为原有配置,+ 标识为更改后的配置。
# # 具体为把lk.config_mqtt(secure="") 这一句, 替换为lk.config_mqtt(secure="", endpoint="${instance-endpoint}"), 其中${instance-endpoint}为企业实例域名。
-lk.config_mqtt(secure="")
+lk.config_mqtt(secure="", endpoint="${instance-endpoint}")
 lk.connect_async()

启动连接

在MQTT连接参数配置(可选),回调函数设置(必选),网络接口信息(可选)操作完成后,需要使用connect_async 调用开始进行实际的连接。

lk.connect_async()
            
注意 调用该函数之后如果因为网络处于连接断开状态导致连接失败,用户无需再次调用connect_async(),SDK会再次尝试连接云端。