單元 4 · 相機框架與驅動

4.1 libcamera 五大元件（含原始碼位置）

4.2 控制資料流（完整追蹤）

你操作高階控制；libcamera 做「控制 → register」的轉換。理解這層抽象，tuning 檔才看得懂（單元 14）。

4.3 unicam：CSI-2 接收器

• unicam 是 RPi 的 CSI-2 前端驅動，收集 MIPI 資料流。
• 處理：lane 對齊、EAV/SAV 解碼、frame 同步。

ls /dev/video* /dev/media*
media-ctl -p -d /dev/media0 | head -30

4.4 DT overlay：每個欄位對驅動的意義

compatible = "ovti,ov5647";     # 匹配 of_device_id → 載入驅動
reg = <0x36>;                    # probe 用 I2C 位址
clocks = <&cam0_clk>;              # XCLK 來源（pixel clock）
reset-gpios = <...>;             # RESET（CAM_GPIO）
pwdn-gpios = <...>;              # PWDN（如有）
port { csi-lane = <2>; }          # MIPI lane 數

sudo dtoverlay -a | grep ov56
dmesg | grep -i -E "ov5647|unicam"

4.5 最小驗收

rpicam-hello --list-cameras
# 預期：ov5647，含 modes（2592x1944 10-bit …）

4.6 常見錯誤

• overlay 名與驅動不符：dtoverlay=ov5647 是 RPi 命名；驅動名是 ov5647.c。
• 改 overlay 沒重啟：device tree 在開機時載入，改後需 reboot。
• reg 位址與硬體不符：overlay 宣告 0x36，但板子實體位址不同 → probe 失敗。

4.6 深入：libcamera 的 Sensor 驅動介面

libcamera 對感測器驅動有一套「標準控制介面」，ov5647.c 實作：

4.7 深入：DT overlay 與內核匹配的完整鏈

compatible 寫錯一個字 → 驅動不 probe。這是「list-cameras 空」的常見根因。

4.8 練習

1. 執行 dmesg | grep -i ov5647，找 probe 結果。
2. 執行 rpicam-hello --list-cameras，記錄輸出的 modes。
3. 把 DT 宣告的 I2C 位址與 i2cdetect 結果對照。

進階真實情境 Worked Example：用 media-ctl 追蹤完整管線並驗證格式一致

場景：你換了 OV5647 的 init table，但預覽畫面出現異常的綠色條紋。需要確認是 media 管線格式不一致還是 ISP 參數問題。

# 1. 完整列出所有 entity 與 pad format
media-ctl -p -d /dev/media0

# 輸出節錄：
# - entity 3: ov5647 0-0036 (1 pad, 1 link)
#     pad0: Source [fmt:SGBRG10_1X10/2592x1944]
# - entity 6: unicam (2 pads, 1 link)
#     pad0: Sink [fmt:SGBRG10_1X10/2592x1944]

# 2. 檢查 ISP pipeline handler 的格式轉換
media-ctl -p -d /dev/media0 | grep -A5 "rpi"

# 3. 若格式不一致，手動設定（不建議但除錯用）
# media-ctl -d /dev/media0 \
#   --set-v4l2 "ov5647 0-0036:0[fmt:SGBRG10_1X10/2592x1944]"

# 4. 用 v4l2-ctl 確認 streaming 格式
v4l2-ctl -d /dev/video0 --list-formats-ext

深入原理擴充：libcamera pipeline handler 的自動格式推導機制

libcamera 的 pipeline handler（RPi 的 PipelineHandlerPiSP）在 probe 時自動建立 media graph，但它的格式推導邏輯比你想的複雜：

• 感測器端：ov5647.c 的 init table 宣告支援的 format（SRGGB10、YUV420 等），pipeline handler 從中選擇「最佳」格式。
• ISP 端：PiSP（RPi5 的 ISP）有硬體限制——某些 format 不支援直接輸入，需要額外的轉換 entity。
• tuning 檔關聯：tuning 檔的格式必須與 pipeline 的實際 format 匹配，否則 ISP 會用錯誤的參數處理——症状通常是色彩偏差而非完全無畫面。

診斷式疑難排解表

進階挑戰題

1. 用 media-ctl -p 畫出從感測器到 ISP 輸出的完整 entity 連結圖（用 ASCII 或文字描述），標出每個 link 的格式與方向（source→sink）。
2. 設計一個「overlay 健康檢查」腳本：自動比對 DT overlay 宣告的 I2C 位址、lane 數、reset-gpios 與 i2cdetect / media-ctl 的實際結果，找出不匹配項。
3. 若你想在 RPi5 上同時使用 OV5647（Camera 0）和自訂感測器（Camera 1），需要為 Camera 1 寫一份 DT overlay。描述你會如何確定 compatible、reg、clocks、reset-gpios 的值。

延伸閱讀

• 下一篇：單元 5 · 第一個鏡頭跑起來。
• libcamera 文件
• 學習路線：複習全站

