LocalThings config_flow 源码走读:setup/reconfigure/reauth 状态机

原创2026-11-11 20:06:311,851 阅读
文章标签:物联网智能家居插件系统

LocalThings config_flow 源码走读:setup/reconfigure/reauth 状态机

LocalThings 是一个让 Home Assistant 通过家庭局域网直接控制三星(Samsung)家电的开源集成,完全不需要三星云端账号。它最核心的入口文件是 config_flow.py(约 2600 行),里面用一个典型的"config flow 状态机"管理了三类流程:setup(新增设备)、reconfigure(修改 IP) 和 reauth(重新认证)。本文带你走读这个状态机:每个步骤何时被触发、失败后流向哪里、成功后如何落成一条配置条目。

LocalThings 三星家电 Home Assistant 本地控制集成 logo

一、先认识状态机的"骨架":LocalThingsConfigFlow

Home Assistant 的集成配置流程是一个由若干 async_step_xxx 步骤组成的状态机:每个步骤要么渲染一个表单(async_show_form)、要么弹出菜单(async_show_menu)、要么创建条目、要么中止(async_abort)。LocalThings 的主状态机定义在 LocalThingsConfigFlow:

class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
    VERSION = 4

几个关键事实:

  • VERSION = 4:条目直接以 v4 形状创建(以 OCF 设备 UUID 为主键),老条目则由 init.py 里的 async_migrate_entry 逐级迁移。
  • 实例状态字段(__init__,config_flow.py#L1036-L1058):_host、_ca_cert_pem、_legacy_leaf、_legacy_token、_psk 等,就是跨步骤传递的"流转上下文"。
  • 失败分类:文件开头定义了一棵异常树(config_flow.py#L138-L270),CannotConnect 是基类,NoResponse、PortsClosed、CertRejected、PskRejected、HandshakeTimeout 等子类各自带一个 error_key,最终映射到 translations/en.json 中给用户看的友好文案。

💡 记住这个设计:每个异常子类 = 一种失败场景 = 一条用户看得懂的提示,这是整个 setup 体验的地基。

二、setup 主流程:从一个 IP 地址开始

1. 入口步骤 async_step_user

用户点击"添加集成 → LocalThings"后进入 async_step_user,表单只有一个字段:家电的 IP 地址。逻辑分四路:

探测结果 去向
探测成功 _finish_probe → 创建条目
LegacyHttpFamily(老设备走 8888 端口) async_step_legacy_token
CertRejected(自动证书被拒) async_step_credential(凭证菜单)
其他 CannotConnect 原地报错,留在表单

细节亮点:

  • 复用凭证(config_flow.py#L1143-L1170):如果系统里已有"证书类"条目,会优先复用其已铸造的 leaf 证书(所有家电都接受同一张 leaf),省得重新联网取 UUID。此时步骤 id 变为 user_reuse(对应 async_step_user_reuse),表单文案不同但逻辑完全复用。
  • 固定源端口(_setup_source_port):对没有条目的 host 使用固定本地端口握手,避免反复重试时在家电端留下一堆"僵尸"DTLS 关联(固件不会主动清理旧 peer)。

2. 探测引擎 _probe_and_validate

真正干活的是模块级函数 _probe_and_validate,流程是:

  1. probing.look(host) 先扫端口——不需要任何凭证,所以 host 不可达会在这里快速失败,而不是白白连一次三星云;
  2. 没有 CA 时默认自签 leaf 证书(_mint_self_signed,config_flow.py#L393-L434),大多数新机型(AC14K_M 世代)接受;
  3. _handshake_and_read(config_flow.py#L888-L937)逐个候选端口握手,对"已知可重试"的失败(peer 碰撞、已确认端口的超时)给一次同端口重试(_worth_retrying);
  4. 全部失败时,_classify_handshake_failure 综合端口扫描形状 + TLS alert 把"没连上"翻译成最具体的那条错误。

3. 去重与落库 _finish_probe

探测成功进入 _finish_probe:

  • 先检查"遗留 serial 主键 + 相同 host"的旧条目,防止重复添加(否则未来 rekey 会删掉原条目的实体和历史);
  • 再用 async_set_unique_id(f"localthings_{device_key}") 按 OCF 设备 UUID 去重——因为部分机型出厂就带相同序列号,serial 不可靠;
  • 设备类型能识别 → _create_entry 直接建条目;不能识别 → 转 async_step_confirm_unknown_type(config_flow.py#L1657-L1672),把型号信息展示给用户,方便其提交诊断报告。

三、两条"备用凭证"支线

1. 凭证菜单与 PSK 支线

自动证书被拒后,async_step_credential 弹菜单:psk_owner / psk_peer / fallback_ca 三项。它还会先读设备明文 doxm 元数据做提示(read_credential_hint),如果设备自报用 PSK 认证,则直接进入 async_step_credential_psk(只是描述文案不同)。

  • PSK 表单(_psk_step)校验 identity/key 后走 _probe_psk 验证;PSK 条目要求设备必须回报可用的 /oic/d di(IdentityUnproven),因为那是 PSK 条目唯一的设备绑定。
  • async_step_fallback_ca 让用户粘贴 AC14K_M 的 CA 证书与私钥,铸出链签 leaf 再探测;再被拒则回到 async_step_ca_rejected 菜单,而不是让用户无限次重贴 CA。

2. 老设备 8888 支线(legacy HTTP)

约 2018–2022 年的部分机型走 HTTPS-on-TCP-8888 老接口。探测到 LegacyHttpFamily 后:

  1. async_step_legacy_token:表单可粘贴 device token;留空提交则触发设备下发 token;
  2. async_step_legacy_token_exchange:用 async_show_progress 进度步骤等待设备回调到 8889 端口(最长约 90 秒),而不是挂住表单;
  3. async_step_legacy_token_received 收结果:回调被拒证书 → 转 fallback_ca;端口被占用 / 未收到 token → 回到 token 表单并给出对应错误;
  4. _finish_legacy 用 token 真正读取设备身份,最终汇入 _finish_probe(新增)或更新条目(reauth,见下节)。

四、reconfigure:改地址而不丢历史

async_step_reconfigure 解决"家电换了 IP"的问题——删掉重加会丢掉实体 id、历史和自动化。它的分支很清晰:

  • PSK 条目 → _probe_psk 用存好的密钥验证;
  • legacy 条目 → _probe_legacy 用存好的 token 验证;
  • DTLS 条目 → _probe_and_validate 复用存好的 leaf。

验证通过后必须过 _identity_matches 这一关(与轮询端的身份解析同一套逻辑):防止你把一个数字敲错,结果把这条目的注册表行"过户"给另一台家电。确认后更新 host/port/MAC/read_mode,调度重载,并以 reconfigure_successful 结束(见 _update_reload_and_abort)。

📌 相关的 async_step_dhcp 则是它的"自动版":条目里存了 MAC 时,DHCP 租约搬家会被 HA 自动发现并直接改写条目地址,同样校验后重载。

五、reauth:token 401 后的重新认证

reauth 是 Home Assistant 的"配置条目认证失效"机制。在 LocalThings 里只有 legacy 8888 条目会触发——当设备返回 401(token 失效)时:

  1. async_step_reauth:非 legacy 传输直接 abort("reauth_unsupported");否则取出条目的 leaf/CA,把返回步骤设为 reauth_confirm;
  2. async_step_reauth_confirm:与 setup 共用同一张 token 表单和同一套 exchange 步骤;
  3. _finish_legacy 检测到 source == SOURCE_REAUTH,走另一分支:校验身份匹配(不匹配报 wrong_device),然后用新 token(及可能的 CA 签 leaf)async_update_entry + 重载,以 reauth_successful 中止。

可以看到 setup 与 reauth 共享了 8888 支线的大部分代码,只在"落库动作"处分叉——这是状态机复用的典型范例。

六、状态机总览

步骤 (step_id) 触发场景 可能去向
user / user_reuse 手动添加设备(首台 / 复用凭证) 建条目、legacy_token、credential、原地报错
credential / credential_psk 自动证书被拒 psk_owner、psk_peer、fallback_ca
fallback_ca 粘贴 AC14K_M CA 并重试 建条目、ca_rejected
legacy_token → legacy_token_exchange → legacy_token_received 8888 设备取 token 建条目 / fallback_ca / 原地报错
confirm_unknown_type 设备类型无法识别 建条目(用户确认)
reconfigure 手动改 IP 更新条目 + 重载,或原地报错
reauth → reauth_confirm 8888 token 401 更新条目 + 重载
dhcp MAC 匹配的租约搬家 自动改址 + 重载,静默中止

以上每一步的用户可见文案都在 translations/en.json(含 13 种语言),流程行为则由 tests/test_config_flow.py 及 tests/test_legacy_flow.py、tests/test_psk_flow.py 等用例覆盖。

七、顺带一提:OptionsFlow

同一文件下半部分是 LocalThingsOptionsFlow,即"每设备设置"菜单:常规设置(写入豁免、结束时间迟滞、模式记忆)、子设备开关、云端课程引导命名(cloud_guided/cloud_wait/cloud_name 一套进度步骤)、以及一个调试原始写入面板。它与 config flow 相互独立,但复用了 async_show_progress 的同款等待模式,读到这里理解起来很轻松。

八、小结:为什么值得读这个文件

  • 状态机思维:所有跨步骤数据都在实例字段里显式流转,分支只有"表单 / 菜单 / 创建 / 中止"四种出口,易于推演;
  • 错误即分类:一棵带 error_key 的异常树,把"连不上"细化到证书被拒、PSK 不符、端口全关等十几种,文案友好且可测试;
  • 复用而非复制:setup 与 reauth 共用 8888 支线,reconfigure 与轮询共用身份校验,_finish_probe 是所有"探测成功"的唯一汇合点。

如果你想继续深入,建议按 _probe_and_validate → _handshake_and_read → probing.py 的顺序读,再看 credentials.py 中凭证归一化与 check_device_binding,即可把整条 setup 链路吃透。

登录后查看全文
localthings