WiFi 传输配置

WiFi Direct 下的 TCP 连接与 COMMAND、响应、SAMPLE 的传输约定。

适用固件：ESP32 v0.5.0
状态：已实现接口规范
推荐数据传输：TCP
设备地址：192.168.4.1

本页只描述自研上位机使用 BCIKit 二进制采样帧时需要的 WiFi 行为。虽然部分 HTTP 路径沿用兼容层名称，但 output="bcikit" 后线上数据是 BCIKit Raw Stream Protocol v1，不是 OpenBCI 数据。

1. 网络模型

• ESP32 建立开放 SoftAP：OpenBCI-XXXX。
• ESP32 IP、网关和 HTTP API 地址：192.168.4.1:80。
• 电脑通常由 DHCP 获得 192.168.4.x 地址。
• 上位机先在电脑本地监听一个 TCP 端口，再把电脑 IP 和端口通过 HTTP 告诉 ESP32。
• ESP32 主动连接上位机监听端口。output="bcikit" 时，这条 TCP 连接是双向 BCIKit 字节流。

这里不是“上位机连接 ESP32 固定数据端口”的模型。

2. 推荐 TCP 连接时序

Host                              ESP32
 |-- connect WiFi AP -------------->|
 |-- GET /board ------------------->|
 |<------------- HTTP 200 JSON -----|
 |-- listen(host_ip, random_port)   |
 |-- POST /tcp output=bcikit ------>|
 |<==== ESP32 connects to listener ==|
 |<------------- HTTP 200 JSON -----|
 |==== PING / GET_INFO / STOP ======>|
 |<=== ACK / DEVICE_INFO / ACK ======|
 |==== SET_* / GET_STATUS ===========>|
 |<=== ACK / DEVICE_STATUS ==========|
 |================ START ============>|
 |<======= ACK + continuous SAMPLE ===|
 |================ STOP =============>|
 |<================ ACK ==============|
 |-- DELETE /tcp ------------------>| 

监听 socket 必须在 POST /tcp 前建立。固件会在处理该请求时同步尝试连接；若电脑防火墙拦截或监听尚未开始，请求返回 504。

3. 设备探测

GET /board

用于确认设备 HTTP 服务存活。当前响应示例：

{
  "board_connected": true,
  "board_type": "cyton",
  "num_channels": 8,
  "gains": [24,24,24,24,24,24,24,24]
}

其中 board_type 是兼容层字段。自研软件只用它判断 HTTP 服务可达；产品型号、固件版本和能力以 TCP GET_INFO 返回的 DEVICE_INFO 为准。

GET /all

返回热点 IP、MAC、名称、空闲堆、兼容层版本和 latency。字段可用于诊断，不建议作为长期数据模型。

4. 配置 TCP 数据目标

请求

POST http://192.168.4.1/tcp

{
  "ip": "192.168.4.2",
  "port": 45123,
  "output": "bcikit",
  "delimiter": false,
  "latency": 10000
}

字段：

成功响应

{
  "connected": true,
  "delimiter": false,
  "ip": "192.168.4.2",
  "output": "bcikit",
  "port": 45123,
  "latency": 10000
}

数据 socket 是连续、双向 TCP 字节流。上位机写入 BCIKit COMMAND，设备写回 ACK、DEVICE_INFO、DEVICE_STATUS 和 SAMPLE。一次 recv() 可能包含半帧、一帧或多帧，必须交给同一个增量解码器并按 frame_type 分发。

5. 原生握手、启停和释放

TCP accept 完成后建议依次发送：

PING
GET_INFO
STOP
SET_OUTPUT_FORMAT(0)
SET_BOARD_COUNT(1..4)
SET_SAMPLE_RATE(250 or 500)
SET_PROFILE
SET_CHANNEL_MASK
GET_STATUS
START

每个 COMMAND 使用唯一的非零 request_id。上位机持续读取整个流，通过 request_id 匹配响应；不能在发送命令后只阻塞等待“下一帧”，因为 START 后 SAMPLE 可以和 ACK 交错。

原生 STOP 是推荐停止方式。HTTP 路径保留为连接引导、兼容和异常恢复接口：

推荐关闭顺序：发送 STOP 并收到 ACK，再 DELETE /tcp，最后关闭本地 listener/data socket。应用异常退出后再次连接时，可先调用 /stream/stop 和 DELETE /tcp 清理旧状态，然后重新创建 listener 并 POST /tcp。

6. UDP 可选模式

POST /udp 使用与 TCP 相同字段，可增加：

{"redundancy": true}

• 每个 UDP datagram 包含一个完整 BCIKit SAMPLE 帧。
• redundancy=false 时每帧发送一次。
• redundancy=true 时同一帧连续发送三份；上位机必须按 sequence 去重。
• UDP 不保证到达、顺序或唯一性。
• DELETE /udp 停止采样并清除目标。

首版专业上位机建议使用 TCP；只有在明确需要低延迟并实现了乱序、去重和丢包统计后再开放 UDP。

7. HTTP 错误处理

HTTP 超时建议 5 秒。控制请求最多重试 2 次；重试前先确认是否已经产生副作用，例如 /stream/start 可能已经成功。

8. v0.5.0 原生控制边界

output="bcikit" 的 TCP 连接支持全部 Device Control Protocol v1 命令：

• PING、GET_INFO、GET_STATUS
• STOP、START
• SET_OUTPUT_FORMAT、SET_SAMPLE_RATE、SET_BOARD_COUNT
• SET_PROFILE、SET_CHANNEL_MASK、RESET_STATS

DEVICE_INFO 的 capabilities bit 11（0x00000800）表示支持此功能。上位机必须检查能力位，旧固件没有该能力时应提示升级，而不是静默改用 OpenBCI /command。

约束：

• WiFi BCIKit 连接上的 SET_OUTPUT_FORMAT 只接受值 0。
• 配置类命令在 streaming 状态返回 BUSY，必须先 STOP。
• SET_SAMPLE_RATE 接受 250/500；1000 SPS 只属于 OpenBCI BrainFlow 兼容路径。
• TCP 支持双向控制；UDP 仍只发送 SAMPLE，不接收 COMMAND。
• 控制响应和 SAMPLE 都是完整 BCIKit 帧，单次写入受固件网络互斥锁保护，不会在字节级交叉。

9. 安全边界

当前热点无密码、协议无认证和加密，适合实验室近距离开发，不适合不可信网络或敏感数据的正式部署。上位机应清楚显示当前连接的是开放热点；涉及人体采集数据时，默认本地存储并由用户明确授权导出。