thermIQ/CONTEXT.md

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 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)