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

**양 → 강도.** 짧은 시간 창 동안 Specter는 캐리어가 존재하는 *시간 비율*을 측정하여 이를 **FIELD %**로 평활화합니다. Flipper 바로 위에 있는 리더는 미터를 끝까지 올리고, 더 약하거나 더 먼 리더는 살짝 움직입니다. 이것이 바늘, 근접 단어, 클릭률을 결정합니다.

**리듬 → 정체성.** 별도로, 그 비트의 모든 전이가 타이밍으로 측정됩니다. 200ms마다 20ms 동안 깨어나는 리더는 거의 지터가 없는 버스트/갭 패턴을 만들어냅니다. 폴링 루프가 크리스털 타이밍 상태 머신에 의해 구동되기 때문입니다. 손 움직임과 RF 노이즈는 그렇게 꾸준하지 않습니다. 그 차이가 **POLLING**과 **INTERMITTENT**를 구분합니다.

### 결정 레이어는 실제 컴퓨터에서 테스트된다

Specter가 숫자를 *주장* — "이것은 폴링 리더다", "이 방은 깨끗하다", "이것이 바늘이 읽어야 할 값이다" — 으로 변환하는 부분은 하드웨어 의존성이 없는 순수 C로 작성되어 있으며, 장치에서 발견되는 것이 아니라 호스트 테스트로 확정됩니다.```bash
make -C test     # 300 checks: classifier, verdict, meter scaling, presence

`.fap` 파일은 `dist/specter.fap`에 생성되며, `ufbt launch`가 `apps/NFC/`로 복사해 바로 실행해 줍니다.

> `icons/`의 아이콘, `images/`의 스크린샷과 배너는 생성된 파일입니다. 다음 명령으로 재생성하세요:
> `python3 tools_gen_icons.py`, `python3 tools_gen_mockups.py`, `python3 tools_gen_banner.py` (`pillow` 필요).

---

## 🎮 사용하기

**처음부터 끝까지 스윕하기:**

1. **Specter**를 실행하세요. **Sweep** 화면에서 **LEFT**를 누르고 3초 동안 가만히 있어
   방의 노이즈 플로어에 보정합니다.
2. Flipper를 평평하게 잡고 확인하려는 대상 위를 **천천히** 움직이세요 — 카드 단말기,
   출입문 리더기, ATM 하단 가장자리, 소포, 책상 등.
   - **조용한 / 평평한 파형** → 범위 내 활성 리더기 없음.
   - **바늘이 올라가고 클릭이 빨라짐** → 이미터에 접근 중입니다. 피크(peak)를 향해 계속 이동하세요.
   - **`● ACTIVE READER` + 알람 테두리** → 활성 리더기가 바로 여기 있습니다.
3. 뭔가 찾았나요? 뒤로 나가 **Fingerprint**를 여세요. Flipper를 그 위에 고정하고
   주기가 안정될 때까지 기다리세요 — 보통 몇 초면 충분합니다. **OK**를 눌러 탐지 결과를 저장하세요.
4. 대신 방 전체를 점검할 건가요? **Site Survey**를 열고 막대가 가득 찰 때까지 공간을 걸어다니며
   결과를 확인하세요.
5. 해당 구역을 떠날 건가요? Flipper를 **Watch Mode**로 전환하면 감시를 서게 됩니다. 자리를 비운 사이
   리더기가 나타나면 깨어나 알림을 울립니다.
6. 저장된 모든 항목은 **Logbook**에서 타임스탬프와 함께 확인하세요 — 또는 SD 카드에서 `logbook.csv`를 꺼내
   스프레드시트로 가져오세요.

> 💡 먼저 정상 동작이 확인된 리더기를 스윕해 보세요 (NFC를 켠 자신의 휴대폰이나 신뢰할 수 있는 비접촉 단말기).
> 그러면 미터에서 강하고 정상적인 필드가 어떻게 보이는지, 그리고 지문이 어떻게 읽히는지 알 수 있습니다. 그런 다음
> 탐색을 시작하세요.

### 컨트롤

| 화면 | 키 | 동작 |
|---|---|---|
| **Sweep** | `OK` | 피크 / 접촉 초기화 |
| | `hold OK` | 현재 측정값 기록 |
| | `LEFT` | 노이즈 플로어 보정 (3초) |
| **Fingerprint** | `OK` | 탐지 결과를 로그북에 저장 |
| | `hold OK` | 측정 다시 시작 |
| **Site Survey** | `OK` | 서베이 다시 실행 |
| **Watch Mode** | `OK` | 재무장 (카운트와 타이머 초기화) |
| *어디서나* | `BACK` | 한 단계 위로 |

---

## 🔬 솔직한 한계

- **13.56MHz(HF) 전용.** Specter는 **NFC 대역**을 감지합니다 — 비접촉 결제 스키머,
  대부분의 최신 출입 통제 리더기, 교통·호텔 리더기가 사용하는 대역입니다. **125kHz(LF)** 리더기는 볼 수 **없습니다**
  (구형 HID Prox / EM4100 출입문 패널). Flipper의 LF 경로에는 이에 상응하는 필드 감지 비트가 없습니다.
- **리더기가 읽는 내용이 아니라 리더기의 *캐리어*를 감지합니다.** Specter는 *활성 리더기가 여기 있고,
  대략 얼마나 가까운지, 어떤 주기로 폴링하는지*를 알려줍니다 — 리더기가 수행하는 어떤 것도 디코딩, 식별, 캡처하지 않습니다.
- **강도는 상대적이며 보정되지 않았습니다.** `FIELD %`와 근접도 표현은 비교식 "가까움 /
  멀어짐" 가이드이지, cm 단위로 측정된 거리가 아닙니다. 일반적인 폴링 대역 대비 캐리어
  듀티 사이클을 *스케일*로 나타낸 값입니다 ([미터 읽기](#-reading-the-meter--fixed-in-23) 참조).
  폴링 주기가 비정상적으로 드문 리더기는 같은 거리에서 더 낮게 표시되고, 연속파 모드의
  리더기는 더 멀리서도 최대치를 찍습니다.
- **미터는 최대치까지 올라갑니다.** `MAX`는 캐리어가 이 리더기가 유지할 수 있는 최대 수준까지 올라갔다는 뜻입니다 —
  그 지점을 지나면 더 가까이 다가가도 더 큰 숫자가 나오지 않습니다. 위치를 비교하려면 `PK` 피크 홀드를
  대신 사용하세요.
- **주기 해상도는 약 2ms입니다.** 이것이 샘플링 주기입니다. 이에 가까운 타이밍은
  **`~`** 로 표시되며 신뢰도도 그에 따라 할인됩니다. Specter는 보증할 수 없는 정밀해 보이는 숫자를
  제시하기보다 자신의 해상도 하한을 스스로 표시하는 쪽을 선택합니다.
- **`CLEAN`은 선택한 감도에서 깨끗하다는 뜻입니다.** 실제 접촉할 때만 깨어나는 휴면 스키머나
  차폐된 스키머는 *어떤* 임계값에서도 보이지 않습니다. 측정값이 없다고 해서 실제로 없다는 보장은 아닙니다.
- **한 번에 하나의 라디오만 사용합니다.** Specter는 스윕하는 동안 NFC 칩을 점유하므로 다른 NFC 앱을 먼저 모두 닫으세요.
  (다른 앱이 라디오를 점유하고 있으면 *NFC를 사용할 수 없음*이라고 표시됩니다).

---

## ⚖️ 법률 및 윤리

Specter는 **방어용, 청취 전용** 도구입니다 — **절대 전송하지 않으며**, 필드를 생성하지도 않고, 리더기를 만지지도
않습니다. **자신의** POS 영역, 출입문, 책상, 소지품 또는 명시적으로 평가할 권한이 있는 하드웨어를
스윕하는 데 사용하세요. 사용 방법에 대한 책임은 당신에게 있습니다. 현지 법률을 숙지하세요.

---

## 🗺️ 로드맵

- [x] 재부팅 후에도 감도 / 사운드 / 진동 / LED 설정 유지
- [x] SD 카드에 타임스탬프와 함께 탐지 "로그북" 저장
- [x] 화면을 끈 상태에서의 백그라운드 스윕 — *스텔스 모드*
- [x] 더 세밀한 범위 제어를 위한 조절 가능한 임계값 — *자동 보정 + 사용자 감도*
- [x] 폴링 주기로 이미터 지문 식별
- [x] 공간 판정을 내리는 타이머 기반 사이트 서베이
- [x] 보고용 로그북 CSV 내보내기 — *.txt와 함께 실시간으로 기록됨*
- [x] 탐지 시 깨어나는 알람이 있는 장기 무인 감시 모드
- [x] 실제 폴링 리더기에 대해 미터가 전체 범위를 사용하도록 개선
- [x] 탐색 중 가까움/멀어짐 추세 화살표
- [ ] LF(125kHz) 코일 기반 리더기 감지를 별도 모드로 조사
- [ ] 기기 내 로그북 유형 필터링

---

## 🗂️ 프로젝트 구조```
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