【免费下载链接】home-assistant-matter-hubPublish your Home-Assistant Instance using Matter.项目地址https://gitcode.com/gh_mirrors/hom/home-assistant-matter-hub点击查看免费下载Home-Assistant-Matter-Hub下称 HAMH是一个把你 Home Assistant 里的设备发布到 Matter 控制器Apple Home、Google Home、Alexa、SmartThings、Aqara Home的桥接工具。它的内部核心是Behavior行为与Endpoint端点两层结构本文带你读懂这套架构并用 matter.js 扩展出自己的 Matter 设备。 一句话心智模型Behavior 负责一个集群怎么干活Endpoint 负责把这些行为拼成一台设备。搞懂这两点整个项目就通了。一、什么是 Behavior 与 Endpoint先建立核心概念HAMH 把一台 Home Assistant 实体如light.living_room翻译成一个 Matter 端点再挂到桥接器Bridge下面。这个过程由两个可复用的积木完成概念通俗理解在 Matter 里的对应代码位置Behavior行为一个会干活的模块负责把 HA 状态映射到某个 Matter 集群Matter Cluster Serverpackages/backend/src/matter/behaviors/Endpoint端点一台设备由若干 Behavior 组合而成Matter Device Typepackages/backend/src/matter/endpoints/打开 HAMH 的All Devices页面你能直观看到每个端点及其Available Clusters可用集群——这些集群正是各个 Behavior 暴露出来的Behavior 是可组合的同一套OnOffServer行为既能用于灯也能用于插座、开关只需传入不同的配置回调。Endpoint 是端点的配方它 一个 matter.js 设备类型 一串 Behavior最后用.set()填入真实的 HA 实体数据。在 Bridge 详情页里你可以看到每个 Endpoint 卡片下方列出的集群清单如onOff、levelControl、colorControl这正是该端点由哪些行为组成的体检报告二、HAMH 如何用 matter.js 组合出一台设备HAMH 基于matter.jsmatter/main实现。它的设备组合套路非常统一从一个现成的 matter.js 设备类型出发用.with()挂上一串 Behavior最后.set()注入 HA 实体。下面是一个可调色温灯的端点配方节选自 dimmable-light.tsexport const DimmableLightType DimmableLightDevice.with( IdentifyServer, // 识别行为配对时闪烁 BasicInformationServer, // 设备身份名称/序列号 HomeAssistantEntityBehavior, // ★ 关键承载 HA 实体的脊梁 GroupsServer, ScenesManagementServer, LightOnOffServer, // 开/关集群 LightLevelControlServer, // 亮度集群 ); 记忆点HomeAssistantEntityBehavior是每个端点都必带的核心行为其他所有行为都靠它读取 HA 状态、回传指令。三、Behavior 开发从 HA 状态到 Matter 集群写一个 Behavior本质是写一个集群 Server 类它遵循同一套固定套路。以温度传感器为例temperature-measurement-server.tsinitialize()先await super.initialize()完成基础初始化再从当前端点加载HomeAssistantEntityBehavior立刻读一次实体状态并订阅它的变更事件。update(entity)核心逻辑——从entity.state/entity.state.attributes里取到 HA 的值换算后写进 Matter 的this.state。写状态用applyPatchState()这是项目封装的安全写状态工具apply-patch-state.ts它只写真正变化的字段并吞掉关机/事务冲突等生命周期错误避免误报。所有行为的取/设值都通过一对配置类型约定cluster-config.tsexport type ValueGetterT (entity, agent) T; // 读HA → Matter export type ValueSetterT (value, agent) HomeAssistantAction; // 写Matter → HA 动作Behavior 对外暴露一个工厂函数方便按场景注入不同配置例如开/关行为on-off-server.tsexport function OnOffServer(config: OnOffConfig {}) { return OnOffServerBase.set({ config }); }⚙️ 进阶亮点像 level-control-server.ts 还内置了乐观状态optimistic state与针对 Alexa/Google 的兼容逻辑解决调亮度后 UI 闪回旧值关灯后又点亮等真实控制器的怪癖。行为的两大方向只读型传感器、温度、湿度只做update()的ValueGetter方向把 HA 值同步到集群。可写型灯、开关、风扇额外实现on()/off()/moveToLevel()等命令方法把控制器指令翻译成 HA 的turn_on、light.turn_on等 action见 home-assistant-entity-behavior.ts 的callAction()。四、Endpoint 开发把行为拼成一台设备单个 Behavior 只是零件按 Home Assistant 领域domain把它们组装成端点的地方是legacy/下的各目录。入口是分发器createLegacyEndpointType()create-legacy-endpoint-type.tsHA 实体 → createLegacyEndpointType() 按 entity_id 的 domain 分发 → legacy/domain/index.ts 各领域的构建函数 → Matter 设备类型 行为服务器 → .set({ homeAssistantEntity })分发器维护了一张domain → 构建函数的映射表例如light → LightDevice、switch → SwitchDevice、cover → CoverDevice、climate → ClimateDevice、vacuum → VacuumDevice等几乎覆盖了 supported-device-types.md 列出的所有设备类型。每个领域的index.ts干三件事选对设备类型例如灯光会依据supported_color_modes在OnOffLight/DimmableLight/ExtendedColorLight之间挑选见 light/index.ts。按能力追加行为有电量就加DefaultPowerSourceServer映射了功率/能量传感器就加HaElectricalPowerMeasurementServer。最后.set()注入实体得到一个可直接实例化的端点类型。端点生成后会经过validateEndpointType()体检validate-endpoint-type.ts对照 Matter 规范检查必填集群是否齐全缺失时打警告日志帮你尽早发现配方写错了。 更完整的管线端点如何被刷新、如何把 HA 状态批量灌进 matter.js见 endpoints.md 与 bridge-endpoint-manager.ts。五、用插件扩展自定义 Matter 设备不想改主代码HAMH 提供了插件系统packages/backend/src/plugins/让你用 JS 就能注册设备甚至自带一个用 matter.js 构建的EndpointType来暴露 HAMH 未内置的集群/命令。官方示例 hamh-plugin-example/index.js 演示了注册一个虚拟温度传感器在onStart()里调用context.registerDevice(...)声明deviceType与集群初始属性再用context.updateDeviceState(...)周期性更新读数。想上完全自定义设备时PluginDevice支持直接传endpointType字段见 types.tsawait context.registerDevice({ id: my-custom-1, name: My Custom Device, endpointType: MyDeviceType, // 自己用 matter.js .with() 拼好的类型 clusters: [ /* 集群与初始属性 */ ], onAttributeWrite: async (clusterId, attribute, value) { /* 收到控制器写操作 */ }, });⚠️ 注意插件里的matter/*版本必须与 HAMH 锁定的版本一致当前为0.17.9否则EndpointType会因来自不同 matter.js 实例而被拒绝。六、关键源码路径速查想动手前先把这几处地图存好均为仓库内相对路径想做什么去看这里写一个新集群行为behaviors/参考on-off-server.ts、temperature-measurement-server.ts理解 HA↔Matter 的脊梁home-assistant-entity-behavior.ts安全写状态apply-patch-state.ts按领域拼端点endpoints/legacy/如light/、switch/、cover/领域分发入口create-legacy-endpoint-type.ts集群枚举校验common/src/clusters/index.ts插件扩展设备plugins/ examples/hamh-plugin-example/官方概念文档developer/behaviors.md、developer/endpoints.md七、添加一个新设备域的完整步骤结合上面内容给 HAMH 加一个新领域/新设备的标准流程是定行为在behaviors/里实现或复用所需集群 Server遵循initialize() → update() → applyPatchState()套路配置用ValueGetter/ValueSetter。拼端点在endpoints/legacy/domain/index.ts写一个构建函数选 matter.js 设备类型用.with()挂上BasicInformationServer、IdentifyServer、HomeAssistantEntityBehavior及你的行为最后.set({ homeAssistantEntity })。接分发把domain → 构建函数加进createLegacyEndpointType()的deviceCtrs表若用到新集群先在 clusters/index.ts 的ClusterId枚举里登记。过校验让validateEndpointType()通过确认必填集群齐全。补兼容在 controller-compatibility.md 补一行各控制器的支持情况。 小结Behavior 让你专注一个集群怎么和 HA 对话Endpoint 让你专注一台设备长什么样。二者通过 matter.js 的.with()组合、.set()注入数据构成了 HAMH 可扩展、易维护的 Matter 设备体系——这也是它能把上百种 HA 实体稳定发布到各家 Matter 控制器的底气所在。赞分享【免费下载链接】home-assistant-matter-hubPublish your Home-Assistant Instance using Matter.项目地址https://gitcode.com/gh_mirrors/hom/home-assistant-matter-hub点击查看免费下载相关推荐Home-Assistant-Matter-Hub 使用教程Home Assistant Matter Hub 使用教程 1. 项目介绍 Home Assistant Matter Hub 是一个开源项目旨在帮助用户将Home Assistant Matter Hub 终极配置指南Home Assistant Matter Hub 终极配置指南 Home Assistant Matter Hub 是一个强大的开源工具它能够将您的 HomHome-Assistant-Matter-Hub 安装与配置完整指南Home Assistant Matter Hub 安装与配置完整指南 项目介绍 Home Assistant Matter Hub 是一个开源项目它能够帮助创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考