跳至主要内容

BLE 通訊規格（WhizToys 藍牙控制盒）

本文件定義 WhizToys 藍牙控制盒所使用的 BLE（Bluetooth Low Energy）GATT Profile，供第三方開發者與系統整合商進行對接開發。

1. WhizToys Profile 架構​

WhizToys 藍牙控制盒作為 BLE 週邊設備（Peripheral），曝露廣播訊息等待手機或其他中心設備連接。連接後停止廣播。Profile 架構如下：

層級項目
ProfileWhizToys Profile
├ ServiceGAP Service（0x1800）
├ ServiceGATT Service（0x1801）
└ Service客製化 Service（0000FEE0-0000-1000-8000-00805F9B34FB）
　├ CharacteristicLayout 資訊
　├ CharacteristicSensor 資訊
　└ CharacteristicLED 控制資訊

2. GAP Service（0x1800）​

標準 BLE 強制實現的服務，包含裝置名稱、外觀及連線參數。

特徵UUID屬性Value說明
Device Name0x2A00Read | Write數組讀取/寫入裝置名稱
Appearance0x2A01Read數組讀取裝置外觀
Peripheral Preferred Connection Parameters0x2A04Read數組讀取週邊設備期望的連線參數

3. GATT Service（0x1801）​

GATT Profile 自定義的服務，包含 "Service Changed" 特徵。當 Service 的 GATT 屬性分佈有變（增加或移除），Server 可透過此特徵通知 Client。

4. 客製化 Service（0x FEE0）​

UUID： 0000FEE0-0000-1000-8000-00805F9B34FB

WhizToys 硬體的核心服務，提供按壓感測資訊與 LED 燈光控制功能。巧拼開機後會自動進行 Mapping Layout，探索巧拼之間的相對位置關係。

此服務包含三個 Characteristics：

屬性UUIDProperties說明
Layout 資訊0000FEE1-0000-1000-8000-00805F9B34FBRead讀取巧拼 Layout
感測器資訊0000FEE2-0000-1000-8000-00805F9B34FBNotify通知感測變化數值
LED 控制指令0000FEE3-0000-1000-8000-00805F9B34FBWrite寫入 LED 燈控制指令

5. 特徵數值設定​

5.1 Layout 資訊（0xFEE1）— Read​

巧拼完成 Mapping 動作後進入感測及待命狀態，Layout 資訊儲存於控制盒中，重新開啟之前不會再改變。設計為一次性 Read 取得。

封包格式（20 bytes）：

Byte 0Byte 1Byte 2...Byte n-1
Layout Row and Column4 Sensor States4 Sensor States...Check Sum

Layout Row and Column（Byte 0）​

一個 byte 拆為兩個 4-bit：

  • 高 4 bit：Layout Row（列數）
  • 低 4 bit：Layout Col（行數）

例如 00010001₂ = 0x11：Row = 1, Col = 1，代表一行一列。

4 Sensor States（Byte 1 ~ n-2）​

每個 byte 代表 4 個感測器的狀態，每 2 bit 代表一個感測器：

二進制十進制感測器狀態
000無拼接巧拼
011無按壓
102按壓中

4 個感測器排列方式為橫向計算的 4 個感測器。

範例 — 兩片巧拼以 1×2 方式拼接，從資料中取得的 8 個感測器狀態排列方式為由左至右、由上到下：

資料：[00010010, 01011010, 01011010, checksum]

解析 Layout：Row=1, Col=2（一列兩行）

感測器矩陣（每片巧拼 4 個感測器）：
┌──────────┬──────────┐
│ 01    01 │ 10    10 │
│          │          │
│ 01    01 │ 10    10 │
└──────────┴──────────┘
 巧拼 1      巧拼 2
 (無按壓)    (按壓中)

Check Sum（最後 1 byte）​

所有資料 byte 經 XOR 運算後的校驗值，確保資料完整傳輸。

5.2 感測器資訊（0xFEE2）— Notify​

啟用 Notify 後，當巧拼被踩踏或腳離開時觸發感測器數值變化通知。

封包格式（20 bytes，每 2 bytes 為一組）：

Byte 0Byte 1Byte 2Byte 3...
感測器變化位置（一）4 個感測器狀態（一）感測器變化位置（二）4 個感測器狀態（二）...

感測器變化位置​

一個 byte 拆為兩個 4-bit：

  • 高 4 bit：Layout Row Index（列索引，從 0 開始）
  • 低 4 bit：Layout Col Index（行索引，從 0 開始）

例如 00010000₂ = 0x10：Row Index = 1, Col Index = 0，代表第二列第一行的巧拼。

4 個感測器狀態​

