subgraph FLIP["Flipper Zero — Specter.fap"]
  A["ST25R3916 NFC chip<br/>external-field detector"] --> S["Sampler thread<br/>~500 samples/s"]
  S --> M["<b>How much?</b><br/>carrier duty-cycle<br/>peak · average · contacts"]
  S --> C["<b>What rhythm?</b><br/>burst / gap edge timing<br/>period · jitter"]
  M --> G["EMF gauge · waveform<br/>geiger clicks · LED · vibe"]
  M --> V["Survey verdict<br/>CLEAN / TRACE / ACTIVE"]
  C --> K["Emitter class<br/>CONTINUOUS / POLLING /<br/>INTERMITTENT + pulse train"]
  V --> L["📖 SD logbook"]
  K --> L
end

**Quanto → intensità.** Su una finestra breve Specter misura *in quale frazione di tempo* un carrier è
presente e la leviga nel **FIELD %**. Un lettore posizionato proprio sopra il Flipper fa schizzare il misuratore;
uno più debole o più lontano lo sposta appena. Questo guida l'ago, la parola di prossimità e la frequenza dei click.

**Quale ritmo → identità.** Separatamente, ogni transizione di quel bit viene cronometrata. Un lettore che si risveglia per
20 ms ogni 200 ms produce un pattern burst/gap con quasi nessun jitter, perché il suo ciclo di polling è
guidato da una macchina a stati temporizzata a cristallo. Il movimento della mano e il rumore RF non sono così stabili. Quella
differenza è ciò che separa **POLLING** da **INTERMITTENT**.

### I livelli decisionali sono testati su un computer reale

