LocalThings config_flow 源码走读:setup/reconfigure/reauth 状态机
LocalThings config_flow 源码走读:setup/reconfigure/reauth 状态机
LocalThings 是一个让 Home Assistant 通过家庭局域网直接控制三星(Samsung)家电的开源集成,完全不需要三星云端账号。它最核心的入口文件是 config_flow.py(约 2600 行),里面用一个典型的"config flow 状态机"管理了三类流程:setup(新增设备)、reconfigure(修改 IP) 和 reauth(重新认证)。本文带你走读这个状态机:每个步骤何时被触发、失败后流向哪里、成功后如何落成一条配置条目。
一、先认识状态机的"骨架":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,流程是:
probing.look(host)先扫端口——不需要任何凭证,所以 host 不可达会在这里快速失败,而不是白白连一次三星云;- 没有 CA 时默认自签 leaf 证书(
_mint_self_signed,config_flow.py#L393-L434),大多数新机型(AC14K_M 世代)接受; _handshake_and_read(config_flow.py#L888-L937)逐个候选端口握手,对"已知可重试"的失败(peer 碰撞、已确认端口的超时)给一次同端口重试(_worth_retrying);- 全部失败时,_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/ddi(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 后:
- async_step_legacy_token:表单可粘贴 device token;留空提交则触发设备下发 token;
- async_step_legacy_token_exchange:用
async_show_progress进度步骤等待设备回调到 8889 端口(最长约 90 秒),而不是挂住表单; - async_step_legacy_token_received 收结果:回调被拒证书 → 转
fallback_ca;端口被占用 / 未收到 token → 回到 token 表单并给出对应错误; - _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 失效)时:
- async_step_reauth:非 legacy 传输直接
abort("reauth_unsupported");否则取出条目的 leaf/CA,把返回步骤设为reauth_confirm; - async_step_reauth_confirm:与 setup 共用同一张 token 表单和同一套 exchange 步骤;
_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 链路吃透。
