lizbit-official/pumpsaver-ir-protocol
GitHub: lizbit-official/pumpsaver-ir-protocol
SymCom/Littelfuse PumpSaver Plus 泵保护继电器红外广播协议的逆向工程规范与纯 Python 参考解码器，解决了此前无法第三方接收该设备实时遥测数据的问题。
Stars: 5 | Forks: 0
# pumpsaver-ir-protocol
**SymCom / Littelfuse PumpSaver Plus** 泵保护继电器的 IR 数据广播协议规范和参考解码器（在 233-P 上逆向工程得出）。
这些继电器通过旨在用于 SymCom 已停产的 "Informer" 手持设备的 baseband IR 链路不断广播其内部状态：
- 实时 **电压、电流、功率、功率因数**
- 寿命周期内的 **泵启动** 和 **运行时间** 计数器
- 跳闸点配置和最近 20 次故障历史记录
这个仓库记录了该协议——这显然是全网首份——并提供了一个经过测试的参考解码器。
**想要将其接入 Home Assistant？** 请参阅配套仓库 [esphome-pumpsaver](https://github.com/lizbit-official/esphome-pumpsaver) 获取现成的
ESPHome 组件（只需一个 ESP32 和一个价值 0.30 美元的红外光敏三极管对准设备即可）。
## 一段话概述协议
5,000 波特率的 NRZ 通过 baseband IR 传输（无载波），每个脉冲的*宽度*编码了一段连续的相同位。每个突发数据代表一个 32 位的字—— `0x90 | register:8 | value:16` ——尾部的零位会被吸收到间隔中。117 个寄存器循环广播：实时遥测数据每约 1.5 秒一次，其他所有数据每约 5.8 秒一次。没有校验和；状态可以通过约 6 秒的信号完全重建。完整细节、寄存器映射和证据：[PROTOCOL.md](PROTOCOL.md)。
## 快速开始
```
$ git clone https://github.com/lizbit-official/pumpsaver-ir-protocol && cd pumpsaver-ir-protocol
$ python3 -m pumpsaver_ir table examples/sample_capture.ndjson
...
reg 0x0F ( 15) = 11179 0x2BAB n=10 11179 starts (pump_starts)
reg 0x10 ( 16) = 26 0x001A n=10 26 W (power)
reg 0x11 ( 17) = 2439 0x0987 n=10 243.9 V (voltage)
reg 0x12 ( 18) = 14 0x000E n=10 0.14 A (current)
reg 0x13 ( 19) = 781 0x030D n=10 0.781 (power_factor)
...
reg 0x17 ( 23) = 57671 0xE147 n=11 57671 min (run_minutes)
...
117 registers; 594 words (120 sync), 0 undecodable bursts
```
其他命令：`events`（随时间变化的寄存器）、`csv`（时间序列）、`stats`（解码质量）。除了 Python 3.10+ 之外没有其他依赖项。
### 库的使用
```
from pumpsaver_ir import decode_capture, registers_from_words, Word
words = [w for w in decode_capture(timings) if isinstance(w, Word)]
regs = registers_from_words(words)
print(f"{regs[0x11] / 10} V, {regs[0x10]} W, {regs[0x0F]} lifetime starts")
```
`timings` 是一个以 µs 为单位的有符号脉冲持续时间列表（正/负 = 两种 IR 电平），
例如 ESPHome 的 `remote_receiver` 原始转储数据。极性会自动检测。
## 捕获您自己的数据
任何能够以约 10 µs 的分辨率对 baseband IR 边缘进行时间戳记录的接收器都可以使用。**38 kHz 解调接收器（TSOP 风格）不适用** ——因为该信号没有载波。经过验证的设置
（裸 IR 光敏三极管 + ESP32 `remote_receiver`）已在
[esphome-pumpsaver](https://github.com/lizbit-official/esphome-pumpsaver) 中记录，
其中包括与此解码器兼容的 NDJSON 捕获管道。
## 仓库布局
```
PROTOCOL.md the specification (start here)
pumpsaver_ir/decoder.py reference decoder (~100 lines, stdlib only)
pumpsaver_ir/registers.json machine-readable register map with confidence levels
examples/sample_capture.ndjson 30 real transmissions from a 233-P (~15 s, 2.5 broadcast cycles)
tests/test_decoder.py round-trip + real-capture tests
```
## 许可证
MIT。与 Littelfuse, Inc. 无关也未获其认可——请参阅 PROTOCOL.md §9。
标签：Python, 云资产清单, 无后门, 智能家居, 物联网, 硬件, 逆向工具, 逆向工程