# GF AI Box — 測試人員操作指南

> 文件版本：v2.0
> 適用韌體：gf_ai_box_v4
> 更新日期：2026-06-14

---

## 一、測試環境準備

### 所需工具
- 藍芽串口工具（iOS：LightBlue / Serial Bluetooth Terminal；Android：Serial Bluetooth Terminal）
- CAN bus 分析儀（選配，用於驗證 CAN 訊號）
- 油門踏板（CAN 測試時需要）

### 連線方式
1. 開啟藍芽工具，掃描並連線到 AI Box 的 BLE 裝置
2. 完成握手後即可送出指令
3. 指令為**純文字**，大小寫不分，直接輸入後送出

### 重要說明
- **硬體 Reset 後預設為正常模式**，必須先送 `test_enter` 才能執行測試指令
- 進入測試模式後，AI Box 的 AI 推論結果暫停處理（NPU 繼續運算但不派發事件）
- 測試模式下如果 **60 秒無任何指令**，系統會自動退出測試模式並恢復正常
- 若 TEST_ALL 系列正在執行，請勿重複送出測試指令

---

## 二、基本控制指令

| 指令 | 說明 | 預期回覆 |
|------|------|---------|
| `test_enter` | 進入測試模式 | `TEST_ACK ENTER` |
| `test_exit`  | 退出測試模式，恢復正常 | `TEST_EXIT_OK` |

---

## 三、大項一：BLE JSON 測試

**測試目的**：驗證各警示事件觸發時，藍芽送出的 JSON 格式與內容正確。
**注意**：只送出 BLE JSON，**不觸發** CAN bus 指令與 Buzzer。

### 3.1 單項測試指令

#### Violation（草地違規）

| 指令 | 說明 | 預期 BLE 回傳 JSON |
|------|------|-----------------|
| `test_ble violation 1` | 觸發 violation level=1 | `{"response_type":"violation","content":{"id":"...","date":"...","type":"lane","level":1}}` |
| `test_ble violation 0` | 解除 violation | `{"response_type":"violation","content":{"id":"...","date":"...","type":"lane","level":0}}` |

#### Collision（碰撞警示）

| 指令 | 說明 | 預期 BLE 回傳 JSON |
|------|------|-----------------|
| `test_ble collision 1` | 觸發 collision level=1（type=vehicle）| `{"response_type":"collision_warning","content":{"level":1,"type":"vehicle"}}` |
| `test_ble collision 0` | 解除 collision | `{"response_type":"collision_warning","content":{"level":0,"type":null}}` |

#### Alert（方向警示）

| 指令 | 說明 | 預期 BLE 回傳 JSON |
|------|------|-----------------|
| `test_ble alert 1 tree 0 null` | 左側 tree 警示，右側無 | `{"response_type":"alert","content":{"left":{"level":1,"type":"tree"},"right":{"level":0,"type":null}}}` |
| `test_ble alert 0 null 1 person` | 左側無，右側 person | `{"response_type":"alert","content":{"left":{"level":0,"type":null},"right":{"level":1,"type":"person"}}}` |
| `test_ble alert 1 tree 1 vehicle` | 左右都有警示 | `{"response_type":"alert","content":{"left":{"level":1,"type":"tree"},"right":{"level":1,"type":"vehicle"}}}` |
| `test_ble alert 0 null 0 null` | 解除所有 alert | `{"response_type":"alert","content":{"left":{"level":0,"type":null},"right":{"level":0,"type":null}}}` |

> **Alert 指令格式**：`test_ble alert <左level> <左type> <右level> <右type>`
> type 可以是：`tree` / `person` / `vehicle` / `null`

### 3.2 BLE 全項自動測試

| 指令 | 說明 |
|------|------|
| `test_ble_all` | 自動跑完所有 BLE 測項（約 20 秒）|

**TEST_BLE_ALL 執行順序：**

