ESP32 WiFi Probe — 基于混杂模式的无线设备感知系统

在线体验：https://monitor.npc-ai.fun/probes

GitHub：dr4g00n/myAgent-Shopping/AgentESP32

硬件：ESP32-DevKitC + USB 供电

项目概述

AgentESP32 是一个基于 ESP32 的 Wi-Fi 探针系统，通过 Wi-Fi 芯片的混杂模式（Promiscuous Mode）被动嗅探 802.11 管理帧，实现对周边无线设备的感知、跟踪和生命周期管理。

它不是传统的 WiFi 扫描工具——传统的扫描只能看到自己连接的网络，而混杂模式可以捕获所有 802.11 管理帧：Probe Request、Beacon、Authentication、Deauthentication... 这意味着你可以看到周围所有设备（即使它们没有连接到你的网络）。

核心功能

1. 被动嗅探

ESP32 的 Wi-Fi 芯片在混杂模式下接收所有 802.11 管理帧，不区分是否发给自己：

• Probe Request：设备搜索网络（手机、电脑在找 WiFi）
• Probe Response：AP 响应探测
• Beacon：AP 广播自身存在
• Authentication/Deauthentication：认证过程、强制断开检测
• Association/Disassociation：设备关联/断开 AP

2. 设备生命周期跟踪

从发现到消失的完整状态机：

DISCOVERED → PROBING → AUTHENTICATING → ASSOCIATED → CONNECTED
                                              ↓
                                       DISCONNECTED → OFFLINE → GONE

每个设备维护完整的时间线：首次发现、首次探测、关联时间、断开时间、信号强度变化。

3. 多探针协同定位

支持部署多个 ESP32 探针，通过 MQTT 将数据汇聚到中央 Hub：

• 按 MAC 地址或前缀扫描特定设备
• 比较不同探针的 RSSI 信号强度，推断设备位置
• 最近 7 天出现时间线可视化（SVG 时间线）

4. 厂商识别

内置 30+ 厂商 OUI 数据库：

• Apple（202 个 OUI）
• Huawei（204 个）
• Samsung（50 个）
• Xiaomi、OPPO、vivo、Intel、MediaTek...

支持随机 MAC 检测：通过 LAA bit（mac[0] & 0x02）识别随机化 MAC 地址。

硬件组成

┌──────────────────────────────────────┐
│         ESP32-DevKitC                │
│  ┌──────────────┐  ┌──────────────┐ │
│  │  Wi-Fi 芯片   │  │  4MB Flash   │ │
│  │  (混杂模式)   │  │  (SPIFFS)    │ │
│  └──────────────┘  └──────────────┘ │
│  ┌──────────────┐                   │
│  │  MQTT 客户端  │  USB 供电         │
│  │  (PubSub)    │                   │
│  └──────────────┘                   │
└──────────────────────────────────────┘
              │
              ▼ MQTT
┌──────────────────────────────────────┐
│         Agora Hub                    │
│  ┌──────────────┐  ┌──────────────┐ │
│  │  MQTT Broker  │  │  Monitor UI  │ │
│  │  (EMQX)      │  │  (Web)       │ │
│  └──────────────┘  └──────────────┘ │
└──────────────────────────────────────┘

技术架构

信道跳频

后台 FreeRTOS 任务每 250ms 切换一次信道，覆盖 2.4GHz 的 13 个信道：

uint8_t channels[] = {1, 6, 11, 2, 7, 12, 3, 8, 13, 4, 9, 5, 10};

双模式运行

// SNIFFING 模式：混杂模式捕获，Wi-Fi 断开
if (g_mode == RunMode::SNIFFING) {
    if (now - g_mode_start_time >= cfg.report_interval_ms) {
        enter_reporting_mode();  // 切换模式
    }
}

// REPORTING 模式：连接 WiFi + MQTT，上报数据
if (g_mode == RunMode::REPORTING) {
    mqtt_manager_loop();
    agent_runtime_heartbeat();
    agent_runtime_report_events();
    if (now - g_mode_start_time >= 3000) {
        enter_sniffing_mode();  // 3秒后切回
    }
}

去重机制

5 秒窗口内相同 MAC+SSID 丢弃，避免重复记录：

if (now - g_dedup[i].last_seen <= DEDUP_WINDOW_SEC) {
    return false;  // 重复，丢弃
}

数据持久化

• 每个 MAC 一个 JSON 文件（/history/aabbccddeeff.json）
• 最多保存 50 次出现记录
• 最多 200 个 MAC 文件，自动淘汰最旧的

监控面板

访问 https://monitor.npc-ai.fun/probes：

关键技术栈

快速开始

git clone https://github.com/dr4g00n/myAgent-Shopping
cd AgentESP32

# 安装 PlatformIO
pip install platformio

# 编译并烧录
pio run --target upload

# 监控串口输出
pio device monitor

配置 data/config.json：

{
    "agent_id": "esp32_probe_001",
    "report_interval_ms": 10000,
    "channels": [1, 6, 11, 2, 7, 12, 3, 8, 13, 4, 9, 5, 10],
    "watchlist": ["aa:bb:cc:dd:ee:ff"]
}

应用场景

场景 A：设备资产管理

• 企业内网中追踪未授权设备接入
• 识别随机 MAC 地址的访客设备

场景 B：安全监控

• 检测 Deauthentication 攻击（WiFi 干扰）
• 监控特定设备的在线状态

场景 C：人流统计

• 商场/门店的客流分析（不侵犯隐私，仅统计 MAC 出现频次）
• 多探针协同，绘制热力图

项目意义

AgentESP32 证明了硬件 Agent 也是 AgentHub 生态的一等公民：它像软件 Agent 一样注册能力、发送心跳、响应任务，只是它的"能力"是感知物理世界。

这为"物联网 + AI Agent"的融合提供了一个范例：每个传感器不仅是数据采集器，更是可以自主协商、主动上报的智能实体。