Status LED Indicators

Relevant source files

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

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

The HomeSecurity system uses a set of five distinct LEDs to provide at-a-glance visual feedback on its operational status. These indicators are crucial for understanding the system's state, including power, sensor calibration, network connectivity, and real-time security alerts. Each color-coded LED is mapped to a specific system event or status, allowing for immediate diagnosis and monitoring without needing a serial connection.

The LED control logic is integrated into various FreeRTOS tasks, ensuring that status updates are handled concurrently and do not block critical security monitoring operations. This provides a responsive and clear user interface directly on the hardware.

Sources: HomeSecurity/README.md:195-209, HomeSecurity/src/main.cpp:8-13

Hardware Configuration

The five status LEDs are connected to specific GPIO pins on the ESP32 DOIT DevKit V1. The pins are defined as macros in led.h and configured as OUTPUT in the setupLed() function.

Sources: HomeSecurity/include/led.h:6-10, HomeSecurity/src/led.cpp:3-8

GPIO Pin Mapping

The following table details the GPIO pin assignments for each LED.

LED Color	GPIO Pin	Macro Name	Purpose
Yellow	19	yellowLED	Hall sensor triggered
Blue	18	blueLED	PIR motion detected
Red	23	redLED	Intrusion confirmed by radar
Green	4	greenLED	System calibrated/ready
White	13	whiteLED	WiFi connected

Sources: HomeSecurity/include/led.h:6-10, HomeSecurity/README.md:111-119

Software Interface

The control of the LEDs is abstracted through a set of functions declared in led.h and implemented in led.cpp. This provides a clean and reusable interface for other modules to manipulate the LED states.

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

Core Functions

• void setupLed(): Initializes the GPIO pins for all LEDs by setting their mode to OUTPUT. This function is called once during system setup.
• void turn<Color>LedOn(): A set of functions (e.g., turnYellowLedOn(), turnGreenLedOn()) that set the corresponding GPIO pin to HIGH, turning the LED on.
• void turn<Color>LedOff(): A set of functions (e.g., turnYellowLedOff(), turnGreenLedOff()) that set the corresponding GPIO pin to LOW, turning the LED off.

The code below shows the implementation for initializing the LED pins.

// File: HomeSecurity/src/led.cpp:3-9

void setupLed() {
  pinMode(yellowLED, OUTPUT);
  pinMode(blueLED, OUTPUT);
  pinMode(redLED, OUTPUT);
  pinMode(greenLED, OUTPUT);
  pinMode(whiteLED, OUTPUT);    
}

Sources: HomeSecurity/src/led.cpp:3-9

LED Status Logic

Each LED's state is controlled by a specific FreeRTOS task that monitors a particular aspect of the system.

LED State Flow

This diagram illustrates the sequence of events that control the Green and White LEDs during system startup, and the events that control the alert LEDs (Yellow, Blue, Red) during runtime.

🟢 Green LED: System Ready

The Green LED indicates that the PIR sensor has completed its mandatory 30-second calibration period and the system is fully armed and ready to detect motion.

• Task: calibratePirSensorTask
• Logic: The task waits for 30 seconds after boot. Once the time has elapsed, it sets the pirCalibrated flag to true and calls turnGreenLedOn().
• File: src/pir_sensor.cpp

Sources: HomeSecurity/src/pir_sensor.cpp:11-15, HomeSecurity/README.md:198

⚪ White LED: WiFi Status

The White LED provides a clear indication of the device's network connectivity status.

• Task: WiFiCheckTask and initial connection
• Logic: The connectToWiFi function calls turnWhiteLedOn() immediately after a successful connection to the WiFi network is established. The WiFiCheckTask ensures the connection is maintained and attempts to reconnect if it's lost.
• File: src/wifi_manager.cpp

Sources: HomeSecurity/src/wifi_manager.cpp:25-26, HomeSecurity/README.md:199

🟡 Yellow LED: Hall Sensor Trigger

The Yellow LED indicates that the perimeter has been breached, specifically that a door or window equipped with the Hall effect sensor has been opened.

• Task: handleHallMovementTask
• Logic: This task continuously checks the state of the Hall sensor. If isHallSensorTriggered() returns true, it calls turnYellowLedOn(). The LED is turned off when the sensor is no longer triggered.
• File: src/motion_logic.cpp

This sequence diagram shows the handleHallMovementTask polling the Hall sensor and turning the yellow LED on or off based on its state.

Sources: HomeSecurity/src/motion_logic.cpp:25-33, HomeSecurity/README.md:200

🔵 Blue LED: PIR Motion Detected

The Blue LED signals that the PIR sensor has detected motion. This serves as the first level of interior motion detection.

• Task: handlePirMovementTask
• Logic: This task polls the PIR sensor via isPirActive(). If motion is detected, it calls turnBlueLedOn(). The LED is turned off when motion is no longer detected.
• File: src/motion_logic.cpp

Sources: HomeSecurity/src/motion_logic.cpp:38-44, HomeSecurity/README.md:201

🔴 Red LED: Intrusion Confirmed

The Red LED indicates a confirmed intrusion. This is a higher-level alert triggered only when the microwave radar sensor detects sustained movement for more than 2 seconds.

• Task: handleRadarMovementTask
• Logic: If the radar sensor (isRadarActive()) is active, a timer is started. If the sensor remains active for 2000ms or more, turnRedLedOn() is called to signify a confirmed presence. The LED is turned off when the radar no longer detects movement.
• File: src/motion_logic.cpp

Sources: HomeSecurity/src/motion_logic.cpp:117-121, HomeSecurity/README.md:202

Summary

The status LED indicators are an integral part of the HomeSecurity system's physical interface. They provide immediate, clear, and multi-faceted feedback on the system's operational state, from initial setup and calibration to real-time threat detection. By mapping specific system events to distinct colors, the LEDs serve as a simple yet effective diagnostic and monitoring tool for the end-user.

Sources: HomeSecurity/README.md:195-197