联犀开发者文档

VRF空调接入

约 542 字大约 2 分钟

设备接入第三方协议VRF中央空调

2026-08-20

简介

VRF 协议（vrfMqtt）是联犀平台对接 VRF（Variable Refrigerant Flow，多联机）中央空调网关的 MQTT 直连协议。设备通过 MQTT 以联犀标准式三元组认证连接，上报/下发采用 E2.0/K19 私有 JSON 报文。

应用场景

  • VRF 多联机空调：格力等品牌中央空调网关接入
  • 空调控制：开关机、温度设定、模式切换等

前置条件

  1. 协议容器已部署：protocol-vrf 容器运行正常
  2. MQTT Broker 可访问：平台 MQTT 服务端口 1883 开放
  3. 产品约束：产品 ID 需为 vrf001（协议进程 DeviceAuth.ProductID 硬校验）

产品配置

创建产品时选择协议 vrfMqtt（传输协议 MQTT），产品 ID 需为 vrf001。

设备接入

设备详情「设备接入」Tab 展示三元组（打开即自动生成）：

设备接入

三元组（联犀标准式）

参数值
ClientID{productID}&{deviceName}
Username{ClientID};12010126;{connID 5位随机};{expiry 10天后unix秒}
PasswordHMAC-SHA256(username, base64decode(deviceSecret));hmacsha256

Topic

方向Topic说明
上行订阅recv_topic设备上报（固定字符串，无占位符）
下行发布send_topic平台下发（固定字符串）

报文格式（E2.0/K19 私有 JSON）

{
  "ver": "E2.0",
  "type": "K19",
  "sn": "{设备名}",
  "msg": {
    "o": "heart | rep | query_ack",
    "p": "/gw/info | /ac/{id}/status | ...",
    "v": {}
  }
}
  • sn 即设备名（网关设备名）
  • o=heart 心跳、o=rep 上报、o=query_ack 查询应答

技术方案

接入架构

VRF空调网关 ──MQTT──> protocol-vrf 容器(订阅 recv_topic) ──> 联犀平台
  • 设备连接 MQTT（认证走平台标准认证链），产品需为 vrf001
  • 报文身份靠 JSON 内 sn 字段（=设备名）识别
  • 下行经 send_topic 发布 E2.0/K19 指令（cfg/query 等）
  • 子设备（空调）命名 {网关设备名}-{空调ID}

注意事项

  • 产品 ID 必须为 vrf001，否则认证失败
  • 三元组由配置页自动生成，过期后可手动刷新
  • 协议进程自身 LoginAuth 只校验 clientID==username + 产品匹配（密码不校验，走标准认证链）

更新日志

2026/8/21 03:59
查看所有更新日志
  • 4ab8f-Merge #25 into master from docs/third-party-protocols于