Update Readme.md
This commit is contained in:
246
Readme.md
246
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 📝 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.
|
||||
# 💻 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.
|
||||
Reference in New Issue
Block a user