KL630 Host Stream Firmware
即時影像語義分割系統，運行於 Kneron KL630 (Cortex-A7, uClibc)。 透過 IMX662 DOL-HDR 雙曝光攝影機進行 STDC 語義分割，並將結果以 RTSP 串流或 HDMI 輸出。
技術細節 → 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 已安裝並執行中
- Python 3.8+
安裝
pip install -r requirements.txt
| 套件 | 用途 |
|---|---|
flask |
Web 控制台 + HTTP file server |
opencv-python |
RTSP 串流預覽（內建 FFmpeg，無需另外安裝） |
啟動
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 完成：
- 停止舊 firmware
- 下載 binary、INI、NEF 模型
- 下載
demo_rtsp.sh、demo_hdmi.sh、demo_rtsp_hdmi.sh - 設定 VOC 輸出模式
- 啟動 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/ 目錄下所有可下載的檔案，以及裝置端手動部署指令：
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 下指令：
cat /tmp/fw.log # 查看 firmware 啟動 log
cat /tmp/rtsp_demo.log # 查看 RTSP demo log
ps | grep firmware # 確認 firmware 是否在執行
killall kp_firmware_host_stream
CLI 版本（不需要瀏覽器）
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、故障排查：