透過研華GMSL相機安裝系統快速配置GMSL相機驅動程式與相關功能
投稿指南將 研華GMSL相機安裝系統（adv-cam） 定位為 Advantech ASR702 八個 GMSL 接頭的集中設定工具，可快速配置 GMSL 相機驅動程式與相關功能。操作者不必逐項手動協調 Device Tree、I²C 位址、MIPI 配線與開機驅動程式，只需記錄每個通道連接的相機型號，再由工具產生對應設定。
來源所述適用範圍如下：
| 項目 | 來源標示值 |
|---|---|
| 平台 | Advantech ASR702 |
| 處理器平台 | NVIDIA Jetson AGX Thor |
| 軟體堆疊 | JetPack 7.2 / L4T R39.2 |
| 套件 | advantech-adv-max96712 2.13-10 |
| 工具版本 | adv-cam 2.13-10 |
| 相機接頭 | CH1～CH8 |
這些數值只代表投稿環境，不表示其他版本或平台必然相容。
集中管理相機設定的優點
多相機 GMSL 系統的限制不只發生在單顆相機。通道配置還會影響 serializer／deserializer link、可用串流 pipe、MIPI port 速率、同步方式及開機時啟動的 ROS 2 節點。adv-cam 將這些決策放入同一份設定，並提供三種可交替使用的介面：
| 介面 | 指令 | 適用情境 |
|---|---|---|
| 圖形介面 | sudo adv-cam | 有螢幕的本機設定 |
| 文字介面 | sudo adv-cam --tui | SSH 或序列主控台 |
| 指令列 | sudo adv-cam CH1=d457 … | 腳本、量產與遠端批次設定 |
主要價值是可重複性與提早檢查：在工具轉換為底層設定前，先檢視整台機器的實體拓撲與資源限制。
偵測、對應並檢查相機
CAMERA CONNECTION 頁面將 CH1～CH4 與 CH5～CH8 對應至相機 profile；未連接的接頭應設為 None。來源指出，視窗開啟後的硬體偵測約需 20 秒。RE-SCAN 可重新查詢，Auto Apply 或 APPLY DETECTED 則可把偵測結果填入選單。
圖 1. CAMERA CONNECTION 將通道對應、硬體偵測與套用前檢查集中在同一頁。
偵測結果不一定只顯示通用 profile。投稿範例會讀取 StereoLabs EEPROM，將同屬 zedx profile 的裝置進一步辨識為 ZED X Nano 或 ZED X Mini，並用總結訊息確認儲存設定是否與實際連線一致。
VALIDATION 也會顯示整機限制。投稿畫面包含兩項重要警告：
- 同一顆 deserializer 宣告 9 路串流，但只有 8 個 pipe，因此最多只能同時開啟 8 路；
- 共用同一條 D-PHY／MIPI port 的相機要求不同速率時，該 port 會以最高需求速率運作。
這正是集中設定相較於分散修改設定檔的優點：資源超額與共用連線的影響能在部署前被看見。
設定全機共用的影像同步
TIME SYNC 頁面控制由兩顆 MAX96712 deserializer 與八個通道共用的 trigger pulse。Trigger frequency 為 off 時，相機各自 free-run；選取頻率後，會設定整台機器共用的同步脈衝。
圖 2. TIME SYNC 顯示共用觸發訊號狀態；投稿畫面為相機各自運作。
指南區分兩個控制層次：
- TIME SYNC 頁面決定 SoC 是否產生脈衝；
adv-cam-fsync決定相機是否跟隨脈衝。
兩側都完成設定才會真正同步曝光。來源提供的相機端範例如下：
sudo adv-cam-fsync on
不要假設所有相機與驅動程式都支援相同觸發模式；請在目標硬體確認電氣時序、曝光行為及選用頻率。
在相同拓撲中管理 ROS 2 開機啟動
ROS CONFIGURATION 頁面列出 CAMERA MODEL、CHANNEL 與 START AT BOOT。開關預設為 DISABLED；開啟後，該相機的 ROS 2 節點會在下一次開機時自動啟動。
圖 3. ROS 開機設定直接沿用相機與通道對應，不必另外維護兩份拓撲。
投稿畫面顯示 ROS 2 Jazzy detected。來源另外說明：
- Orbbec Gemini 335Lg 的 ROS 驅動需要先開啟 TIME SYNC 才會輸出影像；
- 若未安裝 ROS 2 Jazzy，各列會維持 Disabled。這代表 ROS 環境不可用，不是相機偵測失敗。
安全套用設定
APPLY DETECTED 只會填入選單，不會儲存。確認設定與警告後，按 SAVE & APPLY 並確認對話框；工具會產生並儲存 Device Tree 設定，再詢問是否重新開機。
- **Yes：**立即重新開機，讓新設定生效。
- **No：**先儲存，稍後再自行重新開機。
指南指出一個例外：由 2.13-4 以前版本升級，或由其他無法在 reboot 時重置相機的驅動程式切換而來時，第一次可能需要完整斷電約 30 秒；之後的變更則只需一般 reboot。中斷正式系統前，仍應依實際安裝版本確認此行為。
Headless 與自動化流程
TUI 支援純鍵盤操作：
↑／↓：切換通道；←／→：選取相機 profile；N：將通道設為未連接；F10或S：儲存並套用；Esc或Q：不儲存離開。
CLI 提供相同資料模型：
sudo adv-cam --show
sudo adv-cam --detect
sudo adv-cam CH1=d457 CH2=zedx CH6=g335Lg
sudo adv-cam CH1=d457 CH6=g335Lg FSYNC=15
:::caution 通道指定指令代表完整設定
來源說明，未列在通道指定指令中的接頭會被視為 none。套用前必須檢查完整指令，否則可能關閉原本使用中的通道。
:::
來源列出的相機代號包括：
| 代號 | 相機 profile |
|---|---|
d457 | RealSense D457 |
g335Lg | Orbbec Gemini 335Lg |
zedx | StereoLabs ZED X／Mini／Nano |
zedxone | StereoLabs ZED X One（GS） |
zedxone4k | StereoLabs ZED X One 4K |
li-isx031 | Leopard Imaging ISX031 |
li-ox03f10 | Leopard Imaging OX03F10 |
appro-ar0234 | Appropho AR0234 ISP module |
sw | Sensing World SG8A |
none | 未連接 |
--detect 可能顯示 serializer 位址、ID、EEPROM 型號與序號、link 速率不符，以及建議的完整設定指令。最後一行應視為待檢查的起點，不應未經確認直接執行。
新板子的建議流程
來源提出下列初次設定順序：
sudo apt install ./advantech-adv-max96712_<version>_arm64.deb
sudo reboot
sudo adv-cam
請使用 apt，不要只執行 dpkg -i，讓系統能處理相依套件。在 GUI 等待偵測完成、檢視硬體與警告、按 APPLY DETECTED，再按 SAVE & APPLY。重新開機後，確認預期的 video node：
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=30 --stream-to=/dev/null
測試前先確認實際 /dev/video* 節點。指令成功返回仍不足以證明整體正常；還需驗證影格、相機身分、必要的同步，以及 ROS 開機啟動狀態。
限制與注意事項
- 來源指出每顆 deserializer 最多同時承載 8 路串流；D457 與 Gemini 335Lg 各佔 4 路，ZED X 佔 2 路。
- 設定必須重新開機才會生效。
- 共用 MIPI port 的相機會使用最高需求速率。
- Sensing World（
sw）目前只列為測試支援。 - 有程式正在開啟
/dev/video*串流時，硬體偵測會切成唯讀；關閉串流程式後再重新偵測，才能取得完整資訊。 - 套件版本、支援型號與重置行為可能變更，應以實際安裝工具的 help 與 release 文件為準。