StereoLabs 相機整合
AFE-A702 搭配 StereoLabs 相機
本指南說明如何在 AFE-A702 上整合 StereoLabs 相機,包括實體連接、具備影格同步模式的驅動程式安裝、ZED 公用程式,以及 ROS 2 節點。
本指南內容依據以下環境編寫:
| 項目 | 說明 |
|---|---|
| 平台 | AFE-A702 |
| 已驗證相機 | ZED X / ZED X Mini / ZED X nano |
| 作業系統版本 | Jetpack 7.2 v1 (Ubuntu 24.04) |
| ROS 發行版本 | ROS 2 Jazzy |
| ZED SDK | 5.5.0 |
| ZED ROS 2 封裝套件 | v5.5.0 分支 |
以上為已測試之來源環境版本,並不代表其他 BSP、SDK 或套件版本組合亦相容。
1. 在斷電狀態下連接相機
連接相機的 FAKRA 纜線前,請先關閉 AFE-A702 電源。AFE-A702 最多支援 8 台 ZED X 系列相機。
完成硬體連接後,重新開啟 AFE-A702 電源並進入 Ubuntu 桌面。
2. 安裝 ZED X 系列相機驅動程式
從 AFE-A702 的 GMSL 驅動程式下載 ZED X 系列相機驅動程式,依照以下步驟安裝驅動程式並重新啟動。
$ unzip StereoLabs_ZEDX_AFE-A702_Jetpack7.2v1_20260922.zip
$ cd StereoLabs_ZEDX_AFE-A702_Jetpack7.2v1_20260922/
$ sudo dpkg -i StereoLabs_ZEDX_AFE-A702_Jetpack7.2v1_20260922.deb
$ sudo reboot
重新啟動後,安裝 V4L2 公用程式並列出視訊節點。每台 ZED X 相機應顯示為兩個視訊節點,分別對應左眼串流與右眼串流。
$ sudo apt install v4l-utils -y
$ v4l2-ctl --list-devices
3. 驗證左眼與右眼串流
安裝符合 AFE-A702 上 Jetpack 7.2 目標版本的 NVIDIA GStreamer 套件;若使用其他 BSP,則需要安裝不同版本。
$ sudo apt install nvidia-l4t-gstreamer=39.2.0-20260601141651
分別啟動兩個視訊串流:
$ gst-launch-1.0 nvarguscamerasrc sensor-id=0 ! nvvidconv ! xvimagesink
$ gst-launch-1.0 nvarguscamerasrc sensor-id=1 ! nvvidconv ! xvimagesink
第一台立體相機的右眼為 sensor-id=0,左眼為 sensor-id=1。
第二台相機的右眼為 sensor-id=2,左眼為 sensor-id=3,後續相機依此類推。
4. 切換影格同步模式
ZED X 系列相機支援影格同步模式,預設為不同步模式。使用者可編輯 zed_x_daemon.service 設定以切換模式;以下命令會將相機設為影格同步模式。
$ sudo sed -i 's/^sync_mode=0/sync_mode=2/' /etc/systemd/system/zed_x_daemon.service
$ sudo systemctl daemon-reload
$ sudo systemctl restart zed_x_daemon.service
切換模式後,進入超級使用者模式,並設定同步訊號的工作週期與頻率。
工作週期應設為 25%,頻率則應設為所有相機皆支援的每秒影格數。
$ sudo -s
# cd /sys/class/cdi_tsc_class/cdi_tsc
# echo 25 > duty_cycle
# echo 30 > freq_hz
上述命令會讓所有已連接相機採用相同的影格時序。
每次系統開機時都必須執行這些命令,因此使用者可將其加入啟動指令碼,使設定持續生效。
使用者可透過下一節安裝的 ZED_Studio 公用程式檢查同步狀態。
5. ZED SDK
從 StereoLabs ZED SDK 發行頁面下載適用於 Jetpack 7.2 的 ZED SDK。本指南使用 5.5.0 版,以下命令會在 AFE-A702 上安裝 SDK。
$ chmod +x ZED_SDK_Tegra_L4T39.2_v5.5.0.zstd.run
$ ./ZED_SDK_Tegra_L4T39.2_v5.5.0.zstd.run
安裝程式採互動式操作,且可能會下載其他模型。回答前請仔細閱讀每項提示。安裝完成後,即可使用 ZED SDK 與相關公用程式。
ZED_Studio
開啟 ZED_Studio 公用程式,檢查已連接的相機及其左/右眼 RGB 串流。
官方網站參考資料:ZED Studio 指南。
$ ZED_Studio
ZED Studio 左側會顯示已連接的相機。按一下 Image 與 Depth Map 右側的眼睛圖示,即可顯示相機的左/右眼 RGB 影像與深度串流。下方區域會顯示目前的相機資訊。
請等待各視訊串流正常輸出後,再開啟下一個串流。
下圖顯示同時啟用全部四台相機的 RGB 串流與深度圖。
6. ZED ROS 2 封裝套件
確認 AFE-A702 已連上網際網路,並已安裝 ROS 2 Jazzy 環境。
您可安裝 Advantech Robotic Suite,或依照 ROS 官方安裝指南中的說明安裝 ROS 2 Jazzy。
依照 StereoLabs 官方 GitHub 的說明,為 ZED X 系列相機建置 ZED ROS 2 封裝套件。
安裝相依套件
$ sudo apt update && sudo apt install python3-rosdep python3-colcon-common-extensions \
ros-${ROS_DISTRO}-zed-msgs ros-${ROS_DISTRO}-nmea-msgs ros-${ROS_DISTRO}-geographic-msgs \
ros-${ROS_DISTRO}-diagnostic-updater ros-${ROS_DISTRO}-robot-localization \
ros-${ROS_DISTRO}-backward-ros ros-${ROS_DISTRO}-zed-description v4l-utils -y
建立工作空間並建置 StereoLabs zed-ros2-wrapper
$ mkdir -p ~/ros2_ws/src/
$ cd ~/ros2_ws/src/
$ git clone https://github.com/stereolabs/zed-ros2-wrapper.git -b v5.5.0
$ cd ..
$ sudo rosdep init && sudo rosdep update
$ sudo rosdep install --from-paths src --ignore-src -r -y
$ colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Release
在工作空間根目錄載入設定指令碼,並可選擇將此設定設為持續生效。
$ echo source ~/ros2_ws/install/local_setup.bash >> ~/.bashrc
$ source ~/.bashrc啟動 ROS 2 節點
使用 camera_model、camera_name、camera_id 參數啟動 ZED ROS 2 節點,範例命令如下。
$ ros2 launch zed_wrapper zed_camera.launch.py camera_name:=zed_front camera_model:=zedx camera_id:=0
| 參數 | 說明 |
|---|---|
camera_model | 已連接的相機型號,包括 zed、zedm、zed2、zed2i、zedx、zedxm、zedxnano、zedxhdrmini、zedxhdr、zedxhdrmax、virtual、zedxonegs、zedxone4k、zedxonehdr。 |
camera_name | 此相機 ROS 2 節點主題的命名空間。 |
camera_id | 相機 ID,可使用命令 $ ZED_Explorer -a 查詢。 |
若 AFE-A702 連接了第二台相機,請開啟另一個終端機,使用不同的 camera_name 與 camera_id 執行上述命令,以啟動第二個節點。
$ ros2 launch zed_wrapper zed_camera.launch.py camera_name:=zed_back camera_model:=zedx camera_id:=1
開啟新的終端機並使用 ros2 topic list 列出所有 ROS 2 主題;相機主題應會顯示在清單中。
$ ros2 topic list
使用 RViz2 將資料視覺化
開啟 RViz2,將相機輸出視覺化。請確認已啟動的節點正在執行,且主題處於作用中。
$ rviz2
新增 RGB 串流主題 /zed_front/zed_node/rgb/color/rect/image、深度串流主題 /zed_front/zed_node/depth/depth_registered,以及點雲主題 /zed_front/zed_node/point_cloud/cloud_registered。
7. 效能記錄
| 項目 | 設定 |
|---|---|
| 相機型號 | ZED X |
| 相機數量 | 4 |
| 解析度 | 左眼 1920x1200@30、右眼 1920x1200@30、深度 1920x1200@30 |
| CPU 使用率(10 分鐘內) | 最大:30%、最小:25%、平均:27.18% |
| GPU 使用率(10 分鐘內) | 最大:96%、最小:12%、平均:78.25% |
| 測試結果 | 所有視訊通道皆維持 30 FPS;螢幕擷取畫面如第 5 節所示。 |