设备快速连接¶

在EZtCloud中，设备快速连接的核心思路是：设备上电时，可通过“调用一个HTTP API”的方式，获取到连接信息，设备根据该信息，连接到 EZtCloud.

本文档描述了设备快速连接到EZtCloud的两种场景及其实现方式。

连接场景¶

EZtCloud支持如下两种场景下的设备快速连接：

场景一：设备上电后直接接入指定项目
场景二：用户扫码添加设备

当设备具备写入变量 ProjectKey 的能力时，推荐优先采用前者，其优点是设备上电即自动连接EZtCloud，全程无需人工干预。当设备不具备上述能力时，则可采用后者。

场景一：设备上电后直接接入指定项目¶

前提条件¶

设备需具备写入变量 ProjectKey 的能力。这种能力的表现形式不限，如：生产烧录设备时写入、通过设备自带的液晶屏和按键写入、通过上位机软件+串口线写入、通过专用设备写入等。

💡 提示

可在 控制台 > 项目设置 > 应用层API 中获取 ProjectKey。

连接流程¶

设备上电后，通过场景一的获取连接信息接口获取连接信息。
设备使用获取到的连接信息连接到云端。

获取连接信息API¶

当项目中不存在该设备时，则自动创建该设备。

进一步的，当项目中不存在该设备类型时，则自动创建该设备类型。

说明¶

为了兼容尽可能多的设备，下述接口同时支持请求参数传参和请求体传参，其效果相同。两者的并集将作为最终的传参，两者同时传入时，以请求体参数为准。

为了兼容尽可能多的设备，下述接口同时支持 POST 和 GET方法，其效果相同。受限于HTTP协议，当采用GET方法时，不支持请求体传参。

请求信息¶

URL: <HTTPS API 接入点>/api/connect/1/?project=<project>&product=<product>&sn=<sn>
方法: POST 或 GET
需要认证或鉴权: 否
熔断频率: 基于IP，1000次/小时

请求参数¶

project: ProjectKey
product: 产品识别码或产品Key
sn: 设备SN

请求体¶

{
 "project": "ProjectKey",
 "product": "产品识别码 或 产品Key",
 "sn": "设备SN"
}

响应¶

状态码 420: 项目不存在
状态码 436: 产品识别码不存在
状态码 200: 成功，返回连接信息

场景二：用户扫码添加设备¶

前提条件¶

每个设备需具备唯一的二维码，格式为如下二者之一：

格式1:

https://qr.eztcloud.com/{product}&{sn}

格式2:

{product}&{sn}

⚠️ 注意

尽可能使用格式1，它具有扫码拉起EZtCloud移动端应用的能力。第二种格式仅在设备太小，用于展示二维码的空间紧张时使用。

连接流程¶

用户通过移动端登录项目，扫描设备二维码。
设备上电后，通过场景二的获取连接信息接口获取连接信息。
设备使用获取到的连接信息连接到云端。

获取连接信息API¶

当项目中不存在该设备时，则返回错误码 401.

说明¶

为了兼容尽可能多的设备，下述接口同时支持请求参数传参和请求体传参，其效果相同。两者的并集将作为最终的传参，两者同时传入时，以请求体参数为准。

为了兼容尽可能多的设备，下述接口同时支持 POST 和 GET方法，其效果相同。受限于HTTP协议，当采用GET方法时，不支持请求体传参。

请求信息¶

URL: <HTTPS API 接入点>/api/connect/2/?product=<product>&sn=<sn>
方法: POST 或 GET
需要认证或鉴权: 否
熔断频率: 基于IP，1000次/每小时

请求参数¶

product: 产品识别码或产品Key
sn: 设备SN

请求体¶

{
 "product": "产品识别码 或 产品Key",
 "sn": "设备SN"
}

响应¶

状态码 436: 产品识别码不存在
状态码 401: 设备不存在
状态码 200: 成功，返回连接信息

连接信息¶

成功响应将返回如下格式的连接信息：

{
    "mqtt": {
        "host": "mqtt.eztcloud.com",
        "port": 7883,
        "username": "DU_JEwVTAmL3m",
        "password": "1234567890"
    },
    "mqtts": {
        "host": "mqtt.eztcloud.com",
        "port": 7885,
        "username": "DU_JEwVTAmL3m",
        "password": "1234567890"
    },
    "tcp": {
        "host": "tcp.eztcloud.com",
        "port": 6879,
        "reg": "DU_JEwVTAmL3m&1234567890"
    },
    "topic": {
        // 设备上报属性
        "attributes": "attributes/DU_JEwVTAmL3m",

        // 设备上报属性的响应
        "attributes_response": "attributes_response/DU_JEwVTAmL3m",

        // 设备获取云端属性
        "attributes_get": "attributes_get/DU_JEwVTAmL3m",

        // 设备获取云端属性的响应
        "attributes_get_response": "attributes_get_response/DU_JEwVTAmL3m",

        // 云端下发属性至设备
        "attributes_push": "attributes_push/DU_JEwVTAmL3m",

        // 设备上报事件
        "event_report": "event_report/DU_JEwVTAmL3m",

        // 设备上报事件的响应
        "event_response": "event_response/DU_JEwVTAmL3m",

        // 云端下发命令至设备
        "command_send": "command_send/DU_JEwVTAmL3m",

        // 云端下发命令至设备的响应
        "command_reply": "command_reply/DU_JEwVTAmL3m",

        // 子设备上报上线通知
        "sub_connect": "gateway_connect/DU_JEwVTAmL3m",

        // 子设备上报下线通知
        "sub_disconnect": "gateway_disconnect/DU_JEwVTAmL3m",

        // 子设备上报属性
        "sub_attributes": "gateway_attributes/DU_JEwVTAmL3m",

        // 子设备上报属性的响应
        "sub_attributes_response": "gateway_attributes_response/DU_JEwVTAmL3m",

        // 子设备获取云端属性
        "sub_attributes_get": "gateway_attributes_get/DU_JEwVTAmL3m",

        // 子设备获取云端属性的响应
        "sub_attributes_get_response": "gateway_attributes_get_response/DU_JEwVTAmL3m",

        // 云端下发属性至子设备
        "sub_attributes_push": "gateway_attributes_push/DU_JEwVTAmL3m",

        // 子设备上报事件
        "sub_event_report": "gateway_event_report/DU_JEwVTAmL3m",

        // 子设备上报事件的响应
        "sub_event_response": "gateway_event_response/DU_JEwVTAmL3m",

        // 云端下发命令至子设备
        "sub_command_send": "gateway_command_send/DU_JEwVTAmL3m",

        // 云端下发命令至子设备的响应
        "sub_command_reply": "gateway_command_reply/DU_JEwVTAmL3m"
    }
}

设备可以根据自身支持的协议类型，选择相应的连接信息进行连接。

上述为默认响应格式，必要时，可通过如下方式自定义响应格式：

基于公共产品库创建设备类型。
打开上述设备类型的详情页，点击设置选项卡，点击 设备连接信息 并编辑保存。