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 → intensidade.** Em uma janela curta, o Specter mede *que fração do tempo* um carrier está
presente e suaviza isso no **FIELD %**. Um leitor posicionado bem em cima do Flipper satura o medidor;
um mais fraco ou mais distante apenas o desloca. Isso comanda a agulha, a palavra de proximidade e a taxa de cliques.

**Que ritmo → identidade.** Separadamente, cada transição desse bit é cronometrada. Um leitor que desperta por
20 ms a cada 200 ms produz um padrão de burst/gap com quase nenhum jitter, porque seu loop de polling é
controlado por uma máquina de estados temporizada por cristal. Movimento de mão e ruído de RF não são tão estáveis. Essa
diferença é o que separa **POLLING** de **INTERMITTENT**.

### As camadas de decisão são testadas em um computador real

Os pontos onde o Specter transforma números em uma *afirmação* — "este é um leitor polling", "esta sala está
limpa", "isto é o que a agulha deveria marcar" — são C puro sem dependências de hardware, e são
fixados por testes no host em vez de descobertos no dispositivo:```bash
make -C test     # 300 checks: classifier, verdict, meter scaling, presence

O `.fap` vai para `dist/specter.fap`; `ufbt launch` copia-o para `apps/NFC/` e inicia-o por ti.

> Os ícones em `icons/`, as capturas de ecrã e o banner em `images/` são gerados — regenera com
> `python3 tools_gen_icons.py`, `python3 tools_gen_mockups.py` e `python3 tools_gen_banner.py` (requer `pillow`).

---

## 🎮 Como usar

**Uma varredura, de início ao fim:**

1. Inicia o **Specter**. No ecrã **Sweep**, prime **LEFT** e mantém-te imóvel durante 3 segundos para
   calibrar ao ruído de fundo da sala.
2. Mantém o Flipper plano e move-o **lentamente** sobre o que estás a verificar — um terminal de cartões, um
   leitor de porta, a parte inferior de uma ranhura de ATM, uma encomenda, uma secretária.
   - **Forma de onda calma / plana** → nenhum leitor ativo ao alcance.
   - **Ponteiro a subir, cliques a acelerar** → estás a aproximar-te de um emissor. Continua em direção ao pico.
   - **`● ACTIVE READER` + borda de alarme** → há um leitor ativo mesmo aqui.
3. Encontraste algo? Sai e abre **Fingerprint**. Mantém o Flipper imóvel junto ao leitor e deixa a
   cadência estabilizar — alguns segundos costumam ser suficientes. Prime **OK** para guardar a descoberta.
4. Vais limpar uma sala inteira? Abre **Site Survey**, percorre o espaço até a barra encher e lê
   o veredicto.
5. Vais sair da área? Deixa o Flipper em **Watch Mode** e ele fica de guarda, acordando e soando
   se um leitor aparecer enquanto estás fora.
6. Consulta o **Logbook** para tudo o que guardaste, com data e hora — ou extrai o `logbook.csv` do cartão
   para uma folha de cálculo.

> 💡 Varre primeiro um leitor que sabes ser bom (o teu próprio telemóvel a fazer NFC, ou um terminal contactless em que confias) para
> ver como é um campo forte e legítimo no medidor — e como se lê a sua impressão digital. Depois
> vai à caça.

### Controlos

| Ecrã | Tecla | Ação |
|---|---|---|
| **Sweep** | `OK` | Reiniciar pico / contactos |
| | `hold OK` | Registar a leitura atual |
| | `LEFT` | Calibrar o ruído de fundo (3 s) |
| **Fingerprint** | `OK` | Guardar a descoberta no logbook |
| | `hold OK` | Reiniciar a medição |
| **Site Survey** | `OK` | Executar a varredura novamente |
| **Watch Mode** | `OK` | Rearmar (limpar contagem e relógio) |
| *em qualquer lugar* | `BACK` | Subir um nível |

---

## 🔬 Limitações honestas

- **Apenas 13,56 MHz (HF).** O Specter deteta a **banda NFC** — a usada por skimmers de pagamento contactless,
  pela maioria dos leitores de acesso modernos, leitores de transportes e de hotéis. **Não consegue** ver leitores de **125 kHz (LF)**
  (painéis de porta HID Prox / EM4100 mais antigos); o caminho LF do Flipper não tem um bit equivalente de deteção de campo.
- **Deteta a *portadora* de um leitor, não o que ele lê.** O Specter diz-te *que há um leitor ativo aqui,
  aproximadamente a que distância, e com que ritmo faz polling* — não descodifica, identifica nem captura nada
  do que o leitor faz.
- **A intensidade é relativa, não calibrada.** `FIELD %` e as palavras de proximidade são um guia comparativo de "mais quente /
  mais frio" para varredura, não uma distância medida em cm. É uma leitura *escalada* do duty-cycle da portadora
  em relação a uma banda de polling típica (ver [Ler o medidor](#-reading-the-meter--fixed-in-23));
  um leitor que faz polling invulgarmente esparso lerá mais baixo à mesma distância, e um em modo de onda contínua
  ficará no máximo a partir de mais longe.
- **O medidor satura.** `MAX` significa que a portadora está tão alta quanto este leitor alguma vez a mantém — a partir
  desse ponto, aproximar-te genuinamente não pode produzir um número maior. Usa o peak-hold `PK` para comparar
  posições em vez disso.
- **A cadência resolve até ~2 ms.** Esse é o período de amostragem. Temporizações próximas disso são mostradas com um
  **`~`** e a confiança é descontada em conformidade — o Specter prefere sinalizar o seu próprio limite de resolução
  do que citar um número de aparência precisa que não pode sustentar.
- **`CLEAN` significa limpo à sensibilidade que escolheste.** Um skimmer dormente que só acorda com um toque real,
  ou um que esteja blindado, permanece invisível a *qualquer* limiar. A ausência de leitura não é garantia de
  ausência.
- **Um rádio de cada vez.** O Specter assume o controlo do chip NFC enquanto faz varredura, por isso fecha primeiro qualquer outra app NFC
  (dirá *NFC unavailable* se algo mais estiver a usar o rádio).

---

## ⚖️ Legal e ético

O Specter é uma ferramenta **defensiva, apenas de escuta** — **nunca transmite**, nunca alimenta um campo, nunca toca
no leitor. Usa-o para varrer a **tua própria** área de POS, porta, secretária ou pertences, ou hardware que estejas **explicitamente
autorizado** a avaliar. És responsável pela forma como o usas. Conhece as leis locais.

---

## 🗺️ Roadmap

- [x] Persistir sensibilidade / som / vibração / LED entre reinícios
- [x] "Logbook" de deteções com data e hora para o cartão SD
- [x] Varredura em segundo plano com o ecrã desligado — *modo furtivo*
- [x] Limiar ajustável para controlo de alcance mais fino — *auto-calibração + sensibilidade personalizada*
- [x] Impressão digital de um emissor pela sua cadência de polling
- [x] Varredura de local temporizada com veredicto da sala
- [x] Exportar o logbook como CSV para relatórios — *escrito em tempo real ao lado do .txt*
- [x] Modo de vigilância prolongada sem supervisão com alarme de despertar por deteção
- [x] Fazer o medidor usar todo o seu alcance contra leitores de polling reais
- [x] Seta de tendência mais quente/mais frio durante a caça
- [ ] Investigar uma deteção de leitor baseada em bobina LF (125 kHz) como modo separado
- [ ] Filtragem do logbook no dispositivo por tipo

---

## 🗂️ Estrutura do projeto```
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

> A pré-visualização social é o único recurso que o GitHub não consegue extrair do repositório — ela
> precisa ser enviada manualmente uma vez em **Settings → Social preview**. É o que é renderizado
> quando o repositório é compartilhado no Slack, X, LinkedIn ou Discord.

---

## 🙏 Créditos

- Criado por **[at0m-b0mb](https://github.com/at0m-b0mb)**.
- Parte de uma família de ferramentas de segurança para Flipper: **[Argus](https://github.com/at0m-b0mb/Argus-FlipperZero)** (watchdog de deauth Wi-Fi / evil-twin), **[GhostTag](https://github.com/at0m-b0mb/GhostTag-FlipperZero)** (caçador anti-stalking BLE) e **[Cerberus](https://github.com/at0m-b0mb/flipper-cerberus)** (watchdog de RF Sub-GHz).
- Desenvolvido com o [firmware do Flipper Zero](https://github.com/flipperdevices/flipperzero-firmware) NFC HAL (`furi_hal_nfc` field detection) + [ufbt](https://github.com/flipperdevices/flipperzero-ufbt).

## 📄 Licença

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