# xx-nichtlachen-xx/opendtu architecture

> Architecture diagram of the GitHub repository xx-nichtlachen-xx/opendtu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xx-nichtlachen-xx/opendtu
- Repository: https://github.com/xx-nichtlachen-xx/opendtu

## Overview

OpenDTU is an ESP32-based telemetry gateway intended to replace a Hoymiles DTU, receiving inverter data and exposing it through a web interface and MQTT integrations. The runtime entry point initializes configuration, networking, MQTT handlers, the Web API, and display services before running the scheduler. The source excerpts establish these startup calls and Home Assistant publication behavior; several protocol, API, and frontend details are unsampled, so those relationships are shown only where documented or left unconnected.

Main entry points: [`src/main.cpp`](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/main.cpp) (Runtime startup), [`lib/Hoymiles/src/Hoymiles.cpp`](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/Hoymiles.cpp) (Hoymiles protocol), [`src/WebApi.cpp`](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi.cpp) (Web API), [`src/MqttHandleHass.cpp`](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleHass.cpp) (Home Assistant discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Device runtime"]
  node_main["Runtime startup<br/>[main.cpp]"]
  node_scheduler["Task scheduler<br/>[Scheduler.h]"]
end

subgraph group_protocol["Inverter communications"]
  node_inverter_core["Hoymiles protocol<br/>[Hoymiles.cpp]"]
  node_radio_cmt["CMT radio"]
  node_radio_nrf["NRF radio"]
  node_command_queue["Command queue<br/>[CommandQueue.cpp]"]
  node_alarm_parser["Alarm parser<br/>[AlarmLogParser.cpp]"]
  node_grid_parser["Grid profile parser"]
end

subgraph group_services["Device services"]
  node_config["Configuration<br/>[Configuration.cpp]"]
  node_datastore[("Telemetry state<br/>[Datastore.cpp]")]
  node_network["Network settings"]
  node_webapi["Web API<br/>[WebApi.cpp]"]
  node_api_inverter["Inverter endpoints"]
  node_api_mqtt["MQTT endpoints<br/>[WebApi_mqtt.cpp]"]
  node_display["Display output"]
end

subgraph group_integrations["External integrations"]
  node_mqtt_settings["MQTT connection<br/>[MqttSettings.cpp]"]
  node_mqtt_inverter["Inverter MQTT"]
  node_mqtt_hass["Home Assistant discovery<br/>[MqttHandleHass.cpp]"]
  node_mqtt_dtu["DTU MQTT<br/>[MqttHandleDtu.cpp]"]
  node_mqtt_total["Total MQTT"]
end

subgraph group_frontend["Web interface"]
  node_webapp["Web application<br/>[main.ts]"]
  node_app_shell["App shell<br/>[App.vue]"]
  node_home_view["Live dashboard<br/>[HomeView.vue]"]
  node_inverter_view["Inverter administration"]
end

node_operator(("Device user"))
node_mqtt_broker(("MQTT broker"))

node_operator -.->|"uses"| node_webapp
node_main -->|"initializes"| node_config
node_main -->|"initializes"| node_network
node_main -->|"initializes"| node_webapi
node_main -->|"initializes"| node_display
node_main -->|"initializes"| node_mqtt_settings
node_main -->|"initializes"| node_mqtt_inverter
node_main -->|"initializes"| node_mqtt_hass
node_main -->|"initializes"| node_mqtt_dtu
node_main -->|"initializes"| node_mqtt_total
node_main -->|"executes"| node_scheduler
node_mqtt_hass -->|"publishes through"| node_mqtt_settings
node_mqtt_hass -->|"reads local IP"| node_network
node_mqtt_settings -.->|"connects to"| node_mqtt_broker
node_inverter_core -.->|"uses radio"| node_radio_cmt
node_inverter_core -.->|"uses radio"| node_radio_nrf
node_inverter_core -.->|"dispatches commands"| node_command_queue
node_alarm_parser -.->|"parses responses"| node_inverter_core
node_grid_parser -.->|"parses responses"| node_inverter_core
node_webapi -.->|"routes to"| node_api_inverter
node_webapi -.->|"routes to"| node_api_mqtt
node_webapp -->|"mounts"| node_app_shell
node_app_shell -.->|"renders route"| node_home_view
node_app_shell -.->|"renders route"| node_inverter_view
node_webapp -.->|"requests data"| node_webapi

click node_main "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/main.cpp"
click node_scheduler "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/include/Scheduler.h"
click node_config "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Configuration.cpp"
click node_datastore "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Datastore.cpp"
click node_network "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/NetworkSettings.cpp"
click node_webapi "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi.cpp"
click node_api_inverter "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi_inverter.cpp"
click node_api_mqtt "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi_mqtt.cpp"
click node_display "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Display_Graphic.cpp"
click node_inverter_core "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/Hoymiles.cpp"
click node_radio_cmt "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/HoymilesRadio_CMT.cpp"
click node_radio_nrf "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/HoymilesRadio_NRF.cpp"
click node_command_queue "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/queue/CommandQueue.cpp"
click node_alarm_parser "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/parser/AlarmLogParser.cpp"
click node_grid_parser "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/parser/GridProfileParser.cpp"
click node_mqtt_settings "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttSettings.cpp"
click node_mqtt_inverter "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleInverter.cpp"
click node_mqtt_hass "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleHass.cpp"
click node_mqtt_dtu "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleDtu.cpp"
click node_mqtt_total "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleInverterTotal.cpp"
click node_webapp "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/main.ts"
click node_app_shell "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/App.vue"
click node_home_view "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/views/HomeView.vue"
click node_inverter_view "https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/views/InverterAdminView.vue"

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_scheduler,node_operator toneBlue
class node_inverter_core,node_radio_cmt,node_radio_nrf,node_command_queue,node_alarm_parser,node_grid_parser toneAmber
class node_config,node_datastore,node_network,node_webapi,node_api_inverter,node_api_mqtt,node_display toneMint
class node_mqtt_settings,node_mqtt_inverter,node_mqtt_hass,node_mqtt_dtu,node_mqtt_total toneRose
class node_webapp,node_app_shell,node_home_view,node_inverter_view,node_mqtt_broker toneIndigo
```

## Components

### Device runtime

- [Runtime startup](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/main.cpp): `src/main.cpp`
- [Task scheduler](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/include/Scheduler.h): `include/Scheduler.h`

### Inverter communications

- [Hoymiles protocol](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/Hoymiles.cpp): `lib/Hoymiles/src/Hoymiles.cpp`
- [CMT radio](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/HoymilesRadio_CMT.cpp): `lib/Hoymiles/src/HoymilesRadio_CMT.cpp`
- [NRF radio](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/HoymilesRadio_NRF.cpp): `lib/Hoymiles/src/HoymilesRadio_NRF.cpp`
- [Command queue](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/queue/CommandQueue.cpp): `lib/Hoymiles/src/queue/CommandQueue.cpp`
- [Alarm parser](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/parser/AlarmLogParser.cpp): `lib/Hoymiles/src/parser/AlarmLogParser.cpp`
- [Grid profile parser](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/lib/Hoymiles/src/parser/GridProfileParser.cpp): `lib/Hoymiles/src/parser/GridProfileParser.cpp`

### Device services

- [Configuration](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Configuration.cpp): `src/Configuration.cpp`
- [Telemetry state](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Datastore.cpp): `src/Datastore.cpp`
- [Network settings](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/NetworkSettings.cpp): `src/NetworkSettings.cpp`
- [Web API](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi.cpp): `src/WebApi.cpp`
- [Inverter endpoints](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi_inverter.cpp): `src/WebApi_inverter.cpp`
- [MQTT endpoints](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/WebApi_mqtt.cpp): `src/WebApi_mqtt.cpp`
- [Display output](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/Display_Graphic.cpp): `src/Display_Graphic.cpp`

### External integrations

- [MQTT connection](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttSettings.cpp): `src/MqttSettings.cpp`
- [Inverter MQTT](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleInverter.cpp): `src/MqttHandleInverter.cpp`
- [Home Assistant discovery](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleHass.cpp): `src/MqttHandleHass.cpp`
- [DTU MQTT](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleDtu.cpp): `src/MqttHandleDtu.cpp`
- [Total MQTT](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/src/MqttHandleInverterTotal.cpp): `src/MqttHandleInverterTotal.cpp`

### Web interface

- [Web application](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/main.ts): `webapp/src/main.ts`
- [App shell](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/App.vue): `webapp/src/App.vue`
- [Live dashboard](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/views/HomeView.vue): `webapp/src/views/HomeView.vue`
- [Inverter administration](https://github.com/xx-nichtlachen-xx/opendtu/blob/master/webapp/src/views/InverterAdminView.vue): `webapp/src/views/InverterAdminView.vue`

### Other components

- **Device user**
- **MQTT broker**

## Connections

- Device user → Web application: uses
- Runtime startup → Configuration: initializes (evidence: `src/main.cpp`)
- Runtime startup → Network settings: initializes (evidence: `src/main.cpp`)
- Runtime startup → Web API: initializes (evidence: `src/main.cpp`)
- Runtime startup → Display output: initializes (evidence: `src/main.cpp`)
- Runtime startup → MQTT connection: initializes (evidence: `src/main.cpp`)
- Runtime startup → Inverter MQTT: initializes (evidence: `src/main.cpp`)
- Runtime startup → Home Assistant discovery: initializes (evidence: `src/main.cpp`)
- Runtime startup → DTU MQTT: initializes (evidence: `src/main.cpp`)
- Runtime startup → Total MQTT: initializes (evidence: `src/main.cpp`)
- Runtime startup → Task scheduler: executes (evidence: `src/main.cpp`)
- Home Assistant discovery → MQTT connection: publishes through (evidence: `src/MqttHandleHass.cpp`)
- Home Assistant discovery → Network settings: reads local IP (evidence: `src/MqttHandleHass.cpp`)
- MQTT connection → MQTT broker: connects to
- Hoymiles protocol → CMT radio: uses radio
- Hoymiles protocol → NRF radio: uses radio
- Hoymiles protocol → Command queue: dispatches commands
- Alarm parser → Hoymiles protocol: parses responses
- Grid profile parser → Hoymiles protocol: parses responses
- Web API → Inverter endpoints: routes to
- Web API → MQTT endpoints: routes to
- Web application → App shell: mounts (evidence: `webapp/src/main.ts`)
- App shell → Live dashboard: renders route
- App shell → Inverter administration: renders route
- Web application → Web API: requests data
