◀ 上一章：App 架構 | 下一章：資料流與同步策略 ▶

本文件定義 SolidFocus App 與健身設備之間的藍牙 (BLE) 通訊設計，基於 FTMS v1.0.1 規範與 SolidFocus 客製化需求。

涵蓋內容:

• 支援的設備種類 (Bike)
• GATT Services & Characteristics 定義
• BLE 連線狀態機
• 即時數據解析 (Indoor Bike Data, Rower Data)
• 控制指令發送 (Control Point)
• 錯誤處理與 Retry 策略

3.2.1 支援的裝置種類¶

第一版支援:

• SolidFocus Bike (健身車 - 電控阻力)
  • 廣播名稱: SF-Bike-XXXX
  • 型號: SF-Bike-M1(範例)
  • FTMS Indoor Bike Data (0x2AD2)

3.2.2 廣播封包 (Advertising Packet) 定義¶

為確保 App 能精確識別 SolidFocus 設備，設備端必須在廣播封包中包含以下 AD Types：

Fitness Machine Type (AD Type 0x16 的一部分):

• SF-Bike 必須設置: Bit 5 (Indoor Bike Supported) = 1

App 掃描策略:

• 為避免連接到其他品牌的 FTMS 設備，App 掃描時會優先過濾 Complete Local Name 中包含 SF-Bike- 或 SF-Rower- 的設備
• 同時驗證 Service UUIDs 中包含 0x1826 (FTMS)

3.2.3 GATT Services & Characteristics 概述¶

必要服務:

1. Device Information Service (0x180A)¶

用於識別設備型號與製造商。

2. Fitness Machine Service (0x1826)¶

核心運動數據與控制服務。

3. Battery Service (0x180F) - Optional¶

3.2.4 BLE 連線狀態機 (State Machine)¶

┌────────────────────────────────────────────────────────┐
│                  BLE Connection States                 │
└────────────────────────────────────────────────────────┘

  [Disconnected]
       │
       │ 1. Start Scan (篩選 SF-Bike-XXXX / SF-Rower-XXXX)
       ▼
  [Scanning] ──────────► Device Found
       │                        │
       │ Timeout                │ 2. Connect
       ▼                        ▼
  [Scan Failed]           [Connecting]
                                │
                                │ Success
                                ▼
                          [Connected]
                                │
                                │ 3. Discover Services (0x180A, 0x1826)
                                ▼
                    [Discovering Services]
                                │
                                │ Services Discovered
                                ▼
                        [Services Ready]
                                │
                                │ 4. Read Device Info (0x2A24, 0x2A29)
                                │ 5. Read Feature (0x2ACC)
                                ▼
                        [Feature Read]
                                │
                                │ 6. Subscribe to Notify (0x2AD2, 0x2ADA)
                                ▼
                          [Subscribed]
                                │
                                │ 7. Request Control (0x00)
                                ▼
                          [Controlled]
                                │
                                │ 8. Ready for Workout
                                ▼
                      [Ready / Idle State]

狀態說明:

重要: App 必須按照上述順序執行，否則可能導致控制指令失敗。

3.2.5 Fitness Machine Feature (0x2ACC) 詳細規格¶

此 Characteristic 是 App 識別設備功能的關鍵。設備必須正確設置以下 Bits，App 會根據這些 Bits 動態決定 UI 顯示項目。

Bike - Fitness Machine Features (Table 4.3)¶

Bike - Target Setting Features (Table 4.4)¶

App 動態 UI 建構邏輯:

1. App 連線後先讀取 0x2ACC
2. 檢查 Bit 2 (Resistance Target Setting):
3. 若為 1 → 顯示「阻力控制滑桿」（使用者可調整）
4. 若為 0 → 僅顯示「當前阻力」（唯讀，如 Rower）
5. 檢查 Bit 10 (Heart Rate Measurement):
6. 若為 1 → 顯示「心率」欄位
7. 若為 0 → 不顯示

3.2.6 Indoor Bike Data (0x2AD2) 數據封包結構¶

此 Characteristic 用於推播即時運動數據。封包結構為可變長度，根據 Flags (前 2 bytes) 決定包含哪些欄位。