```
[00s] violation level=1            → 等 3 秒
[03s] violation level=0            → 等 2 秒
[05s] collision level=1            → 等 3 秒
[08s] collision level=0            → 等 2 秒
[10s] alert left=tree, right=無    → 等 3 秒
[13s] alert clear                  → 等 2 秒
[15s] alert left=tree, right=vehicle → 等 3 秒
[18s] alert clear                  → 等 2 秒
[20s] TEST_BLE_ALL_DONE，自動退出測試模式
```

---

## 四、大項二：CAN bus 測試

**測試目的**：驗證各警示事件觸發時，CAN bus 送出正確速度指令。
**注意**：只觸發 CAN bus 速度指令，**不送出** BLE JSON，**不啟動** Buzzer。

### 速度對照表

| 事件 | CAN 速度值 |
|------|-----------|
| 正常行駛 | 240 |
| Violation / Alert | 35 |
| Collision | 10 |

### 4.1 單項測試指令

#### Violation CAN 測試

| 指令 | CAN 速度 | 預期回覆 |
|------|---------|---------|
| `test_can violation 1` | 35 | `TEST_ACK CAN VIOLATION 1 speed=35` |
| `test_can violation 0` | 240 | `TEST_ACK CAN VIOLATION 0 speed=240` |

#### Collision CAN 測試

| 指令 | CAN 速度 | 預期回覆 |
|------|---------|---------|
| `test_can collision 1` | 10 | `TEST_ACK CAN COLLISION 1 speed=10` |
| `test_can collision 0` | 240 | `TEST_ACK CAN COLLISION 0 speed=240` |

#### Alert CAN 測試

| 指令 | CAN 速度 | 預期回覆 |
|------|---------|---------|
| `test_can alert 1` | 35 | `TEST_ACK CAN ALERT 1 speed=35` |
| `test_can alert 0` | 240 | `TEST_ACK CAN ALERT 0 speed=240` |

### 4.2 CAN 全項自動測試

| 指令 | 說明 |
|------|------|
| `test_can_all` | 自動跑完所有 CAN 測項（預設觀察 10 秒，約 39 秒）|
| `test_can_all 15` | 每個測項觀察時間改為 15 秒 |

**TEST_CAN_ALL 執行順序（預設觀察 10 秒）：**

```
[00s]  violation level=1 → speed=35
          ↓ 觀察 10 秒（踩油門，確認轉速被限制）
[10s]  violation level=0 → speed=240
          ↓ 等 3 秒（確認恢復正常）
[13s]  collision level=1 → speed=10
          ↓ 觀察 10 秒（踩油門，確認轉速被限制到最低）
[23s]  collision level=0 → speed=240
          ↓ 等 3 秒
[26s]  alert level=1     → speed=35
          ↓ 觀察 10 秒
[36s]  alert level=0     → speed=240
          ↓ 等 3 秒
[39s]  TEST_CAN_ALL_DONE，自動退出測試模式
```

---

## 五、大項三：Buzzer 測試

**測試目的**：驗證各警示事件觸發時，Buzzer 發出正確嗶聲節奏。
**注意**：只觸發 Buzzer，**不送出** BLE JSON，**不發** CAN bus 指令。

### Buzzer Pattern 對照表

| Pattern | 節奏 |
|---------|------|
| OFF（靜音）| 無聲 |
| GRASS（Violation 草地）| 慢速：500ms 響 / 500ms 停 |
| ALERT（Alert 方向警示）| 中速：300ms 響 / 200ms 停 |
| COLLISION（碰撞）| 急促：100ms 響 / 100ms 停 |

### 5.1 單項測試指令

| 指令 | Buzzer 動作 | 預期回覆 |
|------|-----------|---------|
| `test_buzzer grass` | 慢速嗶（500ms 響 / 500ms 停）| `TEST_ACK BUZZER GRASS OK` |
| `test_buzzer alert` | 中速嗶（300ms 響 / 200ms 停）| `TEST_ACK BUZZER ALERT OK` |
| `test_buzzer collision` | 急促嗶（100ms 響 / 100ms 停）| `TEST_ACK BUZZER COLLISION OK` |
| `test_buzzer off` | 靜音 | `TEST_ACK BUZZER OFF OK` |

> Buzzer 指令送出後立即生效，持續到下一個指令為止。

