Home Assistant HomematicIP Cloud 集成：set_home_cooling_mode 动作实现全屋采暖/制冷模式切换-二趣网

Home Assistant HomematicIP Cloud 集成：set_home_cooling_mode 动作实现全屋采暖/制冷模式切换

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本文以 Home Assistant 官方文档仓库中homematicip_cloud.set_home_cooling_mode动作页为核心，讲解如何在 HomematicIP Cloud 集成中通过自动化、脚本与 YAML 配置，一键将整个 Homematic IP 家庭在"采暖"与"制冷"两种运行模式之间切换，并结合集成文档与相关动作页面说明其参数语义、适用前提和排障入口。

动作概述：全屋级别的采暖/制冷开关

homematicip_cloud.set_home_cooling_mode动作用于在 Home Assistant 中切换整个 Homematic IP 家庭的暖通运行方向：

将cooling设为true：把全屋切换到制冷模式（cooling mode）；
将cooling设为false：恢复为采暖模式（heating mode）。

这个动作的粒度是"整屋"而非单个房间或单个气候实体，适合在季节交替、室外温度变化等场景下由自动化统一调度所有房间的供暖/制冷策略。需要特别注意的适用前提有两个：

该动作仅对 Home Assistant 的管理员用户可用（管理员权限限制来自动作文档本身）；
HomematicIP Cloud 集成以"云推送"（Cloud Push）方式接入 Homematic IP 的云端服务器，API 无官方文档、基于逆向工程实现，因此实际行为以 Homematic IP 云端逻辑为准。

在用户界面（UI）中配置该动作

如果你倾向可视化地搭建自动化，Home Assistant 会引导你逐步完成，无需任何 YAML 知识。完整操作步骤（继承自动作文档）：

进入设置 > 自动化与场景（Settings > Automations & scenes）。
打开一个现有自动化或脚本，或者选择创建自动化 > 创建新自动化。
如果是新建自动化，在When部分添加触发条件；脚本不需要触发条件，它在被其他逻辑调用时执行。
在Then do部分选择添加操作（Add action）。
在搜索框中搜索并选择HomematicIP Cloud: Set home cooling mode。
切换到制冷模式就把Cooling打开，切换到采暖模式就关闭它。
选择保存（Save）。

此外，该动作不支持 target 目标。在 UI 中你不会看到选择区域（area）、设备（device）、实体（entity）或标签（label）的提示——这是由动作本身的语义决定的：它作用于整个家庭，而非某个具体对象。

UI 中的选项

选项	说明	是否必填
Cooling	打开为制冷模式，关闭为采暖模式	否
Access point ID	Homematic IP 接入点的 ID，即 SGTIN（Serialized Global Trade Item Number，序列化全球贸易项目号码）。如果只有一个接入点，可以省略	否

在 YAML 中使用该动作

如果直接编写 YAML，或者想弄清 Home Assistant 底层实际下发的是什么内容，YAML 中该动作的名称为homematicip_cloud.set_home_cooling_mode。文档给出的基础示例：

action: | action: homematicip_cloud.set_home_cooling_mode data: cooling: true

这条调用会把整个家庭切换到制冷模式；将cooling改为false（或省略，见下节默认值说明）则恢复采暖。

YAML 中的完整选项参考

字段	类型	必填	默认值	说明
`cooling`	boolean	否	`true`	打开为制冷模式，关闭为采暖模式
`accesspoint_id`	string	否	—	Homematic IP 接入点的 ID（SGTIN）。若只有一个接入点可省略

两个细节值得注意：

cooling的默认值是true（YAML 选项中明确标注default: true），也就是说只写action: homematicip_cloud.set_home_cooling_mode而不带data时，语义上等同于请求制冷模式；
多接入点部署时，accesspoint_id的获取方式在集成文档中有说明：可以在 HomematicIP Cloud 集成页面顶部找到，或查看接入点背面印刷的编号。

背景：HomematicIP Cloud 集成是如何工作的

