Alarm Control Module

Relevant source files

The following files were used as context for generating this wiki page:

• HomeSecurity/src/alarm.cpp
• HomeSecurity/include/alarm.h
• HomeSecurity/src/motion_logic.cpp
• HomeSecurity/src/main.cpp
• HomeSecurity/include/motion_logic.h
• HomeSecurity/README.md

# Alarm Control Module

The Alarm Control Module provides a non-blocking mechanism for managing an audible alarm within the HomeSecurity system. Its primary responsibility is to activate a buzzer for a predefined duration when an intrusion is detected, without halting other system processes. This is achieved through a state-based management system that is polled by a high-priority FreeRTOS task.

The module is triggered by the possibleHumanMovementDetectedTask, which is the central logic for handling initial sensor alerts from the PIR or Hall effect sensors. Upon triggering, the alarm sounds concurrently with a Firebase push notification being sent to the user.

Sources: HomeSecurity/src/alarm.cpp, HomeSecurity/src/motion_logic.cpp:52-75, HomeSecurity/README.md

Architecture and API

The module's architecture is simple, consisting of a hardware pin definition, state variables, and three main functions that form its public API. It is designed to be integrated into a cooperative multitasking environment like FreeRTOS.

Sources: HomeSecurity/include/alarm.h, HomeSecurity/src/alarm.cpp

Configuration

The alarm's behavior is defined by two constants in alarm.h.

Constant	Value	Description	File
BUZZER_PIN	25	The GPIO pin connected to the active buzzer.	HomeSecurity/include/alarm.h:5
ALARM_DURATION	3000	The duration in milliseconds for which the alarm will sound.	HomeSecurity/include/alarm.h:6

Core Functions

The module exposes three functions for its control:

• void setupAlarm(): Initializes the BUZZER_PIN as an OUTPUT and sets its initial state to LOW. This function is called once during system setup.
  Sources: HomeSecurity/src/alarm.cpp:6-10

• void triggerAlarm(): Activates the alarm if it is not already active. It sets the isAlarmActive flag to true, records the start time, and sets the BUZZER_PIN to HIGH. This function is non-blocking.
  Sources: HomeSecurity/src/alarm.cpp:15-22

• void handleAlarm(): Manages the alarm's active state. It checks if the ALARM_DURATION has elapsed since the alarm was triggered. If so, it deactivates the alarm by setting the BUZZER_PIN to LOW and resetting the isAlarmActive flag. This function must be called repeatedly in a loop.
  Sources: HomeSecurity/src/alarm.cpp:27-34

State Management

The module uses a state machine with two states: INACTIVE and ACTIVE. The state is managed by the isAlarmActive boolean variable. The transition from ACTIVE back to INACTIVE is time-based, controlled by comparing the current time (millis()) with the stored alarmStartTime.

Sources: HomeSecurity/src/alarm.cpp:3-4, HomeSecurity/src/alarm.cpp:27-34

The diagram below illustrates the alarm's state transitions.

Execution Flow

The alarm is integrated into the system's main motion detection logic. The possibleHumanMovementDetectedTask is responsible for monitoring sensor states and initiating the alert process.

1. The possibleHumanMovementDetectedTask detects a trigger from either the PIR or Hall sensor.
2. It calls triggerAlarm() to immediately sound the buzzer.
3. Concurrently, it sends a push notification via the FirebaseNotifier.
4. The task's main loop continues to call handleAlarm() on every iteration.
5. handleAlarm() checks the elapsed time and deactivates the buzzer after ALARM_DURATION has passed, without blocking the task.

Sources: HomeSecurity/src/motion_logic.cpp:52-75

The following sequence diagram shows the interaction between the motion detection task and the alarm module.

handleAlarm() Logic

The core of the non-blocking design resides in the handleAlarm function.

Implementation Snippets

The non-blocking nature is evident in the separation of the trigger and handler logic.

triggerAlarm()

This function simply initiates the alarm state and returns immediately.

// File: HomeSecurity/src/alarm.cpp

void triggerAlarm() {
  if (!isAlarmActive) {
    isAlarmActive = true;
    alarmStartTime = millis();
    digitalWrite(BUZZER_PIN, HIGH);
    Serial.println("[ALARM] Alarma a fost pornită.");
  }
}

Sources: HomeSecurity/src/alarm.cpp:15-22

handleAlarm()

This function checks the state on each call and acts only when the timer condition is met.

// File: HomeSecurity/src/alarm.cpp

void handleAlarm() {
  if (isAlarmActive && (millis() - alarmStartTime >= ALARM_DURATION)) {
    digitalWrite(BUZZER_PIN, LOW);
    isAlarmActive = false;
    Serial.println("[ALARM] Alarma a fost oprită.");
  }
}

Sources: HomeSecurity/src/alarm.cpp:27-34

Conclusion

The Alarm Control Module is an essential component for providing immediate, audible feedback upon intrusion detection. Its non-blocking, state-driven design is crucial for maintaining the responsiveness of the overall security system, allowing sensor monitoring and cloud communication to proceed without interruption while the alarm is active.