esp32-fpm10a-versi-3v3

Imported from slice-code/finger (esp32-fpm10a-versi-3v3/AGENTS.md). Install upstream with npx skills add slice-code/finger --skill esp32-fpm10a-versi-3v3. Copyright stays with the author.

AGENTS.md — ESP32 FPM10A (folder esp32-fpm10a-versi-3v3)

Firmware baku untuk board 3V3 dan 5V. Aturan proyek umum ada di /AGENTS.md root repo; dokumen ini khusus sketch di folder ini + changelog perilaku yang wajib dihormati saat edit.

Compile / upload (tidak berubah setelah pecah modul):

arduino-cli compile --fqbn esp32:esp32:esp32:PartitionScheme=no_ota_lfs \
  /home/gugus/Documents/Project/pjtki/arduino/esp32-fpm10a-versi-3v3/esp32-fpm10a-versi-3v3.ino
arduino-cli upload --fqbn esp32:esp32:esp32:PartitionScheme=no_ota_lfs --port /dev/ttyUSB0 \
  /home/gugus/Documents/Project/pjtki/arduino/esp32-fpm10a-versi-3v3/esp32-fpm10a-versi-3v3.ino

Arduino CLI/IDE menggabungkan semua *.ino di folder ini (file utama dulu, lalu alfabet). setup()/loop() harus di m12/m13 agar simbol modul sudah terdefinisi.

Struktur file

