企业官网建设流程全解析

Home Assistant 智能水疗（SmartTub）集成：使用 smarttub.set_secondary_filtration 动作管理热水浴缸次级过滤模式

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

导读

本文围绕 Home Assistant 官方文档仓库中的smarttub.set_secondary_filtration动作（Action）展开，讲解如何通过该动作在自动化与脚本中更新 SmartTub 热水浴缸的次级过滤模式。读完本文，你将掌握该动作的 UI 可视化配置步骤、完整 YAML 语法与参数取值范围、目标（Target）选择机制，以及一个"离家自动降低过滤强度"的实战自动化范例，让浴缸在你离家时自动进入省电的 away 模式。

背景：SmartTub 集成与次级过滤

SmartTub 是 Home Assistant 官方支持的云轮询（Cloud Polling）集成，用于查看和控制使用 SmartTub 系统，该集成通过配置流（Config Flow）完成账户接入，属于 hub 类型集成，提供以下实体平台：

• binary_sensor（二进制传感器）
• climate（气候，用于水温控制）
• light（灯光）
• sensor（传感器，含过滤循环状态传感器）
• switch（开关）

过滤系统是热水浴缸保持水质清洁的核心环节。SmartTub 通常区分主过滤（primary filtration）与次级过滤（secondary filtration）：

• 主过滤循环可设置运行时长与起始时间（对应smarttub.set_primary_filtration动作，详见 source/_actions/smarttub.set_primary_filtration.markdown）；
• 次级过滤则是按模式（frequent / infrequent / away）切换的补充过滤周期，即本文主角smarttub.set_secondary_filtration。

每次过滤循环的状态由一个sensor实体暴露，例如sensor.jacuzzi_j_335_secondary_filtration_cycle，它既是动作的目标（target），也是你观察过滤状态的入口。

动作总览：smarttub.set_secondary_filtration

该动作在 Home Assistant 中的标识为smarttub.set_secondary_filtration，功能一句话概括：

Updates the secondary filtration mode on a hot tub.（更新热水浴缸上的次级过滤模式。）

它只有一个必填参数mode，用于指定次级过滤模式。因此它非常适合放进"离家""回家""睡眠"等场景型自动化中，实现过滤强度的动态调节。

在 UI 中配置该动作

如果你习惯可视化搭建自动化，无需接触 YAML。官方文档给出了完整的分步指引（见 source/_actions/smarttub.set_secondary_filtration.markdown）：

1. 进入设置 > 自动化与场景（Settings > Automations & scenes）。
2. 打开一个已有的自动化或脚本；或选择创建自动化 > 创建新的自动化。
3. 如果是新建自动化，在何时（When）部分添加一个触发条件；脚本无需触发器——脚本由其他自动化或调用方显式触发运行。
4. 在然后执行（Then do）部分选择添加动作（Add action）。
5. 在搜索框中搜索并选择SmartTub: Update secondary filtration settings（SmartTub：更新次级过滤设置）。
6. 在目标（By target）下选择你的热水浴缸次级过滤循环传感器（详见下文"动作的目标"一节）。
7. 选择模式（Mode）。
8. 点击保存。

整个流程由 UI 逐步引导：你只需选择目标、调整选项并保存，无需掌握 YAML 语法。

UI 中的选项

mode的三种取值含义如下：

• frequent（频繁）：过滤周期更密集，适合浴缸使用频繁、需要持续保持水质的场景；
• infrequent（不频繁）：过滤周期较稀疏，适合使用率不高的时段；
• away（离家）：最小化过滤运行，适合家中无人、浴缸长时间无人使用的场景，可显著节省电力与水处理成本。

在 YAML 中使用该动作

对于直接编写 YAML 或希望精确控制底层行为的用户，文档提供了技术参考（见 source/_includes/actions/yaml_header.md），列出了字段名、类型与必填性。

基础示例

action: smarttub.set_secondary_filtration target: entity_id: sensor.jacuzzi_j_335_secondary_filtration_cycle data: mode: away

上述配置将次级过滤循环切换为away（离家）模式。

YAML 参数表

从源码结构看（参考 source/_actions/smarttub.set_secondary_filtration.markdown 的options_yaml定义），mode是唯一参数且为必填项，因此调用该动作时必须提供mode，否则动作将无法执行。

