One thought. World responds.
不是用意念打开一盏灯，而是让一个完整空间共同响应。
EVOKE 是一套主动脑机驱动的空间模式系统。
今天的智能空间已经拥有灯光、音响、屏幕、窗帘等大量可控设备，但用户仍然需要打开 App、寻找入口，再逐项完成操作。设备越来越智能，体验却依然被拆成一个个按钮。
EVOKE 尝试把交互从“控制某件设备”提升为“唤醒一种空间状态”：
- 用户主动发出经过训练的脑电控制指令；
- 系统实时接收 8 通道 EEG 数据并识别三类运动想象信号；
- 分类结果被映射为 Relax、Focus、Party 等空间模式；
- 前端同步呈现脑电活动、信号质量和分类置信度；
- 场景代码通过串口、TCP 或 HTTP 发送给下游设备；
- 灯光、屏幕、声音及其他环境设备共同响应。
EVOKE 不是一个只有离线准确率的模型实验，也不是一个只播放概念视频的品牌页面。它是一个在黑客松周期内完成的、覆盖产品叙事、Web 交互、实时后端、EEG 推理、硬件通信和设备反馈的端到端 Demo。
当用户准备休息、工作或与朋友欢聚时，真正想要的通常不是“把灯调到 40%”，而是让整个环境进入适合当下的状态。
传统方式需要连续完成：
- 调整灯光亮度与色温；
- 开关窗帘；
- 切换屏幕内容；
- 播放音乐或白噪声；
- 调整其他环境设备。
EVOKE 将这些动作预先编排为可复用的空间模式，让一次主动指令触发完整环境变化。
许多 BCI Demo 的终点是显示一条 EEG 曲线或一个分类标签。EVOKE 继续向前走了一步：分类结果不只是“Left / Right / Feet”，而会转化为真实世界可感知的光、声音、画面和设备动作。
EVOKE 不会根据疲劳、情绪或注意力擅自改变环境。用户先形成明确意图，再主动触发经过训练的运动想象指令。系统负责识别和执行，控制权始终属于用户。
首页以 “One thought. World responds.” 为核心视觉，通过 3D 大脑、8 通道 / 250 Hz 参数和沉浸式动效，快速建立 EVOKE 的品牌认知：
一念起，环境响应。
这一部分不是独立的宣传页，而是整套技术 Demo 的入口。
用户可以在同一居家空间中切换三种模式：
- 暖色环境灯开启；
- 床头灯调暗；
- 窗帘关闭；
- 白噪声或舒缓声音播放；
- 屏幕进入低刺激状态。
- 冷白任务灯开启；
- 工作区域照明增强；
- 窗帘打开；
- 播放低干扰专注音乐；
- 屏幕切换为工作状态。
- 彩色灯带与氛围灯开启；
- 屏幕切换为比赛或娱乐内容；
- 游戏与互动设备进入活动状态；
- 播放节奏更鲜明的音乐。
模式展示页通过视频时间轴跳转、放大检查、场景说明和特征列表，让抽象的“空间模式”变成可以直接理解的体验。
最后的 Live Neural Classification 监控页承担两项任务：
- 向观众解释系统此刻如何工作；
- 为现场调试和采集提供可操作界面。
监控页包含：
- 三分类实时置信度；
- 正式采集与推理状态；
- 采集窗口和推理窗口配置；
- Start / Stop 控制；
- 后端、TCP 数据流和错误状态；
- 信号质量与当前活动模式；
- 8 通道 EEG 头皮拓扑；
- 可拖动校准的电极位置；
- 基于
fsaverage皮层模型的 3D 活动场展示。
因此，网页既是品牌 Demo，也是实时系统的可视化控制台。
┌──────────────────────────────────────────────┐
│ EEG 采集硬件 / 配套上位机 │
│ 8 channels · raw EEG stream │
└─────────────────────┬────────────────────────┘
│ TCP binary frames
│ 328 B/frame
▼
┌──────────────────────────────────────────────┐
│ Python TCP Receiver │
│ 帧校验 · 断线重连 · 字节/帧诊断 │
└─────────────────────┬────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ Realtime Session │
│ 重采样 · 1 s 切换保护 · 4 s 窗口 / 2 s 步长 │
│ 滤波 · 质量评估 · 基线校准 · 三分类推理 │
└─────────────────────┬────────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ FastAPI Realtime Hub │
│ 会话编排 · 命令控制 · 多客户端消息广播 │
│ 运行状态 · 正式结果聚合 · 设备动作触发 │
└──────────────┬───────────────────┬───────────┘
│ WebSocket │ Device Adapter
▼ ▼
┌──────────────────────────┐ ┌───────────────────────────┐
│ React 实时监控与品牌网站 │ │ 串口 / TCP / HTTP 输出 │
│ 2D Topomap · 3D Cortex │ │ 0 / 1 / 2 场景代码 │
└──────────────────────────┘ └─────────────┬─────────────┘
▼
┌───────────────────────────┐
│ T5AI / 场景控制终端 │
│ 灯光 · 屏幕 · 声音 · 设备 │
└───────────────────────────┘
系统围绕统一的三类协议运行：
| 运动想象分类 | 信号代码 | Demo 空间模式 |
|---|---|---|
| Left | 0 |
Relax Mode |
| Right | 1 |
Focus Mode |
| Feet | 2 |
Party Mode |
空间模式映射可以重新配置。运动想象分类是底层控制码，Relax / Focus / Party 是本次 Demo 的产品表达，两者不是同一个概念。
当前仓库的实时链路接收 8 通道 EEG 数据。现场采集设备及配套上位机通过 TCP 向系统持续发送二进制数据帧。
单帧协议为：
| 字段 | 格式 | 含义 |
|---|---|---|
num_samples |
Little-endian int32 |
每帧固定 10 个采样点 |
sampling_rate |
Little-endian int32 |
上游实际采样率 |
| EEG payload | float32[80] |
10 samples × 8 channels |
每帧大小为 328 bytes。接收端会执行完整帧读取、长度校验、通道还原和时间戳生成。
上游设备的采样率可以不同，实时会话会通过 polyphase resampling 统一转换到模型所需的 250 Hz。这让硬件输入和后续模型窗口保持一致。
为了适应黑客松现场联调，系统提供两种输入模式：
demo：使用可重复运行的模拟 EEG 数据源，保证网页和演示流程在没有硬件时仍可展示；tcp：接入真实 EEG 数据流，执行完整采集和推理。
这种设计不是用模拟数据替代硬件验证，而是为现场展示提供安全回退，避免某个 USB、网络或设备问题让整套 Demo 无法讲解。
数据进入后端后，会进入滚动 EEG Buffer：
- 目标采样率：250 Hz；
- 窗口长度：4 秒，即 1000 个采样点；
- 窗口步长：2 秒；
- 缓冲保留：10 秒；
- 状态切换保护：1 秒。
系统在从静息采集切换到正式运动想象推理时，会清空重叠缓冲并跳过 1 秒过渡数据，避免提示切换、动作准备和上一阶段信号污染新窗口。
实时预处理链包括：
- 4–30 Hz 带通滤波；
- 50 Hz 陷波；
- 可配置重参考；
- 峰峰值
PTP检查； - 均方根
RMS检查； - 质量阈值从部署 checkpoint 的协议元数据中读取。
前端会同步显示信号质量和 EEG 空间分布，帮助现场人员判断佩戴、接触或环境噪声是否异常。
当前仓库实际部署的 checkpoint 为：
checkpoints/realtime_mi_relative_bandpower_v1.joblib
在线分类使用相对频带功率特征 + Extra Trees Soft-Voting 集成分类器。当前 checkpoint 内含 8 个采用不同随机种子的 ExtraTreesClassifier，并对它们的概率进行软投票：
- 从 8 通道输入中按 checkpoint 协议选择特征通道；
- 使用 Welch 方法估计功率谱；
- 提取
8–12、12–16、16–22、22–30 Hz四个频段； - 对功率取对数；
- 分别聚合静息基线窗口和任务窗口；
- 计算“任务特征 − 静息基线特征”；
- 输出 Left / Right / Feet 三类概率。
概率随后经过指数平滑，减少瞬时波动。正式推理还可以对多个模型输出窗口求平均，再锁定最终结果。
当前 checkpoint 记录的 38 个完整 Session、5 个 blocked file-group folds 验证结果为：
| 指标 | 当前部署 checkpoint |
|---|---|
| Balanced Accuracy | 0.482456 |
| Macro-F1 | 0.480410 |
| 三分类随机水平 | 0.333333 |
该 checkpoint 的元数据同时明确提示：候选模型是在同一份 grouped-CV 报告上选择的，不能视为独立测试集结果。因此这组指标只能作为黑客松阶段的工程验证，不应描述为消费级脑机控制精度。
EEG 存在明显的个体差异和会话漂移。先采集静息基线，再比较任务期频带功率变化，可以降低绝对幅值差异对分类的影响，也更适合短时间现场校准。
后端基于 Python + FastAPI + asyncio 构建。
负责：
- 数据重采样；
- 阶段切换和缓冲清空；
- 过渡期跳过；
- 滚动窗口生成；
- 在线预处理；
- 信号质量判断；
- 模型校准与推理；
- 概率平滑；
- 2D Topomap 数据生成。
负责：
- 启动或停止采集；
- 在 Demo/TCP 数据源之间切换；
- 管理 collecting、inferring、complete 等状态；
- 聚合多个推理窗口；
- 通过 WebSocket 广播 EEG、概率、质量和 Topomap；
- 记录 TCP 连接、字节、帧和异常诊断；
- 将最终结果发送给设备适配器。
每个 WebSocket 客户端拥有独立的异步消息队列。慢客户端不会阻塞 EEG 数据接收和其他浏览器；当队列持续堆积时，系统会主动断开该客户端，保护实时主链路。
| 接口 | 用途 |
|---|---|
GET /health |
后端健康检查 |
GET /realtime/status |
获取当前采集、推理和 TCP 状态 |
WS /ws/realtime |
实时数据广播与控制命令 |
前端通过 WebSocket 发送 start_acquisition、stop_acquisition 和 get_status 命令，并接收统一 Envelope 格式的事件。
前端采用：
- React 18；
- TypeScript；
- Vite；
- Tailwind CSS；
- Three.js；
- React Three Fiber；
- Drei；
- WebSocket 实时状态同步。
首页通过暗色视觉、3D 大脑视频、巨型排版和渐变品牌色，建立“意念驱动空间”的未来感。三个全屏 Section 依次完成：
- 品牌主张；
- 空间模式体验；
- 实时技术证明。
这让技术链路不再是分散的调试页面，而成为一段完整的产品叙事。
模式页通过 React 状态、视频 seek 和动效控制 Relax / Focus / Party 三种场景。用户可以：
- 点击按钮跳转到不同场景；
- 放大空间画面；
- 查看对应模式的设备变化；
- 使用关闭按钮或 Escape 返回；
- 通过整页滚动继续进入实时监控。
头皮图使用 Canvas 实时绘制 8 通道空间能量：
- 根据电极位置插值颜色场；
- 显示即时或时间平均 Topomap；
- 支持拖动电极进行现场位置校准；
- 将校准位置保存在浏览器 LocalStorage；
- 支持一键恢复默认布局。
3D 模块加载 fsaverage-pial.glb 皮层模型，并将实时脑信号映射为空间活动场：
- 拖动旋转；
- 滚轮缩放；
- 实时材质与颜色变化；
- 与 2D 电极位置保持关联。
它不是医学诊断图像，而是将实时信号转化为观众可以理解的空间可视化。
监控页允许现场操作人员设置：
- 基线采集窗口数；
- 正式推理结果窗口数；
- 开始采集；
- 停止采集。
同时显示：
- Backend / Source 连接状态；
- TCP 是否持续收到完整帧；
- 已接收字节和帧数；
- 当前采集或推理进度；
- 最终分类结果与置信度；
- 设备动作是否已经发送；
- 错误与超时信息。
系统通过 Device Adapter 将推理与具体硬件解耦。
当前支持：
| 输出模式 | 用途 |
|---|---|
| Serial | 通过 USB 串口向场景控制板发送 0/1/2 |
| TCP | 向局域网设备或中间控制器发送场景代码 |
| HTTP | 调用设备控制服务的 REST 接口 |
| Noop | 仅记录动作，用于无硬件调试和自动测试 |
串口适配器针对现场 T5AI 开发板进行了稳定性处理：
- 通过 CH342 的
VID:PID = 1A86:55D2自动识别设备； - 优先选择 Channel A 命令端口；
- 使用 115200 baud、8N1；
- 避免通过 DTR/RTS 误触发开发板重启；
- 写入失败时自动关闭并重连；
- 相同场景代码不会重复发送；
- 无法自动判断端口时给出明确配置提示。
最终发送格式非常简单：
0\n -> Left -> Relax
1\n -> Right -> Focus
2\n -> Feet -> Party
在完整展项中，T5AI 场景终端可继续驱动 LCD 画面、RGB 灯效和场景音乐。当前仓库包含 PC 端设备输出适配器；开发板固件属于展项硬件工程，不在本仓库内。
EVOKE 的目标不是在几天内伪装成成熟消费产品，而是在有限时间内证明一条新的交互链路可以闭环运行。
为此，项目加入了多项适合现场展示的工程设计：
- 没有 EEG 硬件时可以使用 Demo Source；
- 没有场景设备时可以使用 Noop Adapter；
- 前端断开 WebSocket 后仍保留演示数据和重连能力。
- 健康检查接口；
- TCP 连接、帧和字节级状态；
- WebSocket 命令确认；
- 信号质量指标；
- 推理阶段与窗口进度；
- 设备输出成功或错误状态。
- TCP 数据源自动重连；
- 串口发送失败后重试；
- T5AI 端口自动识别；
- 前后端状态重新同步；
- Start / Stop 允许现场重新开始一轮推理。
- 数据源与推理解耦；
- 推理与 Web 展示解耦；
- 推理结果与具体设备协议解耦；
- 场景模式与底层运动想象标签解耦。
这意味着黑客松之后可以替换 EEG 设备、升级模型、增加空间模式或接入新的智能硬件，而不需要推翻整套系统。
| 层级 | 技术 |
|---|---|
| EEG 数据 | 8 通道二进制 TCP 流、NumPy |
| 信号处理 | SciPy、Butterworth Bandpass、IIR Notch、Welch PSD、Polyphase Resampling |
| 模型推理 | scikit-learn、Extra Trees Soft-Voting Ensemble、Joblib checkpoint |
| 实时会话 | Python Dataclass、滚动窗口、基线校准、概率平滑 |
| 后端 | FastAPI、Uvicorn、asyncio、WebSocket |
| 设备通信 | PySerial、TCP Socket、HTTP Adapter |
| 前端 | React 18、TypeScript、Vite、Tailwind CSS |
| 2D 可视化 | Canvas Topomap |
| 3D 可视化 | Three.js、React Three Fiber、Drei、GLB |
| 质量保障 | Pytest、TypeScript Check、ESLint、Vite Production Build |
主要目录：
backend/
app/api/ WebSocket 接口
app/services/ 实时 Hub 与 Session
app/core/ 环境配置和管线定义
models/
preprocessing/ 在线滤波
realtime/ 缓冲、重采样、质量、推理、通信、可视化
frontend/
src/components/ 品牌页面、场景页、监控页、2D/3D 脑活动
public/ 视频、字体、二维码和 3D 模型
checkpoints/ 当前部署推理模型
scripts/ 后端启动与模拟 EEG 数据源
tests/ 实时推理与设备输出测试