數據封包結構 (Bike)¶

重要:

• 所有標記為「強制」的欄位必須在 Feature (0x2ACC) 中宣告支援
• App 必須嚴格依照 Flags 解析封包，不能假設欄位順序

範例封包 (16 進位):

[Flags: 0x0964] [Speed: 0x0320] [Cadence: 0x005A] [Distance: 0x0001F4]
[Resistance: 0x000F] [Power: 0x0078] [Calories: 0x0032] [Heart Rate: 0x78]
[Time: 0x012C]

解析:
- Flags = 0x0964 (Bit 2, 5, 6, 8, 9, 11 = 1)
- Speed = 800 × 0.01 = 8.00 km/h
- Cadence = 90 × 0.5 = 45 rpm
- Distance = 500 公尺
- Resistance = 15
- Power = 120 W
- Calories = 50 kcal
- Heart Rate = 120 bpm
- Time = 300 秒 (5 分鐘)

3.2.7 Fitness Machine Control Point (0x2AD9) 控制指令¶

此 Characteristic 用於 App 控制設備行為。App 必須先發送 Request Control (0x00) 取得控制權，才能發送其他指令。

Bike - Control Point Op Codes¶

Control Point 寫入格式:

[Op Code: 1 byte] [Parameter: 0-N bytes]

範例 1: Request Control
→ App 寫入: [0x00]
← Server Indicate: [0x80, 0x00, 0x01] (Success)

範例 2: Set Resistance Level = 15
→ App 寫入: [0x04, 0x0F, 0x00] (Little Endian)
← Server Indicate: [0x80, 0x04, 0x01] (Success)

範例 3: Start
→ App 寫入: [0x07]
← Server Indicate: [0x80, 0x07, 0x01] (Success)

範例 4: Pause
→ App 寫入: [0x08, 0x02]
← Server Indicate: [0x80, 0x08, 0x01] (Success)

Response Code (Indicate): | Byte 0 | Byte 1 | Byte 2 | 說明 | |--------|--------|--------|------| | 0x80 | Request Op Code | 0x01 | Success | | 0x80 | Request Op Code | 0x02 | Op Code Not Supported | | 0x80 | Request Op Code | 0x03 | Invalid Parameter | | 0x80 | Request Op Code | 0x04 | Operation Failed | | 0x80 | Request Op Code | 0x05 | Control Not Permitted |

3.2.8 Fitness Machine Status (0x2ADA) 狀態通知¶

此 Characteristic 用於通知 App 非 App 觸發的事件（如使用者直接操作設備面板）。

Bike - Status Op Codes¶

重要:

• App 必須即時響應 Status 通知，確保 UI 與設備狀態同步
• 特別是 0x02 (暫停) 和 0x07 (阻力變更)，必須立即更新 UI

範例:

使用者在設備上手動調整阻力 → 設備推播:
[0x07, 0x14, 0x00] (阻力調整為 20)
→ App 必須立即更新 UI 上的阻力滑桿位置為 20

3.2.9 More Data Bit 處理機制¶

當單筆數據封包超過 ATT_MTU 限制（通常為 23 bytes）時，設備會將數據拆分為多個 Notify 封包。

拆分機制¶

Server 職責:

1. 將數據拆分為多個封包
2. 前面所有封包的 Flags Bit 0 = 1
3. 最後一包的 Flags Bit 0 = 0
4. 強制欄位（如 Speed, Cadence）必須在最後一包才發送

App 職責:

1. 檢查 Flags Bit 0
2. 若 Bit 0 = 1 → 緩存此封包，等待下一包
3. 若 Bit 0 = 0 → 組合所有緩存封包，視為一筆完整數據
4. 更新 UI

範例流程:

封包 1: [Flags: 0x0001] [Speed: 0x0320] [Cadence: 0x005A] ...
        → Bit 0 = 1 (More Data) → App 緩存

封包 2: [Flags: 0x0000] [Distance: 0x0001F4] [Resistance: 0x000F] ...
        → Bit 0 = 0 (Last) → App 組合封包 1 + 封包 2 → 更新 UI

