How chaoyi996/esp_relay works
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.