# KL630 Host Stream Firmware

即時影像語義分割系統，運行於 Kneron KL630 (Cortex-A7, uClibc)。
透過 IMX662 DOL-HDR 雙曝光攝影機進行 STDC 語義分割，並將結果以 RTSP 串流或 HDMI 輸出。

**技術細節 → [`docs/technical_report.md`](docs/technical_report.md)**

---

## 目錄結構

```
kl630_build/
├── web_serve.py             # Web 控制台（主要使用）
├── build_and_serve.py       # CLI 版本（不需要瀏覽器）
├── compile.sh               # Docker 內 ARM 交叉編譯腳本
├── Dockerfile               # kl630-dev image 定義
├── requirements.txt         # Python 套件清單
│
├── src/
│   ├── host_stream/         # 主程式（初始化、推論迴圈、結果處理）
│   ├── app_flow/            # VMF pipeline 控制
│   ├── pre_post/            # YOLOv5 前後處理
│   └── stdc/                # STDC 語義分割後處理
│
├── include/
│   ├── stdc/                # stdc_post_process.h（分析結果結構）
│   └── fake/                # SDK 缺少時的 stub headers
│
├── ini/
│   └── host_stream.ini      # 執行期設定（model、stream、ISP、FEC 參數）
│
│
├── lib/                     # 裝置端 .so 函式庫（VMF SDK）
├── docs/
│   └── technical_report.md  # 完整技術文件
└── build/                   # 編譯輸出（由 compile.sh 產生）
```

---

## 快速開始

### 前置條件

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) 已安裝並執行中
- Python 3.8+

### 安裝

```bash
pip install -r requirements.txt
```

| 套件 | 用途 |
|------|------|
| `flask` | Web 控制台 + HTTP file server |
| `opencv-python` | RTSP 串流預覽（內建 FFmpeg，無需另外安裝）|

### 啟動

```bash
python web_serve.py
```

瀏覽器開啟 `http://localhost:8080/`

---

## 新機器首次設定 SOP

全新 KL630 裝置依序執行以下步驟：

### Step 1 — Compile

在 Web 控制台按 **Compile**。
- 自動建立 Docker image（若不存在）
- 交叉編譯 ARM binary
- 複製 binary / INI / 腳本到 `build/`

> 若 binary 已是最新版本，可跳過此步驟直接從 Step 2 開始。

### Step 2 — 設定 Output Mode

在 **INI Settings** 面板選擇輸出模式（預設 RTSP）：

| 組合 | RTSP | HDMI | 啟動腳本 |
|------|------|------|---------|
| RTSP 串流 | ON | OFF | `demo_rtsp.sh` |
| HDMI 顯示 | OFF | ON | `demo_hdmi.sh` |
| RTSP + HDMI 同時 | ON | ON | `demo_rtsp_hdmi.sh`（INI voc_enable=1）|
| 純推論（無輸出） | OFF | OFF | 直接啟動 binary |

### Step 3 — Deploy to KL630

按 **Deploy to KL630**，自動透過 Telnet 完成：
1. 停止舊 firmware
2. 下載 binary、INI、NEF 模型
3. 下載 `demo_rtsp.sh`、`demo_hdmi.sh`、`demo_rtsp_hdmi.sh`
4. 設定 VOC 輸出模式
5. 啟動 firmware

### Step 4 — First-time ISP Setup

按 **First-time ISP Setup**。
寫入 DOL-HDR 所需的 flash 參數（`dwStatisticsSrcType=2`、`bGTREnable=1`），
**只需執行一次**，設定永久保留在 flash，重新 Deploy 不會被覆蓋。

> 跳過此步驟影像會過暗或曝光不正確。

### Step 5 — 魚眼鏡頭校正（FEC）

在 **INI Settings** 面板設定 Fish-Eye Correction：