### 5.2 Buzzer 全項自動測試

| 指令 | 說明 |
|------|------|
| `test_buzzer_all` | 自動跑完所有 Buzzer 測項（約 12 秒）|

**TEST_BUZZER_ALL 執行順序：**

```
[00s] GRASS 慢速嗶     → 等 4 秒
[04s] ALERT 中速嗶     → 等 4 秒
[08s] COLLISION 急促嗶 → 等 4 秒
[12s] OFF 靜音
[12s] TEST_BUZZER_ALL_DONE，自動退出測試模式
```

---

## 六、全功能自動測試

| 指令 | 說明 |
|------|------|
| `test_all` | 依序執行 BLE → CAN → Buzzer 三大群組（預設觀察 10 秒，約 77 秒）|
| `test_all 15` | CAN 觀察時間改為 15 秒（約 92 秒）|

**執行順序（預設觀察 10 秒）：**

1. **BLE 群組**（約 20 秒）— 驗證 BLE JSON
2. 休息 3 秒
3. **CAN 群組**（約 39 秒）— 驗證 CAN bus 速度指令
4. 休息 3 秒
5. **Buzzer 群組**（約 12 秒）— 驗證 Buzzer 嗶聲節奏
6. 送出 `TEST_ALL_DONE`，自動退出測試模式

**進度訊息：**

| 回傳訊息 | 說明 |
|---------|------|
| `TEST_ALL_START` | 全功能測試開始 |
| `TEST_ALL_BLE_GROUP_START` | BLE 群組開始 |
| `TEST_ALL_BLE_GROUP_DONE` | BLE 群組完成 |
| `TEST_ALL_CAN_GROUP_START` | CAN 群組開始 |
| `TEST_ALL_CAN_GROUP_DONE` | CAN 群組完成 |
| `TEST_ALL_BUZZER_GROUP_START` | Buzzer 群組開始 |
| `TEST_ALL_BUZZER_GROUP_DONE` | Buzzer 群組完成 |
| `TEST_ALL_DONE` | 全部完成 |

---

## 七、錯誤回覆說明

| 回傳訊息 | 說明 |
|---------|------|
| `TEST_ERR NOT_IN_TEST_MODE` | 尚未執行 `test_enter` |
| `TEST_ERR ALL_ALREADY_RUNNING` | TEST_ALL 系列仍在執行中，請等待完成 |
| `TEST_ERR UNKNOWN_CMD` | 指令不正確，請確認格式 |
| `TEST_ACK ALREADY_IN_TEST` | 已在測試模式，不需重複 `test_enter` |
| `TEST_TIMEOUT_EXIT` | 60 秒逾時，自動退出測試模式 |

---

## 八、快速測試流程範例

### 範例 A：只測試藍芽 JSON

```
test_enter
test_ble collision 1
（確認收到 collision_warning JSON）
test_ble collision 0
test_exit
```

### 範例 B：只測試 CAN 限速

```
test_enter
test_can collision 1
（踩油門 → 確認轉速被限制 + 確認 ACK speed=10）
test_can collision 0
（確認轉速恢復正常）
test_exit
```

### 範例 C：只測試 Buzzer

```
test_enter
test_buzzer collision
（聽到急促嗶聲）
test_buzzer off
（靜音）
test_exit
```

### 範例 D：全自動測試（觀察 15 秒）

```
test_enter
test_all 15
（等待約 92 秒，觀察各測項）
（收到 TEST_ALL_DONE 後自動退出測試模式）
```

---

## 附錄：指令速查表

```
test_enter
test_exit

test_ble violation <level>                         level = 0 或 1
test_ble collision <level>                         level = 0 或 1
test_ble alert <左level> <左type> <右level> <右type>
test_ble_all

test_can violation <level>                         level = 0 或 1
test_can collision <level>                         level = 0 或 1
test_can alert <level>                             level = 0 或 1
test_can_all [觀察秒數]                            預設 10 秒

test_buzzer grass
test_buzzer alert
test_buzzer collision
test_buzzer off
test_buzzer_all

te