# arjenhiemstra/ithowifi architecture

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

- Interactive diagram: https://gitdiagram.com/arjenhiemstra/ithowifi
- Repository: https://github.com/arjenhiemstra/ithowifi

## Overview

IthoWiFi is ESP32 firmware that connects Itho ventilation units to Wi-Fi for local control and home-automation integration. The principal workflow is a user or automation client issuing a fan-control command through REST, MQTT, or the web interface; the firmware communicates with the unit over I2C or RF. The README also documents Home Assistant discovery, live WebSocket updates, sensors, and web-triggered OTA updates. Paths come from the tree; most implementation excerpts were not sampled, so links show documented product flows rather than unverified internal call chains.

Main entry points: [`software/NRG_itho_wifi/main/ithodevice/IthoDevice.cpp`](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/ithodevice/IthoDevice.cpp) (Itho device logic), [`software/NRG_itho_wifi/main/handlers/WebServerHandlers.cpp`](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/handlers/WebServerHandlers.cpp) (Web handlers), [`software/NRG_itho_wifi/main/api/MqttAPI.cpp`](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/api/MqttAPI.cpp) (MQTT API), [`software/NRG_itho_wifi/main/webroot_source/controls.js`](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/webroot_source/controls.js) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User interfaces"]
  node_web["Web interface<br/>[controls.js]"]
  node_web_handlers["Web handlers"]
  node_rest["REST API v2<br/>[WebAPIv2Rest.cpp]"]
  node_websocket["WebSocket"]
end

subgraph group_domain["Ventilation control"]
  node_itho["Itho device logic<br/>[IthoDevice.cpp]"]
  node_i2c["I2C interface<br/>[i2c_esp32.cpp]"]
  node_rf["RF control<br/>[RFManager.cpp]"]
  node_radio["CC1101 radio<br/>[IthoCC1101.cpp]"]
  node_queue["Itho command queue<br/>[IthoQueue.cpp]"]
end

subgraph group_connectivity["Network integrations"]
  node_mqtt["MQTT API<br/>[MqttAPI.cpp]"]
  node_discovery["HA discovery<br/>[HADiscovery.cpp]"]
  node_network["Network manager<br/>[NetworkManager.cpp]"]
  node_wifi["Wi-Fi connection"]
end

subgraph group_operations["Device operations"]
  node_config["Configuration<br/>[Config.cpp]"]
  node_sensor["Sensor manager<br/>[SensorManager.cpp]"]
  node_ota["OTA updates"]
  node_tasks["Firmware tasks<br/>[task_init.cpp]"]
end

node_user(("User"))
node_automation(("Automation client"))
node_unit(("Itho unit"))

node_user -->|"controls"| node_web
node_user -->|"sends commands"| node_rest
node_automation -->|"sends commands"| node_rest
node_automation -->|"publishes commands"| node_mqtt
node_web -->|"requests"| node_web_handlers
node_web_handlers -->|"controls"| node_itho
node_rest -->|"controls"| node_itho
node_mqtt -->|"controls"| node_itho
node_itho -->|"queues commands"| node_queue
node_itho -->|"communicates"| node_i2c
node_itho -.->|"communicates"| node_rf
node_i2c -->|"exchanges data"| node_unit
node_rf -.->|"dispatches commands"| node_radio
node_radio -.->|"sends RF"| node_unit
node_unit -.->|"sends status"| node_radio
node_mqtt -->|"publishes status"| node_automation
node_websocket -->|"streams updates"| node_web
node_discovery -->|"announces device"| node_automation
node_network -->|"manages connection"| node_wifi
node_config -->|"provides settings"| node_network
node_sensor -->|"provides readings"| node_itho
node_web_handlers -->|"initiates updates"| node_ota
node_ota -->|"downloads firmware"| node_automation
node_tasks -->|"initializes device"| node_itho

