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