Skip to main content

Working with Raspberry Pi

The deserializer board is physically designed for the Raspberry Pi form factor and can be used with the Raspberry Pi 5 mainboard via a ribbon cable connection.

Hardware Connection​

Connecting to Raspberry Pi 5

  • Connect the CSI0 interface of the deserializer board to the CAM1 or CAM0 interface of the Raspberry Pi 5 using the supplied ribbon cable.
  • Insert the deserializer board onto the 40PIN GPIO header of the Raspberry Pi 5.
  • Connect the GMSL camera to the camera interface on the deserializer board using a coaxial cable.
  • Set the CFG switch to the 0100 position (default configuration for the ISX031 camera).

Software Configuration​

info
  • The driver only supports the following Raspberry Pi OS versions. Please use a compatible system version.
    • 2025-05-13-raspios-bookworm-arm64.img.xz, available for download here.
    • 2026-06-18-raspios-trixie-arm64.img.xz, available for download here

  • Flash the image file and boot the Raspberry Pi.

    • Extract the .img image file from the downloaded package.
    • Use the Raspberry Pi Imager or balenaEtcher to write the image file to a TF card.
    • Insert the TF card with the flashed image into the Raspberry Pi mainboard, connect the hardware, and power on.

  • Open a terminal on the Raspberry Pi and use the following commands to download and extract the driver package:

    wget https://files.waveshare.com/wiki/MAX9296-GMSL-Deser-Module/ws-rpi5-gmsl.zip
    unzip ws-rpi5-gmsl.zip

  • Install the drivers

    • Use the cd command to enter the driver package directory:

      cd ws-rpi5-gmsl/

      Enter Driver Directory

    • Add executable permissions to the installation script and execute it:

      sudo chmod a+x rpi5_gmsl_driver_install.sh
      sudo ./rpi5_gmsl_driver_install.sh

  • Configure the config.txt file

    • Edit the file and add the dtoverlay setting as shown in the image below

      sudo nano /boot/firmware/config.txt

      Edit config File

    • Depending on the connected camera, remove the comment symbol # from the corresponding configuration line. Here isx031-gmsl-camera-a is the camera model being connected, and sensor-type=ISX031C_GMSL2F_1CH sets the camera channel parameter.

    • Table of camera models and corresponding configuration parameters:

      Camera ModelCamera Model ParameterCamera Channel ParameterPreview Parameter
      ISX031C-GMSL-Camera-H100isx031-gmsl-camera-aISX031C_GMSL2F_xCHISX031-GMSL-Camera-A
      ISX031-GMSL-Camera-H60isx031-gmsl-camera-bISX031C_GMSL2F_xCHISX031-GMSL-Camera-B
      ISX031-GMSL-Camera-H100isx031-gmsl-camera-bISX031C_GMSL2F_xCHISX031-GMSL-Camera-B
      ISX031-GMSL-Camera-H120isx031-gmsl-camera-bISX031C_GMSL2F_xCHISX031-GMSL-Camera-B
      ISX031-GMSL-Camera-H190isx031-gmsl-camera-bISX031C_GMSL2F_xCHISX031-GMSL-Camera-B
      GMSL-2MP-Camera-Agmsl-2mp-camera-aGMSL_xCHGMSL-2MP-Camera-A
      GMSL-1MP-Camera-Agmsl-1mp-camera-aGMSL_1CH_LINKx / GMSL_2CHGMSL-1MP-Camera-A

      • _xCH: can be configured as 1CH or 2CH depending on the connected camera.

      • _LINKx: When using GMSL-1MP-Camera-A, the program cannot auto‑detect the link; you need to specify it in the config file. For a single GMSL camera, specify the link based on the connected interface: GMSL0 uses GMSL_1CH_LINKA, GMSL1 uses GMSL_1CH_LINKB. For dual cameras, use GMSL_2CH.

  • If one ISX031 camera is connected (either link A or link B; the program will auto‑detect):

    dtoverlay=isx031-gmsl-camera-a,sensor-type=ISX031C_GMSL2F_1CH

  • If two ISX031 cameras are connected:

    dtoverlay=isx031-gmsl-camera-a,sensor-type=ISX031C_GMSL2F_2CH

  • If connecting to the CAM0 interface, add the cam0 parameter at the end:

    dtoverlay=gmsl-isx031,sensor-type=ISX031C_GMSL2F_1CH,cam0
    dtoverlay=gmsl-isx031,sensor-type=ISX031C_GMSL2F_2CH,cam0

  • Supports separate configuration for CAM0 and CAM1 based on the camera model:

    dtoverlay=gmsl-2mp-camera-a,sensor-type=GMSL_2CH,cam0
    dtoverlay=gmsl-1mp-camera-a,sensor-type=GMSL_2CH

  • The default deserializer I2C address is 0x48(0x90 >> 1). To change it, add the dser-addr parameter:

    dtoverlay=isx031-gmsl-camera-a,sensor-type=ISX031C_GMSL2F_1CH,dser-addr=0x4a
    dtoverlay=isx031-gmsl-camera-a,sensor-type=ISX031C_GMSL2F_2CH,dser-addr=0x4a

  • After setting, save the file and reboot the system with sudo reboot

Quick Test

  • Install gstreamer1.0 tools:

    sudo apt install gstreamer1.0-tools -y

  • The driver board provides a test script for preview. After rebooting the system, you can use the following commands to perform a preview test of the camera

    • Use the -h parameter to view usage:

      ws_camera_preview.sh -h

    • Connected to Raspberry Pi CAM1, 2x ISX031C:

      ws_camera_preview.sh --csi1 ISX031-GMSL-Camera-A:2ch

    • Connected to Raspberry Pi CAM1, 1x ISX031C:

      ws_camera_preview.sh --csi1 ISX031-GMSL-Camera-A:1ch

    • Connected to Raspberry Pi CAM0, 2x ISX031C:

      ws_camera_preview.sh --csi0 ISX031-GMSL-Camera-A:2ch

    • Connected to Raspberry Pi CAM0, 1x ISX031C:

      ws_camera_preview.sh --csi0 ISX031-GMSL-Camera-A:1ch

    • Preview both simultaneously:

      ws_camera_preview.sh --csi0 GMSL-1MP-Camera-A:2ch --csi1 ISX031-GMSL-Camera-A:2ch

  • The following image is for reference only:

    Camera preview effect