# aaronalam1987/esp32-aquarium-controller architecture

> Architecture diagram of the GitHub repository aaronalam1987/esp32-aquarium-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaronalam1987/esp32-aquarium-controller
- Repository: https://github.com/aaronalam1987/esp32-aquarium-controller

## Overview

##### Project type and purpose
- This is an embedded IoT project (ESP32-based aquarium controller) with two firmware images:
- Master device (controls sensors, relays, web server, settings)
- Slave device (wirelessly drives relays via ESP-NOW)
- Purpose: automatically monitor/control temperature, lighting, pump/valve relays; provide local (LCD+buttons) and remote (web GUI) control.

##### File structure
- Top-level PlatformIO project:
- / & lib/ – shared headers and libraries
- src/ – master firmware modules (main.cpp, equipmentControl, tempMonitor, wifiFunctions, etc.)
- test/ – unit/integration test placeholders
- slave_device/ subfolder: separate PlatformIO project with its own include, lib, src (main.cpp) and test
- Config: platformio.ini defines targets, board, frameworks
- Key patterns: modular services (xxxControl.cpp), hardware abstraction (espnow, wifiFunctions, timeFunctions), menu/settings layers.

##### Extract README insights
- Hardware: 20×4 LCD, DS18B20 temp probe, 8-channel relay board, RTC
- Features: heating/cooling control, water-change/feed mode, time-based lighting, web server for monitoring/control, EEPROM persistence, optional wireless slave

