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 上方的读取器会使仪表满格；较弱或较远的读取器则只会轻微拨动它。这驱动着指针、接近度词语和点击频率。

**什么节奏 → 身份。** 另外，该比特的每一次跳变都会被计时。一个每 200 ms 唤醒 20 ms 的读取器会产生几乎无抖动的突发/间隙模式，因为其轮询循环由晶振定时的状态机驱动。手部移动和射频噪声则没有这么稳定。这种差异正是区分 **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 下沿、包裹或桌面。
   - **波形安静 / 平坦** → 范围内没有活跃的读卡器。
   - **指针攀升、滴答声加快** → 你正在接近发射源。继续朝峰值方向移动。
   - **`● 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 MHz（HF）。** Specter 感知的是 **NFC 频段**——即非接触式支付盗刷器、大多数现代门禁读卡器、交通和酒店读卡器所使用的频段。它**无法**看到 **125 kHz（LF）** 读卡器（较旧的 HID Prox / EM4100 门禁面板）；Flipper 的 LF 路径没有等效的场检测位。
- **它感知的是读卡器的*载波*，而非其读取的内容。** Specter 会告诉你*此处有活跃读卡器、大致距离多远、以及它以何种节奏轮询*——它不会解码、识别或捕获读卡器所做的任何操作。
- **强度是相对的，而非校准的。** `FIELD %` 和接近程度描述词是用于扫描的对比式“越近越热 / 越远越冷”指南，而非以厘米为单位的实测距离。它是载波占空比相对于典型轮询频带的*缩放*读数（参见 [Reading the meter](#-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 kHz）线圈式读卡器感知作为独立模式
- [ ] 在设备上按类型筛选日志

---

## 🗂️ 项目结构```
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 无法从仓库中自动获取的唯一资源——它必须在 **设置 → 社交预览** 中手动上传一次。当仓库在 Slack、X、LinkedIn 或 Discord 上被分享时，显示的就是这张预览图。

---

## 🙏 致谢

- 由 **[at0m-b0mb](https://github.com/at0m-b0mb)** 构建。
- 属于 Flipper 安全工具家族的一部分：**[Argus](https://github.com/at0m-b0mb/Argus-FlipperZero)**（Wi-Fi 解除认证 / 邪恶双子星看门狗）、**[GhostTag](https://github.com/at0m-b0mb/GhostTag-FlipperZero)**（BLE 反跟踪猎手）以及 **[Cerberus](https://github.com/at0m-b0mb/flipper-cerberus)**（Sub-GHz 射频看门狗）。
- 由 [Flipper Zero 固件](https://github.com/flipperdevices/flipperzero-firmware) NFC HAL（`furi_hal_nfc` 场检测）+ [ufbt](https://github.com/flipperdevices/flipperzero-ufbt) 提供支持。

## 📄 许可证

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