返回使用指南

BCIKit Studio：安装、构建与连接

说明 macOS 与 Windows 的源码运行和构建路径，以及 Wi‑Fi、蓝牙、8–32 通道与本地数据保存边界。

BCIKit Studio 是 BCIKit 的桌面采集上位机，用于教学、科研原型和开发者实验；它不是医疗器械， 不提供医学诊断结论。

当前支持范围

  • 传输方式：BCIKit Wi-Fi TCP、BCIKit BLE v1。
  • 硬件规模：1–4 块 AFE8 板，即 8–32 通道。连接前选择实际板数；软件会读取设备状态来校验 协商后的配置。
  • Wi-Fi：250 或 500 SPS。
  • 蓝牙：单板支持 250/500 SPS，双板仅支持 250 SPS；三、四板或双板 500 SPS 应使用 Wi-Fi。
  • 交付状态：已提供 Windows x64 单文件 .exe 和 Apple Silicon macOS .dmg 下载包。 当前两个包都未提供平台厂商级签名；macOS 包也尚未公证。

项目使用 Python 3.12。模拟设备只保留给自动化测试，不会出现在交付版用户界面中。

下载已编译版本

请从 GitHub Releases v0.1.0 下载对应平台的文件：

Windows 可能显示 SmartScreen 提示，可确认发布来源后选择继续运行。macOS 当前使用 ad-hoc 临时签名，首次打开若被 Gatekeeper 拦截，请在 Finder 中按住 Control 点按应用并选择“打开”。

从源码启动

安装 Git、uv 与 Python 3.12。请不要使用 macOS 自带的 Python 3.9， 也不要用 Python 3.13 创建本项目环境。

git clone <你的-BCIKit-仓库地址>
cd BCIKit
uv python install 3.12
uv sync --extra dev
uv run bcikit-studio

Windows PowerShell 使用相同命令。若安装后找不到 uv，请重新打开 PowerShell，并确认它已加入 PATH。

在 macOS 构建和安装

首个打包版面向 Apple Silicon。先安装 Xcode Command Line Tools：

xcode-select --install
./scripts/package_macos.sh

构建产物为：

dist/macos/BCIKit Studio.app

将应用移入“应用程序”后打开。第一次蓝牙扫描会请求蓝牙权限。当前包采用本机临时签名；若 macOS 阻止来自可信来源的本机构建，可在 Finder 中按住 Control 点按应用并选择“打开”。源码构建脚本仍会 生成 .app，面向用户的交付包请优先使用上面的 DMG。当前尚不包含 Developer ID 签名和 Apple 公证。

在 Windows 构建和安装

必须在 Windows 上构建 Windows 程序；macOS .app 不能转换为 Windows .exe。安装 Python 3.12、 uv，以及 Visual Studio 2022 Build Tools 中的 C++ 构建工具后执行：

git clone <你的-BCIKit-仓库地址>
Set-Location BCIKit
uv python install 3.12
uv sync --extra dev
New-Item -ItemType Directory -Force .build\windows | Out-Null
Push-Location .build\windows
uv run --project ..\.. pyside6-deploy ..\..\main.py --force --name "BCIKit Studio" --mode standalone --extra-modules "QtOpenGL,QtOpenGLWidgets"
Pop-Location

pyside6-deploy 完成时会打印生成的 .exe 或部署目录。源码构建使用 standalone 模式时，必须 分发完整部署目录，不能只复制其中的 .exe；GitHub Release 提供的正式 Windows 包则是已经验证过的 PyInstaller 单文件版本。分发前请在未安装开发环境的 Windows 机器测试启动、防火墙放行、记录和回放。

Wi-Fi 连接

BCIKit Studio 连接首页：选择板数、Wi-Fi、蓝牙、历史记录与芯片诊断

  1. 在系统网络设置中手动加入设备热点 OpenBCI-XXXX。热点可能没有互联网；请保持连接，并暂时 关闭会改写 192.168.4.x 路由的 VPN。
  2. 在 Studio 首页选择实际板数、采样率后，点击 Wi-Fi 连接。
  3. 允许系统防火墙放行来自设备的临时入站 TCP 连接。Studio 会访问 192.168.4.1、创建本机 TCP listener，并完成 PING → GET_INFO → STOP → SET_* → GET_STATUS → START。

以设备读回配置为准。不要同时让 OpenBCI GUI 或其他 Wi-Fi/蓝牙客户端使用同一设备。

蓝牙连接

  1. 为设备烧录 v0.7.0 或更高版本固件，并开启系统蓝牙。
  2. 点击 蓝牙连接，扫描 BCIKit-XXXX 后选择目标设备。
  3. Studio 会校验 BCIKit BLE 服务，订阅独立的控制和采样通知，再执行与 Wi-Fi 相同的 BCIKit 命令握手。

macOS 首次使用会请求蓝牙权限。Wi-Fi 与蓝牙采集会话互斥；高吞吐或长时间多板记录推荐使用 Wi-Fi。

数据位置与安全

会话仅保存在本地，通常位于：

  • macOS：~/Library/Application Support/BCIKit Studio/sessions/
  • Windows：%LOCALAPPDATA%\BCIKit Studio\sessions\

人体连接时，请使用电池或合规隔离供电，并在连接电极前移除非隔离 USB、调试器、示波器地线和 充电器地线等路径。