diff --git a/Readme.md b/Readme.md index c19eb75..301f1a8 100644 --- a/Readme.md +++ b/Readme.md @@ -1,83 +1,195 @@ -# NFC University Gate Access System 🎓🚗 +# 🏷️ Terminal Bramy RFID (ESP32 + Home Assistant) -System kontroli dostępu do bramy lub drzwi na uczelni, wykorzystujący **Elektroniczną Legitymację Studencką (ELS)** oraz komunikację online z bazą danych MySQL. +![ESPHome](https://img.shields.io/badge/ESPHome-Compatible-blue) +![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Integrated-41BDF5) +![ESP32](https://img.shields.io/badge/ESP32-DevKit%20V1-red) +![License MIT](https://img.shields.io/badge/License-MIT-green) +![Power Optimized](https://img.shields.io/badge/Optimized-80MHz%20Underclock-orange) -## 📝 Opis projektu -Projekt umożliwia autoryzację wjazdu na teren uczelni za pomocą standardowych legitymacji studenckich (standard NFC/RFID 13.56MHz). System nie przechowuje listy uprawnionych osób lokalnie na urządzeniu, lecz każdorazowo odpytuje serwer bazy danych, co pozwala na natychmiastowe nadawanie lub odbieranie uprawnień. +Inteligentny terminal RFID do sterowania bramą z wykorzystaniem **ESP32**, **RC522**, **OLED SSD1306** oraz **Home Assistant**. -## ✨ Funkcje systemu +--- -* **Autoryzacja Online:** Weryfikacja kart ELS w czasie rzeczywistym poprzez API PHP i bazę danych MySQL. -* **Tryb Hybrydowy (Offline Cache):** System zapamiętuje 10 ostatnio autoryzowanych kart w pamięci nieulotnej (NVS). Brama otworzy się nawet w przypadku awarii sieci WiFi lub serwera. -* **Zarządzanie Czasowe:** Możliwość blokowania dostępu po wygaśnięciu ważności legitymacji bezpośrednio w bazie danych. -* **Bezpieczeństwo (API Key):** Każde zapytanie z ESP32 do serwera jest autoryzowane unikalnym kluczem, co zapobiega nieautoryzowanym próbom otwarcia bramy. -* **Zapis Logów:** Serwer automatycznie rejestruje datę i godzinę każdego użycia karty (pole `last_entry` w bazie). -* **Niskie Opóźnienie:** Dzięki optymalizacji kodu, czas od zbliżenia karty do reakcji przekaźnika wynosi zazwyczaj poniżej 500ms. +# 🚀 Szybki start +## Konfiguracja +W pliku `secrets.yaml` zdefiniuj: +- `wifi_ssid` +- `wifi_password` +- `api_encryption_key` +- `ota_password` -## 🏗 Architektura systemu -1. **ESP32**: Odczytuje unikalny numer (UID) karty zbliżeniowej. -2. **API (PHP)**: Skrypt pośredniczący, który odbiera UID od ESP32 i komunikuje się z bazą danych. -3. **Baza Danych (MySQL)**: Przechowuje informacje o studentach, ich numerach UID oraz ważności uprawnień. -4. **Przekaźnik**: Fizycznie zwiera styki w sterowniku bramy po otrzymaniu pozytywnej weryfikacji. +## Pomocnik +Utwórz w Home Assistant encję: +input_text.terminal_status -## 🛠 Wymagania sprzętowe -- **Mikrokontroler**: ESP32 (lub ESP8266 z poprawkami w kodzie). -- **Czytnik NFC**: MFRC522 (RC522) lub PN532. -- **Moduł przekaźnika**: 1-kanałowy (Low/High level trigger). -- **Zasilanie**: 5V/12V (zależnie od sterownika bramy). -- **Pozostałe**: Diody LED (status), rezystory, przewody połączeniowe. +## Instalacja +1. Skompiluj projekt w ESPHome +2. Wgraj na ESP32 +3. System automatycznie obniży taktowanie do **80 MHz** (oszczędzanie energii) -## 💻 Struktura bazy danych -Wykonaj poniższe zapytanie SQL, aby przygotować bazę danych: +## Tagi +1. Zeskanuj kartę +2. W Home Assistant → **Tagi** +3. Nazwij tag zaczynając od: +Legitymacja +Np Legitymacja Jan Kowalski -```sql -CREATE TABLE students ( -id INT AUTO_INCREMENT PRIMARY KEY, -card_uid VARCHAR(20) UNIQUE NOT NULL, -full_name VARCHAR(100), -student_id_number VARCHAR(15), -is_active BOOLEAN DEFAULT 1, -expiry_date DATE, -last_entry TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP -); -``` -## 🚀 Instalacja i Konfiguracja -1. Serwer (Backend) -Skopiuj pliki z folderu /server na swój hosting/serwer. -Skonfiguruj połączenie z bazą danych w pliku db_config.php. -Dodaj testowy rekord (UID swojej legitymacji) do tabeli students. -2. Urządzenie (Firmware) -Otwórz projekt w Arduino IDE lub PlatformIO. -Zainstaluj biblioteki: MFRC522 oraz HTTPClient. -W pliku głównym uzupełnij dane: -SSID i Password Twojej sieci WiFi. -API_URL (adres do Twojego skryptu PHP). -Wgraj program na ESP32. +--- -## 🔌 Schemat połączeń (Pinout) +# 🏗️ Architektura systemu -Poniższa tabela przedstawia połączenie czytnika RFID-RC522 z mikrokontrolerem ESP32: +System działa w modelu **Klient–Serwer**. -| Moduł RC522 | ESP32 (GPIO) | Opis | -|:---:|:---:|:---| -| **VCC** | 3.3V | Zasilanie (UWAGA: Nie podłączać pod 5V!) | -| **RST** | GPIO 22 | Reset | -| **GND** | GND | Masa | -| **MISO** | GPIO 19 | Master In Slave Out (SPI) | -| **MOSI** | GPIO 23 | Master Out Slave In (SPI) | -| **SCK** | GPIO 18 | Serial Clock (SPI) | -| **SDA (SS)**| GPIO 5 | Chip Select (SPI) | +### Warstwa sprzętowa +- ESP32 +- RFID RC522 (SPI) +- OLED SSD1306 (I2C) -**Elementy dodatkowe:** -* **Przekaźnik (Relay):** Sygnał sterujący podłączony do **GPIO 2**. -* **Dioda LED (Opcjonalnie):** GPIO 4 (sygnalizacja otwarcia). +### Warstwa logiczna +- Home Assistant weryfikuje tag +- Komunikacja przez Native API (AES-128) +### Optymalizacja +- Lokalny fallback wyświetlania +- Underclocking 80 MHz +- Light Sleep WiFi -## 🔒 Bezpieczeństwo -HTTPS: Zaleca się hostowanie skryptu API na serwerze z certyfikatem SSL. -API KEY: Warto dodać nagłówek autoryzacji w zapytaniach HTTP, aby uniemożliwić ręczne wywoływanie skryptu z przeglądarki. -Fail-safe: System w przypadku braku połączenia z siecią pozostaje w trybie zamkniętym. +--- -## 📄 Licencja -Projekt udostępniony na licencji MIT. Możesz go dowolnie modyfikować na potrzeby własnych projektów edukacyjnych. \ No newline at end of file +# 💻 Wymagania sprzętowe + +| Element | Model | +|----------|--------| +| Mikrokontroler | ESP32 DevKit V1 | +| RFID | RC522 13.56 MHz | +| Wyświetlacz | OLED SSD1306 128x64 | +| Zasilanie | 18650 3.7V lub 5V DC | +| Pasywa | 2× Rezystor 220Ω, Przekaźnik 5V | + +--- + +# 🔌 Pinout + +| Moduł | Pin | ESP32 GPIO | Opis | +|--------|------|-------------|------| +| RC522 | VCC | 3.3V | ⚠ NIE 5V | +| RC522 | RST | GPIO 4 | Reset | +| RC522 | GND | GND | Masa | +| RC522 | MISO | GPIO 19 | SPI | +| RC522 | MOSI | GPIO 23 | SPI | +| RC522 | SCK | GPIO 18 | SPI | +| RC522 | SDA | GPIO 5 | SPI CS | +| OLED | SDA | GPIO 21 | I2C | +| OLED | SCL | GPIO 22 | I2C | +| Przekaźnik | IN | GPIO 13 | Sterowanie | +| LED Zielona | + | GPIO 12 | 220Ω | +| LED Czerwona | + | GPIO 14 | | + +--- + +--- + +# 📝 Kod ESPHome (`czytnik-brama.yaml`) + +```yaml +esphome: + name: terminal-brama + platformio_options: + board_build.f_cpu: 80000000L + + esp32: + board: esp32dev + framework: + type: arduino + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + power_save_mode: LIGHT + fast_connect: true + + api: + reboot_timeout: 0s + encryption: + key: !secret api_encryption_key + + ota: + - platform: esphome + password: !secret ota_password + + logger: + level: INFO + + i2c: + sda: 21 + scl: 22 + + spi: + clk_pin: 18 + mosi_pin: 23 + miso_pin: 19 + + rc522_spi: + cs_pin: 5 + reset_pin: 4 + update_interval: 500ms + on_tag: + then: + - homeassistant.tag_scanned: !lambda 'return x;' + + switch: + - platform: gpio + pin: 13 + id: przekaznik_bramy + restore_mode: ALWAYS_OFF + + +Automatyzacja Home Assistant (automations.yaml) +alias: "Terminal Bramy - Obsługa" +trigger: + - platform: event + event_type: tag_scanned + + action: + - variables: + v_nazwa: "{{ trigger.event.data.name }}" + + - choose: + - conditions: + - condition: template + value_template: "{{ v_nazwa is not none and 'Legitymacja' in v_nazwa }}" + sequence: + - action: input_text.set_value + target: + entity_id: input_text.terminal_status + data: + value: "{{ v_nazwa | replace('Legitymacja ', '') | trim }}" + - action: switch.turn_on + target: + entity_id: switch.terminal_brama_przekaznik_bramy + + - conditions: + - condition: template + value_template: "{{ v_nazwa is none or 'Legitymacja' not in v_nazwa }}" + sequence: + - action: input_text.set_value + target: + entity_id: input_text.terminal_status + data: + value: "Brak Uprawnień" + + mode: restart + +#🔒 Bezpieczeństwo +🔐 Szyfrowanie AES-128 (Native API) +📴 Fail-safe (brama domyślnie zamknięta) +🌐 Zalecane HTTPS dla zdalnego HA +🔋 Optymalizacja +Underclocking 80 MHz +WiFi Light Sleep +OLED auto-off po 60 s +Lokalny reset ekranu po 3 s +#📄 Licencja +Projekt udostępniony na licencji MIT. +Możesz używać w projektach prywatnych i komercyjnych. \ No newline at end of file