Home Assistant Sensibo 集成：用 sensibo.get_device_capabilities 查询设备模式能力，精准配置 Climate 设备
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
本文以 Home Assistant 文档仓库中sensibo.get_device_capabilities动作页为核心，完整讲解这一动作的用途、UI 与 YAML 两种配置方式、参数取值、响应数据结构，以及它与sensibo.full_state、sensibo.enable_climate_react等动作的协作关系。读完你可以掌握：如何在自动化和脚本中先"查询能力"再"下发状态"，从而避免向 Sensibo 设备写入 API 不接受的大小写敏感取值。
为什么需要"先查能力，再下发状态"
Sensibo 集成（集成文档）通过 Sensibo 云 API 轮询设备（默认每分钟一次），并暴露 climate 等实体。它的几个专用动作对取值有硬性要求：
sensibo.full_state：一次性向设备下发完整状态（mode、温度、风扇、摆动、灯光等）；sensibo.enable_climate_react：配置 Climate React，当温度、体感温度或湿度越过阈值时自动切换到你定义的高/低状态。
这两个动作都要求所传数值与 Sensibo API 完全一致，且大小写敏感（case-sensitive）。不同型号的空调/控制器支持的风扇档位、摆动模式各不相同（例如摆动模式取值是fixedMiddleTop、fixedCenter这类驼峰命名，而不是fixed_middle_top）。如果凭感觉写值，指令可能被 API 拒绝或行为不符合预期。sensibo.get_device_capabilities就是为这个问题设计的：它返回指定 HVAC 模式下设备实际支持的设置及其允许取值列表，你可以直接把返回值复制进其他动作、自动化或脚本中。
两点关键性质（见动作文档）：
- 它把结果作为**响应数据（response data）**返回，用于在脚本/自动化中做后续模板处理；
- 它是只读查询，不会改变设备上的任何设置。
在 UI 中配置该动作
按照文档给出的步骤，在"设置 > 自动化与场景"中配置：
- 进入Settings > Automations & scenes（自动化与场景）；
- 打开一个已有的自动化或脚本，或选择Create automation>Create new automation新建；
- 如果是新建自动化，在When（触发条件）部分添加触发器；脚本不需要触发器，由其他机制调用时执行；
- 在Then do（执行动作）部分选择Add action；
- 在By target（按目标）下选择你的 Sensibo climate 设备实体；
- 在该目标可用的动作中选择Sensibo: Get device mode capabilities；
- 选择要查询的HVAC mode；
- 选择Save保存。
参数说明
UI 与 YAML 中的选项一致，核心只有一个必填参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
hvac_mode | string | 是 | 要查询能力所用的 HVAC 模式，取值：cool、heat、dry、fan、auto |
注意该参数只有这五个模式（不含off），因为它查询的是"某种工作模式下设备支持哪些设置"，而off模式没有需要查询的运行参数。目标实体通过通用的target机制指定（文档中通过domain="climate"引入的 Targets 部分说明：只能选择 Sensibo 集成提供的 climate 实体）。
YAML 配置示例
在 YAML 中该动作写作sensibo.get_device_capabilities，文档给出的基础示例如下：
action: | action: sensibo.get_device_capabilities target: entity_id: climate.living_room data: hvac_mode: cool response_variable: capabilities其中response_variable: capabilities把动作返回的能力映射存入名为capabilities的变量，供同一脚本/自动化中的后续步骤或模板引用，而不仅仅是查看。
响应数据结构与大小写敏感问题
动作返回一个映射（mapping），描述设备在所选 HVAC 模式下支持的设置，以及每个设置的允许取值列表。根据设备不同，可能包括：
- 风扇档位（fan levels）；
- 摆动模式（swing modes）；
- 水平摆动模式（horizontal swing modes）；
- 目标温度（target temperatures）；
- 灯光选项（light options）。
文档特别强调：返回的取值大小写敏感，必须原样复制。这一点从相关动作的示例中可以直观看到。在 sensibo.enable_climate_react 文档 中，完整状态（full state）的字段是驼峰命名的on、targetTemperature、mode、fanLevel、temperatureUnit、swing、horizontalSwing、light，取值如fixedBottom、fixedLeft、stopped：
action: | action: sensibo.enable_climate_react target: entity_id: climate.living_room data: high_temperature_threshold: 24 high_temperature_state: on: true targetTemperature: 21 mode: cool fanLevel: high temperatureUnit: C swing: stopped horizontalSwing: stopped light: "on" low_temperature_threshold: 19 low_temperature_state: on: true targetTemperature: 23 mode: heat fanLevel: high temperatureUnit: C swing: stopped horizontalSwing: stopped light: "on" smart_type: temperature而sensibo.full_state（见其文档）中的字段则采用下划线命名（target_temperature、fan_mode、swing_mode、horizontal_swing_mode、light），但取值本身仍然大小写敏感（如集成文档示例中的swing_mode: fixedMiddleTop、horizontal_swing_mode: fixedCenter，见 Sensibo 集成文档 的 Examples 部分）：
automation: alias: "Example full state" triggers: - trigger: time at: "18:00:00" actions: - action: sensibo.full_state data: mode: "heat" target_temperature: 23 fan_mode: "medium" swing_mode: "fixedMiddleTop" horizontal_swing_mode: "fixedCenter" light: "off" target: entity_id: climate.hvac_device这正是get_device_capabilities的价值所在：不同设备的fanLevel/swing合法集合不同，与其记忆这些值，不如先跑一次查询、把允许值列表拉下来再填写。同时记住两条规则（来自 full_state 文档的 "Good to know"）：只下发你的设备支持的字段；所有取值必须与 Sensibo API 期望的完全一致。
推荐的实战工作流
结合文档仓库中该动作的"related actions"引用关系（sensibo.full_state与sensibo.enable_climate_react均在元数据中把本动作列为相关动作），一套典型配置流程是：
- 查询：在脚本或自动化中调用
sensibo.get_device_capabilities，指定hvac_mode（如cool），用response_variable保存结果； - 确认取值：查看返回的允许值映射，确认目标模式下的风扇档位、摆动模式、温度范围等；
- 下发：把确认过的取值填入
sensibo.full_state（一次性完整状态）或sensibo.enable_climate_react的高/低状态 map 中； - 验证：打开Settings > Tools > Actions（开发者工具的动作页面，即文档中 "Try it yourself" 部分所指入口），搜索该动作、填写字段并Perform action，无需写 YAML 即可在真实设备上验证效果。
同一动作家族中还有几个可配合使用的动作：sensibo.assume_state（仅更新 Sensibo 侧认为的设备开/关状态，不向设备发命令，用于物理遥控导致失步时纠正，见其文档）、sensibo.enable_timer、sensibo.enable_pure_boost。另外从集成文档可见：该集成为云轮询（Cloud Polling）架构、需先在 Sensibo 网站注册 API key 完成配置流，且部分实体默认禁用、需手动启用——理解这些背景有助于解释为何"能力"随设备型号而差异明显。
小结
sensibo.get_device_capabilities是 Sensibo 集成中"只读、返回响应数据、大小写敏感"三特征兼具的查询动作：它以hvac_mode（cool/heat/dry/fan/auto）为唯一必填参数，返回所选模式下设备支持的设置及允许取值。把它放在full_state或enable_climate_react之前执行，是保证下发取值与 Sensibo API 完全匹配的最可靠方式。本文所有配置示例均可在仓库对应文档中找到原文：动作主文档、full_state、enable_climate_react 与 Sensibo 集成说明。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