click node_web "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/webroot_source/controls.js"
click node_web_handlers "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/handlers/WebServerHandlers.cpp"
click node_rest "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/api/WebAPIv2Rest.cpp"
click node_websocket "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/handlers/WebSocketHandlers.cpp"
click node_mqtt "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/api/MqttAPI.cpp"
click node_discovery "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/HADiscovery.cpp"
click node_network "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/NetworkManager.cpp"
click node_wifi "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/WiFiConnectionManager.cpp"
click node_itho "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/ithodevice/IthoDevice.cpp"
click node_i2c "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/ithodevice/i2c_esp32.cpp"
click node_rf "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/RFManager.cpp"
click node_radio "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/cc1101/IthoCC1101.cpp"
click node_queue "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/IthoQueue.cpp"
click node_config "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/config/Config.cpp"
click node_sensor "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/SensorManager.cpp"
click node_ota "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/SecureWebCommLite.cpp"
click node_tasks "https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/tasks/task_init.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_web,node_web_handlers,node_rest,node_websocket,node_user,node_automation toneBlue
class node_itho,node_i2c,node_rf,node_radio,node_queue toneAmber
class node_mqtt,node_discovery,node_network,node_wifi toneMint
class node_config,node_sensor,node_ota,node_tasks toneRose
class node_unit toneIndigo
```

## Components

### User interfaces

- [Web interface](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/webroot_source/controls.js): `software/NRG_itho_wifi/main/webroot_source/controls.js`
- [Web handlers](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/handlers/WebServerHandlers.cpp): `software/NRG_itho_wifi/main/handlers/WebServerHandlers.cpp`
- [REST API v2](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/api/WebAPIv2Rest.cpp): `software/NRG_itho_wifi/main/api/WebAPIv2Rest.cpp`
- [WebSocket](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/handlers/WebSocketHandlers.cpp): `software/NRG_itho_wifi/main/handlers/WebSocketHandlers.cpp`

### Ventilation control

- [Itho device logic](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/ithodevice/IthoDevice.cpp): `software/NRG_itho_wifi/main/ithodevice/IthoDevice.cpp`
- [I2C interface](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/ithodevice/i2c_esp32.cpp): `software/NRG_itho_wifi/main/ithodevice/i2c_esp32.cpp`
- [RF control](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/RFManager.cpp): `software/NRG_itho_wifi/main/managers/RFManager.cpp`
- [CC1101 radio](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/cc1101/IthoCC1101.cpp): `software/NRG_itho_wifi/main/cc1101/IthoCC1101.cpp`
- [Itho command queue](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/IthoQueue.cpp): `software/NRG_itho_wifi/main/IthoQueue.cpp`

### Network integrations

- [MQTT API](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/api/MqttAPI.cpp): `software/NRG_itho_wifi/main/api/MqttAPI.cpp`
- [HA discovery](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/HADiscovery.cpp): `software/NRG_itho_wifi/main/HADiscovery.cpp`
- [Network manager](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/NetworkManager.cpp): `software/NRG_itho_wifi/main/managers/NetworkManager.cpp`
- [Wi-Fi connection](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/WiFiConnectionManager.cpp): `software/NRG_itho_wifi/main/managers/WiFiConnectionManager.cpp`

### Device operations

- [Configuration](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/config/Config.cpp): `software/NRG_itho_wifi/main/config/Config.cpp`
- [Sensor manager](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/SensorManager.cpp): `software/NRG_itho_wifi/main/managers/SensorManager.cpp`
- [OTA updates](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/managers/SecureWebCommLite.cpp): `software/NRG_itho_wifi/main/managers/SecureWebCommLite.cpp`
- [Firmware tasks](https://github.com/arjenhiemstra/ithowifi/blob/master/software/NRG_itho_wifi/main/tasks/task_init.cpp): `software/NRG_itho_wifi/main/tasks/task_init.cpp`

### Other components

- **User**
- **Automation client**
- **Itho unit**

## Connections

- User → Web interface: controls
- User → REST API v2: sends commands
- Automation client → REST API v2: sends commands
- Automation client → MQTT API: publishes commands
- Web interface → Web handlers: requests
- Web handlers → Itho device logic: controls
- REST API v2 → Itho device logic: controls
- MQTT API → Itho device logic: controls
- Itho device logic → Itho command queue: queues commands
- Itho device logic → I2C interface: communicates
- Itho device logic → RF control: communicates
- I2C interface → Itho unit: exchanges data
- RF control → CC1101 radio: dispatches commands
- CC1101 radio → Itho unit: sends RF
- Itho unit → CC1101 radio: sends status
- MQTT API → Automation client: publishes status
- WebSocket → Web interface: streams updates
- HA discovery → Automation client: announces device
- Network manager → Wi-Fi connection: manages connection
- Configuration → Network manager: provides settings
- Sensor manager → Itho device logic: provides readings
- Web handlers → OTA updates: initiates updates
- OTA updates → Automation client: downloads firmware
- Firmware tasks → Itho device logic: initializes device