System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:- HomeSecurity/README.md
- HomeSecurity/src/main.cpp
- HomeSecurity/src/motion_logic.cpp
- HomeSecurity/src/wifi_manager.cpp
- HomeSecurity/src/firebase_notifier.cpp
- HomeSecurity/src/pir_sensor.cpp
- HomeSecurity/src/alarm.cpp
- HomeSecurity/include/led.h
- HomeSecurity/include/motion_logic.h
- HomeSecurity/include/firebase_notifier.h
The HomeSecurity project is an IoT-based anti-intrusion system designed for remote monitoring. It leverages an ESP32 microcontroller for local data processing, a suite of sensors for multi-layered detection, and Firebase for cloud-based notifications to a companion Android application. The architecture is designed to be a smart, accessible, and reliable security solution.
The system is built on a distributed multi-tier architecture, separating responsibilities into an Edge Tier (ESP32 and sensors), a Cloud Tier (Firebase), and a Client Tier (Android App). This design facilitates real-time data acquisition, serverless cloud logic, and a responsive user interface for alerts and live video monitoring.
Sources: HomeSecurity/README.md:15-22, 39-49
High-Level Architecture
The system is composed of three distinct tiers that work together to provide a complete security and monitoring solution.
This diagram illustrates the flow of information from sensor detection at the edge to user notification on the client device.
Sources: HomeSecurity/README.md:52-82
Tier Responsibilities
| Tier | Component | Responsibility |
|---|---|---|
| Edge | ESP32 + Sensors | Data acquisition from Hall, PIR, and Radar sensors, local processing, decision making, and communication with the cloud. |
| Cloud | Firebase | Handles user authentication, orchestrates push notifications via FCM, and runs serverless logic using Cloud Functions. |
| Client | Android App | Provides the user interface for receiving alerts, viewing live video streams (RTSP), and managing the system. |
Sources: HomeSecurity/README.md:84-89
Hardware Architecture
The core of the edge tier is the ESP32 DOIT DevKit V1, which interfaces with various sensors and actuators.
Hardware Components
| Component | Model | Purpose |
|---|---|---|
| Microcontroller | ESP32 DOIT DevKit V1 | Central processing unit |
| Magnetic Sensor | KY-003 (Hall Effect) | Door/window open detection |
| PIR Sensor | HC-SR505 | Passive infrared motion detection |
| Radar Sensor | RCWL-0516 | Doppler microwave motion detection |
| Buzzer | KY-012 (Active) | Audible alarm |
| LEDs | 5mm (Various colors) | Visual status indicators |
| IP Camera | TP-Link Tapo C200 | Live video streaming (RTSP) |
Sources: HomeSecurity/README.md:105-116
ESP32 Pin Configuration
The ESP32's GPIO pins are mapped to specific hardware components for input and output operations.
| Pin | Component | Type | Description |
|---|---|---|---|
| GPIO 33 | Hall Sensor | INPUT_PULLUP | Magnetic door sensor |
| GPIO 21 | PIR Sensor | INPUT | Motion detection |
| GPIO 22 | Radar Sensor | INPUT | Doppler motion detection |
| GPIO 25 | Buzzer | OUTPUT | Audio alarm |
| GPIO 19 | Yellow LED | OUTPUT | Hall sensor triggered |
| GPIO 18 | Blue LED | OUTPUT | PIR motion detected |
| GPIO 23 | Red LED | OUTPUT | Intrusion confirmed |
| GPIO 4 | Green LED | OUTPUT | System calibrated/ready |
| GPIO 13 | White LED | OUTPUT | WiFi connected |
Sources: HomeSecurity/README.md:143-157, HomeSecurity/include/led.h:6-10, HomeSecurity/include/pir_sensor.h:6, HomeSecurity/include/hall_sensor.h:5, HomeSecurity/include/microwave_sensor.h:6, HomeSecurity/include/alarm.h:6
Software Architecture (Embedded)
The embedded software runs on the ESP32 and uses the FreeRTOS real-time operating system to manage concurrent tasks for sensor monitoring, network management, and alert logic.
Sources: HomeSecurity/src/main.cpp:9-15, HomeSecurity/README.md:162-164
System Initialization Flow
On boot, the system performs a sequence of initialization steps before entering its main monitoring loop.
This diagram shows the initialization process managed by the setup() function.
Sources: HomeSecurity/src/main.cpp:4-8, HomeSecurity/src/motion_logic.cpp:10-16, HomeSecurity/src/pir_sensor.cpp:12-16
FreeRTOS Task Structure
The system's concurrency is managed by several FreeRTOS tasks, each with a specific role and priority.
| Task | Priority | Stack (Bytes) | Function |
|---|---|---|---|
handleHallMovementTask | 4 (High) | 2048 | Monitors the Hall effect sensor and controls the yellow LED. |
handlePirMovementTask | 4 (High) | 2048 | Monitors the PIR sensor and controls the blue LED. |
possibleHumanMovementDetectedTask | 4 (High) | 6144 | Orchestrates Stage 1 alerts: triggers the buzzer and sends a Firebase notification if PIR or Hall sensor is active. |
calibratePirSensorTask | 3 (Medium) | 1536 | Manages the 30-second PIR sensor warm-up period and turns on the green LED when ready. |
handleRadarMovementTask | 3 (Medium) | 6144 | Monitors the microwave radar sensor for sustained motion to confirm presence (Stage 2 alert). |
WiFiCheckTask | 2 (Low) | 2048 | Periodically checks the WiFi connection and attempts to reconnect if lost. |
Sources: HomeSecurity/src/main.cpp:9-15, HomeSecurity/README.md:179-187
Alert Logic Flow
The system employs a two-stage alert mechanism to reduce false positives.
Stage 1: Initial Detection
This stage is triggered immediately upon detection by the perimeter (Hall) or proximity (PIR) sensors.
- Trigger:
isPirActive()orisHallSensorTriggered()returnstrue. - Action: The
possibleHumanMovementDetectedTasktriggers a 3-second audible alarm, sends a "Mișcare detectată" notification via Firebase, and turns on the corresponding LED (Blue for PIR, Yellow for Hall).
Stage 2: Presence Confirmation
This stage escalates the alert if sustained motion is detected by the radar sensor.
- Trigger:
isRadarActive()returnstruefor a continuous period of 2 seconds. - Action: The
handleRadarMovementTasksends a "Mișcare confirmată" notification via Firebase and turns on the red LED.
Sources: HomeSecurity/src/motion_logic.cpp:52-73, 102-124, HomeSecurity/src/alarm.cpp:16-22
The complete alert logic flow is visualized below.
This diagram shows how an initial alert is followed by a confirmation stage based on radar activity.
Sources: HomeSecurity/src/motion_logic.cpp, HomeSecurity/README.md:255-299
Cloud & Client Architecture
Firebase Integration
The ESP32 communicates with the cloud via HTTPS to trigger push notifications. This is handled by the FirebaseNotifier class.
- Endpoint: The system sends a POST request to a pre-configured Firebase Cloud Function URL.
- Payload: A JSON object containing
title,body, and the target devicetoken. - Security: The connection uses
WiFiClientSecurebut is configured withsetInsecure()for development, which should be reviewed for production use.
Sources: HomeSecurity/src/motion_logic.cpp:4, 8, HomeSecurity/src/firebase_notifier.cpp:6-28, HomeSecurity/include/firebase_notifier.h:10-11
The notification sequence is as follows:
This diagram shows the sequence of events from the ESP32 detecting an event to the user receiving a notification.
Sources: HomeSecurity/README.md:321-327, HomeSecurity/src/firebase_notifier.cpp:16-20
Mobile Application
The companion Android application serves as the primary user interface.
- Technology: Built with Kotlin, Jetpack Compose, and follows an MVVM architecture.
- Features:
- User authentication (Email/Password, Google Sign-In).
- Real-time push notifications via FCM.
- Live video streaming from an IP camera using the RTSP protocol.
- Light/Dark theme support.
Sources: HomeSecurity/README.md:302-319
Summary
The HomeSecurity system architecture is a well-defined, multi-tier IoT solution. It effectively separates concerns between the edge device, cloud services, and the client application. The use of FreeRTOS on the ESP32 allows for robust, real-time, and concurrent processing of sensor data and network tasks. The two-stage alert logic, combining PIR/Hall sensors with radar confirmation, is a key feature designed to improve reliability and reduce false alarms. Finally, the integration with Firebase provides a scalable, serverless backend for delivering critical notifications to the end-user.
Sources: HomeSecurity/README.md