# 串口设备发现（`wifisec serial`）

`wifisec serial` 枚举系统全部串口设备，功能对标 Arduino IDE 的端口列表。它是协处理器路径的入口排查命令：**板子能不能被看见、被谁占用、是哪颗串口芯片**，一条命令全部回答。

固件与协处理器架构见 [wifi_deauth.md](wifi_deauth.md)；本文只覆盖主机侧的串口发现与排错。

## 获取二进制

```bash
go install github.com/ctkqiang/wifisec/cmd/wifisec@latest
```

其他获取方式（Release 下载、源码编译）见仓库 README。

## 1. 功能定位

协处理器模式下，`deauth` 的射频工作在 ESP 板子上，宿主机只通过 USB 串口发协议帧。因此每次开打前必须回答三个问题：

1. **板子在吗**——串口设备节点是否出现（数据线、驱动、供电任一环节断了都不出现）；
2. **是这块板子吗**——多设备插入时靠 VID:PID 与序列号分辨目标板；
3. **端口闲着吗**——Arduino 串口监视器等进程占用端口时 `deauth` 会失败，占用者要提前发现。

`serial` 只读不写：不打开端口、不触发复位、不与固件握手，随时可安全执行。

## 2. 用法

```bash
wifisec serial
```

无参数、无平台差异、不需要 root/管理员权限。

## 3. 输出判读

典型输出（macOS，NodeMCU 板载 CH340，系统虚拟串口随机器不同）：

```
串口设备 · 共 2 个
端口                             类型  VID:PID    产品           序列号
───────────────────────────────────────────────────────────────────────
/dev/cu.usbserial-XXXX           USB   1A86:7523  USB2.0-Serial  -
/dev/cu.Bluetooth-Incoming-Port  系统  -          -              -
```

| 列 | 含义 | 判读要点 |
|:---|:---|:---|
| 端口 | 设备节点路径 | `deauth` 第二参数就用这个值，原样复制 |
| 类型 | USB（绿色）/ 系统（灰色） | 开发板几乎都是 USB；`系统` 是蓝牙等虚拟串口，与目标无关 |
| VID:PID | 串口芯片的 USB 身份 | 唯一能回答「这是哪颗芯片」的字段，对照见 §4 |
| 产品 | USB 描述符里的产品名 | CH340 等廉价芯片常留空或写 `USB2.0-Serial`，不能作为判型依据 |
| 序列号 | USB 序列号 | 常为空（`-`）：CH340 出厂不写序列号；多块同类板只能靠插拔分辨 |

排序与裁剪规则：

- **USB 设备永远排前面**——目标板几乎必是 USB 串口，系统虚拟串口垫底；同类内按端口名排序保证输出稳定，多设备时便于肉眼比对。
- **终端过窄时按优先级裁列**——序列号先隐藏，其次 VID:PID，再产品；端口与类型永不被裁。管道/重定向（无终端宽度）时按固定列数兜底输出。
- **无法获取的字段一律显示 `-`**，与「获取到了但值为空」不区分——对排错而言两者结论相同：该芯片没上报这个描述符。

## 4. VID:PID 芯片对照

开发板板名（Unknown/NodeMCU/ESP32…）都不会出现在 `serial` 输出里——串口芯片只回报自己的身份，不回报载板。认芯片才是认板子的正确姿势：

| VID:PID | 芯片 | 常见载板 |
|:---|:---|:---|
| `1A86:7523` | CH340/CH341 | NodeMCU、Wemos D1 mini 及多数国产 ESP8266/ESP32 板 |
| `1A86:55D4` | CH9102 | 较新的 ESP32-S3/C3 开发板 |
| `10C4:EA60` | CP2102/CP2102N | Espressif 官方 DevKit、部分 NodeMCU |
| `0403:6001` | FT232RL | FTDI 转接板、部分老牌载板 |
| `067B:2303` | PL2303 | 老式 USB-TTL 线，不建议用于烧录 |

判读示例：输出 `1A86:7523` 即 CH340——macOS 需装 CH340 驱动（新版本 macOS 内置）；Linux 内核自带但要求用户在 `dialout` 组。

> 烧录固件时用 `arduino-cli board list`，板名列显示 `Unknown` 是正常现象，原因相同：串口芯片不回报载板身份。端口对得上即可继续。

## 5. 平台差异

| 平台 | 端口形态 | 备注 |
|:---|:---|:---|
| macOS | `/dev/cu.usbserial-*`、`/dev/cu.wchusbserial-*` | 用 `cu.`（呼叫方向）而非 `tty.`，`tty.*` 会等载波信号导致打开阻塞 |
| Linux | `/dev/ttyUSB0`、`/dev/ttyACM0` | 用户需在 `dialout` 组；`ttyACM*` 多为原生 USB（ESP32-S2/S3） |
| Windows | `COM3`、`COM4`… | 设备管理器可查；`serial` 输出直接给出 `COMx` 名 |

## 6. 排错

### 6.1 `未发现任何串口设备`

按出现概率排查：

1. **充电线冒充数据线**——最常见。充电线只有电源两根线，没有 D+/D- 数据线，设备节点物理上不可能出现。换一根确认能传数据的线。
2. **驱动缺失**——CH340 在旧版 macOS 与部分 Windows 上需手动装驱动；CP2102 同理。装完重新插拔。
3. **供电掉口**——射频初始化瞬间电流过载（300mA+）会让 macOS 直接关闭 USB 端口。直连电脑 USB 口、换短线，详见 [wifi_deauth.md §5.5](wifi_deauth.md)。
4. **板子处于深度休眠或损坏**——LED 完全不亮时先排除供电，再怀疑板子。

### 6.2 设备在列表里，但 `deauth` 报端口被占用

`deauth` 打开端口失败时会把占用进程点名到错误信息里（如 `端口正被 Arduino (PID 1234) 占用`），依据是 `lsof` 查询结果。典型占用者：

- **Arduino IDE 串口监视器**——开着监视器再跑 `deauth` 必然冲突，串口是独占资源；
- **上次异常退出的本程序**——极少见（进程退出即释放句柄），出现时按报错里的 PID 清理；
- **调制解调器管理器（Linux）**——`brltty`、`ModemManager` 会抢 CH340，`systemctl disable` 后重插。

### 6.3 列表里出现多个 USB 串口

`deauth` 缺省只自动探测**唯一** USB 串口；多个设备时无法猜你想打谁，会明确要求手动指定：

```bash
wifisec deauth <BSSID> /dev/cu.usbserial-XXXX
```

多块同类板（同芯片、都无序列号）无法靠输出区分，拔一块看另一个是否消失即可锁定端口名。

## 7. 与其他命令的衔接

- **`wifisec deauth`**——`serial` 列出的 USB 端口名就是 `deauth` 的第二参数（[wifi_deauth.md §5.6](wifi_deauth.md)）；
- **固件烧录**——烧录命令中的 `--port` 同样取自这里的端口名，完整流程见 [wifi_deauth.md §5.4](wifi_deauth.md)；
- **`wifisec list`**——枚举的是无线接口与周边网络，与串口无关；协处理器的扫描结果由固件在 `deauth` 过程中自行回传，不经过 `list`。
