63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# Home Assistant Outbound Integration
|
|
|
|
本文档说明当前 Python 项目中已经迁入的 Home Assistant outbound integration layer。
|
|
|
|
这里的 outbound 指：
|
|
|
|
- 由当前 app 主动调用 Home Assistant
|
|
|
|
当前不包含：
|
|
|
|
- `/homeassistant/publish`
|
|
- Home Assistant inbound command gateway
|
|
- Home Assistant 驱动当前 app 的入站消息路由
|
|
|
|
## 当前已支持能力
|
|
|
|
当前 `app/integrations/homeassistant.py` 提供一个轻量的 `HomeAssistantClient`，已支持：
|
|
|
|
- 发布 / 更新 sensor state
|
|
- `POST /api/states/{entity_id}`
|
|
- 触发 Home Assistant webhook
|
|
- `POST /api/webhook/{webhook_id}`
|
|
|
|
这两项能力是按 legacy Go 中 `util/homeassistantutil/homeassistantutil.go` 的出站行为迁入的。
|
|
|
|
## 当前配置
|
|
|
|
当前 outbound adapter 依赖以下配置：
|
|
|
|
- `HOME_ASSISTANT_BASE_URL`
|
|
- `HOME_ASSISTANT_AUTH_TOKEN`
|
|
- `HOME_ASSISTANT_TIMEOUT_SECONDS`
|
|
|
|
如果缺少必要配置，client 会直接抛出配置错误，而不是静默跳过。
|
|
|
|
## 错误处理策略
|
|
|
|
当前策略保持保守和简单：
|
|
|
|
- 配置缺失：抛出 `HomeAssistantConfigError`
|
|
- 参数明显非法：抛出 `ValueError`
|
|
- Home Assistant 返回非 200/201：抛出 `HomeAssistantRequestError`
|
|
- 网络请求失败：抛出 `HomeAssistantRequestError`
|
|
|
|
当前还没有做：
|
|
|
|
- 自动重试
|
|
- 熔断
|
|
- 更复杂的 backoff 策略
|
|
|
|
这一轮重点是先把 app -> Home Assistant 的出站契约和可复用结构迁进来。
|
|
|
|
## Energy、Source 与热力实体
|
|
|
|
Expose 框架还可以把已勾选的 Energy 实体通过 MQTT Home Assistant Discovery 发布；开关位于应用 Config 页的 HA Expose 面板，默认均为关闭。M8 增加了 source online、按 Meter UUID 锚定的累计量/today，以及 heating、hot-water-heating、water、water-tax、fixed、all-in total/today 等 thermal 实体。
|
|
|
|
- source 和 Meter identity 不依赖可变 label；换表会产生新 Meter UUID identity。
|
|
- thermal 组合成本 identity 由当前 heating/hot_water Meter UUID 的有序组合锚定，任一换表都会产生新 identity，避免不同累计域拼接。
|
|
- availability、unit、device/state class 与 today reset 由 provider 声明；operator 应在 HA 中核对，而不应假设同名实体可跨换表连续。
|
|
- 关闭 toggle 后 retained discovery 会被清理；关闭暴露不删除 source、Meter、合同、读数或成本历史。
|
|
|
|
WarmteLink 的 P1 质量会原样保留为 `unverifiable`（若适用），不因发布到 HA 而提升为 `valid`。不要将 raw telegram、equipment id、串口路径、合同金额或 API secret 作为 HA entity/state/attribute 发布。
|