RFID Access Control (ESP32-S3)

A standalone RFID access controller: ESP32-S3 + PN532 (hardware SPI) + 16x2 I2C LCD + a LittleFS-backed fixed-width binary user database, administered from a Python CLI (scripted or interactive shell) over serial. Up to 70000 users, PSRAM-backed, with per-record and whole-database CRC32 integrity checks.

Full docs – wiring, protocol spec, CLI reference, troubleshooting, project structure live on the wiki.

This README only covers getting it cloned, flashed, and running.

Get the project

Either clone the repository:

git clone https://github.com/Hyacinthe-primus/RFID_Access_Control.git

or download the latest stable release from the Releases page.

Arduino requirement: the sketch folder name must match its .ino filename exactly. This repo is already named RFID_Access_Control to match RFID_Access_Control.ino. If you download a release ZIP, extract it and ensure the folder is named RFID_Access_Control before opening it in the Arduino IDE. Likewise, if you rename the cloned repository (or download a ZIP that extracts to something like RFID_Access_Control-main), rename it back or the sketch will not compile.

Firmware

1. Open RFID_Access_Control.ino in Arduino IDE 2.x.
2. Tools > Board -> ESP32S3 Dev Module.
3. Install libraries: Adafruit PN532, LiquidCrystal I2C, ArduinoJson (v7.x).
4. Board options: USB CDC On Boot: Disabled, Flash Size: 16MB, Partition Scheme: Custom (uses partitions.csv), PSRAM: OPI PSRAM.
5. Sketch > Upload.

Wiring diagram and pinout: see the wiki.

Python CLI

cd python_cli
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt

python cli.py                 # no subcommand -> interactive shell
python cli.py status          # or run one-shot scripted commands

Full command reference, batch import/export, and the interactive shell: see the wiki.

Tests

python -m pytest tests/ -v

137 tests, run from the repo root, no hardware required.

License

MIT see LICENSE.md.