# al-sakka/locker-security-system architecture

> Architecture diagram of the GitHub repository al-sakka/locker-security-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/al-sakka/locker-security-system
- Repository: https://github.com/al-sakka/locker-security-system

## Overview

##### Project type and purpose
- This is an embedded security system comprising two ATmega32 microcontrollers (dual‐MCU door lock).
- **HMI_ECU** handles user interface (LCD + keypad) and communicates passwords.
- **Control_ECU** verifies passwords, drives the door motor, handles motion detection (PIR), and triggers alarms (buzzer).

##### File structure
- Top‐level: CONTROL_ECU, HMI_ECU, Simulation, docs.
- Each ECU folder follows a layered architecture:
- Application (business logic)
- HAL (hardware abstractions: sensors, actuators)
- MCAL (microcontroller drivers: GPIO, UART, Timer, I2C, PWM)
- Utils (common types/macros)
- Simulation/Proteus project and documentation assets in docs/.

##### Key insights from the README
- Dual‐MCU layered design with UART link between ECUs.
- Uses I2C for EEPROM, GPIO for PIR and buzzer, PWM for motor control, Timer for delays.
- Operation flows: password creation → authentication → motorized door control → security lockout.

##### Main components and interactions
a. **Components**
- HMI_ECU
- Application layer (main.c, hmi.c/hmi.h)
- HAL: Keypad, LCD
- MCAL: GPIO, UART, Timer
- Control_ECU
- Application layer (main.c, control.c/control.h)
- HAL: EEPROM (I2C), Motor, Buzzer, PIR
- MCAL: GPIO, I2C, UART, PWM, Timer
- External Devices
- 4×4 Keypad
- 8-bit LCD
- External EEPROM chip (I2C)
- H-bridge + DC motor
- PIR motion sensor
- Buzzer
- Communication link
- UART channel (TX/RX pins) between HMI_ECU and Control_ECU

b. **Relationships and Data Flows**
- User → Keypad → HMI Application
- HMI Application ↔ HAL (LCD updates)
- HMI Application ↔ MCAL UART → Control_ECU MCAL UART → Control Application
- Control Application ↔ MCAL I2C → EEPROM (read/write passwords)
- Control Application ↔ MCAL GPIO/PWM → Motor driver → Motor
- Control Application ↔ MCAL GPIO → PIR sensor, Buzzer driver
- Control ECU ↔ HMI_ECU (status/response via UART) → LCD display

c. **Architectural patterns**
- Layered architecture: clear separation of Application, HAL, MCAL, Utils
- Producer–consumer flow (HMI produces password requests; Control consumes and responds)
- Event‐driven interrupts (Timer, UART receive, PIR)

d. **Technologies & Frameworks**
- AVR‐GCC toolchain for ATmega32
- Custom GPIO, UART, I2C, PWM, Timer drivers
- EEPROM over TWI (I2C)
- Proteus for simulation

