# chaoyi996/esp_relay architecture

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

- Interactive diagram: https://gitdiagram.com/chaoyi996/esp_relay
- Repository: https://github.com/chaoyi996/esp_relay

## Overview

This project is an embedded firmware solution for controlling relay (开关) modules on an ESP chip (ESP-01M). Its primary purpose is to control one-, two-, or three-channel relays in home automation scenarios, and it integrates several features such as OTA updates, a web configuration page, MQTT-based remote control (including integration with Home Assistant and similar platforms), and even radio frequency (RF) signal processing for an additional layer of control when WiFi or other services might be unavailable.

##### Project Type and Purpose
- The firmware is designed to run on an ESP microcontroller. It provides relay control and additional home automation features.
- The README clearly explains that this is a personal, open-source firmware for controlling various relay modules, with features like MQTT connectivity, OTA updates, and a web interface.
- This project is not a full-stack web application but a tightly integrated embedded system which interfaces directly with hardware (GPIOs on the ESP module) and external home automation platforms.

##### File Structure
- Top-level directories and files:
- "file": Contains documentation, BOM files, PCB design files, and images showing hardware layouts (including front/back images and LED statuses).
- "include": Contains header files for components like RadioReceive, Relay, RelayConfig (using Protocol Buffers), and a generic template.
- "lib": Houses the “esp_framework” which is a crucial library providing many common functionalities (configuration, debugging, HTTP, LED, MQTT, RTC, utility functions, and WiFi management). This also includes nanopb files for Protocol Buffers support.
- "src": Contains the main application code (e.g., main.cpp) and other source files implementing the relay and radio receive logic.
- "scripts": Contains helper Python scripts (for firmware naming and float stripping) that support build or firmware management tasks.
- Additional files include the PlatformIO configuration file (platformio.ini) suggesting a PlatformIO development environment, and CI/CD files like .travis.yml.

##### Main Components and Their Relationships
- Hardware Layer:
- ESP-01M module with dedicated GPIO pins for relay control and LED indication (as per the IO mapping in the README).
- Physical relay modules (ited as 一路, 二路, and 三路).
- RF circuitry for handling 433MHz/315MHz signals.
- Firmware/Application Layer:
- Main application code (src/main.cpp) that ties together hardware initialization, relay control logic, and module coordination.
- Specific modules for relay control (Relay.cpp, Relay.h) and radio reception (RadioReceive.cpp, RadioReceive.h).
- Library and Support Components:
- “esp_framework” in the lib directory encapsulates core functionalities including configuration (Config.cpp and GlobalConfig), debugging, HTTP serving for the web configuration panel, MQTT handling (for home automation platforms), LED control, and WiFi management.
- Use of Protocol Buffers (protobuf files and generated C code across both include and lib) for relay configuration ensures a structured communication of settings.
- External Communication Interfaces:
- MQTT module that interfaces with external systems like Home Assistant, ioBroker, or any MQTT-supporting platform.
- OTA update mechanism and an embedded HTTP server for configuration through a web page.
- Radio controls provide a fallback when WiFi or cloud systems fail.

