跳到主要内容

YFLink协议

文档信息​

  • 版本：V1.3.0
  • 作者：刘洪峰
  • 日期：2026-01-08

历史版本​

  • 2026-01-08 V1.3.0 去掉Topic前面"/"(以便支持共享订阅)
  • 2022-10-28 V1.2.0 修改设备服务的json定义和广播topic
  • 2022-09-08 V1.1.0 调整登录的topic，事件支持多条，添加续传功能等
  • 2019-08-28 V1.0.0 第一个版本

1 协议说明​

YFLink 是专为物联网设备与 YFIOs 物联网云平台通信设计的通信协议。

协议沿用并扩展了阿里云物联网平台 Alink 的三元组模型，在产品密钥、设备名称、设备密钥基础上，进一步定义为四元组身份体系： ProjectID（项目ID）、ProductID（产品ID）、DeviceID（设备ID）、DeviceKey（设备密钥）。 其中 DeviceKey 由系统自动生成，为 32 位随机混合字符；整套四元组总长度不超过 128 个字符。

ProductID 与 DeviceID 命名规则对标阿里云物联网平台产品标识，仅支持英文字母与数字，首字符不得为数字，长度不超过 31 位，ProjectID 遵循相同命名规范。 平台级通用产品的 ProductID 在全平台唯一；项目级产品的 ProductID 在所属项目内唯一即可；当前版本中，DeviceID 要求在项目维度下保持唯一。

项目名称、产品名称、设备名称支持中文等友好显示名，用于平台界面展示，不参与身份鉴权。

协议当前通信数据包统一采用 JSON 格式进行交互。

2 设备接入​

2.1 MQTT接入​

MQTT支持非加密和TLS 1.2/TLS1.3加密传输，端口号分别为 1883 和 8883。webSocket：WS端口号为8083 WSS端口号为8888

  • clientID – 客户端ID， 设备唯一标识 ，一般为MCU ID或MAC地址等
  • userName – 用户名， 项目ID + "&" + 产品ID+"&"+"设备ID"
  • password - 用户密码
    • 该字段需要进行hmacsha1处理
    • hmacsha1的content为 ClientID+ UserName 两个字符串拼合
    • key字段为设备KEY

2.2 设备登录和登出​

网关设备的登录与登出状态通过 MQTT 连接状态进行判定：MQTT 连接建立成功即为在线登录状态，连接断开则为离线登出状态。心跳机制复用 MQTT 协议自身的心跳保活机制，默认心跳间隔设置为 60 秒。若服务器在 1.5～2 倍心跳周期内未收到设备心跳，则判定设备离线，并主动断开连接。

子设备需完成登录及设备身份认证后，方可正常进行属性、事件与服务的收发通信。该认证机制可避免持有合法设备权限的恶意用户，向无权限设备的 Topic 非法发送数据，提升平台接入安全性。

2.2.1 子设备登录​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/device/login
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/device/login_reply

YFLink请求的JSON包格式： 支持子设备批量登录，如果是多个，则填写多个即可。

{
  "id":1234578,
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params": [
    {
      "clientId":"${clientId}",       //参见mqtt接入
      "userName": "${userName}",  //参见mqtt接入
      "password":"${password}"    //参见mqtt接入
    },
    … …
  ]
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
  "data":[
    {
      "userName": "${userName}" //参见mqtt接入
    },
    …
  ]
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found子设备不存在
1002deivce forbidden子设备被禁用
1003invalid sign子设备签名有误

2.2.2 子设备登出​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/device/logout
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/device/logout_reply

YFLink请求的JSON包格式： 支持子设备批量登出，如果是多个，则填写多个即可。

{
  "id":1234578,
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params": [
    {
      "userName": "${userName}",  //参见mqtt接入   
    },
    … …
  ]
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误

3 设备通信​

3.1 属性​

设备属性由属性ID（标识符）、属性名称、属性类型、属性值及属性描述构成。 其中属性ID支持字母、数字组合，首字符不能为数字，长度不超过31位。

支持的数据类型如下：

  • 整型：int/uint，长度为32位
  • 浮点型：float，单精度浮点数
  • 布尔型：bool，取值为 0 或 1
  • 字符串型：最大长度不超过31个字符

其他数据类型暂不支持。

3.1.1 属性上传（设备需登录）​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/property/post
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/property/post_reply

