Hall Sensor Module

Relevant source files

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

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

The Hall Sensor module provides perimeter detection for the HomeSecurity system. It uses a KY-003 Hall effect magnetic sensor to detect if a door or window has been opened. When triggered, it initiates the first stage of the system's alert logic, which includes a local audible alarm and a remote push notification.

This module is a key component of the system's multi-layered detection strategy, offering immediate alerts for perimeter breaches. Its state is continuously monitored by a dedicated FreeRTOS task.

Sources: HomeSecurity/README.md, HomeSecurity/src/motion_logic.cpp

Architecture and Configuration

The module consists of the physical sensor connected to a specific GPIO pin on the ESP32, and the software functions required to initialize and read its state.

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

Pin Configuration

The Hall sensor is connected to GPIO 33. The pin is configured with an internal pull-up resistor.

Pin	Component	Type	Description
GPIO 33	Hall Sensor	INPUT_PULLUP	Magnetic door/window sensor

Sources: HomeSecurity/include/hall_sensor.h:5, HomeSecurity/src/hall_sensor.cpp:4, HomeSecurity/README.md

Initialization

The sensor is initialized during the system startup sequence via the setupHallSensor() function. This function is called from setupSensors() within the main motion logic module.

// HomeSecurity/src/hall_sensor.cpp:3-5
void setupHallSensor() {
  pinMode(HALL_SENSOR, INPUT_PULLUP);
}

The setupSensors() function orchestrates the initialization of all sensor hardware.

// HomeSecurity/src/motion_logic.cpp:10-15
void setupSensors() {
    setupPirSensor();
    setupHallSensor();
    setupMicrowaveSensor();
    setupLed();
    setupAlarm();
}

Sources: HomeSecurity/src/hall_sensor.cpp:3-5, HomeSecurity/src/motion_logic.cpp:10-15

Core Functionality

The module's primary function is to report whether the sensor is triggered.

State Detection

The isHallSensorTriggered() function reads the digital state of the sensor pin. It returns true if the pin state is HIGH, indicating that the magnetic field is absent (i.e., the door/window is open).

// HomeSecurity/src/hall_sensor.cpp:7-17
bool isHallSensorTriggered() {
  bool retVal = false;
  bool hallSensor = digitalRead(HALL_SENSOR);

  if (hallSensor == HIGH) {
    retVal = true;
  } else {
    retVal = false;
  }

  return retVal;
}

Sources: HomeSecurity/src/hall_sensor.cpp:7-17

Integration with System Logic

The Hall Sensor module is integrated into the main application through a dedicated FreeRTOS task and is a key input for the alert-triggering logic.

Dedicated FreeRTOS Task

In main.cpp, a task named handleHallMovementTask is created with a high priority of 4 to continuously monitor the Hall sensor.

// HomeSecurity/src/main.cpp:9
xTaskCreate(handleHallMovementTask, "HallSensor", 2048, NULL, 4, NULL);

This task, defined in motion_logic.cpp, checks the sensor's status every 100 milliseconds. It only runs after the PIR sensor has completed its calibration phase. Based on the sensor state, it turns the corresponding yellow LED on or off.

The following diagram illustrates the logic flow of the handleHallMovementTask.

Alert Triggering

The Hall sensor's state is a primary trigger for the system's Stage 1 alert. The possibleHumanMovementDetectedTask checks if either the PIR sensor or the Hall sensor is active. If isHallSensorTriggered() returns true, the system initiates an alert.

The alert sequence involves:

1. Sounding the local buzzer by calling triggerAlarm().
2. Sending a remote push notification via a Firebase Cloud Function by calling notifier.sendNotification().

Sources: HomeSecurity/src/motion_logic.cpp:50-68, HomeSecurity/include/alarm.h:11, HomeSecurity/include/firebase_notifier.h:11

The sequence diagram below shows the interactions when the Hall sensor is triggered.

Summary

The Hall Sensor module is a fundamental component for perimeter security in the HomeSecurity project. Through its simple hardware setup (INPUT_PULLUP on GPIO 33) and efficient software integration via a dedicated FreeRTOS task, it provides immediate detection of entry point breaches. Its status directly triggers the system's primary alert mechanism, making it the first line of defense in the intrusion detection logic.

Sources: HomeSecurity/README.md, HomeSecurity/src/motion_logic.cpp, HomeSecurity/src/hall_sensor.cpp