动作的目标（Targets）机制

该动作必须指定目标。目标即动作的作用对象，你可以将动作指向单个实体（entity）、设备（device）、区域（area）、楼层（floor）或标签（label），Home Assistant 会自动对该目标下所有匹配的sensor实体执行动作（参见 source/_includes/actions/targets.md）：

• 实体：单个指定的 sensor 实体，如sensor.jacuzzi_j_335_secondary_filtration_cycle；
• 设备：属于某设备的全部 sensor 实体；
• 区域：某个房间/区域内的全部 sensor 实体；
• 楼层：某个楼层上的全部 sensor 实体；
• 标签：共享某个标签的全部 sensor 实体。

你还可以在同一次动作中混合多种目标类型，例如同时指定一个具体实体和一个区域，动作会一并作用于两者。

对于本动作的典型用法，直接以次级过滤循环传感器实体为目标即可；若你有多个浴缸，也可以把它们归入同一个区域或标签，一次动作批量切换。

实战示例：离家时自动降低过滤强度

官方文档提供了一个开箱即用的自动化场景（见 source/_actions/smarttub.set_secondary_filtration.markdown 中的details折叠块）：

场景：当你离家时，将次级过滤切换为 away 模式，让浴缸在无人使用期间减少过滤，节省能耗。

• 触发器：你离家（person.sam状态变为not_home）
• 动作：SmartTub: Update secondary filtration settings

完整 YAML 如下：

automation: alias: "Hot tub away filtration when not home" triggers: - trigger: state entity_id: person.sam to: not_home actions: - action: smarttub.set_secondary_filtration target: entity_id: sensor.jacuzzi_j_335_secondary_filtration_cycle data: mode: away

将该自动化复制到你的automations.yaml中，并把person.sam换成你自己的家庭成员 person 实体、把sensor.jacuzzi_j_335_secondary_filtration_cycle换成你浴缸实际的次级过滤传感器实体即可生效。

延伸思路

基于同一套机制，你还可以自然扩展出更多组合：

• 回家恢复过滤：以person.sam状态变为home为触发器，调用同一动作并将mode设为frequent，让浴缸在你到家前恢复高强度过滤；
• 与主过滤联动：结合 smarttub.set_primary_filtration（可设置主过滤的duration时长与start_hour起始小时）编排昼夜过滤策略，例如夜间执行主过滤、白天按次级过滤模式动态调整；
• 脚本封装：把常用过滤策略封装为脚本，供多个自动化复用。

立即测试：使用"执行动作"面板

如果你想在写任何 YAML 之前先在真实实体上验证效果，可以打开设置 > 工具 > 动作（Settings > Tools > Actions，参见 source/_includes/actions/try_it.md），搜索smarttub.set_secondary_filtration，填写字段并点击执行动作（Perform action）。你会在实际实体上立即看到变化，无需编写一行 YAML。

常见问题与排障

如果动作未按预期生效，官方文档建议从以下几个方面入手（参见 source/_includes/actions/stuck.md）：

1. 确认实体存在且可写：先在设置 > 工具 > 动作面板中执行一次动作，确认目标传感器实体状态真实存在，且浴缸在线（SmartTub 为云轮询集成，离线设备无法接收指令）；
2. 检查mode取值：该参数必填，且必须严格为frequent、infrequent或away三者之一，拼写错误或缺失都会导致调用失败；
3. 核对目标语法：确认target.entity_id与实际生成的传感器实体 ID 完全一致（可在设置 > 实体中查看）；
4. 检查自动化是否被触发：对于"离家"类自动化，确认 person 实体状态确实发生了not_home转变。

若仍有问题，可以前往 Home Assistant 社区论坛求助，发布时附上你正在调用的动作、预期结果与实际现象，便于他人快速定位。

小结

smarttub.set_secondary_filtration是 SmartTub 集成中最轻量、最实用的动作之一——它只有一个必填参数mode，却能让热水浴缸的过滤策略随你的生活方式自动调整。无论是通过 UI 可视化搭建，还是直接编写 YAML，你都可以快速实现"离家减滤、在家增滤"的节能自动化。结合同系列动作 smarttub.set_primary_filtration、smarttub.reset_reminder 与 smarttub.snooze_reminder，你可以构建出一套完整的浴缸维护自动化体系。

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