Homie Convention版本迁移指南：从3.x到5.x平滑过渡

发布时间：2026/7/10 18:11:36

Homie Convention版本迁移指南：从3.x到5.x平滑过渡

【免费下载链接】convention🏡 The Homie Convention: a lightweight MQTT convention for the IoT项目地址: https://gitcode.com/gh_mirrors/co/convention

Homie Convention是基于MQTT协议的轻量级IoT设备通信标准，本文将详细介绍如何从3.x版本平滑迁移至5.x版本，帮助开发者快速适应新特性并解决兼容性问题。

🌟 为什么需要迁移到5.x版本？

Homie 5.x版本带来了多项重要改进，包括更灵活的设备拓扑结构、增强的属性定义和更严格的消息格式规范。相比3.x版本，5.x提供了以下核心优势：

统一的根主题结构：采用homie/5/[device ID]格式，明确区分不同版本设备
增强的设备描述：通过$descriptionJSON文档统一管理设备元数据
灵活的扩展机制：支持自定义扩展，兼容旧版功能的同时支持新特性
完善的设备生命周期管理：新增sleeping状态，优化设备离线处理逻辑

📋 核心变更概览

1. 主题结构调整

版本	根主题格式	设备属性位置	节点属性位置
3.x	`homie/[device ID]`	直接作为设备主题子节点（如`$localip`）	节点主题下的属性节点（如`$name`）
5.x	`homie/5/[device ID]`	统一通过`$description`JSON文档定义	完全通过`$description`JSON文档定义

迁移要点：

所有设备主题需添加版本前缀5/
移除直接发布的设备属性（如$localip、$mac），统一通过$description文档定义

2. 设备描述文档

Homie 5.x引入了$description属性，使用JSON格式集中定义设备元数据：

{ "homie": "5.0", "name": "智能温度计", "version": 1, "nodes": { "sensor": { "name": "温度传感器", "properties": { "temperature": { "name": "温度值", "datatype": "float", "unit": "°C", "format": "-40:85" } } } } }

迁移步骤：

创建包含设备、节点和属性定义的JSON文档
将文档发布到homie/5/[device ID]/$description主题
确保文档版本号随内容变化递增

3. 数据类型与格式

5.x版本对数据类型进行了标准化，主要变化包括：

新增数据类型：color、datetime、duration、json
格式规范：为每种类型定义严格的格式约束，如颜色支持rgb/hsv/xyz格式
布尔值处理：统一使用"true"/"false"字符串，不再支持自定义文本表示

示例转换：

// 3.x格式 homie/thermostat/temp → "23.5" // 5.x格式（需在$description中定义datatype为float） homie/5/thermostat/sensor/temperature → "23.5"

🔄 迁移实战步骤

1. 准备工作

克隆最新代码库：

git clone https://gitcode.com/gh_mirrors/co/convention

查阅扩展文档：
- 旧版固件属性支持：extensions/documents/homie_legacy_firmware_extension.md
- 统计信息兼容方案：extensions/documents/homie_legacy_stats_extension.md

2. 主题结构改造

修改设备连接逻辑：

更新MQTT连接的根主题为homie/5/[device ID]
设置正确的LWT消息：homie/5/[device ID]/$state设为lost

示例代码片段：

// 3.x版本 String baseTopic = "homie/super-car"; // 5.x版本 String baseTopic = "homie/5/super-car"; mqttClient.setWill(baseTopic + "/$state", "lost", 2, true);

3. 设备描述文档实现

创建包含所有设备元数据的JSON文档，重点包含：

homie字段：指定协议版本（如"5.0"）
nodes对象：定义所有节点及其属性
extensions数组：声明使用的扩展（如遗留固件支持）

4. 处理遗留属性

对于3.x版本中的$localip、$mac等属性，通过以下方式迁移：

使用 legacy-firmware 扩展：

{ "extensions": ["org.homie.legacy-firmware:0.1.1:[4.x]"] }

按扩展规范发布属性：

// 发布遗留属性 mqttClient.publish("homie/5/super-car/$localip", "192.168.0.10".getBytes(), 2, true); mqttClient.publish("homie/5/super-car/$mac", "DE:AD:BE:EF:FE:ED".getBytes(), 2, true);