开发者中心

Appearance

MQTT 设备接入指南 ​

本文档以 MQTT 调试工具 为例介绍如何通过 MQTT 协议 将设备安全接入到Xlink物联网平台，实现数据上报、命令下发等功能。
MQTT（Message Queuing Telemetry Transport）是一种轻量级的发布/订阅消息传输协议，适用于低带宽、不稳定网络环境下的设备通信。
MQTT 调试工具是由 云智易 开发的开源项目，提供功能完善的在线 MQTT 调试与测试能力，支持消息发布、订阅、连接验证等多种操作。您可以访问 https://mqtt-client.app/ 开始使用。

接入准备 ​

  1. 创建产品，在云智易物联网平台中创建一个 产品（Product）。
    创建产品

  2. 定义物模型，创建产品后，您需要进入到产品管理页面定义物模型。平台提供了海量的设备物模型，您可以直接使用，或自定义物模型。
    定义物模型

  3. 注册设备，选择MQTT直连接入方式，注册设备并获取设备凭证。
    注册设备
      设备凭证是系统自动生成的，可以直接复制使用。 查看凭证

连接信息 ​

参数说明示例
Broker 地址MQTT 服务器地址（MQTT/MQTTS 协议与WebSocket 版本ws/wss 协议均支持）mqtt.xlink.cn
ClientID设备认证标识，全平台通用X:DEVICE;A:13;V:5;
Username{ProductId}#{DeviceMac}161ff6d801#ZNCJD001
PasswordSha-256（{ProductID} + {Mac} + {ProductKey}）690DC71B0A620948E...
QoS 支持0 / 10
KeepAlive心跳间隔时间（秒）60

接入配置 ​

  1. 配置连接信息，获取MQTT服务器的连接信息，并在MQTT 调试工具中填充。
    MQTT服务信息
    配置接入信息

  2. 连接服务，创建连接后，点击连接，若连接信息都无误，调试工具即可连接服务器。 连接服务
    连接成功

设备调试 ​

  1. 调试配置，连接上服务后，就可以开始调试属性上报。平台默认提供设备属性上报、设备事件上报、设备服务下发、设备服务下发响应四个Topic。 平台提供了自动生成Topic和payload功能，只需简单操作即可生成。
    物模型Topic

主题规范（Topic） ​

设备与平台通过 Topic 进行通信。常见的主题规范如下：

方向Topic 格式说明
设备 → 平台$xlink/device/{product_id}/{mac}/thing/
attribute/report		设备属性上报
设备 → 平台$xlink/device/{product_id}/{mac}/thing/
event/report		设备事件上报
设备 → 平台$xlink/device/{product_id}/{mac}/thing/
service/{service_name}/invoke/result		设备服务下发响应
平台 → 设备$xlink/device/{product_id}/{mac}/thing/
service/{service_name}/invoke		设备服务下发
  1. 设备调试，在调试工具填入Topic和payload，点击“发布消息”按钮。若上报成功，平台调试页面能看到属性变化。
    发布消息属性值更新

以上就是按照平台标准物模型接入设备的操作介绍，若不希望使用平台物模型，平台提供了自动以Topic和数据解析的方法以满足这种需求。

自定义Topic ​

当平台提供的物模型属性与您的设备不匹配，且不想自定义属性，则可以通过使用自定义Topic+数据解析功能的方式实现设备数据的上报和下发。

  1. 创建自定义Topic，平台支持创建发布、订阅、发布和订阅三种设备操作权限的自定义Topic，您可以根据自己产品的Topic规范定义个性化的Topic。 自定义Topic

  2. 数据解析脚本，支持添加JS解析脚本，将设备自定义Topic数据转换为平台标准物模型数据，或将平台标准物模型主题数据转为设备自定义主题。
    解析脚本
    解析脚本全屏

示例：JS 解析代码 ​