YFLink请求的JSON包格式： 支持多个属性，如果是多个，则填写多个即可。

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params":{
    "${propertyId}": ${propertyValue}, //字符串格式属性值才需要引号
    或
    "${propertyId}": {"value":${propertyValue}, "time":${timestamp}}  //带时间戳的属性上传，二者都可以支持
    … …
  }
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
  "data":  [              //验证不通过的属性标识  
    {
      "propertyId": "${ propertyId }",  //参见mqtt接入   
    },
    … …
  ]
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常

3.1.2 属性下发​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/property/set
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/property/set_reply

YFLink请求的JSON包格式： 支持多个属性，如果是多个，则填写多个即可。

{
  "id":1234578,
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params":{
    "${propertyId}": ${propertyValue},  //字符串格式属性值才需要引号
    … …  
  }
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
  "data":  [              //验证不通过的属性标识  
    {
      "propertyId": "${propertyId}",  //参见mqtt接入   
    },
    … …
  ]
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常

3.2 事件​

相较于阿里云物联网平台，我们对事件类型做了精简与约束，仅支持信息、告警、故障三类事件。

事件格式统一规范为三部分：

  • 事件类型：0—信息，1—告警，2—故障
  • 事件编码（code）：32 位整数
  • 事件内容：长度不超过 1024 字节

3.2.1 事件上传​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/event/post
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/event/post_reply

YFLink请求的JSON包格式：

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params":[
    {
      "type":0,            //事件类型  
      "code":123,   
      "content":"${content}",   
      "time": ${timestamp}     //非必选字段
    }
  ]
}

服务器响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常

3.3 服务​

与阿里云物联网平台相比，我们对服务类型同样做了精简约束，仅支持命令、参数两类服务。
服务交互可采用同步模式实现：平台下发服务调用后，将等待设备返回响应，超时时间统一设置为 60 秒。

3.3.1 服务下发​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/server/send
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/server/send_reply

服务器请求的JSON包格式：

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "serviceType":0,                //0-命令  1-参数
  "params":{    
    "command":"xxxx",         //服务命令
    "parameter":"yyyyy",   
  }
}

设备响应的JSON包格式：

{
  "id":1234578,
  "ver":"1.0.0",         //非必选字段
  "params":{    
    "code":123,              //服务响应标识符
    "content":"${content}",     //服务响应内容
  }
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常

3.4 校时​

校时由设备端向服务器发送请求。

3.4.1 服务请求​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/ntp/request
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/ntp/response

YFLink请求的JSON包格式：

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "params":{  
    "deviceSendTime": xxxxx，  //1970年1月1日以来的毫秒数
  }
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
  "params":{    
    "deviceSendTime": xxxxx，   //设备发送请求的时间
    "serverRecvTime": xxxxx，   //服务器接收到该请求的时间
    "serverSendTime": xxxxx，   //服务器发起发送该响应的时间
  }
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常

3.5 广播​

广播是服务器主动发起，向指定项目和产品下的所有设备进行广播通知。

3.5.1 广播下发​

  • 请求Topic：
    • ${ProjectID}/${ProductID}/broadcast （全产品广播）
    • ${ProjectID}/broadcast （全项目广播）

YFLink请求的JSON包格式：

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "params":{  
    "code":123,               //广播编码
    "content":"${content}",      //广播内容
  }
}

3.6 断线续传​

网络断开后，以下两类数据支持断线续传：累积产生的事件、设备属性。
其中，事件类数据可通过批量上报的方式完成断线续传。

3.6.1 属性数据包上传​

  • 请求Topic：${ProjectID}/${ProductID}/${DeviceID}/property/packagepost
  • 响应Topic：${ProjectID}/${ProductID}/${DeviceID}/property/package_reply

YFLink请求的JSON包格式： 支持多个属性，如果是多个，则填写多个即可。

{
  "id":1234578,        //32位整数
  "ver":"1.0.0",         //非必选字段
  "timestamp": xxxxx，  //非必选字段 1970年1月1日以来的毫秒数
  "params":{ 
    "${propertyId}": [{"value":${propertyValue}, "time":${timestamp}},…]
    … …
  }
}

YFLink响应的JSON包格式：

{
  "id":1234578,
  "code": 200,           //返回结果编码 200 – 表示成功
  "message":"success"，  //返回结果描述
  "data":  [              //验证不通过的属性标识  
    {
      "propertyId": "${propertyId}",  //参见mqtt接入    
    },
    … …
  ]
}

结果编码：

结果编码结果描述说明
200success操作成功
460request parameter error请求参数有误
1001device not found设备不存在
1002deivce forbidden设备被禁用
1004device not login设备未登录
6000system exception系统异常