227 lines
6.5 KiB
Markdown
227 lines
6.5 KiB
Markdown
# 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)**
|