# phunkafizer/ot-thing architecture

> Architecture diagram of the GitHub repository phunkafizer/ot-thing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phunkafizer/ot-thing
- Repository: https://github.com/phunkafizer/ot-thing

## Overview

OTthing is ESP32 firmware bridging OpenTherm equipment to local web, MQTT, and Home Assistant interfaces. Its main loop initializes and services the communication, network, portal, sensor, and integration modules. The graph preserves the documented heating-control stages and major user-facing capabilities. Some subsystem interactions are documented only at a high level; dashed edges mark those unverified links rather than asserting source-level calls.

Main entry points: [`Firmware/src/otcontrol.cpp`](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/otcontrol.cpp) (OpenTherm control), [`Firmware/src/main.cpp`](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/main.cpp) (Firmware runtime), [`Firmware/src/portal.cpp`](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/portal.cpp) (Web portal and API), [`Firmware/src/mqtt.cpp`](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/mqtt.cpp) (MQTT integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and network"]
  node_main["Firmware runtime<br/>[main.cpp]"]
  node_network["WiFi provisioning<br/>[netw.cpp]"]
  node_config[("Device configuration<br/>[devconfig.cpp]")]
end

subgraph group_opentherm["OpenTherm gateway"]
  node_otcontrol["OpenTherm control<br/>[otcontrol.cpp]"]
  node_requests["Master requests<br/>[masterrequests.cpp]"]
  node_values["OpenTherm values<br/>[otvalues.cpp]"]
end

subgraph group_heating["Heating control"]
  node_heating["Heating circuits<br/>[CHcontrol.cpp]"]
  node_curve["Heating curve<br/>[heatingcurve.cpp]"]
  node_schedule["Time scheduler<br/>[scheduler.cpp]"]
  node_dhw["DHW control<br/>[dhwControl.cpp]"]
  node_vent["Ventilation control<br/>[vent.cpp]"]
  node_flame["Flame statistics<br/>[flamestats.cpp]"]
end

subgraph group_interfaces["Web interface"]
  node_portal["Web portal and API<br/>[portal.cpp]"]
  node_commands["Command interface<br/>[command.cpp]"]
end

subgraph group_integrations["Integrations and telemetry"]
  node_sensors["Sensors and telemetry<br/>[sensors.cpp]"]
  node_aux["Auxiliary inputs<br/>[auxInput.cpp]"]
  node_status["Runtime status<br/>[devstatus.cpp]"]
  node_mqtt["MQTT integration<br/>[mqtt.cpp]"]
  node_discovery["Home Assistant discovery<br/>[HADiscLocal.cpp]"]
  node_ha_library["Discovery publisher<br/>[HADiscovery.cpp]"]
end

node_user(("Local user"))
node_boiler{{"Boiler / thermostat"}}
node_ha(("Home Assistant"))
node_broker{{"MQTT broker"}}

node_main -->|"initializes / services"| node_network
node_main -->|"initializes / services"| node_config
node_main -->|"initializes / services"| node_otcontrol
node_main -->|"initializes / services"| node_portal
node_main -->|"initializes"| node_commands
node_main -->|"initializes / services"| node_sensors
node_main -->|"initializes"| node_discovery
node_main -->|"initializes / services"| node_mqtt
node_main -->|"services"| node_aux
node_user -->|"uses dashboard / API"| node_portal
node_portal -.->|"provisions WiFi"| node_network
node_portal -.->|"requests control"| node_otcontrol
node_portal -.->|"reads / updates"| node_config
node_boiler -->|"OpenTherm messages"| node_otcontrol
node_otcontrol -.->|"uses polling requests"| node_requests
node_otcontrol -.->|"decodes / exposes"| node_values
node_otcontrol -.->|"manages circuits"| node_heating
node_heating -.->|"calculates flow target"| node_curve
node_heating -.->|"schedules setpoints"| node_schedule
node_otcontrol -.->|"coordinates DHW"| node_dhw
node_otcontrol -.->|"supports ventilation"| node_vent
node_otcontrol -.->|"tracks flame data"| node_flame
node_sensors -.->|"provides measurements"| node_otcontrol
node_aux -.->|"supplies control inputs"| node_heating
node_otcontrol -.->|"updates health state"| node_status
node_mqtt -->|"publishes / subscribes"| node_broker
node_ha -->|"integrates through MQTT"| node_broker
node_discovery -->|"uses discovery support"| node_ha_library
node_discovery -.->|"publishes discovery"| node_mqtt
node_mqtt -.->|"applies control topics"| node_otcontrol
node_mqtt -.->|"publishes telemetry"| node_sensors

click node_main "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/main.cpp"
click node_network "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/netw.cpp"
click node_config "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/devconfig.cpp"
click node_portal "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/portal.cpp"
click node_commands "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/command.cpp"
click node_otcontrol "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/otcontrol.cpp"
click node_requests "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/masterrequests.cpp"
click node_values "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/otvalues.cpp"
click node_heating "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/CHcontrol.cpp"
click node_curve "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/heatingcurve.cpp"
click node_schedule "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/scheduler.cpp"
click node_dhw "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/dhwControl.cpp"
click node_vent "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/vent.cpp"
click node_flame "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/flamestats.cpp"
click node_sensors "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/sensors.cpp"
click node_aux "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/auxInput.cpp"
click node_status "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/devstatus.cpp"
click node_mqtt "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/mqtt.cpp"
click node_discovery "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/HADiscLocal.cpp"
click node_ha_library "https://github.com/phunkafizer/ot-thing/blob/master/Firmware/lib/HADiscovery/src/HADiscovery.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_network,node_config,node_user toneBlue
class node_otcontrol,node_requests,node_values toneAmber
class node_heating,node_curve,node_schedule,node_dhw,node_vent,node_flame toneMint
class node_portal,node_commands toneRose
class node_sensors,node_aux,node_status,node_mqtt,node_discovery,node_ha_library,node_boiler,node_ha,node_broker toneIndigo
```

## Components

### Runtime and network

- [Firmware runtime](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/main.cpp): `Firmware/src/main.cpp`
- [WiFi provisioning](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/netw.cpp): `Firmware/src/netw.cpp`
- [Device configuration](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/devconfig.cpp): `Firmware/src/devconfig.cpp`

### OpenTherm gateway

- [OpenTherm control](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/otcontrol.cpp): `Firmware/src/otcontrol.cpp`
- [Master requests](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/masterrequests.cpp): `Firmware/src/masterrequests.cpp`
- [OpenTherm values](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/otvalues.cpp): `Firmware/src/otvalues.cpp`

### Heating control

- [Heating circuits](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/CHcontrol.cpp): `Firmware/src/CHcontrol.cpp`
- [Heating curve](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/heatingcurve.cpp): `Firmware/src/heatingcurve.cpp`
- [Time scheduler](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/scheduler.cpp): `Firmware/src/scheduler.cpp`
- [DHW control](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/dhwControl.cpp): `Firmware/src/dhwControl.cpp`
- [Ventilation control](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/vent.cpp): `Firmware/src/vent.cpp`
- [Flame statistics](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/flamestats.cpp): `Firmware/src/flamestats.cpp`

### Web interface

- [Web portal and API](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/portal.cpp): `Firmware/src/portal.cpp`
- [Command interface](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/command.cpp): `Firmware/src/command.cpp`

### Integrations and telemetry

- [Sensors and telemetry](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/sensors.cpp): `Firmware/src/sensors.cpp`
- [Auxiliary inputs](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/auxInput.cpp): `Firmware/src/auxInput.cpp`
- [Runtime status](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/devstatus.cpp): `Firmware/src/devstatus.cpp`
- [MQTT integration](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/mqtt.cpp): `Firmware/src/mqtt.cpp`
- [Home Assistant discovery](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/src/HADiscLocal.cpp): `Firmware/src/HADiscLocal.cpp`
- [Discovery publisher](https://github.com/phunkafizer/ot-thing/blob/master/Firmware/lib/HADiscovery/src/HADiscovery.cpp): `Firmware/lib/HADiscovery/src/HADiscovery.cpp`

### Other components

- **Local user**
- **Boiler / thermostat**
- **Home Assistant**
- **MQTT broker**

## Connections

- Firmware runtime → WiFi provisioning: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Device configuration: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → OpenTherm control: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Web portal and API: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Command interface: initializes (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Sensors and telemetry: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Home Assistant discovery: initializes (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → MQTT integration: initializes / services (evidence: `Firmware/src/main.cpp`)
- Firmware runtime → Auxiliary inputs: services (evidence: `Firmware/src/main.cpp`)
- Local user → Web portal and API: uses dashboard / API (evidence: `README.md`)
- Web portal and API → WiFi provisioning: provisions WiFi
- Web portal and API → OpenTherm control: requests control
- Web portal and API → Device configuration: reads / updates
- Boiler / thermostat → OpenTherm control: OpenTherm messages (evidence: `README.md`)
- OpenTherm control → Master requests: uses polling requests
- OpenTherm control → OpenTherm values: decodes / exposes
- OpenTherm control → Heating circuits: manages circuits
- Heating circuits → Heating curve: calculates flow target
- Heating circuits → Time scheduler: schedules setpoints
- OpenTherm control → DHW control: coordinates DHW
- OpenTherm control → Ventilation control: supports ventilation
- OpenTherm control → Flame statistics: tracks flame data
- Sensors and telemetry → OpenTherm control: provides measurements
- Auxiliary inputs → Heating circuits: supplies control inputs
- OpenTherm control → Runtime status: updates health state
- MQTT integration → MQTT broker: publishes / subscribes (evidence: `README.md`)
- Home Assistant → MQTT broker: integrates through MQTT (evidence: `README.md`)
- Home Assistant discovery → Discovery publisher: uses discovery support
- Home Assistant discovery → MQTT integration: publishes discovery
- MQTT integration → OpenTherm control: applies control topics
- MQTT integration → Sensors and telemetry: publishes telemetry