# dariiats/esp32-security-system architecture

> Architecture diagram of the GitHub repository dariiats/esp32-security-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dariiats/esp32-security-system
- Repository: https://github.com/dariiats/esp32-security-system

## Overview

#### Purpose and Entry Point
This is ESP32 firmware for a local smart-security system: PIR motion detection triggers Bluetooth user notification; a user can request or ignore an alarm; an authorized RFID card is required to deactivate an active alarm. The firmware entry point is `src/main.cpp`, built and uploaded through the PlatformIO project defined by `platformio.ini`.

#### Embedded Runtime and Hardware Boundary
The system runs on an ESP32 DevKit and directly controls GPIO-connected PIR, LEDs, and buzzer/alarm circuitry. It communicates with the RFID reader over I²C. Hardware-specific initialization and the continuous device event loop are expected to be centralized in `src/main.cpp`; the application has no stated Wi‑Fi, cloud, server, or persistent-backend dependency.

Paths:
- `src/main.cpp`
- `platformio.ini`

#### Motion Detection Stage
The PIR sensor is the initiating event source. Motion causes the firmware to evaluate the detected activity and notify the connected Bluetooth client, rather than immediately relying solely on physical alarm output. This establishes a control boundary between physical sensor input and user-directed alarm decisions.

Paths:
- `src/main.cpp`

#### Bluetooth Command Control
ESP32 Bluetooth provides the human-control channel, exposing the device as `ESP32Security` for an Android serial-Bluetooth terminal. The intended command flow is: motion notification → user sends `alarm` or `ignore` → firmware changes alarm behavior. Bluetooth is therefore both an outbound notification transport and an inbound command interface.

Paths:
- `src/main.cpp`

#### Alarm Actuation and State
The active alarm is represented through visual LEDs and an audio buzzer driven from the ESP32. Alarm activation can be requested remotely; ignoring a motion event suppresses/escalation handling. Deactivation is deliberately gated by RFID authorization, creating a security boundary: Bluetooth commands manage the response decision, while RFID identity authorizes alarm shutdown.

Paths:
- `src/main.cpp`

#### RFID Authentication
RFID card reads are handled through the bundled MFRC522 I²C driver. The application compares a presented card’s UID with an authorized UID configured in firmware; only a match may deactivate an active alarm. The local library owns reader-level I²C/register communication, while application policy and authorization belong in the main firmware.

Paths:
- `lib/MFRC522_I2C/MFRC522_I2C.h`
- `lib/MFRC522_I2C/MFRC522_I2C.cpp`
- `src/main.cpp`

#### Dependency and Build Boundary
The project vendors its RFID dependency rather than requiring external installation. `MFRC522_I2C` integrates with the ESP32’s I²C/Wire stack and includes a standalone Arduino usage example, while the root firmware remains the deployable security application. PlatformIO is the material build/upload infrastructure.

Paths:
- `lib/MFRC522_I2C/library.properties`
- `lib/MFRC522_I2C/examples/mfrc522_i2c/MFRC522_i2c.ino`
- `platformio.ini`

