docs/network_setup.md

# 一边采集脑电、一边联网 —— 双网络接口配置

## 问题

帽子是个 **Wi-Fi 热点(ESPBCI)**,电脑必须连上它才能收数据。但 Mac 只有一块 Wi-Fi 网卡,
连了 ESPBCI 就等于把**默认路由**交给了这个没有外网的热点 → 采集时断网,没法查资料 / 跑
Claude Code / 同步代码。

**根因不是"只能连一个网络"** —— macOS 支持多个接口同时工作。真正的问题是
**默认路由(default route)只有一个**,而 macOS 按「服务顺序 Service Order」决定给谁。
ESPBCI 的 DHCP 会下发网关 192.168.4.1,如果 Wi-Fi 排在最前面,默认路由就被它抢走了。

**解法:让另一个接口拿默认路由(负责上网),Wi-Fi 只保留 192.168.4.0/24 这条子网路由(负责帽子)。**
两者互不干扰,可以同时用。

---

## 方案 A(推荐,零成本):iPhone USB 网络共享

你的 Mac 上已经有 `iPhone USB` 这个网络服务(`networksetup -listnetworkserviceorder` 可见)。

1. 用数据线把 iPhone 连到 Mac;iPhone → **设置 · 个人热点 · 允许其他人加入** 打开。
   (走 USB 线,不占用 Wi-Fi,也比无线热点稳)
2. **系统设置 · 网络 · 右下角「⋯」· 设定服务顺序(Set Service Order)**,
   把 **`iPhone USB` 拖到 `Wi-Fi` 上面** → 完成 → 应用。
3. Wi-Fi 连上 **ESPBCI**。
4. 验证:`python src/acquisition/net_check.py` 应显示 **✅ 帽子 + 互联网 同时在线**。

> 这个顺序调一次就长期有效:没插线时 Wi-Fi 依然正常上网;插上线采集时,上网自动走 iPhone。

## 方案 B(最稳):USB-C 有线网卡

同方案 A,只是把 `iPhone USB` 换成 `Ethernet / USB 10/100/1000 LAN`,拖到 Wi-Fi 之上。
有线最稳定、延迟最低,长时间采集推荐。

## 方案 C(可选加固):给 Wi-Fi 设静态 IP、清空路由器字段

**系统设置 · 网络 · Wi-Fi · 详细信息 · TCP/IP**:
- 配置 IPv4:**手动**
- IP 地址 `192.168.4.2`,子网掩码 `255.255.255.0`
- **路由器一栏留空** ← 关键:Wi-Fi 就永远不会抢默认路由

两个额外好处:
- 板子只往 `192.168.4.2` 发数据,静态 IP **保证你一定拿到 .2**(不会因为别的客户端占用而变成 .3/.4)
- 不依赖服务顺序也能保证外网走别的口

⚠ 注意:TCP/IP 设置是**按网络服务**(整个 Wi-Fi)生效,不是按 SSID。设了静态 IP 后连家里
Wi-Fi 会不通。解决办法:用 **网络位置(Location)** —— 系统设置 · 网络 · ⋯ · 位置 · 编辑位置,
新建一个叫 `EEG` 的位置照上面配置;日常用「自动」,采集时从 苹果菜单  · 位置 一键切到 `EEG`。

---

## ⚠ 连上 ESPBCI 后 Clash 代理失效 —— 原因与修复

**症状**:有线网卡已接、排序也对,连上 ESPBCI 后帽子能连、也能上网,**但 Clash 代理不起作用了**。

**实测诊断**(`net_check.py` + `networksetup`):

| 检查项 | 结果 |
|---|---|
| 有线 `SZNX LAN 100M` (en8) 持有默认路由 | ✔ 192.168.31.238 → 192.168.31.1 |
| Clash Party(mihomo 内核)监听 7890 | ✔ |
| mihomo `tun.enable` | `false`(纯系统代理模式) |
| mihomo `interface-name` | **未设置** → 由 mihomo **自动探测出站网卡** |
| Wi-Fi 服务的 IPv4 配置 | **DHCP** |

