# ESP32 LED Control Program with Push Buttons
# MicroPython Implementation with Full Documentation

# Import necessary libraries
from machine import Pin  # Provides GPIO pin control functionality
import time             # Handles time-related functions like delays

# ===== HARDWARE PIN CONFIGURATION =====
# Initialize LED pins as digital outputs
# Note: Replace pin numbers (14,15,16,17) with your actual GPIO connections
LED1 = Pin(14, Pin.OUT)  # LED1 connected to GPIO14
LED2 = Pin(15, Pin.OUT)  # LED2 connected to GPIO15
LED3 = Pin(16, Pin.OUT)  # LED3 connected to GPIO16
LED4 = Pin(17, Pin.OUT)  # LED4 connected to GPIO17

# Initialize switch pins as digital inputs with pull-up resistors
# Buttons should be wired between these pins and GND (active-low configuration)
SW1 = Pin(18, Pin.IN, Pin.PULL_UP)  # Switch1 connected to GPIO18
SW2 = Pin(19, Pin.IN, Pin.PULL_UP)  # Switch2 connected to GPIO19
SW3 = Pin(21, Pin.IN, Pin.PULL_UP)  # Switch3 connected to GPIO21

# ===== INITIALIZATION =====
# Set all LEDs to OFF state (LOW) when program starts
LED1.value(0)  # Turn LED1 OFF
LED2.value(0)  # Turn LED2 OFF
LED3.value(0)  # Turn LED3 OFF
LED4.value(0)  # Turn LED4 OFF

# ===== LED EFFECT FUNCTIONS =====
def blink_all(delay=1):
    """
    Blinks all LEDs simultaneously
    Args:
        delay: Time in seconds for both ON and OFF states
    Operation:
        1. Turns all LEDs ON
        2. Waits for specified delay
        3. Turns all LEDs OFF
        4. Waits for specified delay
    """
    # Turn all LEDs ON
    LED1.value(1)  # Set LED1 HIGH (ON)
    LED2.value(1)  # Set LED2 HIGH (ON)
    LED3.value(1)  # Set LED3 HIGH (ON)
    LED4.value(1)  # Set LED4 HIGH (ON)
    time.sleep(delay)  # Keep LEDs ON for delay seconds
    
    # Turn all LEDs OFF
    LED1.value(0)  # Set LED1 LOW (OFF)
    LED2.value(0)  # Set LED2 LOW (OFF)
    LED3.value(0)  # Set LED3 LOW (OFF)
    LED4.value(0)  # Set LED4 LOW (OFF)
    time.sleep(delay)  # Keep LEDs OFF for delay seconds

def run_right_to_left(delay=2):
    """
    Creates a chasing effect from right to left (LED1 to LED4)
    Args:
        delay: Time in seconds each LED stays ON
    Operation:
        1. Turns on LED1, waits, then turns it off
        2. Turns on LED2, waits, then turns it off
        3. Repeats for all LEDs in sequence
    """
    LED1.value(1)  # Turn LED1 ON
    time.sleep(delay)  # Hold for delay seconds
    LED1.value(0)  # Turn LED1 OFF
    
    LED2.value(1)  # Turn LED2 ON
    time.sleep(delay)  # Hold for delay seconds
    LED2.value(0)  # Turn LED2 OFF
    
    LED3.value(1)  # Turn LED3 ON
    time.sleep(delay)  # Hold for delay seconds
    LED3.value(0)  # Turn LED3 OFF
    
    LED4.value(1)  # Turn LED4 ON
    time.sleep(delay)  # Hold for delay seconds
    LED4.value(0)  # Turn LED4 OFF

def run_left_to_right(delay=4):
    """
    Creates a chasing effect from left to right (LED4 to LED1)
    Args:
        delay: Time in seconds each LED stays ON
    Operation:
        1. Turns on LED4, waits, then turns it off
        2. Turns on LED3, waits, then turns it off
        3. Repeats for all LEDs in reverse sequence
    """
    LED4.value(1)  # Turn LED4 ON
    time.sleep(delay)  # Hold for delay seconds
    LED4.value(0)  # Turn LED4 OFF
    
    LED3.value(1)  # Turn LED3 ON
    time.sleep(delay)  # Hold for delay seconds
    LED3.value(0)  # Turn LED3 OFF
    
    LED2.value(1)  # Turn LED2 ON
    time.sleep(delay)  # Hold for delay seconds
    LED2.value(0)  # Turn LED2 OFF
    
    LED1.value(1)  # Turn LED1 ON
    time.sleep(delay)  # Hold for delay seconds
    LED1.value(0)  # Turn LED1 OFF

# ===== MAIN PROGRAM LOOP =====
try:
    print("Program started. Ready for button input...")
    
    while True:  # Infinite loop until KeyboardInterrupt
        time.sleep(0.01)  # Small delay to reduce CPU usage
        
        # Check if Switch1 (SW1) is pressed (active LOW)
        if SW1.value() == 0:
            print("LED IS BLINKING 1 SECOND DELAY, SWITCH1 IS PRESSED")
            # Keep blinking while button is held
            while SW1.value() == 0:
                blink_all(1)  # Blink with 1 second interval
        
        # Check if Switch2 (SW2) is pressed
        elif SW2.value() == 0:
            print("LED IS RUNNING LEFT TO RIGHT 2 SECOND DELAY, SWITCH2 IS PRESSED")
            # Keep chasing left-to-right while button is held
            while SW2.value() == 0:
                run_right_to_left(2)  # 2 second delay per LED
        
        # Check if Switch3 (SW3) is pressed
        elif SW3.value() == 0:
            print("LED IS RUNNING RIGHT TO LEFT 4 SECOND DELAY, SWITCH3 IS PRESSED")
            # Keep chasing right-to-left while button is held
            while SW3.value() == 0:
                run_left_to_right(4)  # 4 second delay per LED
        
        # No buttons pressed - ensure all LEDs are OFF
        else:
            LED1.value(0)  # Ensure LED1 OFF
            LED2.value(0)  # Ensure LED2 OFF
            LED3.value(0)  # Ensure LED3 OFF
            LED4.value(0)  # Ensure LED4 OFF
            print("LED OFF, PRESS SWITCH TO TURN ON THE LED")
            time.sleep(0.01)  # Small delay

# ===== PROGRAM CLEANUP =====
except KeyboardInterrupt:
    # Turn off all LEDs when program is interrupted (Ctrl+C)
    LED1.value(0)  # Turn LED1 OFF
    LED2.value(0)  # Turn LED2 OFF
    LED3.value(0)  # Turn LED3 OFF
    LED4.value(0)  # Turn LED4 OFF
    print("\nProgram stopped by user. All LEDs turned OFF.")