重要:

• Elapsed Time (Bit 11) 建議在每個封包都包含，方便 App 重組數據
• App 必須實作緩存邏輯，否則會漏失數據

3.2.10 App 實作指南¶

掃描與識別流程¶

1. 自動連線 (優先):
2. App 啟動時，檢查是否有已儲存的設備 ID (Complete Local Name)
3. 若有 → 嘗試直接連線

4. 若連線失敗 → 進入手動搜尋流程

5. 手動搜尋流程:

6. App 開始掃描，篩選 Complete Local Name 包含 SF-Bike- 或 SF-Rower- 的設備
7. 顯示設備列表 (顯示 Complete Local Name)
8. 使用者選擇設備 → 儲存設備 ID → 連線

連線後動態 UI 建構¶

1. 讀取設備型號 (0x180A):
2. Model Number String (0x2A24) → 判斷是 Bike 還是 Rower

3. Manufacturer Name String (0x2A29) → 驗證是否為 SolidFocus

4. 讀取功能特徵 (0x2ACC):

5. 檢查 Bit 2 (Resistance Target Setting):
   • 若為 1 → 顯示阻力控制滑桿（Bike）
   • 若為 0 → 顯示當前阻力（唯讀，Rower）

6. 檢查 Bit 10 (Heart Rate Measurement):

   • 若為 1 → 顯示心率欄位
   • 若為 0 → 不顯示

7. 訂閱數據:

8. 訂閱 Indoor Bike Data (0x2AD2) - Notify
9. 訂閱 Fitness Machine Status (0x2ADA) - Notify

10. 訂閱 Control Point (0x2AD9) - Indicate

11. 取得控制權:

12. 向 Control Point (0x2AD9) 寫入 [0x00] (Request Control)
13. 等待 Indicate 回應 [0x80, 0x00, 0x01] (Success)

運動流程控制¶

開始運動:

1. 使用者選擇課程 → 進入運動畫面
2. App 發送 Reset (0x01) → 重置所有累計數據
3. App 發送 Set Target Resistance Level (0x04) → 設定初始阻力
4. App 發送 Start (0x07) → 開始運動
5. 設備開始推播 Indoor Bike Data (0x2AD2)

阻力調整 (依課程時間軸): - App 根據課程設定，定時發送 Set Target Resistance Level (0x04)

暫停 / 繼續:

• 暫停: App 發送 Stop or Pause (0x08, 0x02)
• 繼續: App 發送 Start or Resume (0x07)

結束運動:

• App 發送 Stop or Pause (0x08, 0x01)
• 顯示訓練完成畫面（顯示累計數據）

處理使用者手動操作¶

當使用者直接操作設備面板時，App 會收到 Fitness Machine Status (0x2ADA) 通知：

3.2.11 Custom Service (設備訓練名稱)¶

⚠️ 待定義 - 需與 SolidFocus 確認 UUID 與格式

用途:

• App 將課程名稱傳送給設備，設備可在螢幕上顯示

預期規格:

• Service UUID: (待定義)
• Characteristic UUID: (待定義)
• 權限: Write
• 格式: UTF-8 字串 (最大長度待定義)

範例:

App 寫入: "20分鐘燃脂訓練" (UTF-8 編碼)
→ 設備螢幕顯示: "20分鐘燃脂訓練"

3.2.12 錯誤處理與 Retry 策略¶

BLE 常見錯誤¶

Response Code 錯誤處理¶

重要原則¶

• ✅ 所有 BLE 錯誤都不應導致 App crash
• ✅ 提供清楚的錯誤訊息給使用者
• ✅ 運動中的資料必須先儲存本機 (避免斷線導致數據遺失)
• ✅ 斷線重連成功後，繼續使用本機儲存的數據
• ✅ 不應無限 retry，避免耗盡電量

🔗 相關章節¶

• 03.1 App 架構 - React Native 技術堆疊與架構
• 03.3 資料流與同步策略 ⭐ - 資料同步核心邏輯

◀ 上一章：App 架構 | 下一章：資料流與同步策略 ▶