# apurboislam/iot-home-automation architecture
> Architecture diagram of the GitHub repository apurboislam/iot-home-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/apurboislam/iot-home-automation
- Repository: https://github.com/apurboislam/iot-home-automation
## Overview
1. **What this repo is**
- This is a single-device firmware project for a **NodeMCU ESP8266** that connects to **Blynk Cloud** and controls up to **4 relay-driven appliances**. There is no separate backend server; the device firmware is the product.
2. **Top-level runtime**
- The Arduino sketch **`BlynkEdgent_ESP8266.ino`** is the entrypoint.
- The rest of the `.h` files are supporting modules that split the firmware into provisioning, state handling, OTA, UI feedback, and configuration storage.
3. **Core application boundary**
- The main boundary is between:
- **Blynk mobile app / Blynk Cloud** on one side
- **ESP8266 firmware + relay hardware** on the other
- The cloud/app sends device commands over Wi‑Fi using Blynk virtual pins, and the firmware translates those commands into GPIO relay actions.
4. **Cloud control model**
- The README defines the Blynk mapping:
- **V1–V4** control the four relays
- **V0** is used for state memory / sync behavior
- This means the firmware is stateful and expects cloud synchronization, not just one-way button pushes.
5. **Hardware control layer**
- The physical outputs are the relay pins mapped to ESP8266 GPIOs:
- **D1 → IN1**
- **D2 → IN2**
- **D3 → IN3**
- **D4 → IN4**
- The firmware’s job is to keep these outputs aligned with the cloud state and restore them after reconnects or reboot.
6. **Provisioning and onboarding**
- **`BlynkEdgent.h`** and **`ConfigMode.h`** indicate use of Blynk’s Edgent-style onboarding flow.
- This likely covers initial Wi‑Fi setup, device discovery, and pairing with the Blynk app without hardcoding a network from the start.
7. **Persistent configuration**
- **`ConfigStore.h`** and **`Settings.h`** separate device configuration from live runtime state.
- The architecture suggests storing template/device settings and Wi‑Fi/Blynk-related data so the device can survive resets and reconnect consistently.
8. **Runtime state machine**
- **`BlynkState.h`** implies an explicit firmware state machine for device lifecycle management.
- Typical states in this architecture are: boot, connect Wi‑Fi, connect Blynk, configuration mode, and normal operation.
9. **OTA update path**
- **`OTA.h`** shows the firmware is OTA-ready.
- Updates are part of the device lifecycle, meaning the system is designed to receive new firmware without a physical USB reflash, which matters for deployed home automation devices.
10. **User feedback and diagnostics**
- **`Indicator.h`**, **`Console.h`**, and **`ResetButton.h`** cover local device interaction:
- visual status indication
- serial/debug console output
- physical reset/provisioning button handling
- These modules provide the local control plane separate from the cloud control plane.
11. **Data flow summary**
- Command path: **Blynk app → Blynk Cloud → Wi‑Fi → ESP8266 firmware → GPIO relay pins → appliances**
- State path: **relay/state changes → firmware state tracking → Blynk sync / cloud state memory**
- Setup path: **physical reset / first boot → configuration mode → Wi‑Fi + Blynk provisioning**
12. **Build and artifacts**
- The `build/esp8266.esp8266.nodemcuv2/` directory contains compiled outputs (`.bin`, `.elf`, `.map`), which are generated artifacts for the ESP8266 target and not part of the logical runtime architecture.
13. **Architectural takeaway**
- This repo is a **modular embedded firmware system** with three major concerns:
- **connectivity and provisioning**
- **relay control and state sync**
- **OTA / lifecycle management**
- For a diagram, the cleanest representation is an ESP8266 device node with internal modules around a Blynk/Edgent communication core and four relay outputs to home appliances.
Main entry points: [`BlynkEdgent_ESP8266.ino`](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent_ESP8266.ino) (Main sketch), [`BlynkEdgent.h`](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent.h) (Edgent core), [`BlynkState.h`](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkState.h) (State machine), [`ConfigStore.h`](https://github.com/apurboislam/iot-home-automation/blob/main/ConfigStore.h) (Config store)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_external["External"]
node_blynk_app(("Blynk app
mobile app"))
node_blynk_cloud[("Blynk Cloud
cloud service")]
node_wifi(("Wi‑Fi
network"))
end
subgraph group_firmware["Firmware"]
node_sketch["Main sketch
entrypoint"]
node_edgent["Edgent core
integration core
[BlynkEdgent.h]"]
node_state["State machine
lifecycle state
[BlynkState.h]"]
node_config_mode["Config mode
provisioning
[ConfigMode.h]"]
node_config_store[("Config store
persistent storage
[ConfigStore.h]")]
node_settings["Settings
device config
[Settings.h]"]
node_ota["OTA update
update flow
[OTA.h]"]
node_indicator["Indicator
status feedback
[Indicator.h]"]
node_console["Console
diagnostics
[Console.h]"]
node_reset_btn(("Reset button
physical input
[ResetButton.h]"))
end
subgraph group_hardware["Hardware"]
node_relay_ctrl["Relay control
gpio control"]
node_relay_bank[("Relays
outputs")]
node_appliances(("Appliances
loads"))
end
node_blynk_app -->|"commands"| node_blynk_cloud
node_blynk_cloud -->|"transport"| node_wifi
node_wifi -->|"connects"| node_edgent
node_sketch -->|"boots"| node_edgent
node_sketch -->|"drives"| node_state
node_edgent -->|"onboards"| node_config_mode
node_edgent -->|"persists"| node_config_store
node_config_store -->|"loads"| node_settings
node_state -->|"signals"| node_indicator
node_state -->|"logs"| node_console
node_reset_btn -->|"triggers"| node_config_mode
node_blynk_cloud -->|"virtual pins"| node_sketch
node_sketch -->|"maps state"| node_relay_ctrl
node_relay_ctrl -->|"drives"| node_relay_bank
node_relay_bank -->|"switches"| node_appliances
node_sketch -->|"updates"| node_ota
click node_sketch "https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent_ESP8266.ino"
click node_edgent "https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent.h"
click node_state "https://github.com/apurboislam/iot-home-automation/blob/main/BlynkState.h"
click node_config_mode "https://github.com/apurboislam/iot-home-automation/blob/main/ConfigMode.h"
click node_config_store "https://github.com/apurboislam/iot-home-automation/blob/main/ConfigStore.h"
click node_settings "https://github.com/apurboislam/iot-home-automation/blob/main/Settings.h"
click node_ota "https://github.com/apurboislam/iot-home-automation/blob/main/OTA.h"
click node_indicator "https://github.com/apurboislam/iot-home-automation/blob/main/Indicator.h"
click node_console "https://github.com/apurboislam/iot-home-automation/blob/main/Console.h"
click node_reset_btn "https://github.com/apurboislam/iot-home-automation/blob/main/ResetButton.h"
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_blynk_app,node_blynk_cloud,node_wifi toneBlue
class node_sketch,node_edgent,node_state,node_config_mode,node_config_store,node_settings,node_ota,node_indicator,node_console,node_reset_btn toneAmber
class node_relay_ctrl,node_relay_bank,node_appliances toneMint
```
## Components
### External
Cloud, app, and local physical environment around the device
- **Blynk app**: mobile app · User interface for controlling the device and viewing state.
- **Blynk Cloud**: cloud service · Remote command, sync, and device connectivity layer.
- **Wi‑Fi**: network · Connectivity path between the ESP8266 and Blynk services.
### Firmware
ESP8266 runtime modules and lifecycle logic
- [Main sketch](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent_ESP8266.ino): entrypoint · Arduino firmware entrypoint that wires the modules together. · `BlynkEdgent_ESP8266.ino`
- [Edgent core](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkEdgent.h): integration core · Blynk Edgent bootstrap and device integration logic. · `BlynkEdgent.h`
- [State machine](https://github.com/apurboislam/iot-home-automation/blob/main/BlynkState.h): lifecycle state · Explicit firmware lifecycle control for boot, connect, config, and run states. · `BlynkState.h`
- [Config mode](https://github.com/apurboislam/iot-home-automation/blob/main/ConfigMode.h): provisioning · Wi‑Fi and device onboarding flow used during setup or recovery. · `ConfigMode.h`
- [Config store](https://github.com/apurboislam/iot-home-automation/blob/main/ConfigStore.h): persistent storage · Storage for device configuration and reconnectable settings. · `ConfigStore.h`
- [Settings](https://github.com/apurboislam/iot-home-automation/blob/main/Settings.h): device config · Structured configuration values used by runtime and provisioning code. · `Settings.h`
- [OTA update](https://github.com/apurboislam/iot-home-automation/blob/main/OTA.h): update flow · Over-the-air firmware update path for deployed devices. · `OTA.h`
- [Indicator](https://github.com/apurboislam/iot-home-automation/blob/main/Indicator.h): status feedback · Local visual status feedback for connection and lifecycle state. · `Indicator.h`
- [Console](https://github.com/apurboislam/iot-home-automation/blob/main/Console.h): diagnostics · Serial/debug output for runtime diagnostics and troubleshooting. · `Console.h`
- [Reset button](https://github.com/apurboislam/iot-home-automation/blob/main/ResetButton.h): physical input · Button handling for reset and provisioning triggers. · `ResetButton.h`
### Hardware
On-device outputs and physical controls
- **Relay control**: gpio control · Translates synced device state into relay on/off actions.
- **Relays**: outputs · Four relay-driven outputs mapped to ESP8266 GPIO pins D1 to D4.
- **Appliances**: loads · Connected home devices switched by the relay outputs.
## Connections
- Blynk app → Blynk Cloud: commands · User actions are sent through the Blynk cloud backend.
- Blynk Cloud → Wi‑Fi: transport · Cloud interaction reaches the device over the network.
- Wi‑Fi → Edgent core: connects · Network connectivity enables the firmware to reach Blynk services.
- Main sketch → Edgent core: boots · The main sketch initializes the Edgent integration.
- Main sketch → State machine: drives · Startup and runtime execution are governed by the lifecycle state machine.
- Edgent core → Config mode: onboards · Edgent handles first-time setup and recovery provisioning.
- Edgent core → Config store: persists · Device configuration is loaded and saved through the config store.
- Config store → Settings: loads · Persisted values are materialized into runtime settings.
- State machine → Indicator: signals · Lifecycle state is reflected in local indicators.
- State machine → Console: logs · State transitions and diagnostics are emitted to the console.
- Reset button → Config mode: triggers · Physical reset or provisioning actions can enter configuration mode.
- Blynk Cloud → Main sketch: virtual pins · V0 to V4 device state and relay commands are delivered to the firmware.
- Main sketch → Relay control: maps state · Cloud-synced device state is converted into relay actions.
- Relay control → Relays: drives · GPIO control energizes the relay outputs.
- Relays → Appliances: switches · Relays control the attached home appliances.
- Main sketch → OTA update: updates · Firmware lifecycle includes over-the-air update handling.