How andreicatanoiu/homeguardesp works
Project type and purpose
• HomeGuardESP is an embedded IoT security‐monitoring firmware targeting the ESP8266/ESP32 platform.
• It integrates multiple sensors (PIR motion, MQ2 gas, potentially magnetic/contact or smoke sensors), processes their signals, and reports events in real time over Wi-Fi/MQTT to a remote application.
• It also supports over-the-air (OTA) firmware updates and a small DNS server for captive-portal style configuration.
File structure
• Top level: CMakeLists.txt, platformio.ini, sdkconfig.esp32dev → build and board configuration
• certs/ → TLS certificates for secure MQTT or captive portal
• / and lib/ → shared headers and libraries, documented by separate READMEs
• src/ → core firmware modules, each split into .c/.h pairs:
• main.c → application entry point and initialization
• decoder → sensor data decoding
• sensor_selector → multiplexing between different hardware inputs
• mq2_module, pir_module → driver wrappers for each sensor
• mqtt_comm → publishes and subscribes via MQTT
• dns_server → handles captive-portal DNS for initial Wi-Fi config
• wifi → Wi-Fi connection management
• ota_updates → remote firmware fetching and flashing
• system_time → real-time clock or timestamping
• settings → persistent configuration (thresholds, broker URL, Wi-Fi credentials)
• test/ → unit or integration tests
Extract additional insights from the README
• Emphasis on real-time alerts, MQTT integration, remote configuration via mobile app
• Future extension point: mobile app UI consumes MQTT topics and displays sensor states
• Ease of installation via PlatformIO/Arduino IDE.
1. Hardware layer
• Sensors: PIR module, MQ2 gas module, (optionally smoke/contact sensors)
• ESP32/ESP8266 MCU
• Sensor Drivers (pir_module, mq2_module)
• Sensor Selector & Decoder
• Settings & System Time
• Connectivity
• Wi-Fi Manager
• DNS Server (captive portal)
• MQTT Communication
• OTA Update Engine
3. External services
• MQTT Broker (cloud or local)
• Mobile Application / Dashboard
• Certificate Authority (for TLS certs in certs/)
b. Relationships and interactions
• Sensors → Sensor Drivers → Sensor Selector → Decoder → Settings & System Time
• Decoded data → MQTT Communication → MQTT Broker → Mobile App
• Mobile App → (optional) → Settings → firmware Settings module (via special MQTT topics)
• Firmware requests OTA updates from a remote HTTP(S) server → OTA engine → flash new firmware
• On first-boot or reconfiguration: DNS Server responds to all DNS queries to serve a captive-portal page (not shown in code, but implied)
• Wi-Fi Manager orchestrates network connectivity before MQTT or DNS modules run
c. Architectural patterns
• Modular, single-responsibility C modules (each module .c/.h handles one concern)
• Pub/Sub pattern via MQTT for decoupled event distribution
• Factory/Selector pattern in sensor_selector for dynamic sensor activation
• Over-the-air update pipeline decoupled from main monitoring loop
d. Key technologies & frameworks
• ESP-IDF or PlatformIO (CMake, platformio.ini)
• POSIX-style C modules, header files under include/
• mbedTLS (or similar) for TLS (certs/fullchain.pem)
• lwIP TCP/IP stack for Wi-Fi and DNS server
• Paho or built-in MQTT client library for ESP
Be comprehensive—but don’t overcomplicate
• Every src/ module as at least a labeled sub‐component
• Inter‐module dependencies (e.g., settings is used by decoder, mqtt_comm, ota_updates)
• Runtime view: how data and control signals move, how the system boots and recovers