# ThermIQ — Communication Architecture

## Overview

| Protocol | Usage | Physical |
|----------|-------|----------|
| RS485 Modbus RTU | Deye inverter, energy meters | RS485 bus, USB gateway |
| MQTT | Internal data bus | Ethernet/TCP |
| gRPC | Miner Braiins OS API | Ethernet/TCP |
| LAN/Ethernet | All IP devices | Wired, industrial switch |

## RS485 Modbus RTU

### Deye Hybrid Inverter

- **Protocol**: RS485 Modbus RTU (NOT Modbus TCP — LAN interface unreliable)
- **Library**: [sunsynk](https://github.com/kellerza/sunsynk) running on Raspberry Pi
- **Reference**: https://www.youtube.com/watch?v=u9df0YHfNtM
- **Data available**: Solar production, battery SOC, grid power, load consumption
- **Connection**: USB RS485 adapter → Raspberry Pi

### Energy Meters

- RS485 Modbus RTU
- Polled by Node-RED running on Raspberry Pi
- USB RS485 gateway on Raspberry Pi (or RevPi)

## MQTT

**Broker**: Mosquitto, running on Raspberry Pi, localhost
**Port**: 1883 (standard)
**Clients**:
- RevolutionPi: publishes field state, subscribes to setpoints
- Node-RED: publishes Modbus data, subscribes to RevPi state
- Home Assistant: subscribes to all topics (read-only visualization)

### Topic Structure (planned)

```
thermiq/
├── miners/
│   ├── 1/state          # online | offline | error
│   ├── 1/power          # watts
│   ├── 1/hashrate       # TH/s
│   ├── 2/state
│   └── 2/power
├── pumps/
│   ├── p3/setpoint      # 0.0–10.0 V
│   ├── p4/setpoint
│   └── p5/setpoint
├── valves/
│   ├── rv1/state        # open | closed | moving
│   └── rv2/state
├── cooler/state         # on | off
├── heatpump/
│   ├── evu_sperre       # true | false
│   └── state            # running | blocked | fault
├── inverter/
│   ├── solar_power      # W
│   ├── battery_soc      # %
│   ├── grid_power       # W (negative = export)
│   └── load_power       # W
├── temps/
│   ├── puffer           # °C
│   ├── warmwasser       # °C
│   └── miner_outlet     # °C
└── safety/
    ├── state            # ok | tripped
    └── reason           # flow | temp | estop | none
```

## Braiins OS gRPC API

**Server**: Antminer with Braiins OS, port 50051
**Service**: `braiins.bos.v1.PerformanceService`
**Auth**: Bearer token in metadata
**Key methods**:
- `GetTunerState` — current power tuning state
- Power scaling via tuner (reduce hash rate = reduce power = reduce heat)

**Reference implementation**: `src/miners/client.js`

### Integration Pattern

```
Node-RED → HTTP/gRPC call → Antminer → response
                ↓
            MQTT publish → thermiq/miners/1/power
```

## Network Configuration

| Device | IP | Role |
|--------|-----|------|
| RevolutionPi | fixed (e.g. 192.168.0.10) | PLC, MQTT client |
| Raspberry Pi | fixed (e.g. 192.168.0.11) | MQTT broker, Node-RED, HA |
| Miner 1 | fixed (e.g. 192.168.0.101) | Braiins gRPC |
| Miner 2 | fixed (e.g. 192.168.0.102) | Braiins gRPC |
| Deye inverter | RS485 only | not on LAN |

- All wired Ethernet, no WiFi for critical devices
- NTP time synchronization required on RevPi and RPi
- VLAN optional but recommended for isolation
- Industrial managed switch preferred

## Deye RS485 Wiring Note

The Deye inverter's native Modbus TCP LAN interface is not trusted for production use. Use RS485 directly. Wire RS485 A/B to USB adapter on Raspberry Pi. Termination resistor at cable end if bus > 1 device.