javascript
// 仅自定义Topic支持数据解析
// 解析脚本生效后，物模型Topic将不可用
// 以下为脚本模版，您可以基于以下模版进行脚本编写
/**
 * 将设备自定义topic数据转换为平台标准物模型数据，设备发布主题时调用，注：设备发布的自定义主题必须是设备可发布权限。
 * 入参：topic   string 上报消息的原始topic
 * 入参：topicParams   Object 主题包含的变量，如定义了主题为device/${id}，那么这里会将${id}作为变量提取。
 * 入参：payload byte[]数组的HEX字符串，
 * 出参：返回设备协议主题数据
 */
function transformFrom(topic, topicParams, payload) {
  //发布示例： {  "temp": 18,  "hum": 15}
  //自定义解码
  var payloadJson = hexToJson(payload);
  var temp = payloadJson.temp;
  var hum = payloadJson.hum;
  return {
    "topics": [{
      "topic": "$xlink/device/16a8dcd14848000116a8dcd14848e201/17244517454545/thing/attribute/report", // 平台标准的设备协议主题
      "payload": {
        "attribute": {
          "v": "2",
          "extra": {
            "temperature": temp,
            "humidity": hum
          }
        }
      }
    }]
  }
}
/**
 *  将平台标准物模型主题数据转为设备自定义主题，平台控制下发时调用，注：转出的设备自定义主题必须是设备可订阅权限。
 * 入参：topic   string 下发报消息的原始topic
 * 入参：topicParams   Object 主题包含的变量，一般是平台标准物模型主题定义的变量，如${product_id},${mac}等
 * 入参：payload byte[]数组的HEX字符串，
 */
function transformTo(topic, topicParams, payload) {
  //自定义解码
  //
  var payloadJson = hexToJson(payload);
  var msgId = payloadJson.msg_id;
  var serviceName = topicParams.service_name;
  var productId = topicParams.product_id;
  var mac = topicParams.mac;
  return {
    "topics": [{
      "topic": "down",
      "format": "TEXT",
      "payload": {
        "mac": mac,
        "serverName": serviceName,
        "msgId": msgId,
        "productId": productId
      }
    }]
  }
}

function hexToJson(hexString) {
  jsonString = '';
  for (i = 0; i < hexString.length; i += 2) {
    hex = hexString.substr(i, 2);
    jsonString += String.fromCharCode(parseInt(hex, 16));
  }
  return JSON.parse(jsonString);
}

示例中只是简单地把设备属性转为平台属性，您还可以通过解析脚本对数据进行各种运算后再转换。

批量注册设备 ​

除上述单个设备接入的方法，平台还提供了批量注册设备的方法，通过导入设备列表csv文件实现设备的批量注册。 批量注册

使用平台激活凭证 ​

若使用平台激活凭证激活设备，可以按照设备激活凭证生成方法，给批量生成激活凭证，并配置到设备上。

txt
// 设备激活凭证生成方法
ClientID: 客户端ID，全平台统一，`X:DEVICE;A:13;V:5;`
Username: 用户名，`{ProductId}#{DeviceMac}`
Password: 密码，`Sha-256（{ProductID} + {Mac} + {ProductKey}）`

使用自定义激活凭证 ​

若使用自定义的激活凭证激活设备，可以通过在设备列表文件中补全设备激活凭证字段即可通过自定义的激活凭证激活设备。 设备激活凭证

设备列表文件字段解析 ​

参数说明
MAC设备MAC地址，用作平台的设备唯一标识
SN设备序列号，全球唯一的识别编号
NAME设备名称，用作平台显示的设备名称
MQTT_CLIENT_ID客户端ID，用于设备激活
MQTT_USERNAME用户名，用于设备激活
MQTT_PASSWORD密码，用于设备激活

常见问题 FAQ ​

Q1：连接失败（return code 5）是什么原因？ A1：一般是用户名或签名错误，请确认 username、password、clientId 输入无误。

Q2：设备掉线频繁？ A2：请确保设备定期发送心跳包，或增大 keepalive 时间。