a. Main components
1. Master Firmware (ESP32)
- Initialization & config (main.cpp, settings)
- Sensor monitoring (tempMonitor, inputMonitor)
- Control logic (tempControl, lightControl, equipmentControl)
- User interface (menuControl, optionMenus + LCD + buttons)
- Comm interfaces
– Wi-Fi + Async WebServer (wifiFunctions)
– ESP-NOW broadcast (espnow)
- Persistence layer (EEPROM via settings module)
- Time source (RTC via timeFunctions)
2. Slave Firmware (ESP32)
- ESP-NOW listener (lib/espnow)
- Relay driver (slave/src)
3. Hardware peripherals
- DS18B20 temperature probe (OneWire bus)
- 8-channel relay boards (GPIO outputs)
- 20×4 LCD + buttons (I2C or GPIO)
- RTC (I2C)
- Power supply
4. External systems
- Web client (browser/mobile)
- Network (Wi-Fi router)
b. Relationships & data flows
- Sensors → Master sensor modules → Control logic → Relays (local or via ESP-NOW → Slave → relays)
- Buttons → menuControl → settings/control modules → EEPROM
- RTC → timeFunctions → lighting schedules
- Master WebServer ↔ Web client: command & telemetry over HTTP/WS
- Master → ESP-NOW → Slave: relay commands
c. Architectural patterns & principles
- Layered design: hardware abstraction layer (HAL), service modules, UI layer, persistence layer
- Separation of concerns: each “xxxControl” handles one domain
- Event-driven (button presses, timer interrupts, web requests, ESP-NOW packets)
- Modular code reuse (shared include/lib for both master & slave)
d. Key technologies & frameworks
- PlatformIO build system
- ESP-IDF or Arduino-ESP32 core (defined in platformio.ini)
- AsyncWebServer for HTTP UI
- ESP-NOW for peer-to-peer wireless control
- EEPROM for flash-based settings
- OneWire & DS18B20 libraries
- LiquidCrystal or equivalent LCD library

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Master Device Domain
    subgraph "Master ESP32"
        direction TB
        init["Initialization & Configuration"]:::software
        settings["Settings Module (EEPROM)"]:::software
        tempMon["Temperature Monitoring"]:::software
        inputMon["Input Monitoring"]:::software
        tempCtrl["Temperature Control"]:::software
        lightCtrl["Lighting Control"]:::software
        equipCtrl["Equipment Control"]:::software
        menuCtrl["Menu Control"]:::software
        optionMenus["Option Menus"]:::software
        wifi["Wi-Fi & WebServer"]:::network
        espnowM["ESP-NOW Broadcast"]:::network
        timeF["Time Functions (RTC)"]:::software
        sharedLib["Shared Libs"]:::software
    end

    %% Slave Device Domain
    subgraph "Slave ESP32"
        direction TB
        slaveMain["Relay Driver & ESP-NOW Listener"]:::software
        slaveIncl["Slave Include Files"]:::software
        slaveLib["Slave Libraries"]:::software
    end

    %% Configuration Files
    config["PlatformIO Config"]:::hardware
    configSlave["Slave Config"]:::hardware

    %% Hardware Peripherals
    ds18["DS18B20 Probe"]:::hardware
    lcdBtns["LCD + Buttons"]:::hardware
    rtcHW["RTC"]:::hardware
    relayLocal["Relay Board (Local)"]:::hardware
    relayRemote["Relay Board (Remote)"]:::hardware

    %% External Systems
    router["Wi-Fi Router"]:::external
    webClient["Web Client"]:::external

    %% Connections - Master Initialization
    config --> init
    init --> settings
    init --> tempMon
    init --> inputMon
    init --> menuCtrl
    init --> wifi
    init --> espnowM
    init --> timeF

    %% Hardware to Modules
    ds18 --> tempMon
    lcdBtns --> menuCtrl
    lcdBtns --> optionMenus
    rtcHW --> timeF

    %% Sensor to Control
    tempMon --> tempCtrl
    inputMon --> equipCtrl

    %% Control to Relays
    tempCtrl --> relayLocal
    lightCtrl --> relayLocal
    equipCtrl --> relayLocal

    %% Control to ESP-NOW
    tempCtrl -->|"ESP-NOW Cmd"| espnowM
    lightCtrl -->|"ESP-NOW Cmd"| espnowM
    equipCtrl -->|"ESP-NOW Cmd"| espnowM

    %% ESP-NOW to Slave
    espnowM -->|"ESP-NOW Cmd"| slaveMain
    slaveMain --> relayRemote

    %% Web Interface
    wifi -->|"HTTP/WS"| router
    router -->|"HTTP/WS"| webClient

    %% Shared Libs Usage
    sharedLib -.-> init
    sharedLib -.-> settings
    sharedLib -.-> tempMon
    sharedLib -.-> inputMon
    sharedLib -.-> tempCtrl
    sharedLib -.-> lightCtrl
    sharedLib -.-> equipCtrl
    sharedLib -.-> menuCtrl
    sharedLib -.-> optionMenus
    sharedLib -.-> wifi
    sharedLib -.-> espnowM
    sharedLib -.-> timeF
    sharedLib -.-> slaveMain
    sharedLib -.-> slaveIncl
    sharedLib -.-> slaveLib

    %% Config for Slave
    configSlave --> slaveIncl
    configSlave --> slaveLib
    configSlave --> slaveMain

    %% Click Events
    click init "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/main.cpp"
    click settings "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/settings.cpp"
    click tempMon "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/tempMonitor.cpp"
    click inputMon "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/inputMonitor.cpp"
    click tempCtrl "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/tempControl.cpp"
    click lightCtrl "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/lightControl.cpp"
    click equipCtrl "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/equipmentControl.cpp"
    click menuCtrl "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/menuControl.cpp"
    click optionMenus "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/optionMenus.cpp"
    click wifi "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/wifiFunctions.cpp"
    click espnowM "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/espnow.cpp"
    click timeF "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/src/timeFunctions.cpp"
    click sharedLib "https://github.com/aaronalam1987/esp32-aquarium-controller/tree/main/include/"
    click slaveMain "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/slave_device/src/main.cpp"
    click slaveIncl "https://github.com/aaronalam1987/esp32-aquarium-controller/tree/main/slave_device/include/"
    click slaveLib "https://github.com/aaronalam1987/esp32-aquarium-controller/tree/main/slave_device/lib/"
    click config "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/platformio.ini"
    click configSlave "https://github.com/aaronalam1987/esp32-aquarium-controller/blob/main/slave_device/platformio.ini"

    %% Styles
    classDef software fill:#AED6F1,stroke:#1B4F72,stroke-width:1px
    classDef hardware fill:#ABEBC6,stroke:#145A32,stroke-width:1px
    classDef network fill:#FDCB6E,stroke:#B9770E,stroke-width:1px
    classDef external fill:#D5D8DC,stroke:#566573,stroke-width:1px
```
