Skip to main content

Quickstart

This page takes you from an assembled device to playing a recitation. If your hardware is not built yet, do the bill of materials and wiring first.

What you need​

  • An assembled Safi (or at minimum an ESP32-S3-N16R8 board for a dashboard-only tryout)
  • A USB-C cable to your computer
  • A microSD card, 8 GB or larger, FAT32 formatted
  • Quran audio files as MP3, organized per reciter
  • A 2.4 GHz WiFi network (the ESP32-S3 radio does not support 5 GHz)

Step 1: Flash the firmware​

Download the latest release assets from GitHub Releases, then flash them with esptool:

pip install esptool
python -m esptool --chip esp32s3 -p /dev/ttyACM0 -b 460800 write_flash \
  0x0      bootloader.bin \
  0x8000   partition-table.bin \
  0x1a000  ota_data_initial.bin \
  0x20000  Safi.bin \
  0x920000 storage.bin

On Windows the port is COMx instead of /dev/ttyACM0. The board enumerates as a USB serial device natively, no UART adapter is needed.

If you prefer building from source, follow developer getting started.

Step 2: Prepare the SD card​

Create one folder per reciter, and name the audio files with a three digit surah number prefix:

/
├── Al-Husary/
│   ├── 001.mp3
│   ├── 002.mp3
│   └── ...
├── Al-Minshawi/
│   ├── 001.mp3
│   └── ...
└── Abdul-Basit/
    └── ...

Anything after the number is ignored by the scanner, so 001_Al-Fatihah.mp3 also works. The repository ships a checker that validates and fixes a card layout for you:

./tools/prepare_sd_card_data.sh --check /path/to/mounted/card

Full details, including WAV support and the surah name display logic, are in SD library.

Step 3: First boot​

  1. Insert the SD card and connect power.
  2. The splash screen shows the Safi mark, the firmware version, and a boot report. On a fully wired device every line is green; missing peripherals are listed in red but the device keeps working without them.
  3. The screen settles on the idle clock. The clock shows --:-- until the first successful time sync, which needs WiFi.

Step 4: Connect WiFi​

Safi tries three provisioning paths in order; use whichever fits you. All three are described in depth in first boot and WiFi.

  1. Saved credentials from a previous session, stored encrypted in flash.
  2. Credentials baked at build time (developers): CONFIG_SAFI_WIFI_SSID and CONFIG_SAFI_WIFI_PASSWORD.
  3. SoftAP provisioning: with neither of the above, the device opens a Safi-XXXXXX access point and the ESP SoftAP Provisioning phone app can push your WiFi credentials to it over the air, authenticated with the proof-of-possession code on the device label.

When association succeeds the WiFi icon appears in the status bar and the device IP address is shown on the idle screen and printed on the serial console.

Step 5: Open the dashboard​

Browse to https://safi.local (the device announces this name over mDNS), or to https://<device-ip> if your network blocks mDNS. Two first-time warnings are expected:

  • Certificate warning: the device ships with a self-signed certificate. Accept it once. To install a proper certificate see HTTPS internals.
  • API token: control actions require a bearer token that the device prints on the serial console on first boot. The dashboard guide shows where to paste it.

From the Library page, pick a reciter and a surah and press play.

Step 6: Play something without the dashboard​

  • Turn the rotary encoder to change volume; press it to enter the library browser.
  • Tap the touch pad to play or pause.
  • Register an NFC card from the dashboard and tapping it will start playback directly, see NFC cards.

Where to go next​