Main entry points: [`lib/MFRC522_I2C/MFRC522_I2C.cpp`](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.cpp) (MFRC522 I²C driver), [`src/main.cpp`](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp) (Security application loop), [`lib/MFRC522_I2C/MFRC522_I2C.h`](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.h) (MFRC522 driver API), [`lib/MFRC522_I2C/library.properties`](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/library.properties) (Library package metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["ESP32 Device"]
  node_esp32["ESP32 DevKit<br/>embedded runtime"]
  node_pir["PIR sensor<br/>GPIO input"]
  node_alarm_hardware["LEDs and buzzer<br/>GPIO actuator"]
  node_rfid_reader["MFRC522 reader<br/>I²C peripheral"]
  node_wire["ESP32 Wire/I²C stack<br/>platform interface"]
end

subgraph group_firmware["Security Firmware"]
  node_main["Security application loop<br/>firmware entry point<br/>[main.cpp]"]
  node_motion["Motion evaluation<br/>event stage<br/>[main.cpp]"]
  node_bt_control["Bluetooth notification and commands<br/>control channel<br/>[main.cpp]"]
  node_alarm_state["Alarm state control<br/>security state<br/>[main.cpp]"]
  node_rfid_policy["UID authorization<br/>access policy<br/>[main.cpp]"]
end

subgraph group_rfid["RFID Dependency"]
  node_mfrc522_driver["MFRC522 I²C driver<br/>vendored Arduino library<br/>[MFRC522_I2C.cpp]"]
  node_driver_api["MFRC522 driver API<br/>library interface<br/>[MFRC522_I2C.h]"]
  node_library_package["Library package metadata<br/>dependency manifest<br/>[library.properties]"]
  node_rfid_example["Standalone RFID example<br/>Arduino example<br/>[MFRC522_i2c.ino]"]
end

node_platformio{{"PlatformIO build/upload<br/>build infrastructure<br/>[platformio.ini]"}}
node_bluetooth_client["Android Bluetooth client<br/>user control client"]

node_platformio -->|"builds and uploads"| node_main
node_main -->|"runs on"| node_esp32
node_pir -->|"motion signal"| node_motion
node_main -->|"handles"| node_motion
node_motion -->|"notifies"| node_bt_control
node_bluetooth_client -->|"alarm / ignore commands"| node_bt_control
node_bt_control -->|"response decision"| node_alarm_state
node_alarm_state -->|"drives"| node_alarm_hardware
node_rfid_reader -->|"card communication"| node_mfrc522_driver
node_mfrc522_driver -->|"uses I²C"| node_wire
node_driver_api -->|"declares"| node_mfrc522_driver
node_main -->|"reads cards through"| node_driver_api
node_mfrc522_driver -->|"card UID"| node_rfid_policy
node_rfid_policy -->|"authorizes deactivation"| node_alarm_state
node_library_package -.->|"packages"| node_mfrc522_driver
node_rfid_example -.->|"demonstrates"| node_driver_api

click node_platformio "https://github.com/dariiats/esp32-security-system/blob/main/platformio.ini"
click node_main "https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp"
click node_motion "https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp"
click node_bt_control "https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp"
click node_alarm_state "https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp"
click node_rfid_policy "https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp"
click node_mfrc522_driver "https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.cpp"
click node_driver_api "https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.h"
click node_library_package "https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/library.properties"
click node_rfid_example "https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/examples/mfrc522_i2c/MFRC522_i2c.ino"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_esp32,node_pir,node_alarm_hardware,node_rfid_reader,node_wire toneBlue
class node_main,node_motion,node_bt_control,node_alarm_state,node_rfid_policy toneAmber
class node_mfrc522_driver,node_driver_api,node_library_package,node_rfid_example toneMint
class node_platformio,node_bluetooth_client toneNeutral
```

## Components

### ESP32 Device

- **ESP32 DevKit**: embedded runtime
- **PIR sensor**: GPIO input
- **LEDs and buzzer**: GPIO actuator
- **MFRC522 reader**: I²C peripheral
- **ESP32 Wire/I²C stack**: platform interface

### Security Firmware

- [Security application loop](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp): firmware entry point · Owns hardware initialization, event handling, and security policy. · `src/main.cpp`
- [Motion evaluation](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp): event stage · `src/main.cpp`
- [Bluetooth notification and commands](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp): control channel · Exposes ESP32Security and accepts alarm or ignore commands. · `src/main.cpp`
- [Alarm state control](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp): security state · Remote activation is allowed; shutdown requires RFID authorization. · `src/main.cpp`
- [UID authorization](https://github.com/dariiats/esp32-security-system/blob/main/src/main.cpp): access policy · Compares presented card UID with the firmware-authorized UID. · `src/main.cpp`

### RFID Dependency

- [MFRC522 I²C driver](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.cpp): vendored Arduino library · Owns reader I²C and register communication. · `lib/MFRC522_I2C/MFRC522_I2C.cpp`
- [MFRC522 driver API](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/MFRC522_I2C.h): library interface · `lib/MFRC522_I2C/MFRC522_I2C.h`
- [Library package metadata](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/library.properties): dependency manifest · `lib/MFRC522_I2C/library.properties`
- [Standalone RFID example](https://github.com/dariiats/esp32-security-system/blob/main/lib/MFRC522_I2C/examples/mfrc522_i2c/MFRC522_i2c.ino): Arduino example · `lib/MFRC522_I2C/examples/mfrc522_i2c/MFRC522_i2c.ino`

### Other components

- [PlatformIO build/upload](https://github.com/dariiats/esp32-security-system/blob/main/platformio.ini): build infrastructure · `platformio.ini`
- **Android Bluetooth client**: user control client

## Connections

- PlatformIO build/upload → Security application loop: builds and uploads
- Security application loop → ESP32 DevKit: runs on
- PIR sensor → Motion evaluation: motion signal
- Security application loop → Motion evaluation: handles
- Motion evaluation → Bluetooth notification and commands: notifies
- Android Bluetooth client → Bluetooth notification and commands: alarm / ignore commands
- Bluetooth notification and commands → Alarm state control: response decision
- Alarm state control → LEDs and buzzer: drives
- MFRC522 reader → MFRC522 I²C driver: card communication
- MFRC522 I²C driver → ESP32 Wire/I²C stack: uses I²C
- MFRC522 driver API → MFRC522 I²C driver: declares
- Security application loop → MFRC522 driver API: reads cards through
- MFRC522 I²C driver → UID authorization: card UID
- UID authorization → Alarm state control: authorizes deactivation
- Library package metadata → MFRC522 I²C driver: packages
- Standalone RFID example → MFRC522 driver API: demonstrates