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 мс, создаёт паттерн «всплеск/пауза» почти без джиттера, потому что его цикл опроса управляется конечным автоматом с кварцевой синхронизацией. Движение руки и радиочастотные помехи не обладают такой стабильностью. Именно это различие отделяет **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` | Сбросить пик / контакты |
| | `hold OK` | Записать текущее показание |
| | `LEFT` | Калибровать уровень шума (3 с) |
| **Fingerprint** | `OK` | Сохранить находку в журнал |
| | `hold 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));
  считыватель, который опрашивает необычно редко, покажет меньше на том же расстоянии, а работающий в режиме непрерывной волны
  упрётся в максимум с большего расстояния.
- **Индикатор упирается в потолок.** `PEGGED` означает, что несущая поднята настолько, насколько этот считыватель её вообще поднимает — за
  этой точкой приближение действительно не может дать большего числа. Flipper один раз жужжит, когда это происходит,
  чтобы вы знали, что нужно прекратить движение, даже если не видите экран. Используйте удержание `PEAK`, чтобы сравнивать
  позиции вместо этого.
- **Ритм разрешается до ~2 мс.** Это период дискретизации. Значения времени вблизи него показываются с
  **`~`**, и уверенность соответственно снижается — Specter предпочтёт обозначить свой собственный предел разрешения,
  чем назвать точное на вид число, за которое не может поручиться.
- **`CLEAN` означает чисто при выбранной вами чувствительности.** Дремлющий скиммер, который просыпается только при реальном касании,
  или экранированный, остаётся невидимым при *любом* пороге. Отсутствие показания не является гарантией
  отсутствия.
- **Одно радио за раз.** Specter захватывает чип NFC во время сканирования, поэтому сначала закройте любое другое приложение NFC
  (оно скажет *NFC unavailable*, если радио занято чем-то другим).

---

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

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

---

## 🗺️ План развития

- [x] Сохранение чувствительности / звука / вибрации / LED между перезагрузками
- [x] «Журнал» обнаружений с отметками времени на SD-карту
- [x] Фоновое сканирование с выключенным экраном — *stealth mode*
- [x] Настраиваемый порог для более тонкого контроля диапазона — *автокалибровка + Custom sensitivity*
- [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)**.
- Часть семейства инструментов безопасности для Flipper: **[Argus](https://github.com/at0m-b0mb/Argus-FlipperZero)** (сторож Wi-Fi деаутентификации / evil-twin), **[GhostTag](https://github.com/at0m-b0mb/GhostTag-FlipperZero)** (охотник за BLE-слежкой) и **[Cerberus](https://github.com/at0m-b0mb/flipper-cerberus)** (сторож Sub-GHz RF).
- Работает на базе [прошивки 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