7.2 核心类簇详解：通用、照明、测量与安防

7.2 词典：核心簇清单与设备类型模板

本节摘要：翻开词库的词典——基本簇与群组簇等通用词汇、照明族的开关调光色温簇、测量族的温湿度簇、安防族的警报与占有簇，以及设备类型模板如何规定"一台标准设备该会哪些词"。本节给出工程中最常用的簇速查与选型核对方法。

一、通用词汇：每台设备都要会的

基本簇是词库里无处不在的基础词汇表：厂商名、型号、日期代码、电源来源、可用电源、场景计数——一台设备无论什么品类，端点上都该有它，工具靠它显示设备身份。群组簇管分组成员关系（加组、退组、查看组成员），第四章的组播寻址靠它维护成员表。场景簇管"一组属性的预设组合"（客厅模式：灯百分之六十亮度加窗帘半开），本质是把多个属性值打包存档、一键恢复。识别簇给可寻址的执行器（开关面板上的按键）编号，让一个面板的多颗按键可以各自绑定不同目标。这四个通用簇搭起了设备身份、分组、场景、按键的通用框架，几乎所有设备类型模板都包含基本簇。

二、照明族：词库里最厚的一章

照明是这个生态最成熟的市场，簇目录也最丰富。开关键簇：最小颗粒的通断语义（开、关、切换命令加开闭状态属性）。调光簇：当前亮度属性（零到二百五十四的整数刻度，弃用两端留作特殊值）、过渡时间（渐变的十分之一秒数）、开关后恢复亮度等配置属性。色温簇：色温属性（色温的兆分之一开尔文单位）、过渡到色温命令。色彩控制簇更复杂，用颜色空间坐标描述彩灯（含色相饱和度的换算），属性与命令都按空间分量拆分。

照明族常用速查（节选）：

开关簇      命令：开 · 关 · 切换          属性：开闭状态
调光簇      属性：当前亮度(0-254) · 过渡时间(0.1秒单位)
            命令：跳转到亮度(带过渡) · 步进增减
色温簇      属性：色温(mired 单位=兆分之一开尔文)
            命令：过渡到色温 · 步进色温
色彩控制簇  属性：当前色相 · 饱和度 · 坐标 · 存储的坐标
            命令：过渡到色相饱和度 · 过渡到坐标
开关配置簇  属性：开关动作方向(按下开还是按下关)
​

值得体会的是过渡时间的无处不在——照明控制的体验核心是"渐变"而非"跳变"，词库把过渡时间做成每个照明命令的可选参数，是产品体验倒逼协议设计的典型例子。

三、测量族与安防族

测量簇族共享同一个骨架：测量值属性（带精度与量纲标度元数据）、最小可感知变化属性（配合上报阈值）、采样频率可选。温度测量簇的值是带符号十六位整数，配合标度属性还原成摄氏度；相对湿度测量簇是无符号十六位；功率测量族（电压、电流、有功功率）撑起能源监控场景。标度机制是序列化一节的好伏笔：值域压缩成整数传输，量纲由元数据还原——低功耗设备避免浮点运算的标准手法。

安防族：占有感应簇（有人无人的占用属性加占用事件上报，人体感应器的本体词汇）、警报簇（鸣叫命令、警报状态、最大时长约束）、门禁类的锁具簇（上锁开锁命令加锁状态，常配合调度与密码扩展）。安防词汇的严肃性体现在约束上——警报簇对鸣叫时长有上限规定，防止误配置造成持续扰民的"狼来了"设备。

四、设备类型模板：会哪些词才算一台标准灯

词典之上，规范为每类产品定义了模板：某设备类型必须实现哪些簇、哪些可选、角色如何分配。比如一个标准"可调光灯"模板：基本簇（强制）、开关键簇（服务端）、调光簇（服务端）、群组簇（服务端）；色温与色彩是可选档位——基础灯、调光灯、色温灯、彩灯构成递进的模板序列。模板的工程价值是验收依据：采购方按模板核对簇清单，缺簇即不符合设备类型声明；认证测试（第十章）也按模板展开用例。

图：设备类型模板的递进与核对法

⚠️ 常见坑：文档宣称符合某设备类型模板，实测缺强制簇或属性只读不可控。模板符合性属于认证范畴，未认证产品的类型声明只能当广告词看——这也是第十章认证流程存在的意义。

本节要点回顾

• 通用四簇：基本（身份）、群组（成员）、场景（预设组合）、识别（按键编号），几乎所有模板的底座；
• 照明族：开关、调光、色温、色彩递进，过渡时间贯穿所有命令是体验驱动的范例；
• 测量族：整数加标度元数据规避浮点，最小变化属性联动上报阈值；
• 安防族：占有、警报、锁具词汇自带安全约束（鸣叫时长上限）；
• 模板价值：设备类型的簇清单是采购验收与认证测试的依据，核对四步从描述符到实测；
• 本节坐标：词典在手，下一节看词库的写法——数据类型与字节级序列化。

延伸：簇目录的版本感

词库是活的——每版规范都在加簇（新设备品类出现）与修订语义（老簇的行为澄清）。做跨版本产品时要留意两点：新簇在旧网关上是"不可见但无害"的（发现不到就忽略）；老簇的新属性同理。真正破坏互操作的是语义修订（同名属性行为变化），这类修订规范极其谨慎，但读勘误表仍是严肃产品维护的必修课。

常见问题

亮度为什么是零到二百五十四而不是零到二百五十五？

规范把两端留作特殊语义值（零常兼作"关"的标识，二百五十五另有含义），有效刻度因此是一到二百五十四之间的整数。解析时把二百五十五当满亮是常见的差一错误，表现为"亮度调满反而异常"。

速查：高频簇卡片

补 cluster 实现的常见坑清单（产品测试时的重点核查项）。坑一，属性上报的节流：温湿度传感器每秒上报一次会把电池与网络拖垮，要按变化阈值加最小间隔双条件上报——测试时验证连续渐变下的上报频率。坑二，on/off 与 level 的联动一致性：灯收到 on 时若 level（亮度）为 0 要恢复到上次亮度——很多便宜灯把这个状态机做错（开灯后黑着）。坑三，配置 report 的持久性：网关配置的上报规则要在设备重启后依然生效（有些设备重启后 report 配置丢失，网关以为还在收数据其实永远等不到）。坑四，多网关或重入网后的绑定清理：设备换网后旧的绑定要清掉，否则它还在向已离开的旧网关上报（浪费电池且信息泄漏）。坑五，单位与量程的规范符合：温度单位是 0.01 摄氏度的有符号整数——实现时单位搞错的设备在网关上显示 1853 度。五个坑全部来自真实产品的返工记录——cluster 的合规实现，细节密度远超协议文本的篇幅。