專案級端到端 Worked Example：自訂 DT overlay 接入第二顆感測器

場景：RPi5 的 Camera 1 要接一顆客製板上的 OV5647。官方 overlay 只覆蓋 Camera 0，你必須為 Camera 1 寫一份自訂 overlay，並驗證到 libcamera 看到兩顆相機。本專案整合單元 1（腳位）、3（I2C）、4（overlay/驅動）、6（bring-up）知識。

// ov5647-cam1.dts（概念，欄位意義對應單元 4.4）
/dts-v1/;
/plugin/;
&i2c_csi_dsi1 {                       # Camera 1 的 I2C（i2c-10）
    compatible = "ovti,ov5647";        # 匹配 ov5647.c
    reg = <0x36>;                       # I2C 位址
    clocks = <&cam1_clk>;               # XCLK
    reset-gpios = <...>;               # CAM_GPIO 1
    pwdn-gpios = <...>;
    port { endpoint { data-lanes = <1 2>; }; };  # 2-lane
};

# 1. 編譯 dts → dtbo（樹莓派工具鏈）
dtc -@ -I dts -O dtb -o ov5647-cam1.dtbo ov5647-cam1.dts
sudo cp ov5647-cam1.dtbo /boot/firmware/overlays/

# 2. 加入 config.txt 並重啟
echo "dtoverlay=ov5647-cam1" | sudo tee -a /boot/firmware/config.txt
sudo reboot

# 3. 驗證 probe（預期出現兩顆）
dmesg | grep -i ov5647
sudo i2cdetect -y 10 | grep 36        # Camera 1 的 bus
rpicam-hello --list-cameras
# 預期：0 : ov5647  1 : ov5647

# 4. 驗證 media graph 兩條管線
media-ctl -p -d /dev/media0 | grep -E "entity|ov5647|unicam"

量測/驗證 SOP：驅動載入與 media graph 驗證

1. dmesg | grep -i ov5647 確認兩顆都 probe（含 Chip ID）。
2. sudo i2cdetect -y 10（Camera 1）與 -y 22（Camera 0）確認各自 0x36。
3. rpicam-hello --list-cameras 確認兩顆 camera 索引。
4. media-ctl -p -d /dev/media0（與 media1）比對感測器 pad 格式與 unicam sink 格式一致。
5. 雙鏡頭各拍一張 RAW，確認無格式錯誤。
6. 記錄 media graph 輸出存檔。

平台間對照：驅動與 device tree

互動式檢核清單

• - [ ] 能逐欄解釋 DT overlay 每個欄位對驅動的意義。
• - [ ] 已為 Camera 1 建立並驗證自訂 overlay。
• - [ ] 能讀懂 media-ctl 輸出並判別格式不一致。
• - [ ] 能說出 libcamera 五大元件與控制資料流。
• - [ ] 能說出 unicam 的角色與 media 節點。
• - [ ] 已記錄兩顆相機的 media graph 快照。

第 3 輪深度加深

① Register 位元級完整工作流：V4L2 subdev 設定曝光

② 多層疑難排解決策樹

決策樹 A：libcamera 與 V4L2 工具衝突

工具衝突
├─ 檢查 A：cam -d /dev/media0 是否佔用 pipeline
│  ├─ 是 → 關閉 cam 後再用 v4l2-ctl
│  └─ 否 → 繼續
├─ 檢查 B：rpicam-hello 是否在背景執行
│  ├─ 是 → kill 後重試
│  └─ 否 → 繼續
└─ 檢查 C：是否有其他 process 打開 /dev/video*
   ├─ 是 → lsof /dev/video* 找出並終止
   └─ 否 → driver 問題，檢查 media topology

③ 量測驗證完整 SOP：Pipeline 延遲量測

1. 方法：GPIO 觸發 + 影像時間戳比對
2. 硬體：RPi5 GPIO 17 接 LED + 示波器
3. 軟體：在影像 callback 中拉 GPIO High，從 raw frame header 讀取 timestamp
4. 量測：
   a. GPIO rising → frame timestamp = sensor → ISP 延遲
   b. frame timestamp → callback timestamp = ISP → 應用延遲
   c. 總延遲 = a + b
5. 重複：100 幀取 p50 / p99 / p99.9 latency
6. 判讀：p50 <33ms (30fps), p99 <50ms = 正常；jitter >10ms = pipeline 有 blocking

④ 四平台終極對照

⑤ 完整 Bring-up 專案 Checklist

• - [ ] 確認 kernel 版本與 media controller driver 版本
• - [ ] media-ctl -d /dev/media0 -p 查看 pipeline topology
• - [ ] 確認 sensor → CSI → ISP → video device 串接正確
• - [ ] 用 v4l2-ctl 逐一設定並驗證各控制項目
• - [ ] 測試 libcamera 與 V4L2 工具切換無衝突
• - [ ] 量測 pipeline 延遲（p50/p99）
• - [ ] 確認 DMA buffer 分配正確（ion/dma-buf）
• - [ ] 整理框架對照表存入專案文件