# 0adill3/mqtt_ota architecture

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

- Interactive diagram: https://gitdiagram.com/0adill3/mqtt_ota
- Repository: https://github.com/0adill3/mqtt_ota

## Overview

MQTT_OTA enables an ESP32 to receive and validate firmware updates over an existing MQTT connection. The workflow runs from a Python publisher’s firmware preparation and staged MQTT messages, through device-side begin/chunk/end handling, to flash validation, version persistence, and restart. The README documents the example’s loop and callback delegation; the sampled example source was not available, so those links reflect documented usage only.

Main entry points: [`tools/MQTT_OTA_firmware_publisher.py`](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py) (Python publisher), [`src/MQTT_OTA.cpp`](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp) (OTA coordinator), [`examples/Basic_MQTT_OTA/Basic_MQTT_OTA.ino`](https://github.com/0adill3/mqtt_ota/blob/main/examples/Basic_MQTT_OTA/Basic_MQTT_OTA.ino) (Device application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_publisher["Firmware Publisher"]
  node_publisher_app["Python publisher"]
  node_hash["MD5 preparation"]
  node_begin_stage["Begin metadata"]
  node_data_stage["Chunk transfer"]
  node_end_stage["End signal"]
end

subgraph group_device["ESP32 OTA"]
  node_example_app["Device application<br/>[Basic_MQTT_OTA.ino]"]
  node_ota["OTA coordinator<br/>[MQTT_OTA.cpp]"]
  node_subscribe["Auto-subscribe<br/>[MQTT_OTA.cpp]"]
  node_metadata_check["Metadata checks<br/>[MQTT_OTA.cpp]"]
  node_flash_write["Firmware write<br/>[MQTT_OTA.cpp]"]
  node_finalize["MD5 finalize<br/>[MQTT_OTA.cpp]"]
end

subgraph group_integrations["Runtime Integrations"]
  node_mqtt_client["PubSubClient"]
  node_update_api["ESP32 Update"]
  node_preferences[("Version preferences")]
  node_restart["ESP32 restart"]
end

node_operator(("Firmware operator"))
node_firmware["Firmware binary"]
node_broker(("MQTT broker"))

node_operator -->|"starts upload"| node_publisher_app
node_firmware -->|"reads file"| node_publisher_app
node_publisher_app -->|"calculates hash"| node_hash
node_publisher_app -->|"builds metadata"| node_begin_stage
node_publisher_app -->|"reads chunks"| node_data_stage
node_publisher_app -->|"signals completion"| node_end_stage
node_begin_stage -->|"publishes begin"| node_broker
node_data_stage -->|"publishes chunks"| node_broker
node_end_stage -->|"publishes end"| node_broker
node_broker -->|"delivers messages"| node_mqtt_client
node_mqtt_client -->|"invokes callback"| node_example_app
node_example_app -->|"delegates callback"| node_ota
node_example_app -->|"calls handle"| node_subscribe
node_subscribe -->|"subscribes"| node_mqtt_client
node_ota -->|"processes begin"| node_metadata_check
node_metadata_check -->|"sets MD5 and begins"| node_update_api
node_ota -->|"processes chunks"| node_flash_write
node_flash_write -->|"writes payload"| node_update_api
node_ota -->|"processes end"| node_finalize
node_finalize -->|"validates update"| node_update_api
node_finalize -->|"stores version"| node_preferences
node_finalize -->|"restarts on success"| node_restart
node_ota -->|"publishes status"| node_mqtt_client
node_mqtt_client -->|"sends status"| node_broker
node_broker -->|"delivers status"| node_publisher_app

click node_publisher_app "https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py"
click node_hash "https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py"
click node_begin_stage "https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py"
click node_data_stage "https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py"
click node_end_stage "https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py"
click node_example_app "https://github.com/0adill3/mqtt_ota/blob/main/examples/Basic_MQTT_OTA/Basic_MQTT_OTA.ino"
click node_ota "https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp"
click node_subscribe "https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp"
click node_metadata_check "https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp"
click node_flash_write "https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp"
click node_finalize "https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.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_publisher_app,node_hash,node_begin_stage,node_data_stage,node_end_stage toneBlue
class node_example_app,node_ota,node_subscribe,node_metadata_check,node_flash_write,node_finalize toneAmber
class node_mqtt_client,node_update_api,node_preferences,node_restart toneMint
class node_operator,node_firmware,node_broker toneIndigo
```

## Components

### Firmware Publisher

- [Python publisher](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py): `tools/MQTT_OTA_firmware_publisher.py`
- [MD5 preparation](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py): `tools/MQTT_OTA_firmware_publisher.py`
- [Begin metadata](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py): `tools/MQTT_OTA_firmware_publisher.py`
- [Chunk transfer](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py): `tools/MQTT_OTA_firmware_publisher.py`
- [End signal](https://github.com/0adill3/mqtt_ota/blob/main/tools/MQTT_OTA_firmware_publisher.py): `tools/MQTT_OTA_firmware_publisher.py`

### ESP32 OTA

- [Device application](https://github.com/0adill3/mqtt_ota/blob/main/examples/Basic_MQTT_OTA/Basic_MQTT_OTA.ino): `examples/Basic_MQTT_OTA/Basic_MQTT_OTA.ino`
- [OTA coordinator](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp): `src/MQTT_OTA.cpp`
- [Auto-subscribe](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp): `src/MQTT_OTA.cpp`
- [Metadata checks](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp): `src/MQTT_OTA.cpp`
- [Firmware write](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp): `src/MQTT_OTA.cpp`
- [MD5 finalize](https://github.com/0adill3/mqtt_ota/blob/main/src/MQTT_OTA.cpp): `src/MQTT_OTA.cpp`

### Runtime Integrations

- **PubSubClient**
- **ESP32 Update**
- **Version preferences**
- **ESP32 restart**

### Other components

- **Firmware operator**
- **Firmware binary**
- **MQTT broker**

## Connections

- Firmware operator → Python publisher: starts upload
- Firmware binary → Python publisher: reads file
- Python publisher → MD5 preparation: calculates hash
- Python publisher → Begin metadata: builds metadata
- Python publisher → Chunk transfer: reads chunks
- Python publisher → End signal: signals completion
- Begin metadata → MQTT broker: publishes begin
- Chunk transfer → MQTT broker: publishes chunks
- End signal → MQTT broker: publishes end
- MQTT broker → PubSubClient: delivers messages
- PubSubClient → Device application: invokes callback
- Device application → OTA coordinator: delegates callback
- Device application → Auto-subscribe: calls handle
- Auto-subscribe → PubSubClient: subscribes
- OTA coordinator → Metadata checks: processes begin
- Metadata checks → ESP32 Update: sets MD5 and begins
- OTA coordinator → Firmware write: processes chunks
- Firmware write → ESP32 Update: writes payload
- OTA coordinator → MD5 finalize: processes end
- MD5 finalize → ESP32 Update: validates update
- MD5 finalize → Version preferences: stores version
- MD5 finalize → ESP32 restart: restarts on success
- OTA coordinator → PubSubClient: publishes status
- PubSubClient → MQTT broker: sends status
- MQTT broker → Python publisher: delivers status