一個 byte 分成 4 組各 2 bit，分別代表左上、左下、右下、右上四個位置的感測器狀態：

值感測器狀態
00無按壓
01Level 1
10Level 2
11Level 3

例如 00001100₂ = 0x0C：左上=無按壓、左下=無按壓、右下=Level 3、右上=無按壓。

5.3 LED 控制指令（0xFEE3）— Write​

客戶端透過 Write 傳入燈光控制指令。

封包格式（20 bytes）：

Byte 0Byte 1~3Byte 4~6...Byte 3n+1
後續資料長度燈光控制指令燈光控制指令...Check Sum

每組燈光控制指令為 3 bytes：

Byte欄位說明
0LocationLED 位於 Layout 中的位置
1Mode燈光控制模式
2Color顏色編號

Location​

格式同感測器變化位置：高 4 bit = Row Index，低 4 bit = Col Index。

Mode（8 bit 拆解）​

Bit用途範圍數值含義
1~3亮燈位置0~70 整片亮、1 左上單獨亮、2 左下單獨亮、3 右下單獨亮、4 右上單獨亮、5 全部單獨亮
4觸發機制0~10 直接觸發一次回饋、1 踩踏後觸發
5~7回饋模式0~70 不指定（直接控制燈光）、1 踩踏無回饋、2 基本、3 閃爍、4 跑馬燈、5 呼吸燈、6 霓虹燈
8回饋時間長短0~10 短、1 長（影響閃爍及跑馬燈速度）
整片亮模式

當 bit 1~3 設定為 0（整片亮），無論踩踏哪個位置感測器，4 顆 LED 會一起亮燈。

Color（顏色編號）​

使用 1 byte 的顏色編號索引，對應預定義的 62 色 RGB 色表：

編號RGB顏色
00000黑（熄滅）
0125500紅色
02~1025525~2250紅→黃漸變
112552550黃色
12~20225~252550黃→綠漸變
2102550綠色
22~30025525~225綠→淺藍漸變
310255255淺藍
32~400225~25255淺藍→藍漸變
4100255藍色
42~5025~2250255藍→紫漸變
512550255紫色
52~602550225~25紫→紅漸變
61255255255白色
完整 62 色 RGB 對照表
編號RGB顏色
00000—
0125500紅色
02255250
03255500
04255750
052551000
062551250
072551500
082551750
092552000
102552250
112552550黃色
122252550
132002550
141752550
151502550
161252550
171002550
18752550
19502550
20252550
2102550綠色
22025525
23025550
24025575
250255100
260255125
270255150
280255175
290255200
300255225
310255255淺藍
320225255
330200255
340175255
350150255
360125255
370100255
38075255
39050255
40025255
4100255藍色
42250255
43500255
44750255
451000255
461250255
471500255
481750255
492000255
502250255
512550255紫色
522550225
532550200
542550175
552550150
562550125
572550100
58255075
59255050
60255025
61255255255白色

6. 連線流程（建議）​

sequenceDiagram
    participant App
    participant 控制盒

    App->>控制盒: 掃描 BLE 廣播
    App->>控制盒: 發起連線
    控制盒-->>App: 連線建立，停止廣播
    App->>控制盒: 讀取 GAP Service（裝置名稱、連線參數）
    App->>控制盒: 讀取 Layout 資訊（0xFEE1）
    App->>控制盒: 啟用 Sensor 資訊 Notify（0xFEE2）
    控制盒-->>App: 推送感測器變化資料
    App->>控制盒: 寫入 LED 控制指令（0xFEE3）

7. 開發注意事項​

  1. Mapping 時機：控制盒開機後會自動進行 Mapping Layout，此過程中請勿踩踏地墊。Mapping 完成後才能讀取 Layout 資訊。
  2. 資料長度：Layout 資訊、感測器資訊、LED 控制指令的封包長度皆為 20 bytes。
  3. Check Sum：所有封包最後一個 byte 為 XOR 校驗值，接收端應驗證資料完整性。
  4. Index 起始值：Row Index 與 Col Index 皆從 0 開始計算。
  5. Android 權限：Android 12+ 需要 BLUETOOTH_SCAN、BLUETOOTH_CONNECT 權限；Android 11 以下需要 ACCESS_FINE_LOCATION。
  6. iOS 限制：iOS 不支援讀取 BLE MAC Address，請使用廣播名稱或 Service UUID 進行裝置識別。

版本紀錄​

版本日期說明
1.02023-03-02原始 WhizToys 客製化藍牙規範文件
1.12026-04-08轉換為線上文件格式
聯絡我們

如需取得完整的 SDK 或有技術整合相關問題，請聯繫：support@seda-gtech.com.tw