理解该动作的前置条件，需要简单了解其所属集成（参见 HomematicIP Cloud 集成文档）：

该集成自 Home Assistant 0.66 版本引入，是一个hub 类型的集成，ha_iot_class为Cloud Push——即 Home Assistant 与 Homematic IP 云端服务器通信，设备事件经云端推送到 Home Assistant；
由于 Homematic IP 云 API 没有官方文档，整个集成基于逆向工程完成，集成文档也明确提示"按自身风险使用"；
集成支持的实体平台包括 alarm_control_panel、binary_sensor、button、climate、cover、diagnostics、event、light、lock、sensor、siren、switch、valve、weather 等，其中climate平台是暖通类动作（如本文的采暖/制冷切换）的实体基础：每个房间对应一个 Homematic IP 供暖组（HmIP-HeatingGroup）生成的 climate 实体，由墙装/散热器温控器或温湿度传感器提供读数；
集成支持配置流（config flow），也保留了手动 YAML 配置方式（accesspoint+authtoken）；
集成文档中有一条对所有"作用于接入点"的动作通用的备注：所有此类动作都接受可选的accesspoint_id参数（SGTIN），单接入点部署可省略——本文动作的accesspoint_id选项正是这一通用约定的具体体现。

从文档结构看，set_home_cooling_mode属于 HomematicIP Cloud 域下少数直接操作"整个接入点/家庭"级别状态的云端动作之一，而非操作某个具体设备实体，这解释了它为什么没有 target、为什么只暴露cooling这一个核心参数。

与其他 HomematicIP Cloud 暖通动作的配合

动作文档的 front matter 中声明了三个相关动作（related actions），它们与set_home_cooling_mode共同构成 Homematic IP 暖通控制的动作族：

Set active climate profile：切换某个 Homematic IP 气候实体的活动气候配置（climate profile）索引，索引从 1 开始，与 Homematic IP 应用中显示的 profile 顺序一致；
Activate eco mode with duration：以分钟为单位定时激活接入点的节能模式（eco mode），时长结束后自动退出；
Activate vacation：激活接入点的度假模式（vacation mode），保持目标温度直至指定日期时间自动退出。

典型的季节切换场景可以这样组合：先调用set_home_cooling_mode（cooling: true）把全屋方向切到制冷，再在夜间用activate_eco_mode_with_duration降低能耗；返程时用deactivate_vacation之类的动作退出度假模式。这些动作大多同样遵循"接入点级操作 + 可选accesspoint_id"的参数约定。

验证动作行为：开发者工具中的 Actions 面板

想在不写任何 YAML 的情况下立即验证该动作，可以打开设置 > 工具 > Actions（即 Developer tools 的 Actions/Services 面板），搜索set_home_cooling_mode，填写cooling字段后选择Perform action，即可在真实设备上观察全屋模式切换的实际效果。

排障与注意事项小结

权限：该动作仅管理员可调用，普通用户角色下可能无权限执行；
多接入点：多接入点部署务必传accesspoint_id（SGTIN），否则会操作默认接入点；ID 可在集成页面顶部或接入点背面查看；
依赖云端：由于集成走 Cloud Push 通道，若 Homematic IP 接入点的云连接异常（可通过集成文档列出的HmIP-HAP云连接二进制传感器观察），动作将无法生效；
设备支持范围：Homematic IP 云端的能力受设备族支持程度限制，若某些暖通行为不可用，可先下载诊断文件（集成页面 > Download diagnostics，已匿名化）确认接入点上报的设备与状态；
遇到其他问题，可参考文档给出的社区渠道（Discord、社区论坛、/r/homeassistant）求助，提问时附上调用的动作与预期结果。

小结：homematicip_cloud.set_home_cooling_mode是一个参数极简、语义明确的家庭级动作——一个布尔值cooling决定全屋暖通方向，一个可选的accesspoint_id定位接入点。掌握它之后，配合气候 profile 切换、节能与度假模式动作，就能在 Home Assistant 中构建完整的季节性暖通调度自动化。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析