kenjicd-source/py-rackbus

# py-rackbus [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](#测试) 一个用于 **Rackbus SL** 串行协议的独立 Python 客户端 —— 这是 1990 年代中期一些 Endress+Hauser 质量 流量计和其他 Commutec 系列变送器使用的早期专有现场总线。 这是一个基于对线路上未加密流量的黑盒观察而进行的**净室逆向工程实现**。未对任何厂商 固件进行反编译，未修改任何厂商软件，也未复制任何 专有文档。 ## 为什么会有这个项目 许多 1995-2003 年间的 Coriolis 流量计和过程仪器通过 RS-485 使用 Rackbus SL 协议。厂商的原始软件 （Commuwin II）早已停止维护，需要老旧的硬件 加密狗，并且只能在 Windows 95/98/XP 上运行。 这些仪器目前仍在乳制品厂、 啤酒厂、化工厂和制药生产线中使用。更换 它们每台需要花费数万欧元，外加数周的 停机时间。 这个库让你可以使用现代、低廉的硬件从这类仪器中读取实时数据： - 一个 5 美元的 USB 转 RS485 适配器和 Python —— 适用于笔记本电脑和网关 PC - 一个 ESP32 + MAX485 模块 —— 适用于嵌入式遥测、MQTT、Home Assistant - 任何带有串口和 RS-485 收发器的平台 设计上为只读 —— 你可以读取质量流量、密度、温度、 累积量和标签，而不会面临意外向在线设备写入错误 配置的风险。 ## 快速开始 ``` git clone https://github.com/kenjicd/py-rackbus.git cd py-rackbus pip install pyserial python examples/basic_usage.py COM5 3 ``` 这里假设仪器位于 `COM5` 的总线地址 3 上。请将 其替换为你实际的配置。接线： ``` Instrument terminal A (or +) ─── USB-RS485 A (D+) Instrument terminal B (or -) ─── USB-RS485 B (D-) Instrument shield / ⊥ ─── USB-RS485 GND (optional) ``` 标准的 RS-485 极性。有关图表和提示，请参见 [hardware/README.md](hardware/README.md)。 ## API ``` from rackbus_client import RackbusClient with RackbusClient(port='COM5', address=3) as client: print(client.read_mass_flow()) # → float (t/h) print(client.read_density()) # → float (g/cm³) print(client.read_temperature()) # → float (°C) print(client.read_totalizer_1()) # → float (t) print(client.read_tag_number()) # → str print(client.read_parameter('V0H0')) # generic by V/H code print(client.read_all()) # → dict of common params ``` 完整的 API 表面和模块布局：[docs/STRUCTURE.md](docs/STRUCTURE.md)。 ## ESP32 固件 适用于 ESP32-S2（以及任何其他 ESP32 变体）的可用的 PlatformIO 固件 包含在 [`firmware/`](firmware/) 中。它通过 MAX485 模块经 RS-485 读取 Promass，提供带有实时值的本地 Web UI，并 可选择将 JSON 遥测数据发送到远程 endpoint。 ``` cd firmware cp include/secrets.h.example include/secrets.h $EDITOR include/secrets.h # WiFi, OTA password, telemetry URL pio run -t upload # first flash over USB pio device monitor # see live transactions ``` 之后你可以通过 WiFi 进行刷写（`pio run -t upload -e ota`），并 在浏览器中打开 `http://promass.local/`。 完整指南请参见 [firmware/README.md](firmware/README.md)， 特别要注意 **MAX485 换向时序**警告 —— 它能帮你省去几个小时的麻烦。 ## 状态 | 组件 | 状态 | |---|---| | 帧结构（请求 + 响应，长帧 + 短帧） | ✅ 完全逆向 | | 地址编码（`0x5F − ASCII` + 校验位） | ✅ 已验证 | | V/H 编码（`0x5F − 原始整数` + 校验位） | ✅ 已验证 | | 数据解码（ASCII 补码、缩放字符、整数、字符串、`@` 无效） | ✅ 在真实值上已验证 | | 请求校验和 | ✅ 已逆向（`crc1 = 0x2E XOR …`，`crc2 = sum + 0x48`） | | 响应校验和 | ⚠ 占位（信任从机；验证器始终返回 `True`） | | 多阶段交换（预热 → VR → DD → 48） | ✅ 已逆向且可靠 | | 测试套件 | ✅ 57 个测试通过 | | 已确认的设备 | Promass 63（`63FS50-FTW91A00B1B`，SW 3.00.00） | | ESP32 固件移植 | ✅ 工作中（`firmware/`，PlatformIO，MAX485） | | Modbus TCP 网关 | 🚧 计划中 | ## 支持的设备 | 制造商 | 型号 | 固件 | 已测试 | 备注 | |---|---|---|---|---| | Endress+Hauser | Promass 63 | SW 3.00.00 / SW COM 3.00.00 | ✅ | 参考设备 | 可能兼容（未测试）—— 请报告： - 其他带有 RACKBUS RS 485 模块的 Endress+Hauser Promass 60 系列 - 同一代的其他 Commutec 系列变送器 （Promag 50/53、Levelflex、Cerabar）的 Rackbus 变体 如果你手头有一台设备，请提交一份 [兼容性报告](../../issues/new?template=compatibility_report.md)。 ## 文档 - [docs/PROTOCOL.md](docs/PROTOCOL.md) — 通信协议规范 （帧格式、编码、校验和、多阶段交换） - [docs/PARAMETERS.md](docs/PARAMETERS.md) — 支持仪器的 V/H 参数映射 - [docs/EXAMPLE_TRANSACTIONS.md](docs/EXAMPLE_TRANSACTIONS.md) — 带有解码值的逐字节捕获示例 - [docs/REVERSE_ENGINEERING.md](docs/REVERSE_ENGINEERING.md) — 协议是如何被破解的、死胡同和经验教训 - [docs/STRUCTURE.md](docs/STRUCTURE.md) — 代码布局和 API 表面 - [hardware/README.md](hardware/README.md) — USB 适配器和 ESP32 的接线图 - [firmware/README.md](firmware/README.md) — ESP32-S2 固件 （PlatformIO）、HTTP/JSON API、遥测发布者、OTA 更新， 以及关于 MAX485 换向时序的严重警告 ## 测试 ``` pip install pytest pyserial pytest ``` 预期输出：`57 passed`。 测试套件使用了从真实设备捕获的逐字节固定数据， 并离线运行（测试无需硬件）。 ## 许可证 MIT —— 请参见 [LICENSE](LICENSE)。本仓库中的所有代码均为贡献者的原创 工作，并非派生自任何专有 来源。 有关逆向工程工作本身的法律定位 （欧盟软件指令 2009/24/EC、美国 17 USC § 1201(f)、商标 说明），请参见 [NOTICE.md](NOTICE.md)。 ## 安全提示 本库特地为**只读**模式。对在线 工业过程仪器进行写操作可能会导致设备损坏、过程 异常或安全事故。在连接到生产线之前，请务必先在测试台上进行测试。

标签：Python, 串口通信, 云资产清单, 工业控制, 无后门, 物联网, 逆向工具, 逆向工程