# PhantomLink

**Repository Path**: ZEROBOX/PhantomLink

## Basic Information

- **Project Name**: PhantomLink
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PhantomLink（幽灵链路）

> © 2026 **ii2026@126.com** · 保留所有权利 · 仅授权非盈利学习 / 个人使用 · 禁止商业用途

基于 **ESP32-S3 N16R8** 的多功能 WiFi / 网络实验固件。自带 Web 管理后台（无需 App），集成 WiFi 配网、ARP 二层协议实验、frp 内网穿透客户端、WiFi CSI 人体感应、DNS 代理与板载灯光控制等模块。

> ⚠️ **合规声明**：本项目包含网络协议实验功能（如 ARP 报文构造/嗅探）。请仅在**你自己完全掌控的隔离测试网络**中使用，并遵守所在地法律法规。作者不对任何滥用行为负责。

---

## 功能特性

- **Web 管理后台**：手机/电脑连接设备热点即可打开，无需安装 App。
- **WiFi 配网（Captive Portal）**：AP 模式 `ESP32-SETUP` + 强制门户，连上热点即可配网。
- **frp 内网穿透客户端**：设备端精简版 frpc，支持多服务器、TCP 转发、NVS 持久化、开机自启。
- **ARP 二层协议实验**：ARP 表复刻 / 毒化 / 嗅探实验，发包间隔可调。
- **WiFi CSI 人体感应**：利用 WiFi 信道状态信息（CSI）粗略判断房间内是否有人及活动距离。
- **DNS 代理**：无线桥接模式下，AP 客户端把 DNS 指向网关即可解析域名。
- **板载灯光**：WS2812B 大灯（RGB 混色 / 呼吸 / 彩虹）+ 双小灯控制。
- **全量 OTA**：后台上传固件即可升级（双 bank OTA）。
- **系统监控**：实时 CPU / 内存 / 存储 / 温度；支持路由器 BSSID 绑定。

---

## 硬件要求

- 芯片：**ESP32-S3**（本项目针对 **N16R8** 模组：16MB Flash + 8MB Octal PSRAM）
- 板载外设：WS2812B 大灯（GPIO48）、小灯 TX/RX（GPIO43/44）、板载温度传感器
- 供电：USB-C（使用数据线）

> 其他 ESP32 系列未做适配，请勿直接套用 `sdkconfig.defaults`。

---

## 软件依赖

