Shad107/OpenXtraflame

# OpenXtraflame [](https://github.com/Shad107/OpenXtraflame/releases) [](LICENSE) [](https://github.com/Shad107/OpenXtraflame) [](https://github.com/Shad107/OpenXtraflame/issues) [](https://github.com/espressif/esp-idf) [](https://home-assistant.io) 为 Extraflame 颗粒炉（以及兼容的 Micronova 设备）定制的开源固件。 **状态**：v0.1.0-rc1（=发布候选版本，已在 Extraflame Teodora Evo 上完成个人使用验证） ## 目标 用通过 MQTT 实现的 100% 本地控制（对接 Home Assistant / Mosquitto）来取代对 Omnyvore 云端的依赖（`mqtt.extraflame.it:8883`）。 **额外功能**：兼容官方 TotalControl 2 应用的云模式（=BETA，仅限 TARGET_BLACKLABEL）。 ## 两个 Target ### Target A：“External”（=推荐，安全） 为并联连接到壁炉串行总线的备用 ESP32 提供的固件。Extraflame Black Label 模块保持原样。 - 硬件：备用的 ESP32-WROOM-32 + dupont 线 - 接线：壁炉串行总线（=主板侧的 TA 接口） - 方法类似于 philibertc/micronova_controller - 云端不可用（=需要原始模块的 matricola + secure_code） ### Target B：“Black Label Replacement”（=进阶） 直接替换 Extraflame Black Label 模块上原厂固件的固件。需要提取原始固件进行备份。 - 硬件：价值 289€ 的 Extraflame Black Label 模块 - 复用原生的 4-pin SERIAL 排针 - 可通过原始固件备份进行恢复 - 兼容 TotalControl 2 的 MQTT 云端（=BETA） ## 架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ UART │ │ Wi-Fi │ │ │ Poêle │38400 8N1│ ESP32 avec │ MQTT │ Home Assistant │ │ Extraflame ├─────────┤ OpenXtraflame ├─────────┤ + Mosquitto │ │ Teodora Evo │Micronova│ firmware │ local │ (=local only) │ │ │ proto │ │ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────┘ │ │ MQTTS (=optionnel, BL only) │ ▼ ┌──────────────┐ │ Omnyvore │ ← app TotalControl 2 │ cloud │ └──────────────┘ ``` ## 功能 (v0.1.0-rc1) **本地（=2个 target 均适用）**： - ✅ 通过 SoftAP + 类 Vue Web UI 进行 Wi-Fi 配网 - ✅ 桥接至 HA 的 MQTT（=状态 + 命令） - ✅ HA Discovery：温度、功率、设定值、计时器、警报、计数器 - ✅ 颗粒计数器（=总公斤数、历史总成本、剩余续航） - ✅ 4 个可编辑计时器配置（=小时 + 星期 + 温度 + 功率） - ✅ 通过 Addrs_dyn 自动检测 stove_type（=I_VENT, I_CANAL, I_CALD, I_IDRO） - ✅ 通过 Web UI + endpoint /ota/pull URL 实现 OTA 空中升级 - ✅ HA 传感器：运行时间、上次启动时间 - ✅ 安全模式（=通过 Web UI 按钮或 3 次自动崩溃触发 → 仅重启最小的 WiFi+OTA 环境） **云端（=仅限 Black Label）**： - ✅ 逆向 Auth 握手（=matricola + secure_code，MQTT 3.1.1） - ✅ 内置 Omnyvore CA 证书（=从原始固件 dump 中提取） - ✅ 完整的 topic 格式：`omv/ex/{MAC}/{model} 1.8/{matricola}/{DIR}/{family}` - ✅ 自动 REST 登录 `appapi.extraflame.it/auth`（=获取 stove_id + model） - ✅ 发布 OUT：temperature, status, settings, workingtimers - ✅ 订阅 IN：settings（=云端指令 → Micronova EEPROM） - ✅ 带有 correlationid 的 MQTT 回复以实现 ack - ✅ 开启/关闭 HA 云端（=在配置了 TC2 登录时条件触发） ## 延迟 - 物理壁炉 → 固件快照：约 9.5s（=完整轮询周期 63 个寄存器 × 150ms） - 快照 → HA（=本地 MQTT 发布）：2s（=publish_interval_ms） - 快照 → Omnyvore 云端：30s（=云端发布周期） 热轮询（=关键寄存器快速轮询）处于 TODO 状态，参见 STATUS.md。 ## 逆向工程 我们对 Extraflame Black Label 模块的原始固件进行了 dump 和分析，以重建以下内容： - Micronova UART 协议（=1200 波特率 8N2，反相线路，EEPROM 读写 opcode） - 包含累加 checksum 的数据帧格式 `[loc][addr][val][cks]` - 60 个 Addrs_dyn 表（=每个型号变体一张） - 云端 MQTT topic 格式 + auth 握手 - Omnyvore TLS CA 证书 参见： - [docs/PROTOCOLE-MICRONOVA.md](docs/PROTOCOLE-MICRONOVA.md) - 串行总线 + 寄存器 - [docs/CLOUD_REVERSE_NOTES.md](docs/CLOUD_REVERSE_NOTES.md) - 云端 MQTT + REST API - [docs/STOVE-TYPES.md](docs/STOVE-TYPES.md) - 支持的 60 种型号 - [analysis/firmware-cartography.md](analysis/firmware-cartography.md) - dump 分析 ## 构建 ``` # 需要 ESP-IDF v5.2.3（推荐通过 docker） cd firmware docker run --rm -v $PWD:/project -w /project espressif/idf:v5.2.3 idf.py build # 或构建 external 目标： docker run --rm -v $PWD:/project -w /project espressif/idf:v5.2.3 \ bash -c "idf.py -DOPENXFLAME_TARGET=external build" ``` 参见 [docs/BUILDING.md](docs/BUILDING.md)。 ## 项目结构 ``` OpenXtraflame/ ├── README.md # ce fichier ├── LICENSE # MIT ├── firmware/ │ ├── CMakeLists.txt # racine, PROJECT_VER + target detect │ ├── sdkconfig.defaults │ ├── partitions.csv # layout compatible dump original │ └── main/ │ ├── main.c # orchestration tasks + safe boot detector │ ├── config_nvs.c/h # config NVS + safe_mode flag │ ├── wifi_bridge.c/h # STA + SoftAP + scan JSON │ ├── mqtt_bridge.c/h # publish state + discovery HA + cmd handler │ ├── cloud_bridge.c/h # MQTT cloud Extraflame (=blacklabel only) │ ├── cloud_rest.c/h # REST API appapi.extraflame.it (=fetch stove info) │ ├── micronova.c/h # protocole série poêle + shadow RAM + write queue │ ├── web_ui.c/h # HTTP config server + OTA endpoint + safe_mode │ ├── log_ring.c/h # 32KB ring buffer pour /debug/logs │ ├── ota.c/h # OTA subsystem + rollback safety │ ├── leds.c/h # status indicators │ ├── web/ # index.html + style.css + script.js embedded │ └── certs/ │ └── extraflame_ca.pem # CA Omnyvore (=extrait du dump firmware) ├── docs/ │ ├── STATUS.md │ ├── BUILDING.md │ ├── DUMPING_ORIGINAL.md # procédure dump 8h │ ├── HARDWARE_TARGET_EXTERNAL.md │ ├── HARDWARE_TARGET_BLACKLABEL.md │ ├── MQTT_PROTOCOL.md # topics HA local │ ├── CLOUD_REVERSE_NOTES.md # reverse cloud Omnyvore/Extraflame │ ├── PROTOCOLE-MICRONOVA.md # bus série + registres RAM/EEPROM │ ├── STOVE-TYPES.md # 60 modèles supportés Addrs_dyn │ ├── OTA.md # procédure mise à jour │ ├── RELATED_PROJECTS.md │ └── IDEAS.md # backlog features ├── analysis/ # reverse engineering notes brutes ├── ha-config/ # exemples HA yaml └── tools/ # scripts helpers (=make_esp32_elf, ghidra, qemu) ``` ## 路线图 - [x] Dump 原始 Extraflame Black Label 固件 - [x] 分析分区 + 协议 - [x] 完整的固件映射 - [x] 搭建 ESP-IDF v5.2.3 + docker 工具链 - [x] 骨架代码 + 构建 - [x] Wi-Fi 管理器 + SoftAP 配置 - [x] 指向本地 Mosquitto 的 MQTT 客户端 - [x] Micronova UART 协议（=1200 8N2，反相线路） - [x] Web UI 配置 + OTA - [x] 在 Black Label 上测试（=Target B，已备份） - [x] 集成 HA MQTT Discovery - [x] 兼容 Extraflame Omnyvore 云端（=BETA，TotalControl 2 可用） - [x] 安全模式 + 启动循环检测器 - [ ] 在备用 ESP32 上测试（=Target A）- 等待使用外部 ESP32 验证 - [ ] 关键寄存器热轮询（=壁炉→HA 延迟 <1s） - [ ] 将恢复固件分离到专用分区 - [ ] 文档 www.isno.fr - [ ] GitHub 公开发布 ## 许可证 MIT（=参见 LICENSE） ## 免责声明 本项目是出于教育和个人使用目的，在个人设备上进行的逆向工程工作。不分发任何衍生自 Extraflame 的二进制代码。内置的 CA 证书源自作者的个人固件 dump（=仅供私下使用）。 在您的设备上使用此固件的风险由您自行承担。Extraflame 不为此类使用提供支持。 **兼容 TotalControl 2 的云端模式**需要注册了壁炉的官方 Extraflame 账户，并使用壁炉标签上的凭证（=matricola + secure_code）。未进行任何绕过或许证违规行为。

标签：ESP32, Home Assistant, 客户端加密, 嵌入式固件, 智能家居, 物联网, 请求拦截