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

> **状态：进行中。** 2026-08-22 已完成临时脚本真机 bring-up，并确认两个可用累计量；
> 仓库内的正式 probe、解析测试和可重复验收流程尚未实现。完成下方 PRE-M8-T01～T03
> 后，才把 Pre-M8 标记为完成并解除 M8 Planning 的入口限制。

## 1. 目的

在进入 M8 正式设计和实现前，用新家的 Vattenfall WarmteLink 建立一条只读 P1 验证链，回答：

1. USB→P1 线、主机串口权限和 WarmteLink P1 端口能否稳定输出可解析数据。
2. 真机使用什么串口参数，telegram 的 framing、CRC、时间戳和 OBIS/M-Bus channel 有何特征。
3. 实际能够读取哪些累计量，以及单位、精度、更新频率和累计语义。
4. P1 值是否与热量表/生活热水表面板一致。

Pre-M8 是 M8 的证据门：它只交付真机事实和可重复 probe，不决定数据库结构、Meter 数据源
绑定、后台采集服务或前端布局。

## 2. 执行边界

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

```text
WarmteLink P1 → USB serial → 原始 telegram → 完整性状态 → 字段解析 → 终端输出
```

明确不做：

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

## 3. 2026-08-22 真机事实

### 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.bin
```

参数名可在实现时小幅调整，但必须保留这些能力：

- 设备路径由用户显式传入，文档推荐 `/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 常驻运行。

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，而不是绕过其校验。

## 5. 实现任务

### PRE-M8-T01 — 纯函数 telegram framing、CRC 与 OBIS parser

- **Status**: `todo`
- **Depends**: `none`
- **Context**: 先把串口 I/O 与解析分开，用脱敏 fixture 固定标准 DSMR 帧和本机异常帧行为。

**Files**

- `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`

**Steps**

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
   写单元测试。

**Out of scope / 不要碰**

- 不打开真实 serial device，不增加依赖，不写数据库/API/MQTT。
- 不因本机正文可读而伪造 `/` header 或把 CRC 状态升级为 valid。

**Acceptance criteria**

- [ ] 标准 fixture 的 frame boundary 与 CRC 可验证为 `valid`。
- [ ] 脱敏本机 fixture 被标为 `unverifiable`，但能按字段而非位置解析 `m³` 和 `GJ` channel。
- [ ] 任意 chunk boundary 和字段顺序不影响结果，未知字段原样保留。
- [ ] 累计量以 `Decimal` + 原单位返回。
- [ ] `pytest tests/test_p1_probe.py`、`pytest`、`ruff check .` 全绿。

**Reviewer checklist**

- CRC 覆盖范围必须严格从 `/` 到 `!`（包含二者），不得对缺失字节做猜测性修补。
- fixture 必须脱敏且保留足以复现 framing 异常的字节结构。
- parser 不得硬编码 channel 1=GJ 或 channel 2=m³。

### PRE-M8-T02 — 只读 serial probe CLI

- **Status**: `todo`
- **Depends**: `PRE-M8-T01`
- **Context**: 在纯 parser 通过后增加最小 serial I/O，使真机验证可以从仓库稳定复现。

**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 交付事实，不交付正式架构：

- 脱敏 telegram 结构、fixture 和全部字段清单。
- GJ 与 m³ 的实际 channel、device type、单位、精度和更新时间。
- 串口参数、稳定设备路径形态与 `dialout` 权限要求。
- parser 适配结论和 `unverifiable` framing/CRC 异常样本。
- “一个 serial source 包含两个独立累计计量 channel”的实测结论。
- 当前 P1 不提供瞬时流量、热功率或温度的明确边界。