# Pre-M8 — WarmteLink P1 真机概念验证

> **状态：等待 USB→P1 线到货后执行。** 本文只定义验证边界与证据要求；当前仓库尚未实现下文所示的 probe 命令。

## 1. 目的

在进入 M8 正式设计和实现前，先用新家的 Vattenfall WarmteLink 做一次只读真机验证，回答以下问题：

1. 当前 USB→P1 线、主机串口权限和 WarmteLink P1 端口能否稳定输出完整 telegram。
2. telegram 的 framing、CRC、时间戳、OBIS/M-Bus channel 和单位能否被 parser 正确识别。
3. 实际能够读取哪些累计量：区域供暖热量（GJ）、生活热水体积（m³）或其它字段。
4. 读数的精度、更新频率和累计语义，是否与热力表/水表面板上的数字一致。

Pre-M8 是 M8 的证据门：在真机字段和语义确认前，不决定数据库结构、Meter 数据源绑定、后台采集服务或前端布局。

## 2. 执行边界

本阶段只建立下面这条最短链路：

```text
WarmteLink P1 → USB serial → 完整 telegram → CRC 校验 → 字段解析 → 终端输出
```

明确不做：

- 不写入 `app.db`，不新增 Alembic migration。
- 不新增 FastAPI API、后台常驻 worker、配置页面或 Energy 前端。
- 不发布 MQTT / Home Assistant Discovery。
- 不修改现有 DSMR Reader MQTT、电费计算或 Meter 逻辑。
- 不在本阶段决定 WarmteLink 应落在哪个正式 Device/Source 模型中。

## 3. 预期操作方式

线到货后，在 workspace 的 virtual environment 中实现并运行一个只读 probe。命令形态暂定为：

```bash
source .venv/bin/activate
python -m scripts.p1_probe \
  --device /dev/serial/by-id/<usb-p1-device> \
  --duration 600 \
  --show-changes \
  --raw-output /tmp/warmtelink-p1-telegram.txt
```

最终参数名可在实现 probe 时调整，但应保留这些能力：

- 使用稳定的 `/dev/serial/by-id/...` 路径，而不是依赖可能变化的 `/dev/ttyUSB0`。
- 连续读取多帧，而不是只看一帧偶然样本。
- 同时显示完整帧/CRC 结果、原始 OBIS 字段和解析后的值/单位。
- 枚举 telegram 中出现的所有 M-Bus channel、device type、equipment id、capture timestamp、value 和 unit，不依赖固定字段顺序。
- 可只显示发生变化的字段，便于观察更新频率。
- 原始 telegram 默认只写到 `/tmp`；未经脱敏不提交到 Git。

### 3.1 分两步 bring-up：Bash 冒烟验证 → Python probe

Home Assistant Community 的一份 WarmteLink 实例提供了一个适合作为硬件
bring-up 起点的[最小 Bash 读取方法](https://community.home-assistant.io/t/solved-dsmr-add-warmtelink-as-data-source/485255/2)：
先把串口设为 115200 baud，逐行读取设备，并从带 `GJ` 的行中取出累计值。该帖展示的
telegram 样例还给出了以下**候选事实**：

- 设备头为 `/NWA-WARMTELINK`，版本字段为 `1-3:0.2.8(50)`。
- M-Bus channel 1 的 device type 样例为 `004`。
- 累计热量样例位于 `0-1:24.2.1(<capture timestamp>)(<value>*GJ)`。
- telegram 以 `!` 加四位 CRC 结束。

这些是其他用户在 2022 年记录的单机样本，只用于提出假设，不能替代本机 firmware、线材和
实际 telegram 的验证。当前 Home Assistant 的
[DSMR 文档](https://www.home-assistant.io/integrations/dsmr/)确认其 DSMR 集成支持 DSMR v5 与
M-Bus subdevice；该集成底层使用
[`dsmr_parser`](https://github.com/ndokter/dsmr_parser)。实现 probe 时可把它作为候选解析基线
进行对照，但是否引入为本项目正式依赖留到 M8 Planning 决定。

线到货后的执行顺序调整为：

1. **Bash 冒烟验证**：用稳定的 `/dev/serial/by-id/...` 路径配置串口并短时读取；先保留完整
   原始字节流，再确认是否能看到 `/NWA-WARMTELINK`、帧尾和带 `GJ` 的行。论坛脚本中的
   `GJ` 文本提取只能用作快速可见性检查，不能算解析或验收通过。
2. **Python probe**：在已确认物理链路工作的前提下，实现上面的 `scripts.p1_probe`，完成
   完整 framing、CRC、全部字段枚举、结构化解析、连续多帧变化观察和人工面板对照。

不复制论坛脚本的 MQTT 发布步骤：Pre-M8 仍只输出到终端和 `/tmp`，MQTT / Home Assistant
集成属于 M8 设计范围。

## 4. 人工对照

probe 运行期间，人工从热力表和相关水表面板记录同一时间附近的显示值，并与终端结果对照：

| 检查项 | 需要记录 |
| --- | --- |
| 区域供暖 | 面板累计值、P1 值、单位、两者时间差 |
| 生活热水 | 面板累计值、P1 是否存在对应字段、单位、两者时间差 |
| 更新时间 | 连续 telegram 中数值变化的间隔 |
| 累计语义 | 数值是否单调累计，是否出现每日归零或其它重置 |

允许 P1 capture time 与按表时间之间存在合理延迟；不能只凭数值接近就认定字段含义，必须同时核对单位、channel/device type 和时间戳。

## 5. 通过条件

Pre-M8 完成需留下以下证据：

- [ ] 连续收到可识别为 WarmteLink 的完整 telegram。
- [ ] CRC 校验通过；若失败，已区分串口/线材问题与 parser 问题。
- [ ] parser 不依赖字段固定顺序，并列出全部实际 channel/OBIS 字段。
- [ ] 找到 GJ 累计值并与热力表面板对照，误差可由显示精度或 capture 延迟解释。
- [ ] 明确实际 telegram 是否包含独立的生活热水 m³ 累计量；若包含，已与水表面板对照。
- [ ] 记录数值精度、telegram 频率、字段更新频率和累计/重置行为。
- [ ] 形成一份脱敏结果摘要，足以支持下一轮 M8 Planning。

如果只能确认 GJ、没有独立生活热水 m³，这也是有效结论，不视为 Pre-M8 失败。

## 6. 失败分类

- 完全无数据：优先检查 USB 识别、串口权限、P1 request line、线材方向/供电。
- 输出乱码或不成帧：优先检查串口参数、信号反相和线材兼容性。
- 原始帧完整但解析失败：保存脱敏样本，调整 parser/字段映射。
- 解析成功但面板对不上：检查 capture timestamp、累计语义、单位和 WarmteLink firmware 差异。

## 7. 向 M8 的交付物

Pre-M8 只向 M8 交付事实，不交付正式架构：

- 已脱敏的 telegram 结构与字段清单。
- GJ / 可选 m³ 的实际 channel、OBIS、单位、精度和更新时间。
- 串口参数、稳定设备路径与部署权限要求。
- parser 适配结论以及需要保留的异常样本。
- 对“一个来源包含几个可用计量通道”的实测结论。