##### Diagramming advice
- Use clear, concise labels (e.g., “HMI_App”, “CTRL_HAL_I2C”).
- Rectangles for software modules (layers)
- Rounded for external HW (Keypad, LCD, Motor, PIR, Buzzer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% HMI ECU Block
    subgraph "HMI_ECU"
        direction TB
        HMI_App_Layer["Application Layer"]:::app
        HMI_Main["main.c"]:::app
        HMI_Logic["hmi.c / hmi.h"]:::app
        HMI_Utils["Utils"]:::utils

        HMI_HAL_Layer["HAL Layer"]:::hal
        Keypad["Keypad Driver"]:::hal
        LCD["LCD Driver"]:::hal

        HMI_MCAL_Layer["MCAL Layer"]:::mcal
        HMI_GPIO["GPIO Driver"]:::mcal
        HMI_UART["UART Driver"]:::mcal
        HMI_Timer["Timer Driver"]:::mcal
    end

    %% Control ECU Block
    subgraph "Control_ECU"
        direction TB
        Control_App_Layer["Application Layer"]:::app
        CTRL_Main["main.c"]:::app
        CTRL_Logic["control.c / control.h"]:::app
        C_Utils["Utils"]:::utils

        CTRL_HAL_Layer["HAL Layer"]:::hal
        EEPROM["EEPROM Driver"]:::hal
        Motor["Motor Driver"]:::hal
        Buzzer["Buzzer Driver"]:::hal
        PIR["PIR Sensor Driver"]:::hal

        CTRL_MCAL_Layer["MCAL Layer"]:::mcal
        C_GPIO["GPIO Driver"]:::mcal
        C_I2C["I2C Driver"]:::mcal
        C_UART["UART Driver"]:::mcal
        C_PWM["PWM Driver"]:::mcal
        C_Timer["Timer Driver"]:::mcal
    end

    %% External Devices
    Keypad_HW(("4×4 Keypad")):::ext
    LCD_HW(("8-bit LCD")):::ext
    EEPROM_HW[(External EEPROM)]:::storage
    Motor_HW(("H-bridge + DC Motor")):::ext
    PIR_HW(("PIR Motion Sensor")):::ext
    Buzzer_HW(("Buzzer")):::ext

    %% Connections HMI
    Keypad_HW -->|GPIO| Keypad
    Keypad -->|API| HMI_Logic
    HMI_Logic -->|Display| LCD
    LCD -->|LCD data| LCD_HW
    HMI_Logic -->|uses| HMI_Utils

    HMI_Main -->|calls| HMI_Logic
    HMI_App_Layer -->|contains| HMI_Main
    HMI_App_Layer -->|contains| HMI_Logic
    HMI_App_Layer -->|uses| HMI_Utils

    HMI_GPIO -->|drives| Keypad_HW
    HMI_GPIO -->|drives| LCD_HW
    HMI_Timer -->|interrupts| HMI_Logic

    %% UART Link
    HMI_UART -->|UART| C_UART
    click HMI_UART "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/MCAL/UART/uart.c"
    click C_UART "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/MCAL/UART/uart.c"
    click Keypad "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/HAL/Keypad/keypad.c"
    click LCD "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/HAL/LCD/lcd.c"

    %% Control connections
    EEPROM_HW -->|I2C| EEPROM
    EEPROM -->|API| CTRL_Logic
    Motor_HW -->|PWM| Motor
    Motor -->|API| CTRL_Logic
    PIR_HW -->|GPIO| PIR
    PIR -->|API| CTRL_Logic
    Buzzer_HW -->|GPIO| Buzzer
    Buzzer -->|API| CTRL_Logic

    CTRL_Main -->|calls| CTRL_Logic
    Control_App_Layer -->|contains| CTRL_Main
    Control_App_Layer -->|contains| CTRL_Logic
    Control_App_Layer -->|uses| C_Utils

    C_GPIO -->|drives| PIR_HW
    C_GPIO -->|drives| Buzzer_HW
    C_I2C -->|connects| EEPROM_HW
    C_PWM -->|drives| Motor_HW
    C_Timer -->|interrupts| CTRL_Logic

    %% Layer containment links
    HMI_HAL_Layer --> Keypad
    HMI_HAL_Layer --> LCD
    HMI_MCAL_Layer --> HMI_GPIO
    HMI_MCAL_Layer --> HMI_UART
    HMI_MCAL_Layer --> HMI_Timer

    CTRL_HAL_Layer --> EEPROM
    CTRL_HAL_Layer --> Motor
    CTRL_HAL_Layer --> PIR
    CTRL_HAL_Layer --> Buzzer
    CTRL_MCAL_Layer --> C_GPIO
    CTRL_MCAL_Layer --> C_I2C
    CTRL_MCAL_Layer --> C_UART
    CTRL_MCAL_Layer --> C_PWM
    CTRL_MCAL_Layer --> C_Timer

    %% Click events for Application and Utils
    click HMI_App_Layer "https://github.com/al-sakka/locker-security-system/tree/main/HMI_ECU/Application"
    click HMI_Main "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/Application/main.c"
    click HMI_Logic "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/Application/hmi.c"
    click HMI_Utils "https://github.com/al-sakka/locker-security-system/blob/main/HMI_ECU/Utils/std_types.h"

    click Control_App_Layer "https://github.com/al-sakka/locker-security-system/tree/main/CONTROL_ECU/Application"
    click CTRL_Main "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/Application/main.c"
    click CTRL_Logic "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/Application/control.c"
    click C_Utils "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/Utils/std_types.h"

    %% Click events for Control HAL and MCAL
    click EEPROM "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/HAL/EEPROM/eeprom.c"
    click Motor "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/HAL/Motor/motor.c"
    click Buzzer "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/HAL/Buzzer/buzzer.c"
    click PIR "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/HAL/PIR/pir.c"
    click C_GPIO "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/MCAL/GPIO/gpio.c"
    click C_I2C "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/MCAL/I2C/i2c.c"
    click C_PWM "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/MCAL/PWM/pwm.c"
    click C_Timer "https://github.com/al-sakka/locker-security-system/blob/main/CONTROL_ECU/MCAL/Timer/timer.c"

    %% Simulation and documentation
    UART_Link(("UART Link Simulation")):::note
    click UART_Link "https://github.com/al-sakka/locker-security-system/blob/main/Simulation/locker_security_system.pdsprj"
    Docs(("Documentation")):::note
    click Docs "https://github.com/al-sakka/locker-security-system/blob/main/docs/ATmega32.pdf"

    %% Legend
    subgraph Legend
        direction TB
        A[Application]:::app
        H[HAL]:::hal
        M[MCAL]:::mcal
        U[Utils]:::utils
        E[External HW]:::ext
        S[Storage]:::storage
        N[Note]:::note
    end

    classDef app fill:#D6EAF8,stroke:#3498DB;
    classDef hal fill:#D5F5E3,stroke:#27AE60;
    classDef mcal fill:#FCF3CF,stroke:#F1C40F;
    classDef utils fill:#F2F3F4,stroke:#95A5A6;
    classDef ext fill:#FADBD8,stroke:#C0392B,stroke-width:2px,shape:roundrect;
    classDef storage fill:#E8DAEF,stroke:#8E44AD,shape:cylinder;
    classDef note fill:#FEF9E7,stroke:#D4AC0D,shape:note;
```
