127 lines
6.5 KiB
Markdown
127 lines
6.5 KiB
Markdown
# 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 适配结论以及需要保留的异常样本。
|
||
- 对“一个来源包含几个可用计量通道”的实测结论。
|