- [ESP-IDF](https://github.com/espressif/esp-idf) **v5.x**（建议 v5.3+，CMake 构建系统）
- Python 3（构建 / 脚本依赖）

---

## 目录结构

```
.
├── CMakeLists.txt            # 工程入口（project(PhantomLink)）
├── sdkconfig.defaults        # 默认配置：目标 esp32s3 / 16MB Flash / Octal PSRAM / NAPT / 日志 WARN
├── partitions.csv            # 双 OTA 分区表（16MB）
├── do_build.ps1              # Windows 一键构建脚本（自动定位 IDF）
├── do_flash.ps1              # Windows 烧录脚本
├── 打包烧录命令.md            # 构建 / 烧录详细文档
├── main/                     # 应用源码
│   ├── main.c                # 主程序：Web 后台、配网、系统监控、OTA、会话与防爆破
│   ├── arp.c / arp_*.inc     # ARP 二层实验模块 + 页面
│   ├── frp_client.c/.h       # frp 内网穿透客户端
│   ├── people.c / people_http.inc   # WiFi CSI 人体感应
│   ├── dns_proxy.c/.h        # DNS 代理
│   ├── light.c/.h            # 板载灯光（WS2812B）
│   └── oui.c/.h              # MAC OUI 厂商识别
├── components/               # 第三方组件（随 IDF / 依赖引入，如 tinyusb）
└── tools/                    # 开发调试脚本（已加入 .gitignore，不随发行版发布）
```

---

## 快速开始

### 1. 构建

```bash
# 设置目标（首次或切换芯片前请先 fullclean）
idf.py set-target esp32s3
idf.py build
```

Windows 也可一键构建（脚本已内置定位 IDF 环境）：

```powershell
powershell -ExecutionPolicy Bypass -File .\do_build.ps1
```

### 2. 烧录与监视

```bash
idf.py -p COM3 flash monitor   # COM3 按设备管理器中的实际端口修改
```

### 3. 配网

上电后设备广播热点 `ESP32-SETUP`（默认密码 `12345678`）：

1. 手机连接该热点 → 浏览器打开 `http://192.168.4.1`；
2. 选择附近 WiFi 并输入密码，设备自动切换为 STA 模式联网；
3. 之后在同一局域网内访问设备 IP 即可打开后台。

更详细的打包 / 烧录 / 量产流程见 [`打包烧录命令.md`](打包烧录命令.md)。

---

## 默认凭据（请务必修改）

| 项目 | 默认值 | 说明 |
| --- | --- | --- |
| AP 热点密码 | `12345678` | 配网热点，可在后台「设备设置」修改 |
| 后台管理员密码 | `admin` | 首次使用后请于「修改密码」页修改 |

> frp 服务器地址、Token、WiFi STA 密码等敏感配置**均在运行时通过 Web 后台配置并存储于 NVS**，源码中不包含任何硬编码凭据。

---

## 功能模块

### Web 后台页面

- `/` 首页：系统实时信息、WiFi 连接 / 配网、AP 设置、灯光、OTA 升级、设备设置（BSSID 绑定、自定义 MAC 等）。
- `/adminpass` 修改管理员密码（持久化到 NVS）。
- `/arp` ARP 二层协议实验。
- `/frp` frp 内网穿透客户端配置与状态。
- `/people` WiFi CSI 人体感应。

### frp 内网穿透

设备端实现精简版 frpc（TCP 模式）：

- 控制连接：`Login(token/user)` → `NewProxy×N` → `Ping/Pong` 心跳；
- 数据转发：frps 回 `ReqWorkConn` 后新开连接，`StartWorkConn` 绑定规则，双向转发到 `local_ip:local_port`；
- `local_ip` 填 `127.0.0.1` 穿透本机管理页；填内网 IP（如 `192.168.1.1:80`）穿透局域网内任意 TCP 服务；
- 支持多服务器（最多 3 个）、独立隧道表、NVS 持久化与开机自启。

在 `/frp` 页面填写你的 frps 地址、端口、Token、user 与隧道规则即可（示例占位：`your-frps-host:7000`、Token `<YOUR_FRP_TOKEN>`）。

### ARP 二层协议实验

构造 / 发送 / 嗅探 ARP 报文，研究局域网二层协议行为。发包间隔可在页面调整（默认 10~30ms，下限 3ms）。

> ⚠️ 仅限在你**自己完全掌控的隔离测试网络**中使用。对防护较弱的路由器，伪装 MAC 可能影响 5G / 有线设备；新款路由器通常会拦截无线侧伪造 ARP，效果取决于上游固件，并非代码缺陷。

### WiFi CSI 人体感应

利用 WiFi CSI（信道状态信息）子载波被人体扰动的特性，粗略判断房间内是否有人活动（无 / 单人 / 多人）与活动距离（远 / 中 / 近）。

> 局限：完全静止的人检测不到；人数与距离为启发式估计，仅供实验演示。校准时请保持无人走动。

### DNS 代理 & 无线桥接

AP 模式开启 NAPT 桥接后，AP 客户端把 DNS 指向网关 `:53` 即可解析域名（无需依赖上游 DNS 透传时机）。

### 板载灯光

- 大灯 WS2812B（GPIO48，RMT 驱动）：RGB 任意混色、静态 / 呼吸 / 彩虹、全局亮度。
- 小灯 TX(GPIO43) / RX(GPIO44)：首次下发开关时该脚从 UART 切为 GPIO（此后该脚不再输出串口日志，烧录不受影响）。

---

## 分区与 OTA

`partitions.csv` 为 16MB 双 OTA 布局：

| 分区 | 说明 | 大小 |
| --- | --- | --- |
| nvs | 配置存储 | 24KB |
| phy_init | PHY 校准 | 4KB |
| ota_0 / ota_1 | 双应用 bank | 各 6.25MB |
| otadata | OTA 状态 | 8KB |
| coredump | 崩溃转储 | 64KB |

后台「OTA 升级」上传 `.bin` 即写入备用 bank 并切换。

---

## 安全与合规

- 本项目为**网络协议教学 / 实验工具**，请在法律允许范围内、于自有隔离网络中使用。
- ARP 模块可能产生对其他主机的网络干扰，滥用可能违反网络使用政策或法律。
- 出厂默认密码为通用值，联网前请修改管理员密码与 AP 密码。
- 任何将本固件用于未授权网络渗透、攻击第三方设备的行为，均与本项目无关。

---

## 源码发布说明 / 隐私

- 源码中的服务器地址、Token、WiFi 密码等均**不硬编码**，由用户通过 Web 后台配置并存储于 NVS。
- `tools/` 目录为开发期调试脚本，已通过 `.gitignore` 排除，不随发行版发布。
- 发布前已移除所有硬编码 IP / Token / 凭据。

---

## 许可证

本项目采用**非商业性许可**：保留版权，仅授权用于**非盈利的学习、研究、个人使用**，禁止任何商业或盈利性用途。详见根目录 [LICENSE](LICENSE)。商业授权请联系 **ii2026@126.com**。欢迎在遵守上述条款前提下提交 Issue 与 PR。