Welcome to HomeSecurity

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/include/motion_logic.h
• HomeSecurity/src/pir_sensor.cpp
• HomeSecurity/include/pir_sensor.h
• HomeSecurity/src/firebase_notifier.cpp
• HomeSecurity/include/firebase_notifier.h
• HomeSecurity/src/wifi_manager.cpp
• HomeSecurity/include/wifi_manager.h
• HomeSecurity/src/alarm.cpp
• HomeSecurity/include/alarm.h
• HomeSecurity/src/led.cpp
• HomeSecurity/include/led.h
• HomeSecurity/src/hall_sensor.cpp
• HomeSecurity/include/hall_sensor.h
• HomeSecurity/src/microwave_sensor.cpp
• HomeSecurity/include/microwave_sensor.h

HomeSecurity is an IoT-based anti-intrusion system designed for remote home security and monitoring. Built upon an ESP32 microcontroller, it leverages a multi-layered sensor approach, FreeRTOS for concurrent task management, and Firebase for cloud integration. The system provides real-time alerts to a companion Android application, featuring live video streaming capabilities to offer a comprehensive and accessible security solution.

The core of the system is a distributed multi-tier architecture consisting of an Edge Tier (ESP32 and sensors), a Cloud Tier (Firebase), and a Client Tier (Android App). This design enables local data acquisition and processing on the ESP32, while using serverless cloud logic for orchestrating notifications and user authentication. The system's primary goal is to reduce false alarms through a two-stage alert logic that fuses data from multiple sensors.

Sources: HomeSecurity/README.md:17-22, 43-53

System Architecture

The project follows a three-tier design to separate concerns between data acquisition, cloud processing, and user interaction.

• Edge Tier: The ESP32 microcontroller is responsible for reading data from the Hall, PIR, and Radar sensors. It performs initial processing, makes decisions based on the alert logic, and communicates with the cloud.
• Cloud Tier: Firebase provides the backend infrastructure. This includes Cloud Functions for serverless logic (like sending notifications), Firebase Cloud Messaging (FCM) for push alert delivery, and Firebase Authentication for managing user access in the mobile app.
• Client Tier: An Android application serves as the user interface. It receives real-time push notifications, displays system status, and provides access to a live video feed from an IP camera via the RTSP protocol.

The following diagram illustrates the interaction between the tiers.

Hardware and Pinout

The system is built around an ESP32 DOIT DevKit V1 and uses a combination of sensors for detection, along with LEDs for status indication and a buzzer for an audible alarm.

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:99-110

ESP32 Pin Configuration

The GPIO pins on the ESP32 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:144-153, HomeSecurity/include/hall_sensor.h:5, HomeSecurity/include/pir_sensor.h:6, HomeSecurity/include/microwave_sensor.h:5, HomeSecurity/include/alarm.h:6, HomeSecurity/include/led.h:6-10

Software Architecture

The firmware runs on FreeRTOS, enabling concurrent execution of multiple tasks for sensor monitoring, network management, and alert logic.

FreeRTOS Task Structure

The application entry point in main.cpp initializes the system and creates several tasks, each with a specific function and priority.

Task	Priority	Stack Size	Function
handleHallMovementTask	4	2048B	Monitors the magnetic Hall sensor and controls the yellow LED.
handlePirMovementTask	4	2048B	Monitors the PIR sensor and controls the blue LED.
possibleHumanMovementDetectedTask	4	6144B	Orchestrates the Stage 1 alert. Triggers the alarm and sends a notification if the PIR or Hall sensor is active.
calibratePirSensorTask	3	1536B	Manages the 30-second PIR sensor warm-up period. Turns on the green LED when calibration is complete.
handleRadarMovementTask	3	6144B	Monitors the microwave radar sensor. If motion is detected for over 2 seconds, it confirms an intrusion (Stage 2 alert).
WiFiCheckTask	2	2048B	Periodically checks the WiFi connection and attempts to reconnect if it is lost.

Sources: HomeSecurity/src/main.cpp:8-13, HomeSecurity/README.md:168-183

Alert Logic Flow

The system uses a two-stage alert mechanism to reduce false positives. An initial alert is triggered by perimeter or general motion sensors, followed by a confirmation alert from a more robust presence sensor.

Stage 1: Initial Alert

An alert is triggered if either the Hall sensor (door/window opened) or the PIR sensor (motion detected) becomes active.

1. The possibleHumanMovementDetectedTask detects the sensor state change.
2. A non-blocking alarm is triggered, sounding the buzzer for 3 seconds (ALARM_DURATION).
3. A push notification with the title "Mișcare detectată" is sent via Firebase.
4. The corresponding LED (Yellow for Hall, Blue for PIR) is turned on.

Sources: HomeSecurity/src/motion_logic.cpp:52-73, HomeSecurity/include/alarm.h:6

Stage 2: Presence Confirmation

After a Stage 1 alert, the system seeks confirmation from the microwave radar sensor.

1. The handleRadarMovementTask monitors the RCWL-0516 radar sensor.
2. If the radar detects continuous movement for 2 seconds or more, it confirms a human presence.
3. A second push notification with the title "Mișcare confirmată" is sent.
4. The red LED is turned on to indicate a confirmed intrusion.

This logic ensures that a brief, non-human event (like an object falling) does not trigger the highest-level alert.

Sources: HomeSecurity/src/motion_logic.cpp:100-123

The complete flow is visualized in the diagram below.

Firebase Integration

The ESP32 communicates with a Firebase backend to send push notifications to the Android client. This is handled by the FirebaseNotifier class.

Notification Flow

1. When an alert condition is met, a function like possibleHumanMovementDetectedTask calls notifier.sendNotification().
2. The FirebaseNotifier::sendNotification method creates a secure HTTPS client.
3. It constructs a JSON payload containing the notification title, body, and the target device token.
4. An HTTP POST request is sent to a predefined Firebase Cloud Function URL.
5. The Cloud Function receives the request and uses the Firebase Cloud Messaging (FCM) service to deliver the push notification to the registered Android device.

Configuration

Key parameters for WiFi and Firebase are hardcoded in the source files.

Parameter	File	Default Value	Description
WIFI_SSID	src/wifi_manager.cpp	"IonutMoto"	The SSID of the WiFi network.
WIFI_PASSWORD	src/wifi_manager.cpp	"12345678"	The password for the WiFi network.
FirebaseNotifier URL	src/motion_logic.cpp	"https://trimitenotificare-k4cqa7es6q-uc.a.run.app"	The URL of the Firebase Cloud Function endpoint.
fcmToken	src/motion_logic.cpp	"d-OlFNUN...NbA"	The Firebase Cloud Messaging token of the target device.
ALARM_DURATION	include/alarm.h	3000 (ms)	The duration for which the buzzer sounds.
PIR Calibration Time	src/pir_sensor.cpp	30000 (ms)	The warm-up time required for the PIR sensor.

Sources: HomeSecurity/src/wifi_manager.cpp:5-6, HomeSecurity/src/motion_logic.cpp:4,7, HomeSecurity/include/alarm.h:6, HomeSecurity/src/pir_sensor.cpp:13