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
|
Inteligentny terminal RFID do sterowania bramą z wykorzystaniem **ESP32**, **RC522**, **OLED SSD1306** oraz **Home Assistant**.
|
||||||
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ń.
|
|
||||||
|
|
||||||
## ✨ Funkcje systemu
|
---
|
||||||
|
|
||||||
* **Autoryzacja Online:** Weryfikacja kart ELS w czasie rzeczywistym poprzez API PHP i bazę danych MySQL.
|
# 🚀 Szybki start
|
||||||
* **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.
|
|
||||||
|
|
||||||
|
## Konfiguracja
|
||||||
|
W pliku `secrets.yaml` zdefiniuj:
|
||||||
|
- `wifi_ssid`
|
||||||
|
- `wifi_password`
|
||||||
|
- `api_encryption_key`
|
||||||
|
- `ota_password`
|
||||||
|
|
||||||
## 🏗 Architektura systemu
|
## Pomocnik
|
||||||
1. **ESP32**: Odczytuje unikalny numer (UID) karty zbliżeniowej.
|
Utwórz w Home Assistant encję:
|
||||||
2. **API (PHP)**: Skrypt pośredniczący, który odbiera UID od ESP32 i komunikuje się z bazą danych.
|
input_text.terminal_status
|
||||||
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.
|
|
||||||
|
|
||||||
## 🛠 Wymagania sprzętowe
|
## Instalacja
|
||||||
- **Mikrokontroler**: ESP32 (lub ESP8266 z poprawkami w kodzie).
|
1. Skompiluj projekt w ESPHome
|
||||||
- **Czytnik NFC**: MFRC522 (RC522) lub PN532.
|
2. Wgraj na ESP32
|
||||||
- **Moduł przekaźnika**: 1-kanałowy (Low/High level trigger).
|
3. System automatycznie obniży taktowanie do **80 MHz** (oszczędzanie energii)
|
||||||
- **Zasilanie**: 5V/12V (zależnie od sterownika bramy).
|
|
||||||
- **Pozostałe**: Diody LED (status), rezystory, przewody połączeniowe.
|
|
||||||
|
|
||||||
## 💻 Struktura bazy danych
|
## Tagi
|
||||||
Wykonaj poniższe zapytanie SQL, aby przygotować bazę danych:
|
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 |
|
### Warstwa sprzętowa
|
||||||
|:---:|:---:|:---|
|
- ESP32
|
||||||
| **VCC** | 3.3V | Zasilanie (UWAGA: Nie podłączać pod 5V!) |
|
- RFID RC522 (SPI)
|
||||||
| **RST** | GPIO 22 | Reset |
|
- OLED SSD1306 (I2C)
|
||||||
| **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) |
|
|
||||||
|
|
||||||
**Elementy dodatkowe:**
|
### Warstwa logiczna
|
||||||
* **Przekaźnik (Relay):** Sygnał sterujący podłączony do **GPIO 2**.
|
- Home Assistant weryfikuje tag
|
||||||
* **Dioda LED (Opcjonalnie):** GPIO 4 (sygnalizacja otwarcia).
|
- 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
|
# 💻 Wymagania sprzętowe
|
||||||
Projekt udostępniony na licencji MIT. Możesz go dowolnie modyfikować na potrzeby własnych projektów edukacyjnych.
|
|
||||||
|
| 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