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, зашкаливает на индикаторе;
более слабый или более удалённый — лишь слегка его шевелит. Это управляет стрелкой, словом близости и частотой щелчков.

**Какой ритм → идентичность.** Отдельно замеряется каждый переход этого бита. Считыватель, который просыпается
на 20 мс каждые 200 мс, создаёт паттерн «всплеск/пауза» почти без джиттера, потому что его цикл опроса
управляется конечным автоматом, синхронизированным по кварцу. Движение руки и 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 плоско и двигайте его **медленно** по проверяемому объекту — терминалу карт,
   считывателю дверей, нижней кромке банкомата, посылке, столу.
   - **Тихая / плоская волна** → активного считывателя в зоне действия нет.
   - **Стрелка растёт, щелчки ускоряются** → вы приближаетесь к излучателю. Продолжайте движение к пику.
   - **`● ACTIVE READER` + тревожная рамка** → активный считыватель прямо здесь.
3. Что-то нашли? Выйдите и откройте **Fingerprint**. Держите Flipper неподвижно у объекта и дайте
   ритму устояться — обычно хватает нескольких секунд. Нажмите **OK**, чтобы сохранить находку.
4. Вместо этого проверяете целую комнату? Откройте **Site Survey**, пройдите по пространству, пока шкала
   не заполнится, и прочитайте вердикт.
5. Покидаете зону? Переведите Flipper в **Watch Mode**, и он будет стоять на страже, просыпаясь и подавая
   сигнал, если считыватель появится, пока вас нет.
6. Проверьте **Logbook** — там всё сохранённое с метками времени — или вытащите `logbook.csv` с карты
   в таблицу.

> 💡 Сначала просканируйте заведомо исправный считыватель (свой телефон в режиме NFC или доверенный
> бесконтактный терминал), чтобы увидеть, как выглядит сильное легитимное поле на индикаторе — и как
> читается его отпечаток. Затем отправляйтесь на поиски.

### Управление

| Экран | Клавиша | Действие |
|---|---|---|
| **Sweep** | `OK` | Сброс пика / контактов |
| | `удержание OK` | Запись текущего показания |
| | `LEFT` | Калибровка шумового фона (3 с) |
| **Fingerprint** | `OK` | Сохранить находку в журнал |
| | `удержание OK` | Перезапустить измерение |
| **Site Survey** | `OK` | Запустить проверку заново |
| **Watch Mode** | `OK` | Перевзвести (сброс счётчика и часов) |
| *в любом месте* | `BACK` | На уровень выше |

---

## 🔬 Честные ограничения

- **Только 13.56 МГц (HF).** Specter чувствует **диапазон NFC** — тот, что используется скиммерами
  бесконтактных платежей, большинством современных считывателей доступа, транспортными и гостиничными
  считывателями. Он **не может** видеть считыватели **125 кГц (LF)** (старые дверные панели HID Prox /
  EM4100); у LF-пути Flipper нет эквивалентного бита обнаружения поля.
- **Он чувствует *несущую* считывателя, а не то, что тот читает.** Specter сообщает вам *здесь есть
  активный считыватель, примерно насколько он близко и с каким ритмом он опрашивает* — он не
  декодирует, не идентифицирует и не захватывает ничего из того, что делает считыватель.
- **Сила относительна, а не откалибрована.** `FIELD %` и слова близости — это сравнительный ориентир
  «теплее / холоднее» для поиска, а не измеренное расстояние в см. Это *масштабированное* показание
  рабочего цикла несущей относительно типичной полосы опроса (см. [Чтение индикатора](#-reading-the-meter--fixed-in-23));
  считыватель с необычно редким опросом будет показывать меньше на той же дистанции, а работающий
  в режиме непрерывной волны — зашкаливать с большего расстояния.
- **У индикатора есть предел.** `MAX` означает, что несущая поднята настолько, насколько этот
  считыватель вообще её поднимает — дальше приближение физически не может дать большее число.
  Используйте пик-удержание `PK` для сравнения позиций.
- **Ритм разрешается до ~2 мс.** Это период дискретизации. Времена, близкие к нему, показываются
  с **`~`**, и достоверность соответственно снижается — Specter предпочитает указать на собственный
  предел разрешения, чем выдать точное на вид число, за которое не может поручиться.
- **`CLEAN` означает чисто при выбранной вами чувствительности.** Спящий скиммер, который просыпается
  только на реальное касание, или экранированный, останется невидимым при *любом* пороге. Отсутствие
  показания — не гарантия отсутствия.
- **Одно радио за раз.** Specter захватывает NFC-чип во время сканирования, поэтому сначала закройте
  любое другое NFC-приложение (оно сообщит *NFC unavailable*, если радио занято чем-то ещё).

---

## ⚖️ Правовые и этические аспекты

Specter — это **оборонительный, только слушающий** инструмент — он **никогда не передаёт**, не питает
поле и не касается считывателя. Используйте его для проверки **своей** зоны POS, двери, стола или
вещей, либо оборудования, которое вам **явно разрешено** оценивать. Ответственность за использование
лежит на вас. Знайте местные законы.

---

## 🗺️ Дорожная карта

- [x] Сохранение чувствительности / звука / вибрации / LED между перезагрузками
- [x] «Журнал» обнаружений с метками времени на SD-карту
- [x] Фоновое сканирование с выключенным экраном — *скрытый режим*
- [x] Регулируемый порог для более точного контроля дальности — *автокалибровка + пользовательская чувствительность*
- [x] Отпечаток излучателя по ритму его опроса
- [x] Таймированный обзор помещения с вердиктом по комнате
- [x] Экспорт журнала в CSV для отчётов — *записывается в реальном времени рядом с .txt*
- [x] Долгий автономный режим наблюдения с будильником по обнаружению
- [x] Использование индикатором полного диапазона против реальных опрашивающих считывателей
- [x] Стрелка тренда «теплее/холоднее» во время поиска
- [ ] Исследование LF-датчика (125 кГц) на катушке как отдельного режима
- [ ] Фильтрация журнала по типу на устройстве

---

## 🗂️ Структура проекта```
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

> Социальный превью — это единственный ресурс, который GitHub не может подхватить из репозитория — его
> нужно один раз загрузить вручную в **Settings → Social preview**. Именно он отображается
> при публикации репозитория в Slack, X, LinkedIn или Discord.

---

## 🙏 Благодарности

- Создано **[at0m-b0mb](https://github.com/at0m-b0mb)**.
- Часть семейства security-инструментов для Flipper: **[Argus](https://github.com/at0m-b0mb/Argus-FlipperZero)** (Wi-Fi deauth / evil-twin watchdog), **[GhostTag](https://github.com/at0m-b0mb/GhostTag-FlipperZero)** (BLE anti-stalking hunter) и **[Cerberus](https://github.com/at0m-b0mb/flipper-cerberus)** (Sub-GHz RF watchdog).
- Работает на базе [прошивки Flipper Zero](https://github.com/flipperdevices/flipperzero-firmware) NFC HAL (`furi_hal_nfc` field detection) + [ufbt](https://github.com/flipperdevices/flipperzero-ufbt).

## 📄 Лицензия

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