thermIQ/docs/ARCHITECTURE.md

ThermIQ — System Architecture

Overview

ThermIQ is a local-first hybrid energy and heating system. The architecture has three layers:

1. Field layer — physical hardware (miners, pumps, valves, sensors)
2. Control layer — RevolutionPi PLC + safety relay
3. Supervision layer — Raspberry Pi (Node-RED + Home Assistant + MQTT)

┌─────────────────────────────────────────────────────────────┐
│                    SUPERVISION LAYER                         │
│   Raspberry Pi: Node-RED | Home Assistant | Mosquitto MQTT  │
└─────────────────────┬───────────────────────────────────────┘
                      │ MQTT (LAN)
┌─────────────────────▼───────────────────────────────────────┐
│                    CONTROL LAYER                             │
│   RevolutionPi Core+DIO+AIO   ←→   Safety Relay (HW)       │
└──────┬──────────────────────────────────────┬───────────────┘
       │ 0-10V / DO / DI                      │ Contactor coils
┌──────▼──────────────────────────────────────▼───────────────┐
│                    FIELD LAYER                               │
│  Miners K10/K11 | Pumps P3-P5 | Valves RV1-RV2             │
│  Cooler K2 | Heat Pump K7 | Sensors | Energy Meters         │
└─────────────────────────────────────────────────────────────┘

Energy Flow Decision Logic

Solar production > consumption?
  → YES: Run miners + charge battery
  → NO:  Battery available?
           → YES: Run miners from battery
           → NO:  Check grid tariff / time of day
                   → Cheap: Run miners from grid
                   → Expensive: Reduce/stop miners

Miner waste heat available?
  → YES: Route to Pufferspeicher via pumps
  → Need cooling? → Rückkühler ON

Pufferspeicher temperature sufficient?
  → YES: Heat pump OFF (EVU Sperre = block)
  → NO:  Heat pump ON (EVU Sperre = release)

Network Topology

[Industrial Switch]
    ├── RevolutionPi (fixed IP, MQTT client)
    ├── Raspberry Pi (fixed IP)
    │     ├── Mosquitto MQTT Broker
    │     ├── Node-RED (Modbus client + automation)
    │     └── Home Assistant (visualization + dashboards)
    ├── USB RS485 Gateway (energy meters, Deye inverter)
    └── [Optional: cloud read-only APIs]

Fixed IPs required for RevPi and MQTT broker. NTP time sync required.

MQTT Data Bus

All internal state flows through MQTT topics on Mosquitto broker (localhost on RPi).

Planned topic structure (TBD):

• thermiq/miners/+/state
• thermiq/miners/+/power
• thermiq/pumps/+/setpoint
• thermiq/pumps/+/feedback
• thermiq/valves/+/state
• thermiq/inverter/+/power
• thermiq/inverter/+/soc
• thermiq/grid/power
• thermiq/temps/puffer
• thermiq/temps/warmwasser
• thermiq/safety/state

Control Philosophy

• RevolutionPi = logic engine and field I/O. Publishes/subscribes MQTT.
• Node-RED = Modbus polling (Deye RS485, energy meters), automation flows, MQTT bridge.
• Home Assistant = visualization only. Does not control field devices directly.
• Safety relay = hardware-only. Independent of all software. Miners cannot run without safety OK.

Seasonal Modes (planned)

Mode	Description
Winter	Miners primary heat source; heat pump backup
Summer	Miners cooled via Rückkühler; heat pump off
Spring/Autumn	Hybrid, temperature-controlled transition
Maintenance	Manual override, miners off

Fallback / Fail-Safe Behavior

Failure	Behavior
RevPi crash	Miners shut down (safety relay de-energizes contactors)
MQTT offline	Heat pump autonomous (EVU contact open = run)
Network loss	All field devices fail-safe (pumps at last setpoint or min)
Temperature MAX	Safety relay trips → miners off immediately
Flow loss	Safety relay trips → miners off immediately

Integration Points

System	Protocol	Direction
Deye inverter	RS485 Modbus RTU	Read (power, SOC, grid)
Energy meters	RS485 Modbus RTU	Read (consumption)
Miners (Braiins OS)	gRPC over LAN	Read/Write (tuner, power)
RevPi	MQTT	Bidirectional
Smartmeter	(TBD)	Read