Contributing Guide

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

This document provides a technical overview of the HomeSecurity IoT system, an anti-intrusion solution built on the ESP32 platform. It details the hardware, software architecture, and core logic for detecting intrusions and notifying the user. The system leverages a multi-sensor approach, a real-time operating system (FreeRTOS) for concurrent processing, and Firebase for cloud-based notifications.

The architecture is distributed across three tiers: the Edge Tier (ESP32 and sensors) for data acquisition, the Cloud Tier (Firebase) for notification orchestration, and the Client Tier (Android App) for user interaction and alerts. This design enables real-time monitoring and minimizes false alarms through a two-stage alert process.

Sources: HomeSecurity/README.md:16-22, 32-41

System Architecture Overview

The system is designed with a distributed multi-tier architecture, separating responsibilities between the edge device, the cloud backend, and the client application.

This diagram illustrates the flow of information from sensor detection at the edge to the user notification on the client application, mediated by the cloud.

Sources: HomeSecurity/README.md:46-73

Tiers of Responsibility

Tier	Component	Responsibility
Edge	ESP32 + Sensors	Data acquisition, local processing, decision making, cloud communication.
Cloud	Firebase	User authentication, notification orchestration via serverless functions, push message delivery.
Client	Android App	User interface, alert reception, and live video display from an IP camera.

Sources: HomeSecurity/README.md:75-80

Hardware and Pin Configuration

The system is centered around an ESP32 DOIT DevKit V1 and uses a combination of sensors for multi-layered detection.

ESP32 GPIO Mapping

The following table details the GPIO pin assignments for all connected peripherals.

Pin	Component	Type	Description	Source File
GPIO 33	Hall Sensor	INPUT_PULLUP	Magnetic door/window sensor	hall_sensor.h:7
GPIO 21	PIR Sensor	INPUT	Passive infrared motion detection	pir_sensor.h:6
GPIO 22	Radar Sensor	INPUT	Doppler microwave motion detection	microwave_sensor.h:6
GPIO 25	Buzzer	OUTPUT	Audible alarm actuator	alarm.h:6
GPIO 19	Yellow LED	OUTPUT	Hall sensor triggered indicator	led.h:6
GPIO 18	Blue LED	OUTPUT	PIR motion detected indicator	led.h:7
GPIO 23	Red LED	OUTPUT	Intrusion confirmed indicator	led.h:8
GPIO 4	Green LED	OUTPUT	System calibrated/ready indicator	led.h:9
GPIO 13	White LED	OUTPUT	WiFi connected indicator	led.h:10

Sources: HomeSecurity/README.md:143-157, HomeSecurity/include/led.h:6-10, HomeSecurity/include/hall_sensor.h:7, HomeSecurity/include/pir_sensor.h:6, HomeSecurity/include/microwave_sensor.h:6, HomeSecurity/include/alarm.h:6

Software Architecture (FreeRTOS)

The firmware utilizes the FreeRTOS real-time operating system to manage multiple concurrent operations, such as sensor monitoring, WiFi management, and alert logic. Tasks are created in main.cpp with different priorities to ensure timely execution of critical functions.

Sources: HomeSecurity/src/main.cpp:7-13

FreeRTOS Task Structure

The following diagram shows the tasks created at startup.

This illustrates the parallel execution of tasks for different system functions.

Task Details

Task	Priority	Stack Size	Function
WiFiCheckTask	2 (Low)	2048 bytes	Manages WiFi connection and auto-reconnects if the connection is lost.
calibratePirSensorTask	3 (Medium)	1536 bytes	Manages the 30-second PIR sensor warm-up period and indicates system readiness.
handleRadarMovementTask	3 (Medium)	6144 bytes	Monitors the radar sensor for sustained motion to confirm presence.
handleHallMovementTask	4 (High)	2048 bytes	Monitors the magnetic Hall effect sensor for perimeter breaches.
handlePirMovementTask	4 (High)	2048 bytes	Monitors the PIR sensor for initial motion detection.
possibleHumanMovementDetectedTask	4 (High)	6144 bytes	Orchestrates the Stage 1 alert logic, triggering the alarm and sending a notification upon PIR or Hall sensor activation.

Sources: HomeSecurity/src/main.cpp:7-13, HomeSecurity/README.md:175-182

Alert Logic and Flow

The system uses a two-stage alert mechanism to reduce false positives. Stage 1 is an initial warning, and Stage 2 is a confirmation of sustained presence.

Alert Flow Diagram

This flowchart details the process from system startup through both stages of alert detection.

Stage 1: Initial Alert

This stage is handled by the possibleHumanMovementDetectedTask.

1. The task continuously checks if the PIR sensor (isPirActive()) or the Hall sensor (isHallSensorTriggered()) is active.
2. If either is triggered, it calls triggerAlarm() to sound the buzzer for 3 seconds.
3. Simultaneously, it uses the FirebaseNotifier instance to send a "Warning" notification to the registered mobile device.
4. A flag (notificareTrimisa) prevents sending multiple notifications for a single continuous event.

Sources: HomeSecurity/src/motion_logic.cpp:46-71, HomeSecurity/src/alarm.cpp:16-23

Stage 2: Presence Confirmation

This stage is managed by handleRadarMovementTask.

1. This task runs in parallel, monitoring the radar sensor (isRadarActive()).
2. If the radar detects continuous motion for a threshold of 2000ms, it confirms a human presence.
3. Upon confirmation, it sends a "Mișcare confirmată" (Movement confirmed) notification via Firebase.
4. The red LED is turned on (turnRedLedOn()) to visually indicate the confirmed intrusion.

Sources: HomeSecurity/src/motion_logic.cpp:103-126

Core Components

Firebase Notifier

The FirebaseNotifier class encapsulates the logic for sending push notifications.

// HomeSecurity/include/firebase_notifier.h
class FirebaseNotifier {
public:
    FirebaseNotifier(const String& functionUrl);
    bool sendNotification(const String& title, const String& body, const String& token);

private:
    String url;
};

• Initialization: It is instantiated with the URL of a Google Cloud Function.
• Operation: The sendNotification method constructs a JSON payload and sends it via an HTTPS POST request. It uses WiFiClientSecure but disables strict certificate checking (client.setInsecure()) for simplicity.

The following diagram shows the notification sequence.

Configuration

Key operational parameters are defined as constants or variables in the source code.

Parameter	Location	Default Value	Description
WIFI_SSID	wifi_manager.cpp:5	"IonutMoto"	The SSID of the WiFi network.
WIFI_PASSWORD	wifi_manager.cpp:6	"12345678"	The password for the WiFi network.
FirebaseNotifier URL	motion_logic.cpp:4	"https://trimitenotificare-k4cqa7es6q-uc.a.run.app"	The endpoint for the notification cloud function.
fcmToken	motion_logic.cpp:7	"d-OlFNUNSaSStUUsL05ofB:APA..."	The Firebase Cloud Messaging token of the target device.
ALARM_DURATION	alarm.h:7	3000 (ms)	The duration for which the buzzer sounds on triggerAlarm().
PIR Calibration Time	pir_sensor.cpp:12	30000 (ms)	The time required for the PIR sensor to calibrate after power-on.
Radar Confirmation Time	motion_logic.cpp:111	2000 (ms)	The duration of continuous radar activity required to confirm presence.

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