I punti in cui Specter trasforma i numeri in una *affermazione* — "questo è un lettore in polling", "questa stanza è
pulita", "questo è ciò che l'ago dovrebbe leggere" — sono puro C senza dipendenze hardware, e sono
fissati da test host anziché scoperti sul dispositivo:```bash
make -C test     # 300 checks: classifier, verdict, meter scaling, presence

Il file `.fap` finisce in `dist/specter.fap`; `ufbt launch` lo copia in `apps/NFC/` e lo avvia per te.

> Le icone in `icons/`, gli screenshot e il banner in `images/` sono generati — rigenerali con
> `python3 tools_gen_icons.py`, `python3 tools_gen_mockups.py` e `python3 tools_gen_banner.py` (richiede `pillow`).

---

## 🎮 Come si usa

**Una scansione, dall'inizio alla fine:**

1. Avvia **Specter**. Nella schermata **Sweep**, premi **LEFT** e resta fermo per 3 secondi per
   calibrare sul rumore di fondo della stanza.
2. Tieni il Flipper piatto e muovilo **lentamente** sopra la cosa che stai controllando — un terminale
   per carte, un lettore di porte, la parte inferiore della fessura di un ATM, un pacco, una scrivania.
   - **Forma d'onda piatta / silenziosa** → nessun lettore attivo nel raggio d'azione.
   - **L'ago sale, i click accelerano** → ti stai avvicinando a un emettitore. Continua verso il picco.
   - **`● ACTIVE READER` + bordo d'allarme** → un lettore attivo è proprio qui.
3. Trovato qualcosa? Esci e apri **Fingerprint**. Tieni il Flipper fermo contro di esso e lascia che la
   cadenza si stabilizzi — qualche secondo di solito basta. Premi **OK** per salvare il risultato.
4. Vuoi invece bonificare un'intera stanza? Apri **Site Survey**, percorri lo spazio finché la barra non
   si riempie e leggi il verdetto.
5. Stai lasciando l'area? Metti il Flipper in **Watch Mode** e resterà di guardia, svegliandosi e
   suonando se compare un lettore mentre sei via.
6. Controlla il **Logbook** per tutto ciò che hai salvato, con timestamp — oppure estrai `logbook.csv`
   dalla scheda e importalo in un foglio di calcolo.

> 💡 Scansiona prima un lettore sicuro (il tuo telefono che fa NFC, o un terminale contactless di cui ti
> fidi) per vedere come appare un campo forte e legittimo sul misuratore — e cosa legge la sua impronta.
> Poi vai a caccia.

### Comandi

| Schermata | Tasto | Azione |
|---|---|---|
| **Sweep** | `OK` | Azzera picco / contatti |
| | `hold OK` | Registra la lettura corrente |
| | `LEFT` | Calibra il rumore di fondo (3 s) |
| **Fingerprint** | `OK` | Salva il risultato nel logbook |
| | `hold OK` | Riavvia la misurazione |
| **Site Survey** | `OK` | Esegui di nuovo la survey |
| **Watch Mode** | `OK` | Riarma (azzera conteggio e orologio) |
| *ovunque* | `BACK` | Torna su di un livello |

---

## 🔬 Limiti onesti

- **Solo 13,56 MHz (HF).** Specter rileva la **banda NFC** — quella usata dagli skimmer per pagamenti
  contactless, dalla maggior parte dei lettori di accesso moderni, dai lettori per trasporti e hotel.
  **Non** riesce a vedere i lettori a **125 kHz (LF)** (i vecchi pannelli per porte HID Prox / EM4100);
  il percorso LF del Flipper non ha un bit equivalente di rilevamento del campo.
- **Rileva la *portante* di un lettore, non ciò che legge.** Specter ti dice *che un lettore attivo è
  qui, all'incirca quanto è vicino e con che ritmo interroga* — non decodifica, identifica o cattura
  nulla di ciò che fa il lettore.
- **L'intensità è relativa, non calibrata.** `FIELD %` e le parole di prossimità sono una guida
  comparativa "più caldo / più freddo" per la scansione, non una distanza misurata in cm. È una lettura
  *riscalata* del duty-cycle della portante rispetto a una banda di polling tipica (vedi [Leggere il
  misuratore](#-reading-the-meter--fixed-in-23)); un lettore che interroga in modo insolitamente rado
  leggerà più basso alla stessa distanza, e uno in modalità onda continua andrà a fondo scala da più
  lontano.
- **Il misuratore arriva al massimo.** `MAX` significa che la portante è attiva tanto quanto questo
  lettore la tiene mai attiva — oltre quel punto, avvicinarsi davvero non può produrre un numero più
  grande. Usa il peak-hold `PK` per confrontare invece le posizioni.
- **La cadenza si risolve a ~2 ms.** Questo è il periodo di campionamento. Le tempistiche vicine a
  questo valore sono mostrate con un **`~`** e la confidenza viene ridotta di conseguenza — Specter
  preferisce segnalare il proprio limite di risoluzione piuttosto che citare un numero dall'aspetto
  preciso su cui non può garantire.
- **`CLEAN` significa pulito alla sensibilità che hai scelto.** Uno skimmer dormiente che si sveglia
  solo a un tap reale, o uno schermato, resta invisibile a *qualsiasi* soglia. L'assenza di una lettura
  non è garanzia di assenza.
- **Una radio alla volta.** Specter prende il controllo del chip NFC durante la scansione, quindi chiudi
  prima qualsiasi altra app NFC (dirà *NFC unavailable* se qualcos'altro tiene occupata la radio).

---

## ⚖️ Legale ed etico

Specter è uno strumento **difensivo, in sola ascolto** — **non trasmette** mai, non alimenta mai un
campo, non tocca mai il lettore. Usalo per scansionare la **tua** area POS, porta, scrivania o oggetti
personali, o hardware che sei **esplicitamente autorizzato** a valutare. Sei responsabile di come lo usi.
Conosci le leggi locali.

---

## 🗺️ Roadmap

- [x] Persistere sensibilità / suono / vibrazione / LED tra i riavvii
- [x] "Logbook" dei rilevamenti con timestamp sulla scheda SD
- [x] Scansione in background con lo schermo spento — *modalità stealth*
- [x] Soglia regolabile per un controllo più fine del range — *auto-calibrazione + sensibilità personalizzata*
- [x] Impronta di un emettitore tramite la sua cadenza di polling
- [x] Site survey a tempo con verdetto sulla stanza
- [x] Esportare il logbook come CSV per il reporting — *scritto in tempo reale insieme al .txt*
- [x] Modalità watch a lungo termine non presidiata con allarme wake-on-detection
- [x] Far usare al misuratore tutto il suo range contro lettori reali in polling
- [x] Freccia di tendenza più caldo/più freddo durante la caccia
- [ ] Studiare un rilevamento di lettori LF (125 kHz) basato su bobina come modalità separata
- [ ] Filtro del logbook per tipo sul dispositivo

---

## 🗂️ Struttura del progetto```
Specter-FlipperZero/
├── application.fam               # Flipper app manifest (category: NFC)
├── specter.c / specter_i.h       # app entry, wiring, alert feedback, stealth
├── helpers/
│   ├── field_detector.{c,h}      # worker thread: samples the field-present bit,
│   │                             #   duty-cycle + edge timing + calibration
│   ├── emitter_classify.{c,h}    # pure: cadence -> CONTINUOUS/POLLING/INTERMITTENT
│   ├── survey_verdict.{c,h}      # pure: survey stats -> CLEAN/TRACE/ACTIVE
│   ├── field_scale.{c,h}         # pure: raw carrier duty -> full-scale meter
│   ├── present_hold.h            # pure: debounce presence across poll gaps
│   ├── specter_settings.{c,h}    # persisted settings (saved_struct)
│   └── specter_log.{c,h}         # SD logbook, RTC-stamped .txt + live .csv
├── views/
│   ├── sweep_view.{c,h}          # the EMF gauge / waveform / alarm screen
│   ├── fingerprint_view.{c,h}    # classification card + pulse-train trace
│   ├── survey_view.{c,h}         # progress + verdict card
│   └── watch_view.{c,h}          # unattended guard: clock + count + alarm
├── scenes/                       # scene-manager navigation
├── test/                         # host tests for the pure decision layers
├── icons/                        # 1-bit Flipper icons (generated)
├── images/                       # banner + screen mockups (generated)
└── tools_gen_*.py                # regenerate icons / mockups / banner

> L'anteprima social è l'unico asset che GitHub non riesce a recuperare dal repo — deve
> essere caricata una volta manualmente in **Settings → Social preview**. È ciò che viene renderizzato
> quando il repo viene condiviso su Slack, X, LinkedIn o Discord.

---

## 🙏 Crediti

- Creato da **[at0m-b0mb](https://github.com/at0m-b0mb)**.
- Parte di una famiglia di strumenti di sicurezza per Flipper: **[Argus](https://github.com/at0m-b0mb/Argus-FlipperZero)** (watchdog Wi-Fi deauth / evil-twin), **[GhostTag](https://github.com/at0m-b0mb/GhostTag-FlipperZero)** (hunter BLE anti-stalking) e **[Cerberus](https://github.com/at0m-b0mb/flipper-cerberus)** (watchdog RF Sub-GHz).
- Basato sul [firmware Flipper Zero](https://github.com/flipperdevices/flipperzero-firmware) NFC HAL (rilevamento campo `furi_hal_nfc`) + [ufbt](https://github.com/flipperdevices/flipperzero-ufbt).

## 📄 Licenza

[MIT](https://github.com/at0m-b0mb/specter-flipperzero/blob/main/LICENSE) © 2026 at0m-b0mb