ad-rpi/open-ec-ags
GitHub: ad-rpi/open-ec-ags
通过逆向工程蓝牙协议，为Cummins EC-AGS+房车发电机提供CLI、Web仪表板和调度器的非官方替代控制方案。
Stars: 1 | Forks: 0
# RV 发电机 — Cummins EC-AGS+ BLE 控制
* 注意：在制作此项目的过程中，使用了 Claude AI 进行 BLE 分析和解码。所有针对真实发电机的测试均由真人完成。
通过蓝牙 LE 从 **Mac** 或 **Raspberry Pi** 控制 Cummins EC-AGS+ 发电机——提供 CLI、Web 仪表板和调度器，作为官方手机应用的替代方案。为了实现互操作性，BLE 协议已进行逆向工程；有关完整规范请参阅 [`PROTOCOL.md`](PROTOCOL.md)，有关实现请参阅 [`agscli.py`](agscli.py)。
## 设置
Python 3.9+ 和 [`bleak`](https://github.com/hbldh/bleak)：
```
python3 -m venv .venv
.venv/bin/pip install bleak
```
* **macOS** — 通过 CoreBluetooth 开箱即用。首次使用时，请授予终端蓝牙权限（系统设置 → 隐私与安全性 → 蓝牙）。设备“地址”是 CoreBluetooth UUID，而不是 MAC。
* **Raspberry Pi / Linux** — 使用 BlueZ。`sudo apt install bluetooth bluez`。地址为 MAC。如果写入操作被拒绝并提示身份验证错误，请预先配对一次：
`bluetoothctl` → `pair ` → `trust `。
## 使用方法
```
# 1. 找到 generator (也会显示是否设置了密码)
.venv/bin/python agscli.py scan
# 2. 与其通信。如果显示 UNREGISTERED，请使用扫描得到的 macId 作为密码。
.venv/bin/python agscli.py -a -p status
.venv/bin/python agscli.py -a -p start
.venv/bin/python agscli.py -a -p stop
.venv/bin/python agscli.py -a -p monitor # live stream
.venv/bin/python agscli.py -a -p info # model/serial
# 添加 -v 以查看原始 RPC/telemetry 流量
```
命令：`scan, status, start, stop, auto-on, auto-off, reset-fault, info, monitor`。
## Web 仪表板
一个基于浏览器的仪表板（扫描/配对/保存设备、实时状态、启动/停止、自动启动/停止规则、日程安排、历史记录和统计图表）位于 `server.py` + `index.html` 中。
```
.venv/bin/pip install -r requirements.txt
.venv/bin/python server.py # open http://localhost:8722
```
* **设备选项卡** — 扫描会查找附近的发电机，“保存/连接”会将其存储（连同密码）并连接。已保存的设备会持久化保存在 `devices.json` 中。在树莓派上，**配对 (Pair)** 按钮会运行 `bluetoothctl pair/trust/connect`；在 macOS 上配对是自动进行的。**自动连接**（在此处切换，默认开启）会在服务器启动以及 BLE 链接断开时自动重新连接到上次使用的设备——除非您亲自点击 **断开连接**，该状态将保持断开，直到您重新连接或重新启用该切换开关。上次连接的设备和该切换状态会持久化保存在 `state.json` 中。
* **控制选项卡** — 实时状态（运行/停止/预热/泵油）、输出电压、电池电压、房屋电池 SOC、故障代码、运行时间；启动/停止/重置故障按钮；以及 **应用自动化** 主开关——这是一个服务器端的总开关，用于控制此应用的所有自动启动/停止规则（电池电压和冷启动）。关闭它后，应用只会进行监控观察，而不会自行启动或停止任何设备。
* **电池启动/停止选项卡** — 一个服务器端规则，当 **房屋电池电压** 降至阈值以下时启动发电机，并在充电回升后停止发电机（带有迟滞区间、最短运行时间，并且它只会停止由其自身启动的发电机运行）。此规则在此机器上运行，因此服务器必须保持开启——其优点是具有完全的可见性，且由单一位置决定发电机何时运行。
* **温度启动选项卡** — 两种独立的机制：**热启动 (A/C)** 是发电机自带的功能（区域温度 *高于* 设定值 → 启动，用于空调；无需此仪表板即可工作，但需要内置的自动模式——请参阅上面的警告）。**冷启动 (加热器)** 是一个服务器端规则，当天气变 *冷* 时启动发电机，以便加热器可以使用发电机的电力运行，而不是耗尽电池电量；它会读取发电机的远程温度传感器或通过 POST 请求发送到 `/api/temp` 的外部读数。与电池规则具有相同的保护机制，并且它会故意忽略安静时段（防冻保护优先）。
* **安静时间选项卡** — 发电机的每日安静时段窗口（发电机端设置）。应用自身的保护规则有意忽略此设置：深度放电和防冻保护的优先级高于安静时段。
* **历史记录选项卡** — **活动日志**（每次启动/停止/故障及其 *触发原因*：手动、电压规则、温度规则、计划安排或发电机/面板本身）由服务器记录，外加发电机存储的故障日志（时间戳 + 解码后的故障名称）和当前活动的故障。故障名称/描述来自 `faultcodes.py`。
* **统计选项卡** — 带有发电机运行区间的房屋电压和 SOC 历史图表，以及每个时间段（24 小时 / 7 天 / 30 天 / 全部）的运行时间和启动次数。连接期间每分钟采样一次，存入本地 SQLite 文件（`stats.db`），保留约 180 天，并在服务器端进行降采样以保持图表轻量化。图表由本地提供的 Chart.js 渲染，因此可以完全脱机工作。
* **设置选项卡 (⚙)** — 选择控制选项卡上显示哪些遥测数据行；其余部分在您需要之前保持隐藏（按浏览器保存在 localStorage 中）。默认显示常用信息；“显示全部”可显示歧管/机油/逆变器温度、平均电压、发动机运行时间等，用于故障排查。
* **日程安排选项卡** — 基于 *本机* 时钟的定时启动/停止运行，独立于发电机的内置自动模式。添加条目，如“周一至周五 07:30 启动” / “每天 22:00 停止”。服务器每约 20 秒检查一次；当条目到期时，它将连接到已保存的设备（使用其存储的密码）并发送命令。最近的触发结果显示在该选项卡上。条目持久化保存在 `schedules.json` 中。这是“不依赖自动模式”的途径——非常适合始终开启的树莓派。
所有浏览器标签页共享一个 BLE 连接。`AGS_PORT` 环境变量可更改端口。为了使调度器可靠触发，请保持服务器运行（在树莓派上使用下面的 systemd 单元）。
### 在树莓派上设置为开机启动
编辑 `ags-dashboard.service` 中的路径，然后运行：
```
sudo cp ags-dashboard.service /etc/systemd/system/
sudo systemctl enable --now ags-dashboard
```
现在，仪表板将始终可以通过 `http://:8722` 访问——将您的手机或笔记本电脑指向该地址即可，无需使用不稳定的应用程序。
## 密码
认证方式为 `base64(SHA256("ST3094…vjGS" + seed + password))`，其中 `seed` 是从发电机实时获取的。`password` 是您在官方应用中设置的任何密码。如果发电机 **从未** 分配过密码（`scan` 输出显示为 `UNREGISTERED`），则密码即为 `scan` 显示的设备 **macId**。
## 状态 / 注意事项
* **已测试硬件：** 已在 **Cummins Onan QG 4000**（配备 EC-AGS+ 控制器）上确认正常工作——连接/身份验证、实时遥测和启动/停止均已端到端验证。其他配备 EC-AGS+ 的发电机极有可能同样适用（相同的 BLE 模块）；欢迎反馈。如果某一步骤卡住，请使用 `-v` 运行并分享输出结果。
* **您能获取的遥测数据取决于您的发电机集成情况。** 在测试设备上，EC-AGS+ 报告 **运行状态、输出电压、电池直流电压、SOC、故障代码和运行时间** —— 但 **不包括** 发动机 RPM、输出频率、负载、发动机/机油/歧管/逆变器温度或累计运行时间（即使在运行期间，这些数据也返回为 `0xFF`“不可用”——在该发电机上，控制器并未接入发动机 ECU 以获取这些信息）。这些字段已被解码但 **未经核实**，因此它们被放置在仪表板设置底部明确的 **⚠ 未测试** 区域中，默认处于关闭状态。集成程度更深的发动机安装可能会填充这些数据——可启用以进行尝试。缺失的值显示为 `—`，绝不会编造虚假数字。
* 该应用始终只使用 20 字节的 MTU，并通过计数器特征值来控制多块写入的节奏；`agscli.py` 复制了这一行为。控制命令（启动/停止/状态）均为单块传输。
* 自备设备：您需要使用一次官方应用来设置/获取发电机的密码。本仓库中不包含任何反编译的应用源代码。
标签：BLE, Bleak, Cummins, Python, Raspberry Pi, recreational vehicle, Web控制面板, 云资产清单, 任务调度, 内存执行, 协议分析, 发电机控制, 嵌入式系统, 康明斯, 开源, 房车, 无后门, 无线通信, 智能家居, 权限提升, 物联网, 自动化控制, 蓝牙低能耗, 蓝牙通信, 逆向工具, 逆向工程