PRE-M8: record WarmteLink findings and implementation plan

docs/design/pre-m8-warmtelink-p1-poc.md

@@ -1,24 +1,27 @@
 # Pre-M8 — WarmteLink P1 真机概念验证
 
-> **状态：等待 USB→P1 线到货后执行。** 本文只定义验证边界与证据要求；当前仓库尚未实现下文所示的 probe 命令。
+> **状态：进行中。** 2026-08-22 已完成临时脚本真机 bring-up，并确认两个可用累计量；
+> 仓库内的正式 probe、解析测试和可重复验收流程尚未实现。完成下方 PRE-M8-T01～T03
+> 后，才把 Pre-M8 标记为完成并解除 M8 Planning 的入口限制。
 
 ## 1. 目的
 
-在进入 M8 正式设计和实现前，先用新家的 Vattenfall WarmteLink 做一次只读真机验证，回答以下问题：
+在进入 M8 正式设计和实现前，用新家的 Vattenfall WarmteLink 建立一条只读 P1 验证链，回答：
 
-1. 当前 USB→P1 线、主机串口权限和 WarmteLink P1 端口能否稳定输出完整 telegram。
-2. telegram 的 framing、CRC、时间戳、OBIS/M-Bus channel 和单位能否被 parser 正确识别。
-3. 实际能够读取哪些累计量：区域供暖热量（GJ）、生活热水体积（m³）或其它字段。
-4. 读数的精度、更新频率和累计语义，是否与热力表/水表面板上的数字一致。
+1. USB→P1 线、主机串口权限和 WarmteLink P1 端口能否稳定输出可解析数据。
+2. 真机使用什么串口参数，telegram 的 framing、CRC、时间戳和 OBIS/M-Bus channel 有何特征。
+3. 实际能够读取哪些累计量，以及单位、精度、更新频率和累计语义。
+4. P1 值是否与热量表/生活热水表面板一致。
 
-Pre-M8 是 M8 的证据门：在真机字段和语义确认前，不决定数据库结构、Meter 数据源绑定、后台采集服务或前端布局。
+Pre-M8 是 M8 的证据门：它只交付真机事实和可重复 probe，不决定数据库结构、Meter 数据源
+绑定、后台采集服务或前端布局。
 
 ## 2. 执行边界
 
 本阶段只建立下面这条最短链路：
 
 ```text
-WarmteLink P1 → USB serial → 完整 telegram → CRC 校验 → 字段解析 → 终端输出
+WarmteLink P1 → USB serial → 原始 telegram → 完整性状态 → 字段解析 → 终端输出
 ```
 
 明确不做：
@@ -28,99 +31,264 @@ WarmteLink P1 → USB serial → 完整 telegram → CRC 校验 → 字段解析
 - 不发布 MQTT / Home Assistant Discovery。
 - 不修改现有 DSMR Reader MQTT、电费计算或 Meter 逻辑。
 - 不在本阶段决定 WarmteLink 应落在哪个正式 Device/Source 模型中。
+- 不写串口、不修改 FTDI EEPROM；probe 必须严格只读。
 
-## 3. 预期操作方式
+## 3. 2026-08-22 真机事实
 