Bedakan board hanya dengan nama BLE (sebelum #include "ble_handler.h" di file utama):

• 3V3: default PJTKI-Finger (hapus override)
• 5V: #define BLE_DEVICE_NAME "PJTKI-Finger-5V"

Konstanta finger/gate/LED (BAKU — jangan tuning)

Jangan menyalin timing folder esp32-fpm10a-versi-5v/ (LED stuck). Jangan LEDcontrol(true) di irUpdateGate() — hanya wake LCD; LED sensor hanya setelah gate terbuka + verifikasi OK.

Changelog perilaku (2026-08-26) — wajib dihormati

1. Hemat RAM → LittleFS

• Absensi: tidak pakai array RAM besar → /attendance.jsonl (streaming).
• Meta finger: tidak pakai fpDB[100] → /fpmeta/<id>.json + cache 1 slot; hex di /fphex/<id>.hex.
• Payload BLE besar: heap malloc/free (bukan BSS tetap), proses di loop.
• HTTP API: client plain HTTP bersama; hindari WiFiClientSecure di path absensi (hemat heap).
• LCD footer kanan atas: sisa heap "%lu kB" (ESP.getFreeHeap()/1024), refresh bersama jam.

2. Autoscan responsif

• Gate buka: IR_CONFIRM 40 ms; T-OUT HIGH tidak ditahan IR_REOPEN_MIN (user 2026-08-27).
• Bukan timing 5V lama 15/200 + LED_WARMUP 30 (LED stuck). LED_WARMUP tetap 120. Jangan LEDcontrol di irUpdateGate().
• getImage NOFINGER + T-OUT masih HIGH → jangan tutup gate / matikan LED (sama enroll waitFinger).
• LED ON → delay(LED_WARMUP_MS) lalu getImage di iterasi yang sama (bukan break + cooldown loop).
• Gate timeout saat jari masih di kaca → cooldown pendek (~200 ms), bukan 2.5 s penuh.
• Angkat jari saat cooldown → cooldown dibatalkan.
• LED auto-off jangan set fingerMustRelease (itu mengunci scan tanpa hasil).
• Setelah hasil (match/nomatch): deteksi angkat→tempel ulang membuka kunci; jangan IR_REOPEN_MIN menahan tempel ulang setelah hold hasil.
• Search autoscan: timeout FP_AUTOSCAN_SEARCH_MS (2500) — jangan biarkan LCD “SCANNING” sampai 8 s.
• Gagal image2Tz/search → tampilkan GAGAL (bukan lcdShowIdle diam-diam). Retry capture 1× jika T-OUT masih HIGH.
• Pakai fpImage2Tz() (timeout perintah) bukan finger.image2Tz() library yang bisa hang.

3. Setelah hapus finger (BLE delete / DELETE_EMP)

• Pause autoscan, matikan LED, flush UART, deleteModel. Jangan lcdShowIdle() / autoscan sebelum hapus server selesai.
• LCD HAPUS: Device → Sensor → Storage → Server (tunggu app unregisterFinger + perintah DELETE_DONE). Baru idle + autoscan langsung (tanpa delay 900 ms). Timeout 12 s jika app tidak ack.
• Saat deleteHoldUi: jangan buka/timeout gate di irUpdateGate() (timeout 3s tanpa getImage → cooldown 2.5s → sentuhan pertama mati).
• Setelah selesai: sensorResumeAfterDelete() — ping getTemplateCount (resync UART) + sensorResumeIdle. Jika T-OUT masih HIGH, fingerMustRelease (angkat dulu). Jangan ubah konstanta gate/LED.

4. Setelah enroll sukses

• Arsip hex inline di akhir enroll (UpChar saat autoscan masih off); defer ke loop hanya jika gagal.
• Quiet post-enroll singkat (~400 ms), cooldown scan ~250 ms, tanpa gate cooldown 800 ms.
• Batas tunggu jari nempel post-enroll ~1.5 s (bukan 5 s).
• Setelah UpChar deferred (jika ada): sensorResumeIdle("post-enroll-hex").
• UI: selama jeda tampilkan “Tunggu / Angkat jari” — jangan tampilkan BERHASIL dulu.
• BERHASIL hanya lewat enrollPresentSuccessThenIdle() saat autoscan benar-benar resume, lalu idle.
• Handler BLE enroll sukses: jangan lcdShowIdle() segera (itu menghapus layar Tunggu).
• Hex ke server: ESP queueRegisterUpload + syncRequestNow() setelah enrollActive=false (bukan HP GET_TEMPLATE). Worker yang bangun saat enroll masih aktif wajib defer + kick ulang — jangan menunggu uploadIntervalMinutes.

5. Autoscan vs CPMI

• Autoscan absensi harian hanya KRY-*.
• CPMI kena autoscan → LCD arahkan tab Izin; tidak tulis absensi harian.
• Izin keluar/masuk: app POST /api/finger/izin/scan setelah identify BLE.

6. BLE / LittleFS

• Callback NimBLE: set flag + buffer saja; jangan buka LittleFS di callback.
• bleEnsureAdvertising() cooldown ≥2 s; supervision timeout tetap ~4 s (jangan turunkan ke 1 s).
• Set ledOn=true hanya jika LEDcontrol(true)==FINGERPRINT_OK; cleanup selalu ledOn=false.

7. Purge lokal MD / sudah terbang (2026-08-27)

• syncWorker GET /api/finger/arduino/inactive (bukan di loop).
• Hapus hanya sensor + LittleFS. Jangan DELETE template server.
• stalePurgeService() di loop: satu slot per iterasi, LCD BERSIH, tanpa deleteHoldUi/ack server.
• Interval: uploadIntervalMinutes + cek pertama ~12 menit setelah WiFi. SYNC_NOW juga memicu.
• Jangan restore (PUT_TEMPLATE) ID yang ada di daftar stale.

Storage LittleFS (ringkas)

Partisi: partitions.csv → littlefs. Jangan erase-flash untuk update firmware biasa. Jangan ganti LittleFS.h → SPIFFS.

Di mana edit apa

Jangan lakukan

1. Upload sketch folder esp32-fpm10a-versi-5v ke produksi.
2. Turunkan debounce/warmup/loop delay “biar cepat”.
3. Hapus fingerConfirm, gate T-OUT, atau verifikasi ledOn.
4. WiFi.mode(WIFI_OFF) saat deteksi sensor di ESP32.
5. Operasi jaringan blocking di loop() / doAutoScan().
6. Gabungkan kembali semua logika ke satu .ino tanpa alasan — pecahan modul untuk maintenance.