##### Key Architectural Patterns and Design Principles
- Layered Architecture: Separation between hardware interaction (GPIO handling, relay control) and higher-level software services (MQTT, OTA updates, web configuration).
- Modularity: Use of a dedicated “esp_framework” library that provides reusable components across the firmware.
- Event-driven communication: Likely, the main program responds to events from hardware (input buttons, RF signals) and network events (MQTT messages, OTA triggers).
- Integration of Protocol Buffers for configuration provides a clear and uniform communication protocol between firmware modules and configuration data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        ESP_Module["ESP-01M Module"]:::hardware
        Relay_1["1-Channel Relay Module"]:::hardware
        Relay_2["2-Channel Relay Module"]:::hardware
        Relay_3["3-Channel Relay Module"]:::hardware
        RF_Hardware["RF Receiver Circuitry"]:::hardware
        Hardware_Doc["Hardware Documentation"]:::hardware
    end

    %% Firmware/Application Layer
    subgraph "Firmware/Application Layer"
        Main_App["Main Application (src/main.cpp)"]:::application
        subgraph "Relay Control Subsystem"
            Relay_Code["Relay Logic (src/Relay.cpp & include/Relay.h)"]:::relay
            Relay_Proto["Relay Config (include/RelayConfig.pb.h & nanopb/RelayConfig.proto)"]:::relay
        end
        RF_Signal["RF Signal Processing (src/RadioReceive.cpp & include/RadioReceive.h)"]:::application
    end

    %% Firmware Services - esp_framework
    subgraph "Firmware Services"
        ESP_Framework["esp_framework Library"]:::library
        MQTT_Module["MQTT Module"]:::library
        HTTP_Module["HTTP/OTA Module"]:::library
    end

    %% External Communication Interfaces
    subgraph "External Interfaces"
        MQTT_External["MQTT Broker / Home Assistant"]:::external
        OTA_Client["OTA & Web Configuration Client"]:::external
    end

    %% Build and Firmware Support Scripts
    subgraph "Build Tools"
        Build_Scripts["Build Scripts"]:::build
    end

    %% Connections from Hardware Layer to Main Application
    ESP_Module -->|"init"| Main_App
    Relay_1 -->|"signal"| Main_App
    Relay_2 -->|"signal"| Main_App
    Relay_3 -->|"signal"| Main_App
    RF_Hardware -->|"trigger"| Main_App

    %% Main Application connections
    Main_App -->|"controls"| Relay_Code
    Main_App -->|"receives"| RF_Signal
    Main_App -->|"utilizes"| ESP_Framework

    %% Relay Control internal (optional connection)
    Relay_Code -->|"configures"| Relay_Proto

    %% esp_framework connections
    ESP_Framework -->|"handles MQTT"| MQTT_Module
    ESP_Framework -->|"handles HTTP/OTA"| HTTP_Module

    %% External Interfaces connections
    MQTT_Module -->|"communicates"| MQTT_External
    HTTP_Module -->|"serves"| OTA_Client

    %% Build Scripts connection
    Build_Scripts -->|"builds"| Main_App

    %% Click Events for Hardware Layer
    click Relay_1 "https://github.com/chaoyi996/esp_relay/tree/master/file/1路开关模块"
    click Relay_2 "https://github.com/chaoyi996/esp_relay/tree/master/file/2路开关模块"
    click Relay_3 "https://github.com/chaoyi996/esp_relay/tree/master/file/3路开关模块"
    click Hardware_Doc "https://github.com/chaoyi996/esp_relay/tree/master/file/images"

    %% Click Event for Main Application Logic
    click Main_App "https://github.com/chaoyi996/esp_relay/blob/master/src/main.cpp"

    %% Click Events for Relay Control Subsystem
    click Relay_Code "https://github.com/chaoyi996/esp_relay/blob/master/src/Relay.cpp"
    click Relay_Code "https://github.com/chaoyi996/esp_relay/blob/master/include/Relay.h"
    click Relay_Proto "https://github.com/chaoyi996/esp_relay/blob/master/include/RelayConfig.pb.h"
    click Relay_Proto "https://github.com/chaoyi996/esp_relay/blob/master/nanopb/RelayConfig.proto"

    %% Click Events for RF Signal Processing
    click RF_Signal "https://github.com/chaoyi996/esp_relay/blob/master/src/RadioReceive.cpp"
    click RF_Signal "https://github.com/chaoyi996/esp_relay/blob/master/include/RadioReceive.h"

    %% Click Event for esp_framework Library
    click ESP_Framework "https://github.com/chaoyi996/esp_relay/tree/master/lib/esp_framework/"

    %% Click Events for MQTT Module within esp_framework
    click MQTT_Module "https://github.com/chaoyi996/esp_relay/blob/master/lib/esp_framework/include/Mqtt.h"
    click MQTT_Module "https://github.com/chaoyi996/esp_relay/blob/master/lib/esp_framework/src/Mqtt.cpp"

    %% Click Events for HTTP/OTA Module within esp_framework
    click HTTP_Module "https://github.com/chaoyi996/esp_relay/blob/master/lib/esp_framework/include/Http.h"
    click HTTP_Module "https://github.com/chaoyi996/esp_relay/blob/master/lib/esp_framework/src/Http.cpp"

    %% Click Events for Build Scripts
    click Build_Scripts "https://github.com/chaoyi996/esp_relay/blob/master/scripts/name-firmware.py"
    click Build_Scripts "https://github.com/chaoyi996/esp_relay/blob/master/scripts/strip-floats.py"

    %% Styles
    classDef hardware fill:#ffe680,stroke:#cc9900,stroke-width:2px;
    classDef application fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef relay fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef library fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
    classDef external fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef build fill:#ead1dc,stroke:#b85486,stroke-width:2px;
```
