What is Safi
Safi (صافي, "pure") is a self-contained Quran audio player built on the ESP32-S3 microcontroller. It plays recitations from a local SD card library and from internet radio stations, shows an Arabic-first interface on a small color display, and is controlled three ways: physically (a rotary encoder and a touch pad), by tapping NFC cards, and from any browser through a secure web dashboard served by the device itself.
There is no phone app to install, no cloud account, and no external service that can disappear. Everything runs on the device.
The feature set
| Feature | What it means in practice |
|---|---|
| SD card library | Folders of reciters and surahs are scanned automatically and browsable from the device and the dashboard |
| Internet radio | MP3, AAC, and HE-AAC streams with station presets, live title metadata, and automatic reconnection |
| Resume | Playback position survives stops, reboots, and power loss; optional auto-resume on boot |
| NFC cards | Any NTAG card can be bound to a surah, a reciter, or a station; tapping it starts playback |
| Arabic display | A 128x160 TFT running LVGL 9 with real Arabic shaping, so surah names render as connected script |
| Web dashboard | Eight pages of control served over HTTPS from the device: playback, library, radio, favorites, NFC, scheduler, settings, updates |
| Scheduler | Time-based playback with clock synchronization over SNTP |
| Favorites | Star surahs and stations, with play counts |
| Battery operation | Charge-aware power management with a safe low-battery shutdown that saves your position |
| OTA updates | Firmware updates from the dashboard with automatic rollback if the new version fails to boot |
The hardware at a glance
Safi targets the ESP32-S3-N16R8 module: a dual-core 240 MHz microcontroller with 16 MB of flash and 8 MB of PSRAM. Around it sit a MAX98357A I2S amplifier, an ST7735S TFT, a microSD slot, a PN532 NFC reader, a rotary encoder, a capacitive touch pad, and a TP4056 battery charger. The full parts list is in the bill of materials and the wiring is in wiring and assembly.
How this documentation is organized
The site has two halves, and they deliberately overlap in coverage but not in depth:
- The User Guide (you are here) explains how to build the device and use every feature. It assumes no programming knowledge.
- The Developer Masterclass explains how every subsystem is implemented and why it is designed the way it is, including the failures that shaped the design. It is written to be readable by a beginner embedded developer while staying useful to an expert.
If you just want a working device, start with the Quickstart. If you want to understand or modify the firmware, start with the architecture tour.
Project status
The firmware is feature-complete and hardware-verified: WiFi, TLS, the dashboard, MP3 and AAC streaming, the Arabic UI, and the OTA update cycle have all been exercised on real hardware with measured, realtime results. The source, issue tracker, and releases live on GitHub.