| 參數 | 推薦設定 | 說明 |
|------|---------|------|
| FEC | ON | 開啟魚眼校正 |
| **Mode** | **4 — 180° Two Direction** | 天花板魚眼鏡頭推薦模式，同時展開水平與垂直方向 |
| Install Type | 0 — Ceiling | 天花板安裝 |
| EIS | 視需求 | 電子防手震 |

按 **Apply to Device + Restart** 套用並重啟 firmware。


---

## Web 控制台功能說明

### Network Config
設定 **Host IP**（這台 PC）、**KL630 IP**、**HTTP Port**、**Docker Image**。
按 Save 後自動更新 `deploy.sh` 的 `HOST_URL`。

### HTTP Server Files
列出 `build/` 目錄下所有可下載的檔案，以及裝置端手動部署指令：
```sh
wget http://<host_ip>:8080/deploy.sh -O /tmp/deploy.sh && sh /tmp/deploy.sh
```

### RTSP Stream Preview
直接在網頁預覽 KL630 串流，不需要開 VLC。
按 **▶ Start Stream** 即可，連線失敗時 6 秒內回報錯誤。

---

## Actions

| 按鈕 | 說明 |
|------|------|
| **Compile** | Docker 交叉編譯 ARM binary，複製到 `build/` |
| **Deploy to KL630** | Telnet 部署 binary / INI / NEF / 腳本，依 Output Mode 啟動 firmware |
| **First-time ISP Setup** | 新機器一次性 ISP flash 設定（DOL-HDR 參數） |
| **Write Autostart** | 寫入開機自動啟動腳本 `/etc/init.d/S99firmware` |

---

## INI Settings

### Fish-Eye Correction (FEC)

| 參數 | 說明 |
|------|------|
| FEC ON/OFF | 開啟或關閉魚眼校正（`fec_mode = 0` 為關閉）|
| Mode 1 | Single Region |
| Mode 2 | 180° All Direction |
| Mode 3 | 180° One Direction |
| **Mode 4** | **180° Two Direction（推薦）** |
| Mode 5 | PT Mode |
| Install Type | Ceiling / Table / Wall（`initial_fec_app_type`）|
| EIS | 電子防手震（`eis_enable`）|
| DrawBox | H.264 burn-in 偵測框（`DrawBoxEnable`）|

### Output Mode

| 選項 | 說明 |
|------|------|
| RTSP | H.264 RTSP 串流輸出，由 `demo_rtsp.sh` 管理 |
| HDMI | VOC HDMI 顯示輸出，由 `demo_hdmi.sh` 管理 |

- **Save INI（disk only）** — 更新本地 `ini/host_stream.ini`，下次 Deploy 時推送至裝置
- **Apply to Device + Restart** — 立即 Telnet 更新裝置 INI 並重啟 firmware

### Model Settings

切換推論模型（NEF 檔）、ModelId、JobId，支援上傳新 NEF。
**Apply to Device + Restart** 會下載 NEF 到裝置並依目前 Output Mode 重啟。

---

## Terminal

Output Log 下方有命令輸入列，可直接在網頁對 KL630 下指令：

```sh
cat /tmp/fw.log           # 查看 firmware 啟動 log
cat /tmp/rtsp_demo.log    # 查看 RTSP demo log
ps | grep firmware        # 確認 firmware 是否在執行
killall kp_firmware_host_stream
```

---

## CLI 版本（不需要瀏覽器）

```bash
python build_and_serve.py            # 編譯 + 檢查 + 啟動 HTTP server
python build_and_serve.py --no-build # 跳過編譯，直接 serve
python build_and_serve.py --port 9090
```

---

## Firmware 執行結果（console log）

```
[STDC] frame=42 mov=1 diff=4.2 bunker=0.0% car=8.3% grass=0.0% greenery=12.1% person=0.0% pond=0.0% road=71.4% tree=8.2%
[STDC] ON ROAD
[STDC WARN] CAR 8.3%
```

---

## 詳細說明

IMX662 DOL-HDR 雙曝光設定、STDC 語義分割架構、新裝置部署 SOP、故障排查：

**[`docs/technical_report.md`](docs/technical_report.md)**