-线到货后，在 workspace 的 virtual environment 中实现并运行一个只读 probe。命令形态暂定为：
+### 3.1 USB、权限与线材
+
+- 新 USB→P1 线是 FTDI FT232R，稳定路径形态为
+  `/dev/serial/by-id/usb-FTDI_FT232R_USB_UART_<redacted>-if00-port0`；正式配置不得依赖
+  `/dev/ttyUSB1`。
+- 运行用户加入 `dialout` 后可以直接读取 tty，无需 root，也不应把容器作为硬件 bring-up
+  的中间层。
+- 已用另一根已知正常的 DSMR 线在电表上读到连续、CRC 正确的 DSMR telegram，证明宿主机
+  串口读取方法本身可用。
+- 曾临时清除新 FTDI 线 EEPROM 的 `INVERT_RXD` 做对照；输出发生变化但仍不可解析，随后已将
+  EEPROM 逐字节恢复为原厂镜像并回读校验。正式方案不得依赖 EEPROM 修改。
+
+### 3.2 串口参数矩阵
+
+真机不是按最初假设的 `115200 8N1` 得到可读正文；当前线材与 WarmteLink 的实测最佳组合为：
+
+```text
+115200 baud, 7 data bits, no parity, 1 stop bit（7N1）
+```
+
+| 参数 | 实测结果 |
+| --- | --- |
+| `115200 7N1` | 正文稳定可读，可枚举 9 个 OBIS 字段 |
+| `115200 7N2` | 同样可读；没有理由增加停止位，正式默认仍用 `7N1` |
+| `115200 8N1/8E1/8O1` | 乱码，无有效 OBIS/CRC |
+| `115200 7E1/7O1` | 乱码，无有效 OBIS/CRC |
+| `120000–3000000`，分别用 `8N1`、`7N1` | 无完整报文；`120000` 仅残留少量可辨识文本 |
+| XON/XOFF 开/关 | 不改变 `7N1` 的字段解析结果 |
+
+[DSMR 5.0.2 P1 Companion Standard](https://www.netbeheernederland.nl/sites/default/files/2024-02/dsmr_5.0.2_p1_companion_standard.pdf)
+规定 `115200 8N1`。因此 `7N1` 是当前设备/线材组合的实测事实，不应被文档或代码包装成
+标准 DSMR framing；CLI 必须允许显式覆盖数据位、校验位和停止位。
+
+### 3.3 Framing 与 CRC 异常
+
+- 连续采集的 telegram 周期约为 10 秒；一次 8 帧盘点中每帧均为 256 字节。
+- 正文结构稳定，版本、时间戳、两个 M-Bus channel、单位和值均可重复解析。
+- 实测头部为 `)TU)2NWA-MYRSKY`，偶见 `)TU{2NWA-MYRSKY`；没有标准要求的 `/` 起始符。
+- 帧尾存在 `!`，但其后的字符并非每帧都稳定为四位十六进制；即使恰好是四位，也无法从
+  缺失的 `/` 起点完成标准 DSMR CRC16 验证。
+
+因此正式 probe 必须把完整性明确表示为 `valid`、`invalid` 或 `unverifiable`，保留原始字节并
+输出原因。它可以在 `unverifiable` 状态下枚举字段用于 PoC，但绝不能把该帧报告为 CRC 已通过。
+M8 若要持久化这些读数，必须在 Planning 中单独锁定异常帧的接纳、重复确认和告警策略。
+
+### 3.4 实际字段清单
+
+连续 8 帧只出现以下 9 个字段；除 capture timestamp 外，字段集合和值均稳定：
+
+| OBIS | 实测结构/值 | 结论 |
+| --- | --- | --- |
+| `1-3:0.2.8` | `(50)` | DSMR P1 输出版本 5.0 |
+| `0-0:1.0.0` | `(YYMMDDhhmmssX)` | telegram/capture timestamp，每 10 秒变化 |
+| `0-0:96.1.1` | `<redacted>` | WarmteLink/gateway equipment identifier |
+| `0-1:24.1.0` | `(006)` | channel 1，M-Bus device type `0x06`，生活热水 |
+| `0-1:96.1.0` | `<redacted>` | channel 1 equipment identifier；样本制造商可解码为 `KAM` |
+| `0-1:24.2.1` | `(<timestamp>)(5.900*m3)` | 生活热水累计体积，输出到 `0.001 m³` 小数位 |
+| `0-2:24.1.0` | `(012)` | channel 2，M-Bus device type `0x0C`，热量表 |
+| `0-2:96.1.0` | `<redacted>` | channel 2 equipment identifier；样本制造商可解码为 `KAM` |
+| `0-2:24.2.1` | `(<timestamp>)(0.017*GJ)` | 区域供暖累计热量，输出到 `0.001 GJ` 小数位 |
+
+人工面板在同一时间显示 `5.900 m³` 和 `0.017 GJ`，与 P1 值完全一致；用户已确认这两个累计量
+足以作为后续 Home Assistant Energy 展示的数据基础。
+
+没有发现瞬时流量、当前热功率、供水温度或回水温度字段。完整 OMS/M-Bus 模型允许这些可选
+量，但 WarmteLink 当前 P1 telegram 没有导出它们；Pre-M8 和 M8 不得假设它们可用。参考
+[OMS Specification Vol. 2 Annex A](https://oms-group.org/wp-content/uploads/2024/05/OMS-Spec_Vol2_AnnexA_F121.pdf)。
+
+### 3.5 对 M8 已经成立的事实
+
+- 一个 WarmteLink serial source 同时暴露两个独立累计 measurement channel。
+- channel 1 是生活热水 `m³`；channel 2 是区域供暖 `GJ`，不能按论坛样例固定 channel。
+- 两个累计量都与物理表一致，可进入 M8 的 Meter/source 映射讨论。
+- 当前没有瞬时流量、温度或热功率；M8 只承诺累计量采集与展示。
+- 串口 framing 和 CRC 异常尚未消失，必须作为正式 ingestion 的显式质量状态处理。
+
+## 4. 正式 probe 的预期操作方式
+
+实现后，在 workspace virtual environment 中运行只读 probe：
 
 ```bash
 source .venv/bin/activate
 python -m scripts.p1_probe \
   --device /dev/serial/by-id/<usb-p1-device> \
+  --baudrate 115200 \
+  --bytesize 7 \
+  --parity N \
+  --stopbits 1 \
   --duration 600 \
   --show-changes \
-  --raw-output /tmp/warmtelink-p1-telegram.txt
+  --raw-output /tmp/warmtelink-p1-telegram.bin
 ```
 
-最终参数名可在实现 probe 时调整，但应保留这些能力：
+参数名可在实现时小幅调整，但必须保留这些能力：
 
-- 使用稳定的 `/dev/serial/by-id/...` 路径，而不是依赖可能变化的 `/dev/ttyUSB0`。
-- 连续读取多帧，而不是只看一帧偶然样本。
-- 同时显示完整帧/CRC 结果、原始 OBIS 字段和解析后的值/单位。
-- 枚举 telegram 中出现的所有 M-Bus channel、device type、equipment id、capture timestamp、value 和 unit，不依赖固定字段顺序。
-- 可只显示发生变化的字段，便于观察更新频率。
-- 原始 telegram 默认只写到 `/tmp`；未经脱敏不提交到 Git。
+- 设备路径由用户显式传入，文档推荐 `/dev/serial/by-id/...`。
+- 串口默认采用本机实测 `115200 7N1`，同时允许显式覆盖 framing。
+- 连续读取多帧，输出 telegram cadence、帧长度和读取/重连错误。
+- 同时显示完整性/CRC 状态、原始 OBIS 字段和解析后的 channel、设备类型、值与单位。
+- parser 不依赖字段固定顺序，也不把 GJ/m³ 固定到 channel 1 或 2。
+- `--show-changes` 可只显示发生变化的字段，原始捕获可写入用户指定的 `/tmp` 路径。
+- 捕获文件默认按原始 bytes 保存；未经脱敏不得提交到 Git。
+- permission denied 时给出 `dialout` 指引；不得建议以 root 常驻运行。
 
-### 3.1 分两步 bring-up：Bash 冒烟验证 → Python probe
+Home Assistant Community 的
+[最小 WarmteLink Bash 读取方法](https://community.home-assistant.io/t/solved-dsmr-add-warmtelink-as-data-source/485255/2)
+仍可作为快速可见性检查，但论坛样例的 header、channel 和 device type 与本机均不同，不能作为
+parser 契约。是否引入 [`dsmr_parser`](https://github.com/ndokter/dsmr_parser) 也由 T01 的实测
+兼容性决定；若它要求标准 `/...!CRC` framing，则应保留小型专用 parser，而不是绕过其校验。
 
-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 样例还给出了以下**候选事实**：
+## 5. 实现任务
 
-- 设备头为 `/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 结束。
+### PRE-M8-T01 — 纯函数 telegram framing、CRC 与 OBIS parser
 
-这些是其他用户在 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 决定。
+- **Status**: `todo`
+- **Depends**: `none`
+- **Context**: 先把串口 I/O 与解析分开，用脱敏 fixture 固定标准 DSMR 帧和本机异常帧行为。
 
-线到货后的执行顺序调整为：
+**Files**
 
-1. **Bash 冒烟验证**：用稳定的 `/dev/serial/by-id/...` 路径配置串口并短时读取；先保留完整
-   原始字节流，再确认是否能看到 `/NWA-WARMTELINK`、帧尾和带 `GJ` 的行。论坛脚本中的
-   `GJ` 文本提取只能用作快速可见性检查，不能算解析或验收通过。
-2. **Python probe**：在已确认物理链路工作的前提下，实现上面的 `scripts.p1_probe`，完成
-   完整 framing、CRC、全部字段枚举、结构化解析、连续多帧变化观察和人工面板对照。
+- `create  scripts/p1_probe.py`
+- `create  tests/fixtures/dsmr_p1_valid.txt`
+- `create  tests/fixtures/warmtelink_p1_7n1.txt`
+- `create  tests/test_p1_probe.py`
 
-不复制论坛脚本的 MQTT 发布步骤：Pre-M8 仍只输出到终端和 `/tmp`，MQTT / Home Assistant
-集成属于 M8 设计范围。
+**Steps**
 
-## 4. 人工对照
+1. 实现不依赖串口的增量 framing、DSMR CRC16 和通用 OBIS 行解析函数。
+2. 用数据结构表达原始 header/footer、完整性状态、timestamp、channel、device type、equipment id、
+   value 和 unit；数值使用 `Decimal`，不使用二进制浮点保存累计量。
+3. 加入一份完全脱敏的本机结构 fixture，并另造一份 CRC 正确的标准 DSMR fixture。
+4. 对字段重排、分块输入、缺失 `/`、非十六进制 footer、CRC mismatch、未知字段和两个 channel
+   写单元测试。
 
-probe 运行期间，人工从热力表和相关水表面板记录同一时间附近的显示值，并与终端结果对照：
+**Out of scope / 不要碰**
 
-| 检查项 | 需要记录 |
-| --- | --- |
-| 区域供暖 | 面板累计值、P1 值、单位、两者时间差 |
-| 生活热水 | 面板累计值、P1 是否存在对应字段、单位、两者时间差 |
-| 更新时间 | 连续 telegram 中数值变化的间隔 |
-| 累计语义 | 数值是否单调累计，是否出现每日归零或其它重置 |
+- 不打开真实 serial device，不增加依赖，不写数据库/API/MQTT。
+- 不因本机正文可读而伪造 `/` header 或把 CRC 状态升级为 valid。
 
-允许 P1 capture time 与按表时间之间存在合理延迟；不能只凭数值接近就认定字段含义，必须同时核对单位、channel/device type 和时间戳。
+**Acceptance criteria**
 
-## 5. 通过条件
+- [ ] 标准 fixture 的 frame boundary 与 CRC 可验证为 `valid`。
+- [ ] 脱敏本机 fixture 被标为 `unverifiable`，但能按字段而非位置解析 `m³` 和 `GJ` channel。
+- [ ] 任意 chunk boundary 和字段顺序不影响结果，未知字段原样保留。
+- [ ] 累计量以 `Decimal` + 原单位返回。
+- [ ] `pytest tests/test_p1_probe.py`、`pytest`、`ruff check .` 全绿。
 
-Pre-M8 完成需留下以下证据：
+**Reviewer checklist**
 
-- [ ] 连续收到可识别为 WarmteLink 的完整 telegram。
-- [ ] CRC 校验通过；若失败，已区分串口/线材问题与 parser 问题。
-- [ ] parser 不依赖字段固定顺序，并列出全部实际 channel/OBIS 字段。
-- [ ] 找到 GJ 累计值并与热力表面板对照，误差可由显示精度或 capture 延迟解释。
-- [ ] 明确实际 telegram 是否包含独立的生活热水 m³ 累计量；若包含，已与水表面板对照。
-- [ ] 记录数值精度、telegram 频率、字段更新频率和累计/重置行为。
-- [ ] 形成一份脱敏结果摘要，足以支持下一轮 M8 Planning。
+- CRC 覆盖范围必须严格从 `/` 到 `!`（包含二者），不得对缺失字节做猜测性修补。
+- fixture 必须脱敏且保留足以复现 framing 异常的字节结构。
+- parser 不得硬编码 channel 1=GJ 或 channel 2=m³。
 
-如果只能确认 GJ、没有独立生活热水 m³，这也是有效结论，不视为 Pre-M8 失败。
+### PRE-M8-T02 — 只读 serial probe CLI
 
-## 6. 失败分类
+- **Status**: `todo`
+- **Depends**: `PRE-M8-T01`
+- **Context**: 在纯 parser 通过后增加最小 serial I/O，使真机验证可以从仓库稳定复现。
 
-- 完全无数据：优先检查 USB 识别、串口权限、P1 request line、线材方向/供电。
-- 输出乱码或不成帧：优先检查串口参数、信号反相和线材兼容性。
-- 原始帧完整但解析失败：保存脱敏样本，调整 parser/字段映射。
-- 解析成功但面板对不上：检查 capture timestamp、累计语义、单位和 WarmteLink firmware 差异。
+**Files**
+
+- `modify  requirements.in`
+- `modify  requirements.txt`
+- `modify  dev-requirements.txt`
+- `modify  scripts/p1_probe.py`
+- `modify  tests/test_p1_probe.py`
+
+**Steps**
+
+1. 增加受约束的 `pyserial` runtime 依赖并用仓库既有 pip-compile 流程同步生成 requirements。
+2. 实现 `--device`、framing 参数、`--duration`、`--show-changes` 和 `--raw-output`。
+3. 默认使用 `115200 7N1`；串口只读，禁止 write、EEPROM 或自动修改设备配置。
+4. 输出每帧完整性状态、全部字段、值变化、cadence 和错误；SIGINT/超时后关闭串口并正常退出。
+5. 用 fake serial/chunk stream 测试 CLI，不要求 CI 存在 `/dev/ttyUSB*`。
+
+**Out of scope / 不要碰**
+
+- 不做 daemon、自动重连 worker、Docker device mapping、数据库、API、MQTT 或 HA Discovery。
+- 不内置本机 FTDI 序列号，不自动扫描或改写任意 USB 设备。
+
+**Acceptance criteria**
+
+- [ ] CLI 可用 `/dev/serial/by-id/...` 读取，且所有 framing 参数都可显式覆盖。
+- [ ] 默认参数准确反映本机 `115200 7N1`，帮助文本说明它是实测值而非 DSMR 标准默认。
+- [ ] raw output 保留原始 bytes；终端清楚区分 `valid`、`invalid`、`unverifiable`。
+- [ ] permission/busy/disconnect 错误非零退出并给出可执行诊断，绝不建议常驻 root。
+- [ ] 依赖输入与两个生成 requirements 文件同步。
+- [ ] `pytest tests/test_p1_probe.py`、`pytest`、`ruff check .` 全绿。
+
+**Reviewer checklist**
+
+- 确认所有 serial write path 均不存在。
+- 确认测试完全 mock 硬件、没有 CI timing flake，退出路径总会关闭文件描述符。
+- 确认 requirements 是生成结果而非仅手改 lock file。
+
+### PRE-M8-T03 — 正式真机验收与 M8 交接
+
+- **Status**: `todo`
+- **Depends**: `PRE-M8-T02`
+- **Context**: 用仓库内 probe 替代本轮临时脚本，形成可重复、脱敏且能支撑 M8 Planning 的证据。
+
+**Files**
+
+- `modify  docs/design/pre-m8-warmtelink-p1-poc.md`
+- `modify  docs/design/m8-warmtelink-energy.md`
+- `modify  docs/design/README.md`
+- `modify  docs/roadmap.md`
+
+**Steps**
+
+1. 在真实 `/dev/serial/by-id/...` 上运行 probe 至少 10 分钟，并保留原始捕获在 `/tmp`。
+2. 汇总帧数、cadence、长度、完整性状态、全部字段和读数变化；不得提交原始设备标识。
+3. 再次与物理表对照 GJ 和 m³，并记录累计/重置行为中本次能证实和不能证实的部分。
+4. 更新本节事实、通过条件和 M8 入口；只有证据齐全后才把 Pre-M8 标记为完成。
+
+**Out of scope / 不要碰**
+
+- 不为完成 checklist 而修补原始字节或放宽 CRC 结果。
+- 不进入 M8 schema/API/worker/frontend 实现。
+
+**Acceptance criteria**
+
+- [ ] 仓库内 probe 在真机连续运行至少 10 分钟，无未处理异常退出。
+- [ ] 脱敏摘要列出两个累计 channel、单位、精度、cadence 和完整性异常。
+- [ ] `0.017 GJ`、`5.900 m³` 的基线或运行时新值与物理表再次对照。
+- [ ] 明确没有从当前 P1 输出读取到瞬时流量、功率或温度。
+- [ ] Pre-M8 状态与 roadmap/M8 入口同步；代码闸门保持全绿。
+
+**Reviewer checklist**
+
+- 证据必须来自正式 CLI，不得只复述本轮临时脚本结果。
+- 任何 equipment id、FTDI serial 和未脱敏 raw capture 都不得进入 Git。
+- CRC/framing 风险必须原样交给 M8，不能用“数值看起来正确”替代完整性判断。
+
+## 6. 当前通过条件
+
+- [x] USB、tty 权限和稳定 `/dev/serial/by-id/...` 路径已验证。
+- [x] 串口参数矩阵已完成，实测正文可读参数为 `115200 7N1`。
+- [x] 已枚举全部实际 channel/OBIS 字段，并确认没有轮换出现的额外测量量。
+- [x] GJ 和生活热水 m³ 均与物理表面板完全一致。
+- [x] 已记录精度、约 10 秒 telegram cadence 和当前字段集合。
+- [x] framing/CRC 失败已保留为显式异常，没有误报为校验通过。
+- [ ] 仓库内 parser、fixtures、probe CLI 和自动化测试完成。
+- [ ] 正式 probe 完成至少 10 分钟真机复验并产出脱敏摘要。
+
+当前人工 bring-up 已足以锁定 M8 的两个累计量目标，但 Pre-M8 milestone 仍需完成 T01～T03。
 
 ## 7. 向 M8 的交付物
 
-Pre-M8 只向 M8 交付事实，不交付正式架构：
+Pre-M8 完成后只向 M8 交付事实，不交付正式架构：
 
-- 已脱敏的 telegram 结构与字段清单。
-- GJ / 可选 m³ 的实际 channel、OBIS、单位、精度和更新时间。
-- 串口参数、稳定设备路径与部署权限要求。
-- parser 适配结论以及需要保留的异常样本。
-- 对“一个来源包含几个可用计量通道”的实测结论。
+- 脱敏 telegram 结构、fixture 和全部字段清单。
+- GJ 与 m³ 的实际 channel、device type、单位、精度和更新时间。
+- 串口参数、稳定设备路径形态与 `dialout` 权限要求。
+- parser 适配结论和 `unverifiable` framing/CRC 异常样本。
+- “一个 serial source 包含两个独立累计计量 channel”的实测结论。
+- 当前 P1 不提供瞬时流量、热功率或温度的明确边界。