# ThermIQ — AI Context / Knowledge Base This file is the master reference for any AI assistant working on ThermIQ. Read this before asking questions or making any suggestions. --- ## What is ThermIQ? ThermIQ (formerly Kryptoheat, project codename ASP1) is a smart hybrid heating system built for German residential homes. The core idea: **crypto miners produce enormous waste heat** — instead of dumping it, ThermIQ routes it into the building's heating system. A smart controller decides when to mine (based on solar/battery/grid economics), how much to mine, and how to distribute the resulting heat. **First installation**: Walda, Germany (a private home with existing Buderus heat pump). --- ## Team & Roles - **Adrian** = software and automation expert + Schaltschrank (electrical cabinet) builder - Other team members access shared docs via Nextcloud at `~/Nextcloud/Projekte/ThermIQ` - Do NOT write to the Nextcloud folder without Adrian's explicit consent --- ## Hardware Stack ### Crypto Miners - 2x **Antminer S19J** (Bitmain) - Run **Braiins OS** (not stock firmware) — exposes gRPC API on port 50051 - Each miner: 2x Schuko plugs → through contactor K10/K11 → through LS breaker → AC bus - Power ~3200 W each at full hash rate → ~14 A per miner per circuit - API: `braiins.bos.v1.PerformanceService` — `GetTunerState`, power tuning - Auth: Bearer token in gRPC metadata ### PLC: RevolutionPi - KUNBUS **RevolutionPi** (Linux-based industrial PLC) - Modules: **Core** (CPU + LAN) + **DIO** (digital I/O) + **AIO** (analog I/O) - Runs MQTT client, connects to switch via Ethernet - Programs RevPi in Python or using Node-RED via MQTT - If RevPi crashes: miners MUST shut down (hardware-enforced by safety relay) ### Solar / Energy: Deye Hybrid Inverters - **Deye hybrid inverter(s)** — model TBD - DO NOT use Modbus TCP over LAN (native LAN interface is unreliable) - Use **RS485 Modbus RTU** instead - Library: **[sunsynk](https://github.com/kellerza/sunsynk)** on Raspberry Pi - Data: solar production (W), battery SOC (%), grid power (W), load (W) ### Battery Storage - Coupled to Deye inverter - Capacity TBD - SOC read via sunsynk/RS485 ### Heat Pump: Buderus WLW186i - **EVU input I1** = dry contact ONLY (potential-free) - Controlled via relay **K7** (24 V DC coil, potential-free output) - Close K7 = EVU Sperre = block heat pump - Open K7 = heat pump free to run (default) - RevPi DO → K7 coil → I1 contact - CRITICAL: Never inject voltage into I1 ### Pumps - **P3**: simple circuit pump (miner cooling loop) — 230V AC, **relay on/off only** (no speed control), RevPi DO - **P4**: **Wilo Stratos PICO plus** (Art.-No. 4244373) — 230V AC + **0-10V analog setpoint** via RevPi AIO AO1 - **P5**: **Wilo Stratos PICO plus** (Art.-No. 4244373) — 230V AC + **0-10V analog setpoint** via RevPi AIO AO2 (Glykol/solar loop) - Only 2x AO required → **1x RevPi AIO module** is sufficient - BMS Connect Module (Wilo Art. 4257834): optional retrofit for 0-10V / SSM / SBM - ⚠️ NOTE: P5 connection to ASP1 is missing the dotted control line in Funktionsschema_Vorlage_Hydraulik.pdf — schema error, P5 IS controlled by ASP1 ### Valves: Belimo - **RV1**, **RV2**: Belimo C320Q-J (3-way valve body) - Actuator: **CQ230A** (230V AC, spring return) - Controlled via relay block K3/K4 (RV1) and K5/K6 (RV2) - RevPi DO → relay → actuator ### Dry Cooler (Rückkühler) - 230V AC fan motor - Relay K2 (24V DC coil) - RevPi DO → K2 - Optional fault feedback to RevPi DI - Enabled only when cooling is needed AND pumps/oil are OK ### Thermal Storage - **Pufferspeicher**: buffer tank (receives miner heat, supplies space heating) - **Warmwasserspeicher**: domestic hot water tank - Temperature sensors: PT1000 or 4-20 mA (exact type TBD) ### Smart Meter - Grid metering — integration protocol TBD ### Energy Meters - RS485 Modbus RTU - Polled by Node-RED via USB RS485 adapter on Raspberry Pi --- ## Safety Architecture **Golden rule: safety is purely hardware. Software is never in the safety chain.** ### Hardware Safety Chain ``` E-Stop 1 (NC) ──┐ E-Stop 2 (NC) ──┤ FLOW OK (NC) ──┤──→ Dual-channel safety relay (Rückführkreis) → K10, K11 coils TEMP MAX (NC) ──┤ Reset (NO) ──┘ ``` - Any NC contact opens = safety relay drops = K10/K11 de-energize = miners off - Manual reset required after trip - K10/K11 Hilfskontakt feeds back into relay Rückführkreis AND RevPi DI (monitoring only) - RevPi gets "Safety OK" signal on DI — software awareness, not control --- ## Communication Architecture | Protocol | Devices | Physical | |----------|---------|----------| | RS485 Modbus RTU | Deye inverter, energy meters | USB RS485 on RPi | | MQTT | RevPi ↔ RPi (Node-RED/HA) | Wired Ethernet | | gRPC (Braiins) | Miners | Wired Ethernet | | 0-10 V analog | Pumps P3-P5 | Shielded cable from RevPi AIO | | Dry contact | Heat pump EVU K7 | Cabinet wiring | | Digital relay | Valves, cooler, contactors | Cabinet wiring | ### Network Rules - Wired Ethernet ONLY for critical devices - Fixed IPs for RevPi and MQTT broker - NTP required - Cloud = optional, read-only, never safety-critical --- ## Software Stack | Layer | Software | Platform | |-------|---------|----------| | PLC logic | RevPi program (Python/IEC 61131) + MQTT | RevolutionPi | | Modbus polling | Node-RED or sunsynk | Site Server (Intel N100) | | Automation flows | Node-RED | Site Server (Intel N100) | | Message bus | Mosquitto MQTT | Site Server (Intel N100) | | Visualization | Home Assistant (Phase 1) → custom web app (Phase 2) | Site Server (Intel N100) | | Miner API | gRPC client (client.js) | Node.js / Site Server | | Inverter data | sunsynk Python library | Site Server (Intel N100) | ### Migration Strategy (Phase 1 → Phase 2) Phase 1 (current): Home Assistant as dashboard + automation glue, runs on Intel N100 alongside Node-RED and Mosquitto. Phase 2 (future): Replace HA with a custom web app (fleet dashboard, multi-site). All logic stays in Node-RED and MQTT — only the visualization layer changes. This is safe because: - Node-RED is the single source of automation logic (not HA automations) - MQTT is the single source of truth for all state - HA is read-only consumer of MQTT topics in Phase 1 — no logic embedded in HA **Rule for Phase 1 development:** Never put control logic inside HA automations. All logic lives in Node-RED. HA is a dashboard only. --- ## Control Logic (Decision Engine) ### Energy Routing Decision ``` 1. Check solar production (from Deye RS485) 2. Check battery SOC (from Deye RS485) 3. Check grid tariff / time-of-use pricing 4. Decision: should miners run? → control K10/K11 via safety relay enable 5. If miners run: monitor outlet temperature 6. Route miner heat to Pufferspeicher via pumps P3/P4 7. If Pufferspeicher too hot: open Rückkühler (K2) 8. If Pufferspeicher too cold: release heat pump (K7 open) ``` ### Thermal Priority - Summer: miners → Rückkühler (reject excess heat outdoors) - Winter: miners → Pufferspeicher → space heating - Always: domestic hot water from Warmwasserspeicher via pump --- ## Project File Structure (~/Projects/ThermIQ) ``` ThermIQ/ ├── CONTEXT.md ← this file ├── README.md ├── .gitignore ├── docs/ │ ├── HARDWARE.md ← all components and specs │ ├── ARCHITECTURE.md ← system topology and data flows │ ├── SAFETY.md ← safety chain, non-negotiables │ ├── COMMUNICATION.md ← RS485, MQTT, gRPC, network │ └── SCHALTSCHRANK.md ← cabinet design, I/O mapping, commissioning └── src/ ├── miners/ │ ├── client.js ← Braiins gRPC client │ └── README.md └── nodered/ └── README.md ``` --- ## Key Decisions & Constraints (from agents.md) 1. Deye inverters: use RS485, NOT LAN Modbus TCP 2. EVU input: dry contact only, NEVER inject voltage 3. Miners: always hard-disconnectable (hardware, not software) 4. Safety relay: dual-channel with Rückführkreis 5. RevPi crash = miners off (by design) 6. No WiFi for critical components 7. Cloud = optional, read-only 8. Local-first: system survives complete internet outage 9. Wired Ethernet, industrial switch, fixed IPs 10. Documentation: multiple small diagrams per subsystem (no monolithic schemas) --- ## Open Questions / Future Work - MQTT topic structure (structure defined above is provisional) - Error handling and fallback state machine - Thermal priority logic: miner vs. heat pump scheduling - Seasonal operating modes (Winter/Summer/Spring/Autumn/Maintenance) - Remote update strategy for RevPi and RPi - Long-term energy statistics and logging - Smart meter integration - Exact sensor types for Pufferspeicher / Warmwasser (PT1000 vs 4-20mA) - Battery capacity and type --- ## Source Files in Nextcloud (read-only for AI) - `251107_GA_Unterlagen_Walda_Heizungstechnik/3_Schema/Topologie/KryptoheatTopologie.drawio` — 8-page topology diagram - `251107_GA_Unterlagen_Walda_Heizungstechnik/3_Schema/Topologie/agents.md` — original AI agent memory - `251107_GA_Unterlagen_Walda_Heizungstechnik/1_Anlagenbeschreibung/` — plant description docs (XLSX/PDF) - `251107_GA_Unterlagen_Walda_Heizungstechnik/4_Datenblätter/` — component datasheets - `251107_GA_Unterlagen_Walda_Heizungstechnik/5_Programmierung/Javascript/client.js` — gRPC client source - `workspace/Node-red/` — Node-RED workspace (package.json: node-red 4.1.1)