com.xrlab.labframe_brainbit 1.1.0 → 1.1.2

package/README.md

@@ -1,237 +1,602 @@
-# LabFrame 2023 - BrainBit Plugin
-
-此套件為 LabFrame 2023 專用的 BrainBit 設備插件，用於連接與管理 BrainBit 腦波儀。
-
-> [!NOTE]
-> 請再記得多安裝此套件 https://github.com/BrainbitLLC/unity_em_st_artifacts.git#a04238a934b3da0494dd9120a489005277063a1f
-> 開發當下此套件最新版(1.0.3)在android平台會有問題
-
-## 支援功能
-1. **設備連線管理：** 自動搜尋並手動觸發連接藍牙 BrainBit 設備。
-2. **EEG 腦波數據收集：** 自動收集四個通道 (T3, T4, O1, O2) 的腦波數據。
-3. **即時阻抗檢查：** 確認電極與頭皮的接觸阻抗值是否過高 (> 200,000Ω)。
-4. **多階段資料分流儲存：** 收集期間可動態切換儲存 Tag（依照遊戲階段無縫寫入不同檔案）。
-5. **情緒與光譜分析：** 透過 NeuroSDK `EegEmotionalMath` 即時運算專注 / 放鬆（MindData）與 δ/θ/α/β/γ 五頻段光譜百分比。
-
----
-
-## 基本使用方式
-
-### 1. 手動觸發設備連線
-預設啟動遊戲時**不會**自動連線，需在適當時間點（例如點擊按鈕或進入準備階段時）透過程式碼手動掃描並連線。
-```csharp
-BrainBitManager.Instance.ManualConnect();
-```
-
----
-
-### 2. 關於 EEG (持續腦波) 的收集方式
-
-#### 👉 開始 / 停止收集
-開始收集時，可傳入對應的遊戲階段 Tag：
-```csharp
-// "Intro_Phase" 將作為存檔檔名的後綴
-BrainBitManager.Instance.StartEEGStream(true, "Intro_Phase");
-
-// 停止收集
-BrainBitManager.Instance.StopEEGStream();
-```
-
-#### 👉 動態無縫切換儲存階段 (Tag)
-當遊戲進入下一個階段時，你**不需**停止收集，只需修改 Tag：
-```csharp
-if (BrainBitManager.Instance.IsStreamingEEG)
-{
-    // 下一毫秒收集的封包，就會被寫進 "Tutorial_Phase" 的檔案中
-    BrainBitManager.Instance.SetEEGTag("Tutorial_Phase");
-}
-```
-
-#### 👉 取得最新的 EEG 值
-若需要在遊戲邏輯中使用即時腦波：
-```csharp
-var eegData = BrainBitManager.Instance.GetLatestEEGData();
-if (eegData != null)
-{
-    Debug.Log($"T3:{eegData.T3} | T4:{eegData.T4} | O1:{eegData.O1} | O2:{eegData.O2}");
-}
-```
-
----
-
-### 3. 關於 Impedance (阻抗) 的檢測方式
-
-> 阻抗 (Impedance) 資料流與 EEG (腦波) 資料流是**獨立**的。通常在實驗或遊戲開始前，先開啟阻抗檢測確認配戴良好，然後停止阻抗檢測，再開始 EEG 腦波收集。
-
-#### 👉 開啟 / 停止阻抗檢測與修改 Tag (與 EEG 邏輯完全相同)
-```csharp
-// 啟動阻抗數據流並儲存至 "Preparation_Impedance"
-BrainBitManager.Instance.StartImpedanceStream(true, "Preparation_Impedance");
-
-// 也可呼叫這個無縫切換 Tag 
-BrainBitManager.Instance.SetImpedanceTag("Another_Phase_Impedance");
-
-// 停止阻抗流
-BrainBitManager.Instance.StopImpedanceStream();
-```
-
-#### 👉 判斷各通道阻抗是否過高與取得數值
-可以在 `Update()` 或檢查迴圈中呼叫此段程式碼，一次取得四個通道的數值與警示結果：
-```csharp
-void CheckImpedanceStatus()
-{
-    // 確保有資料進來
-    var data = BrainBitManager.Instance.GetLatestImpedanceData();
-    if (data == null) return;
-
-    // 直接一次性取得所有數值與 Boolean (各通道大於 200,000 即為 true)
-    var (t3_val, t3_high, t4_val, t4_high, o1_val, o1_high, o2_val, o2_high) = data.GetImpedanceValues();
-
-    // 判斷是否「整體」阻抗都正常 (< 200,000)
-    if (data.IsImpedanceGood)
-    {
-        Debug.Log("✅ 所有通道阻抗良好！可以開始遊戲/實驗了！");
-        // 進入下一階段、開啟 EEG 等等...
-    }
-    else
-    {
-        Debug.LogWarning("❌ 有通道阻抗太高！");
-        
-        // 具體顯示是哪個通道有問題
-        if (t3_high) Debug.LogWarning($"- 左側前額 (T3) 接觸不良，目前數值高達: {t3_val}");
-        if (t4_high) Debug.LogWarning($"- 右側前額 (T4) 接觸不良，目前數值高達: {t4_val}");
-        if (o1_high) Debug.LogWarning($"- 左後腦 (O1) 接觸不良，目前數值高達: {o1_val}");
-        if (o2_high) Debug.LogWarning($"- 右後腦 (O2) 接觸不良，目前數值高達: {o2_val}");
-    }
-}
-```
-
----
-
-### 4. 情緒與光譜分析 (MindData / SpectralData)
-
-整合 NeuroSDK `EegEmotionalMath`，即時取得受測者的**專注度 / 放鬆度**以及**五頻段光譜百分比**。
-
-> 情緒處理需要先完成約 6 秒的**校正** (請受測者安靜配戴)，校正完成後才會開始輸出有效的 MindData / SpectralData。
-
-#### 👉 開始 / 停止情緒處理
-
-```csharp
-// 啟動情緒處理（若 EEG 尚未啟動，會自動開啟；停止時會一併停止該次自動啟動的 EEG）
-BrainBitManager.Instance.StartEmotionsProcessing(
-    autoWriteToLabData: true,
-    mindTag: "Gameplay_Mind",
-    spectralTag: "Gameplay_Spectral");
-
-// 停止情緒處理
-BrainBitManager.Instance.StopEmotionsProcessing();
-```
-
-#### 👉 等待校正完成
-
-```csharp
-BrainBitManager.Instance.OnCalibrationProgress += pct => Debug.Log($"校正中 {pct}%");
-BrainBitManager.Instance.OnCalibrationFinished += () => Debug.Log("校正完成！");
-
-// 或在輪詢中判斷：
-if (BrainBitManager.Instance.IsEmotionsCalibrated)
-{
-    // 此時才能讀到有效的 MindData / SpectralData
-}
-```
-
-若遊戲中需要重新校正（換受測者、中途摘下又戴回）：
-```csharp
-BrainBitManager.Instance.RestartCalibration();
-```
-
-#### 👉 取得最新的專注 / 放鬆值
-
-```csharp
-void Update()
-{
-    if (!BrainBitManager.Instance.IsEmotionsCalibrated) return;
-
-    var mind = BrainBitManager.Instance.GetLatestMindData();
-    if (mind == null) return;
-
-    Debug.Log($"專注: {mind.Attention:F1} / 放鬆: {mind.Relaxation:F1}");
-    // mind.InstAttention / mind.InstRelaxation 為瞬時值（抖動大，僅進階使用）
-}
-```
-
-#### 👉 取得最新的五頻段光譜百分比
-
-```csharp
-var spec = BrainBitManager.Instance.GetLatestSpectralData();
-if (spec != null)
-{
-    Debug.Log($"δ:{spec.Delta:F1} θ:{spec.Theta:F1} α:{spec.Alpha:F1} β:{spec.Beta:F1} γ:{spec.Gamma:F1}");
-}
-```
-
-#### 👉 事件訂閱（event-driven 寫法）
-
-```csharp
-BrainBitManager.Instance.OnMindDataReceived     += mind => { /* 更新 UI */ };
-BrainBitManager.Instance.OnSpectralDataReceived += spec => { /* 更新 UI */ };
-BrainBitManager.Instance.OnEmotionsArtifact     += hasArtifact => { /* 顯示雜訊警告 */ };
-```
-
-#### 👉 動態無縫切換儲存階段 (Tag)
-
-```csharp
-// 不用停情緒處理，下一筆資料就會被寫進新 tag
-BrainBitManager.Instance.SetMindTag("Boss_Phase_Mind");
-BrainBitManager.Instance.SetSpectralTag("Boss_Phase_Spectral");
-```
-
-#### 👉 可調設定（`BrainBitConfig`）
-
-| 欄位 | 預設 | 說明 |
-|---|---|---|
-| `EmotionsCalibrationLength` | `6` | 校正時間（秒）。越長越穩，但受測者需要等更久 |
-| `EmotionsMentalEstimation` | `false` | 啟用 Mental Estimation（依實驗類型決定） |
-| `EmotionsPrioritySide` | `SideType.NONE` | 優先分析腦側：`NONE` / `LEFT` / `RIGHT` |
-
----
-
-### 5. 設備搜尋與多設備選擇機制
-
-預設情況下，`BrainBitManager` 會自動過濾周遭的藍牙設備，只尋找型號為 `SensorLEBrainBit` 的腦波儀。
-
-如果現場有多台 BrainBit 同時開啟，系統如何決定連哪台？
-你可以在 Unity Inspector 或是程式碼中修改 `BrainBitConfig.AutoSelectBestSignal` 的設定：
-
-- **`AutoSelectBestSignal = false`（預設）：** 先搶先贏。系統會直接連線到藍牙掃描名單上的第一台設備。
-- **`AutoSelectBestSignal = true`：** 訊號最強優先。系統會比較所有掃描到的 BrainBit 訊號強度 (RSSI)，並自動連線到訊號最強（距離接收器最近）的那台設備。建議在展位或多人環境中開啟此設定。
-
----
-
-### 6. 實用除錯工具：獲取設備詳細參數
-
-如果需要查看設備底層的詳細資訊（例如：電量、硬體版本、韌體版本、取樣頻率等），可使用內建的解析器 `SensorInfoProvider.cs` 將複雜的底層參數結構化。
-
-```csharp
-using NeuroSDK;
-
-void ShowDeviceInfo(BrainBitSensor sensor)
-{
-    // 將龐雜的系統屬性轉換為易讀的 Dictionary
-    Dictionary<string, string> parameters = SensorInfoProvider.GetBrainBitSensorParameters(sensor);
-
-    foreach (var param in parameters)
-    {
-        Debug.Log($"[{param.Key}]: {param.Value}");
-        // 範例輸出： [BattPower]: 85, [State]: StateInRange, [SamplingFrequency]: 250
-    }
-}
-```
-
----
-
-## 平台需求與建置 (Android / iOS)
-
-本套件已內附相關處理機制：
-- **Android：** 必須包含定位 (`ACCESS_FINE_LOCATION`) 與藍牙及掃描 (`BLUETOOTH_CONNECT`, `BLUETOOTH_SCAN` 等) 權限。相關權限已配置在 `Runtime/Plugins/Android/AndroidManifest.xml` 中，Unity 建置時將自動打包。
-- **iOS：** 打包後製腳本 `BrainBitPostProcess.cs` 會自動為 `Info.plist` 加入必要藍牙權限 (`NSBluetoothAlwaysUsageDescription`)。
+# LabFrame BrainBit Package
+
+LabFrame BrainBit Package 是給 LabFrame 2023 專案使用的 BrainBit 腦波儀套件。它負責搜尋與連接 BrainBit、讀取 EEG 腦波與阻抗資料，並可把資料自動寫入 LabFrame 的資料系統。套件也整合 NeuroSDK 的情緒與頻譜分析，讓實驗或互動專案可以直接取得專注、放鬆與五頻段腦波比例。
+
+這份文件面向使用者與實驗操作人員，重點是怎麼安裝、怎麼戴、怎麼開始錄資料，以及錄出來的資料代表什麼。
+
+## 支援功能
+
+- 搜尋並連接 BrainBit 藍牙低功耗裝置。
+- 讀取 4 通道 EEG：`T3`、`T4`、`O1`、`O2`。
+- 檢查 4 通道阻抗，協助確認電極與頭皮接觸狀態。
+- 依實驗階段用不同 tag 自動寫入 LabFrame 資料。
+- 即時取得專注、放鬆與 `Delta`、`Theta`、`Alpha`、`Beta`、`Gamma` 五頻段百分比。
+- 提供阻抗檢查 UI 控制器與範例場景。
+
+## 設備說明
+
+本套件主要支援實驗室使用的 BrainBit Headband。BrainBit 是 4 通道乾式 EEG 頭帶，透過 Bluetooth LE 連線。官方文件標示 BrainBit 有 `O1`、`O2`、`T3`、`T4` 四個資料通道，每個通道取樣頻率為 250 Hz。
+
+| 通道 | 位置 | 常見用途 |
+|---|---|---|
+| `T3` | 左側顳葉區 | 常用於注意、專注相關節律觀察 |
+| `T4` | 右側顳葉區 | 常用於注意、專注相關節律觀察 |
+| `O1` | 左側枕葉區 | 常用於 alpha、放鬆相關節律觀察 |
+| `O2` | 右側枕葉區 | 常用於 alpha、放鬆相關節律觀察 |
+
+配戴時，前額的參考/共用電極要貼在額頭，`T3`、`T4` 靠近左右顳側，`O1`、`O2` 靠近後腦枕側。頭帶要貼合但不需要勒緊；如果阻抗過高，通常代表接觸不穩、頭髮擋住電極、頭帶位置偏移，或裝置電極沒有確實貼到皮膚。
+
+本套件不是醫療診斷工具。EEG、專注、放鬆與頻譜資料適合用於研究、教育、互動體驗與實驗紀錄，不應直接解讀為醫療結論。
+
+## 安裝
+
+### 1. Unity 與 LabFrame
+
+- 建議 Unity 版本：`2022.3.62f2`，或同系列 `2022.3` LTS。
+- 需要 LabFrame package：`com.xrlab.labframe`。
+- 本 package 的 `package.json` 已依賴 BrainBit `NeuroSDK2`。
+
+### 2. 安裝情緒/頻譜分析套件
+
+此 package 的情緒與頻譜功能會使用 `SignalMath`，請在 Unity Package Manager 加入下列 Git URL：
+
+```text
+https://github.com/BrainbitLLC/unity_em_st_artifacts.git#a04238a934b3da0494dd9120a489005277063a1f
+```
+
+目前建議使用上面的固定 commit。開發時曾遇過較新的 Android 版本套件相容性問題，因此不要任意升級到最新版，除非你已經重新測試 Android build。
+
+### 3. 平台權限
+
+Android 權限已放在：
+
+```text
+Packages/LabFrame_Brainbit/Runtime/Plugins/Android/AndroidManifest.xml
+```
+
+它包含定位、Bluetooth scan、Bluetooth connect 等權限。實機第一次啟動時仍可能需要使用者允許權限。
+
+iOS build 後處理會自動加入藍牙用途文字：
+
+```text
+NSBluetoothAlwaysUsageDescription
+NSBluetoothPeripheralUsageDescription
+```
+
+## 建議使用流程
+
+1. 開啟 BrainBit，確認電量足夠。
+2. 在手機、平板或電腦開啟藍牙，並允許 App 使用藍牙與定位權限。
+3. 戴上 BrainBit，調整前額與左右/後方電極位置。
+4. 呼叫 `ManualConnect()` 或使用範例 UI 連線。
+5. 先開啟阻抗檢查，確認 4 個通道接觸穩定。
+6. 停止阻抗檢查。
+7. 開始 EEG 錄製，並用 tag 標示實驗階段。
+8. 若需要專注、放鬆或頻譜資料，啟動情緒處理並等待校正完成。
+9. 實驗階段切換時，用 `SetEEGTag()`、`SetMindTag()`、`SetSpectralTag()` 切換資料 tag。
+10. 結束時停止情緒處理、EEG 與阻抗串流，必要時斷線。
+
+## 快速開始
+
+### 連接設備
+
+預設不會在遊戲啟動時自動連線。請在開始畫面、準備階段或使用者按下按鈕時呼叫：
+
+```csharp
+BrainBitManager.Instance.ManualConnect();
+```
+
+斷線：
+
+```csharp
+BrainBitManager.Instance.ManualDisconnect();
+```
+
+常用狀態：
+
+```csharp
+bool connected = BrainBitManager.Instance.IsConnected;
+bool scanning = BrainBitManager.Instance.IsScanning;
+string deviceName = BrainBitManager.Instance.ConnectedDeviceName;
+string deviceAddress = BrainBitManager.Instance.ConnectedDeviceAddress;
+```
+
+### 阻抗檢查
+
+阻抗資料用來確認電極接觸品質。建議在正式錄 EEG 前先檢查阻抗，確認通道穩定後再開始實驗。
+
+```csharp
+BrainBitManager.Instance.StartImpedanceStream(
+    autoWriteToLabData: false,
+    tag: "precheck_impedance");
+```
+
+讀取目前阻抗：
+
+```csharp
+var impedance = BrainBitManager.Instance.GetLatestImpedanceData();
+if (impedance != null)
+{
+    Debug.Log(impedance.ToString());
+
+    if (impedance.IsImpedanceGood)
+    {
+        Debug.Log("All channels are ready.");
+    }
+    else
+    {
+        Debug.LogWarning(impedance.GetImpedanceStatus());
+    }
+}
+```
+
+停止阻抗檢查：
+
+```csharp
+BrainBitManager.Instance.StopImpedanceStream();
+```
+
+本套件目前用 `200000` ohm 作為預設警示門檻。若任何通道高於此值，`IsImpedanceGood` 會是 `false`。
+
+### EEG 錄製
+
+開始 EEG：
+
+```csharp
+BrainBitManager.Instance.StartEEGStream(
+    autoWriteToLabData: true,
+    tag: "baseline_eeg");
+```
+
+取得最新 EEG：
+
+```csharp
+var eeg = BrainBitManager.Instance.GetLatestEEGData();
+if (eeg != null)
+{
+    Debug.Log($"T3:{eeg.T3} T4:{eeg.T4} O1:{eeg.O1} O2:{eeg.O2}");
+}
+```
+
+切換實驗階段時，不需要停止 EEG，可以直接改 tag：
+
+```csharp
+BrainBitManager.Instance.SetEEGTag("task1_eeg");
+```
+
+停止 EEG：
+
+```csharp
+BrainBitManager.Instance.StopEEGStream();
+```
+
+### 專注、放鬆與五頻段資料
+
+情緒處理會使用 EEG 訊號計算 MindData 與 SpectralData。啟動後需要先校正，預設校正時間為 6 秒。校正完成前 `GetLatestMindData()` 與 `GetLatestSpectralData()` 可能回傳 `null`。
+
+啟動：
+
+```csharp
+BrainBitManager.Instance.StartEmotionsProcessing(
+    autoWriteToLabData: true,
+    mindTag: "baseline_mind",
+    spectralTag: "baseline_spectral");
+```
+
+監聽校正：
+
+```csharp
+BrainBitManager.Instance.OnCalibrationProgress += progress =>
+{
+    Debug.Log($"Calibration: {progress}%");
+};
+
+BrainBitManager.Instance.OnCalibrationFinished += () =>
+{
+    Debug.Log("Calibration finished.");
+};
+```
+
+讀取專注與放鬆：
+
+```csharp
+if (BrainBitManager.Instance.IsEmotionsCalibrated)
+{
+    var mind = BrainBitManager.Instance.GetLatestMindData();
+    if (mind != null)
+    {
+        Debug.Log($"Attention:{mind.Attention:F1} Relaxation:{mind.Relaxation:F1}");
+    }
+}
+```
+
+讀取五頻段百分比：
+
+```csharp
+var spectral = BrainBitManager.Instance.GetLatestSpectralData();
+if (spectral != null)
+{
+    Debug.Log(
+        $"Delta:{spectral.Delta:F1} " +
+        $"Theta:{spectral.Theta:F1} " +
+        $"Alpha:{spectral.Alpha:F1} " +
+        $"Beta:{spectral.Beta:F1} " +
+        $"Gamma:{spectral.Gamma:F1}");
+}
+```
+
+切換 tag：
+
+```csharp
+BrainBitManager.Instance.SetMindTag("task1_mind");
+BrainBitManager.Instance.SetSpectralTag("task1_spectral");
+```
+
+停止：
+
+```csharp
+BrainBitManager.Instance.StopEmotionsProcessing();
+```
+
+若中途換受測者、頭帶取下後重新戴上，或資料明顯不穩，可以重新校正：
+
+```csharp
+BrainBitManager.Instance.RestartCalibration();
+```
+
+## 完整範例程式
+
+以下範例示範一個常見實驗流程：連線、檢查阻抗、開始錄 EEG 與情緒資料、切換階段、結束錄製。
+
+```csharp
+using UnityEngine;
+
+public class BrainBitSessionExample : MonoBehaviour
+{
+    private void OnEnable()
+    {
+        BrainBitManager.Instance.OnConnectionStatusChanged += HandleConnectionChanged;
+        BrainBitManager.Instance.OnCalibrationProgress += HandleCalibrationProgress;
+        BrainBitManager.Instance.OnCalibrationFinished += HandleCalibrationFinished;
+        BrainBitManager.Instance.OnError += HandleError;
+    }
+
+    private void OnDisable()
+    {
+        if (BrainBitManager.Instance == null) return;
+
+        BrainBitManager.Instance.OnConnectionStatusChanged -= HandleConnectionChanged;
+        BrainBitManager.Instance.OnCalibrationProgress -= HandleCalibrationProgress;
+        BrainBitManager.Instance.OnCalibrationFinished -= HandleCalibrationFinished;
+        BrainBitManager.Instance.OnError -= HandleError;
+    }
+
+    public void ConnectBrainBit()
+    {
+        BrainBitManager.Instance.ManualConnect();
+    }
+
+    private void HandleConnectionChanged(bool connected)
+    {
+        if (!connected) return;
+
+        Debug.Log($"Connected: {BrainBitManager.Instance.ConnectedDeviceName}");
+
+        BrainBitManager.Instance.StartImpedanceStream(
+            autoWriteToLabData: false,
+            tag: "precheck_impedance");
+    }
+
+    public void StartRecordingIfReady()
+    {
+        var impedance = BrainBitManager.Instance.GetLatestImpedanceData();
+        if (impedance == null || !impedance.IsImpedanceGood)
+        {
+            Debug.LogWarning("BrainBit impedance is not ready. Adjust the headband first.");
+            return;
+        }
+
+        BrainBitManager.Instance.StopImpedanceStream();
+
+        BrainBitManager.Instance.StartEEGStream(
+            autoWriteToLabData: true,
+            tag: "baseline_eeg");
+
+        BrainBitManager.Instance.StartEmotionsProcessing(
+            autoWriteToLabData: true,
+            mindTag: "baseline_mind",
+            spectralTag: "baseline_spectral");
+    }
+
+    public void SetExperimentPhase(string phaseName)
+    {
+        BrainBitManager.Instance.SetEEGTag($"{phaseName}_eeg");
+        BrainBitManager.Instance.SetMindTag($"{phaseName}_mind");
+        BrainBitManager.Instance.SetSpectralTag($"{phaseName}_spectral");
+    }
+
+    private void Update()
+    {
+        if (!BrainBitManager.Instance.IsEmotionsCalibrated) return;
+
+        var mind = BrainBitManager.Instance.GetLatestMindData();
+        var spectral = BrainBitManager.Instance.GetLatestSpectralData();
+
+        if (mind != null)
+        {
+            Debug.Log($"Attention:{mind.Attention:F1} Relaxation:{mind.Relaxation:F1}");
+        }
+
+        if (spectral != null)
+        {
+            Debug.Log($"Alpha:{spectral.Alpha:F1} Beta:{spectral.Beta:F1}");
+        }
+    }
+
+    public void StopRecording()
+    {
+        BrainBitManager.Instance.StopEmotionsProcessing();
+        BrainBitManager.Instance.StopEEGStream();
+        BrainBitManager.Instance.StopImpedanceStream();
+    }
+
+    private void HandleCalibrationProgress(int progress)
+    {
+        Debug.Log($"Calibration progress: {progress}%");
+    }
+
+    private void HandleCalibrationFinished()
+    {
+        Debug.Log("BrainBit emotion calibration finished.");
+    }
+
+    private void HandleError(string message)
+    {
+        Debug.LogError($"BrainBit error: {message}");
+    }
+}
+```
+
+## 範例場景
+
+本 repo 內有一個範例場景：
+
+```text
+Packages/LabFrame_Brainbit/Sample/SampleScene.unity
+```
+
+範例場景使用 `BrainBitCheckController` 顯示連線狀態、阻抗數值與阻抗警示。它適合拿來做實驗前的配戴檢查畫面，也可以直接參考按鈕如何呼叫 `BrainBitManager`。
+
+## 資料格式
+
+當 `autoWriteToLabData` 設為 `true` 且 `LabDataManager` 已初始化時，套件會把資料物件寫入 LabFrame。實際檔案位置與檔案格式由 LabFrame 專案設定決定；下面列的是本套件交給 LabFrame 的資料欄位。
+
+### EEG：`BrainBit_EEGData`
+
+| 欄位 | 型別 | 單位 | 說明 |
+|---|---|---|---|
+| `T3` | `double` | V | 左側顳葉通道 EEG |
+| `T4` | `double` | V | 右側顳葉通道 EEG |
+| `O1` | `double` | V | 左側枕葉通道 EEG |
+| `O2` | `double` | V | 右側枕葉通道 EEG |
+| `EEGValues` | `List<double>` | V | 順序為 `T3`、`T4`、`O1`、`O2` |
+
+BrainBit 官方資料流每通道為 250 samples/sec。本套件保留最新一筆 EEG，可用 `GetLatestEEGData()` 取得。
+
+### 阻抗：`BrainBit_ImpedanceData`
+
+| 欄位 | 型別 | 單位 | 說明 |
+|---|---|---|---|
+| `T3` | `double` | ohm | 左側顳葉通道阻抗 |
+| `T4` | `double` | ohm | 右側顳葉通道阻抗 |
+| `O1` | `double` | ohm | 左側枕葉通道阻抗 |
+| `O2` | `double` | ohm | 右側枕葉通道阻抗 |
+| `ImpedanceValues` | `List<double>` | ohm | 順序為 `T3`、`T4`、`O1`、`O2` |
+| `IsImpedanceGood` | `bool` | 無 | 4 通道都低於 `200000` ohm 時為 `true` |
+
+輔助方法：
+
+```csharp
+string status = impedance.GetImpedanceStatus();
+var values = impedance.GetImpedanceValues();
+```
+
+### 專注與放鬆：`BrainBit_MindData`
+
+| 欄位 | 型別 | 範圍 | 說明 |
+|---|---|---|---|
+| `Attention` | `double` | 約 0-100 | 相對專注度，較平滑，建議顯示給使用者 |
+| `Relaxation` | `double` | 約 0-100 | 相對放鬆度，較平滑，建議顯示給使用者 |
+| `InstAttention` | `double` | 約 0-100 | 瞬時專注度，波動較大 |
+| `InstRelaxation` | `double` | 約 0-100 | 瞬時放鬆度，波動較大 |
+
+MindData 必須等 `IsEmotionsCalibrated == true` 後才有穩定意義。
+
+### 五頻段百分比：`BrainBit_SpectralData`
+
+| 欄位 | 型別 | 單位 | 說明 |
+|---|---|---|---|
+| `Delta` | `double` | percent | Delta 波百分比 |
+| `Theta` | `double` | percent | Theta 波百分比 |
+| `Alpha` | `double` | percent | Alpha 波百分比 |
+| `Beta` | `double` | percent | Beta 波百分比 |
+| `Gamma` | `double` | percent | Gamma 波百分比 |
+
+### 連線事件：`BrainBit_ConnectionData`
+
+| 欄位 | 型別 | 說明 |
+|---|---|---|
+| `IsConnected` | `bool` | 連線狀態 |
+| `DeviceName` | `string` | BrainBit 裝置名稱 |
+| `DeviceAddress` | `string` | BrainBit 裝置位址 |
+| `EventType` | `string` | `Connected`、`Disconnected`、`EEG_Stream_Started` 等事件 |
+
+## Tag 與資料分段
+
+`tag` 是寫入 LabFrame 時用來區分資料階段的名稱。建議使用清楚且穩定的命名，例如：
+
+```text
+baseline_eeg
+baseline_mind
+baseline_spectral
+task1_eeg
+task1_mind
+task1_spectral
+rest_impedance
+```
+
+EEG、MindData、SpectralData 都可以在不中斷串流的情況下切換 tag：
+
+```csharp
+BrainBitManager.Instance.SetEEGTag("task2_eeg");
+BrainBitManager.Instance.SetMindTag("task2_mind");
+BrainBitManager.Instance.SetSpectralTag("task2_spectral");
+```
+
+下一筆寫入的資料會使用新的 tag。
+
+## 事件 API
+
+若你不想在 `Update()` 裡輪詢，可以訂閱事件：
+
+```csharp
+BrainBitManager.Instance.OnEEGDataReceived += data =>
+{
+    Debug.Log(data.ToString());
+};
+
+BrainBitManager.Instance.OnImpedanceDataReceived += data =>
+{
+    Debug.Log(data.GetImpedanceStatus());
+};
+
+BrainBitManager.Instance.OnMindDataReceived += data =>
+{
+    Debug.Log($"Attention:{data.Attention:F1}");
+};
+
+BrainBitManager.Instance.OnSpectralDataReceived += data =>
+{
+    Debug.Log($"Alpha:{data.Alpha:F1}");
+};
+
+BrainBitManager.Instance.OnEmotionsArtifact += hasArtifact =>
+{
+    if (hasArtifact)
+    {
+        Debug.LogWarning("BrainBit signal artifact detected.");
+    }
+};
+```
+
+## 設定項目
+
+`BrainBitConfig` 可控制掃描、重連與情緒校正行為。
+
+| 欄位 | 預設 | 說明 |
+|---|---:|---|
+| `AutoConnectOnInit` | `false` | Manager 初始化後是否自動掃描連線 |
+| `DisconnectNotification` | `true` | 斷線時是否顯示提示 |
+| `ScanTimeoutSeconds` | `10.0` | 掃描逾時秒數 |
+| `ImpedanceWarningThreshold` | `200000.0` | 阻抗警示參考門檻，單位 ohm |
+| `AutoReconnectAttempts` | `3` | 斷線後自動重連嘗試次數 |
+| `ReconnectIntervalSeconds` | `2.0` | 重連間隔秒數 |
+| `AutoSelectBestSignal` | `false` | 多台 BrainBit 時是否選 RSSI 最強者 |
+| `TargetDeviceAddress` | `""` | 優先連線的 BrainBit MAC；留空時維持原本選台行為 |
+| `ConnectDelaySeconds` | `1.0` | 停止掃描後等待多久才建立連線 |
+| `EmotionsCalibrationLength` | `6` | 情緒處理校正秒數 |
+| `EmotionsMentalEstimation` | `false` | 是否啟用 Mental Estimation |
+| `EmotionsPrioritySide` | `SideType.NONE` | 情緒分析優先腦側：`NONE`、`LEFT`、`RIGHT` |
+
+如果現場同時有多台 BrainBit，建議用 `TargetDeviceAddress` 優先指定 MAC。設定後，掃描會先尋找該 MAC；如果連續 3 次、每次間隔 2 秒的掃描結果都沒有看到目標，系統會改用原本的選台策略尋找其他 BrainBit。`AutoSelectBestSignal` 只建議在沒有指定 MAC、或目標 MAC 找不到後可接受用 RSSI 選台時使用。
+
+Android 實機若要每台頭顯綁定不同 BrainBit，請在各裝置的 `Application.persistentDataPath/Config/BrainBitConfig.json` 放完整設定檔，例如：
+
+```json
+{
+    "AutoConnectOnInit": false,
+    "DisconnectNotification": true,
+    "ScanTimeoutSeconds": 20.0,
+    "ImpedanceWarningThreshold": 200000.0,
+    "AutoReconnectAttempts": 3,
+    "ReconnectIntervalSeconds": 2.0,
+    "AutoSelectBestSignal": false,
+    "ConnectDelaySeconds": 1.0,
+    "EmotionsCalibrationLength": 6,
+    "EmotionsMentalEstimation": false,
+    "EmotionsPrioritySide": 0,
+    "TargetDeviceAddress": "E0:39:7A:68:75:58"
+}
+```
+
+若裝置上已有舊版 `BrainBitConfig.json`，請整檔覆蓋成最新欄位；磁碟上的設定會優先於內建範本。
+
+目前 `BrainBit_ImpedanceData.IsImpedanceGood` 使用 `200000` ohm 作為判斷門檻；若你的實驗需要不同標準，請在 UI 或檢查流程中使用自訂門檻判斷。
+
+## 設備資訊查詢
+
+需要查看電量、韌體版本、硬體版本、取樣頻率等資訊時，可使用 `SensorInfoProvider`：
+
+```csharp
+using NeuroSDK;
+using System.Collections.Generic;
+
+void ShowDeviceInfo(BrainBitSensor sensor)
+{
+    Dictionary<string, string> parameters =
+        SensorInfoProvider.GetBrainBitSensorParameters(sensor);
+
+    foreach (var item in parameters)
+    {
+        Debug.Log($"{item.Key}: {item.Value}");
+    }
+}
+```
+
+一般使用者不一定需要呼叫這段。它比較適合現場除錯、確認電量與確認裝置版本。
+
+## 常見問題
+
+### 掃不到設備
+
+- 確認 BrainBit 已開機且有電。
+- 確認 App 已允許藍牙、定位與附近裝置權限。
+- 確認 BrainBit 沒有被其他 App 或其他手機連線。
+- 把 BrainBit 靠近執行 App 的裝置後再掃描。
+- 如果現場有多台 BrainBit，優先在 `TargetDeviceAddress` 填入指定 MAC；若目標連續 3 次、每次間隔 2 秒的掃描都找不到，Manager 會改找其他設備。
+
+### 阻抗一直太高
+
+- 調整頭帶位置，讓 `T3`、`T4`、`O1`、`O2` 更貼近頭皮。
+- 撥開頭髮，避免頭髮卡在電極與頭皮之間。
+- 確認前額參考電極有貼住皮膚。
+- 讓受測者先保持不動，再觀察數值是否下降。
+- 若只有單一通道高，優先調整該通道所在的位置。
+
+### MindData 或 SpectralData 一直是空的
+
+- 確認已呼叫 `StartEmotionsProcessing()`。
+- 確認 EEG 正在輸入。
+- 等待 `OnCalibrationFinished` 或 `IsEmotionsCalibrated == true`。
+- 校正期間請受測者保持安靜、少眨眼、少咬牙、少說話。
+- 若中途重新配戴，呼叫 `RestartCalibration()`。
+
+### 資料沒有寫入 LabFrame
+
+- 確認呼叫串流時 `autoWriteToLabData` 是 `true`。
+- 確認 `LabDataManager.Instance.IsInited` 為 `true`。
+- 確認 tag 不為空字串。
+- 確認有呼叫 `StartEEGStream()` 或 `StartEmotionsProcessing()`。
+
+### Android build 或執行出錯
+
+- 確認已安裝 `unity_em_st_artifacts` 固定 commit。
+- 確認 Android 權限已在實機上允許。
+- 若使用較新的 Android 版本，請特別檢查 `BLUETOOTH_SCAN` 與 `BLUETOOTH_CONNECT` 權限。
+
+## 官方參考
+
+- BrainBit SDK - Receiving data: https://sdk.brainbit.com/sdk2_bb/
+- BrainBit SDK - Device recommendation: https://sdk.brainbit.com/device-recommendation/
+- BrainBit SDK - Emotions library: https://sdk.brainbit.com/lib-emotions/
+- BrainBit SDK - Overview and supported platforms: https://sdk.brainbit.com/sdk2_overview/