Adrian Bretsch
ba6622bed7
All Markdown documentation files for the ThermIQ smart hybrid heating system. PDFs excluded via .gitignore — generated on demand. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
240 lines
9.4 KiB
Markdown
240 lines
9.4 KiB
Markdown
# 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)
|