**根因:ESPBCI 会下发一个"竞争性默认网关" `192.168.4.1`。**
Wi-Fi 走 DHCP,一连上 ESPBCI 就把 `192.168.4.1` 装成了网关。mihomo 在网络变化时会
**重新自动探测出站网卡**,很容易改绑到这条死路(ESPBCI 根本没有外网)。于是:

- 走代理的流量(以及 mihomo 自己的 DoH DNS `https://doh.pub/dns-query`)全部发往 ESPBCI → 失败
- 命中 `DIRECT` 规则的流量仍走 en8 → **"能上网,但代理不起效"**

### 修复(推荐:根除竞争网关)

**系统设置 · 网络 · Wi-Fi · 详细信息… · TCP/IP**
- 配置 IPv4:**手动**
- IP 地址:`192.168.4.2`   子网掩码:`255.255.255.0`
- **路由器:留空** ← 关键
- 再到 **DNS** 标签页:把 DNS 服务器**全部删除**(留空)

保存后:Wi-Fi 只提供 `192.168.4.0/24` 这条子网路由(够连帽子),**永远不会**成为默认路由候选,
mihomo 就只能继续用 en8 出站,代理正常。**顺带保证你一定拿到 `192.168.4.2`**(板子只往 .2 发数据)。

> Wi-Fi 的 TCP/IP 设置是按**整个服务**生效、不是按 SSID。设完之后连家里 Wi-Fi 会不通。
> 用**网络位置**解决:系统设置 · 网络 · ⋯ · 位置 · 编辑位置 · 新建 `EEG` 用上面的配置;
> 日常留在「自动」,采集时从  菜单 · 位置 一键切到 `EEG`。

### 加固(可选):把 mihomo 出站网卡钉死

Clash Party · **设置 · 覆写(Override)** · 新建一个 YAML 覆写:

```yaml
interface-name: en8      # 你的 USB-C 有线网卡;强制所有出站走它
```

> 别直接改 `~/Library/Application Support/mihomo-party/work/config.yaml` —— 那是**每次加载订阅
> 都会重新生成**的运行时文件,改了会被覆盖。必须用「覆写」才持久。
>
> 注意副作用:钉死 en8 后,**拔掉有线网卡代理就会断**(此时把这条覆写关掉即可)。

### 验证

```bash
python src/acquisition/net_check.py
```
连上 ESPBCI 后应当看到:`✅ 帽子 + 互联网 同时在线` + 代理区 `✔ 通过代理能出网 (CONNECT)`,
且 `✔ Wi-Fi 不会抢默认网关`。

---

## 方案 D(长期最优):请厂商加 STA(客户端)模式固件

让板子**主动加入你家的 Wi-Fi**,而不是自己开热点。这样:
- Mac 一直待在家里 Wi-Fi,网络完全正常,不用任何切换
- 板子从路由器拿一个 IP(如 192.168.31.x),代码里把 `--host` 改成那个 IP 即可,**其余逻辑不用动**
- 顺带还能解决"多台设备同时看数据"的问题

参考实现:`third_party/Cerelog/`(同为 ESP32 + ADS1299)的 `esp_hostfw.ino` 就带 STA 模式 + TCP。
建议一并请厂商加 **TCP 流模式**(见 `research/Cerelog_adaptation_notes.md`),UDP 丢包问题一起解决。

## 方案 E:采集机 / 主力机分离

一台旧笔记本或树莓派连 ESPBCI 专职采集,通过有线网 / LSL 把数据转发给主力 Mac。
最灵活但最麻烦,只有前面都不可行时再考虑。

---

## 不推荐

- **USB Wi-Fi 网卡**:macOS(尤其 Apple Silicon)第三方 Wi-Fi 网卡驱动支持很差,容易翻车。
- **手工 `route add`**:能临时救急,但重连就没了,不如调服务顺序一劳永逸。

---

## 采集前一键自检

```bash
python src/acquisition/net_check.py          # 单次
python src/acquisition/net_check.py --watch  # 每 3 秒刷新(边调边看)
```

它会列出各接口 IP、默认路由归属,并检查:在不在帽子子网、本机是否为 `192.168.4.2`、
能否 ping 通帽子、能否上网、UDP 2244 是否被占用(厂商 `main_ui` 会抢)。
脚本**只读**,不会改你的网络设置。