Mv series camera appnotes 4 rpi
1 Introduction
The MV series cameras are cameras introduced for AI applications in the industrial field. It uses the MIPI CSI-2 interface, which is especially suitable for embedded computing platforms.
It features rich data formats and trigger characteristics, extremely low latency, extremely high bandwidth and reliable stability.
This article describes how to use the MV series camera on the Raspberry Pi platform.
1.1 Camera module list
| Series | Model | Status |
|---|---|---|
| MV series | MV-MIPI-IMX178M | Done |
2 Hardware Setup
MV series cameras need to use ADP-MV1 adapter board in order to connect to Raspberry Pi.
We take MV-MIPI-IMX178M as an example to introduce the hardware installation method.
2.1 Connection of MV-MIPI-IMX178M and ADP-MV1
The two are connected using 0.5 mm pitch*30P FFC cable with opposite direction. The cable must be inserted with the silver contacts facing outside.
(TODO picture)
2.2 Connection of ADP-MV1 to Raspberry Pi
2.2.1 Power supply
The ADP-MV1 requires a separate 5V power supply and can be powered directly from the Raspberry Pi motherboard using a Dupont cable.
(TODO picture)
2.2.2 Raspberry Pi Model B and B+
The two are connected using 1.0 mm pitch*15P FFC cable with opposite direction. Pay attention to the silver contacts facing side.
(TODO picture)
2.2.3 Raspberry Pi Zero, Zero W and Computer Module
The two are connected using 15Pto22P FFC cable with same direction. Pay attention to the silver contacts facing side.
(TODO picture)
3 piOS Configuration
For details on how to install the Raspberry Pi system, please refer to the official documentation at Install raspberry pi guide.
Initially, the Raspberry Pi system I2C is not enabled. After booting, we need to turn them on manually by executing the following command:
sudo raspi-config
Enter Interface Options, enable I2C, and then restart the Raspberry Pi.
It is recommended to enable the ssh service and samba service of Raspberry Pi system, here we will not go into the details of how to enable ssh and samba service of Raspberry Pi system.
4 Legacy mode and V4L2 mode introduction
The difference between these two modes is described in detail on the Raspberry Pi website. The libcamera-stack mode mentioned on the Raspberry Pi website is architecturally identical to the V4L2 mode we are talking about.
4.1 Legacy mode
Traditional mode, relying on Broadcom's GPU for image processing. The traditional raspicam software set uses this model.
The disadvantage of this model is closed. The GPU side is closed source, can not freely access sensor.
The Raspberry Pi organization has switched to the libcamera camera stack, but this model still has value:
- More use of GPU resources and lower CPU load. This is useful for earlier versions of the Raspberry Pi where CPU performance is poorer.
- It is possible to simply and directly fetch image data to the application layer without the support of the driver layer. This is especially useful for cameras that do not rely on the Raspberry Pi's isp.
- libcamera lacks some feature support now.
There are two ways to use Legacy mode.
- Use the Legacy version of piOS.
- For the bullseye or newer version of piOS, turn on the Legacy Camera option in raspi-config.
Since the two modes cannot co-exist, Legacy mode needs to be turned off when using V4L2 mode.
4.2 libcamera and V4L2 mode
Now piOS has switched to libcamera-stack mode.
Libcamera is essentially centered on implementing isp functionality, something that is not needed for the MV series cameras. Therefore, we have adopted the V4L2 mode instead of using libcamera-stack.
As with libcamera-stack, our V4L2 model implements the standard V4L2 driver for the linux driver layer too. Based on this driver, the application layer can directly develop programs to acquire images and perform further processing.
5 V4L2 mode manual
We have saved the code for v4l2 mode in this github repository.
5.1 Download the driver package
wget https://github.com/veyeimaging/raspberrypi_v4l2/releases/latest/download/raspberrypi_v4l2.tgz
5.2 Install driver
tar -xzvf raspberrypi_v4l2.tgz
cd raspberrypi_v4l2/release/
chmod +x *
sudo ./install_driver.sh veye_mvcam
Then reboot Raspberry Pi.
Note: If you are prompted that the corresponding version of the driver cannot be found, it means that we do not provide a compiled driver corresponding to your piOS version. Please try to compile from the source code.
5.3 Uninstall the driver
If you need to change to Legacy mode, or want to change to another camera module model driver, you must uninstall the current driver first.
sudo ./uninstall_driver.sh veye_mvcam
5.4 Check system status
Take MV-MIPI-IMX178M as an example.
dmesg | grep mvcam
You can see the camera model and the version of the camera probed during the Linux boot phase.
camera is: MV-MIPI-IMX178M
firmware version: 0x1080102
And the /dev/video0 node exists, which proves that the camera status is normal.
5.5 v4l2-ctl application examples
5.5.1 Install v4l2-utils
sudo apt-get install v4l-utils
5.5.2 Install yavta
git clone git://git.ideasonboard.org/yavta.git
cd yavta;make
5.5.3 Configure parameters using v4l2-ctl
5.5.3.1 List the data formats supported by the camera
v4l2-ctl --list-formats-ext
ioctl: VIDIOC_ENUM_FMT
Type: Video Capture
[0]: 'GREY' (8-bit Greyscale)
Size: Discrete 3088x2064
[1]: 'Y10P' (10-bit Greyscale (MIPI Packed))
Size: Discrete 3088x2064
[2]: 'Y10 ' (10-bit Greyscale)
Size: Discrete 3088x2064
[3]: 'Y12P' (12-bit Greyscale (MIPI Packed))
Size: Discrete 3088x2064
[4]: 'Y12 ' (12-bit Greyscale)
Size: Discrete 3088x2064
[5]: 'UYVY' (UYVY 4:2:2)
Size: Discrete 3088x2064
Note: UYVY data format is for debugging use only.
5.5.3.2 List the configurable parameters of the camera implemented in the driver
v4l2-ctl -L
User Controls
horizontal_flip 0x00980914 (bool) : default=0 value=0
vertical_flip 0x00980915 (bool) : default=0 value=0
trigger_mode 0x00981901 (int) : min=0 max=2 step=1 default=0 value=0 flags=volatile
trigger_src 0x00981902 (int) : min=0 max=1 step=1 default=1 value=1 flags=volatile
soft_trgone 0x00981903 (button) : flags=write-only, execute-on-write
frame_rate 0x00981904 (int) : min=0 max=22 step=1 default=22 value=22 flags=volatile
Parameters can be set and get using the following methods.
v4l2-ctl --set-ctrl [ctrl_type]=[val]
v4l2-ctl --get-ctrl [ctrl_type]
All the above functions can be implemented using mv_mipi_i2c.sh.
None of the above parameters can be modified in the state when the image acquisition is started.
Each of them is described below:
5.5.3.3 horizontal and vertical flip
- horizontal flip
v4l2-ctl --set-ctrl horizontal_flip=1
- vertical flip
v4l2-ctl --set-ctrl vertical_flip=1
5.5.3.4 Trigger Mode
v4l2-ctl --set-ctrl trigger_mode=[0-2]
0：Video streaming mode
1：Normal trigger mode.
2：High-speed continuous trigger mode.
5.5.3.5 Trigger Source
v4l2-ctl --set-ctrl trigger_src=[0-1]
0: Software trigger mode.
1: Hardware trigger mode.
5.5.3.6 Software trigger command
v4l2-ctl --set-ctrl soft_trgone=1
5.5.3.7 Set frame rate
v4l2-ctl --set-ctrl frame_rate=[1-max]
The maximum frame rate is automatically updated as the resolution changed.
5.5.3.8 Set ROI
For example, for MV-MIPI-IMX178M:
v4l2-ctl --set-selection=target=crop,top=32,left=64,width=2592,height=1944
The maximum frame rate will be adjusted automatically after setting ROI.
5.6 Set ROI and save the image
5.6.1 Set ROI
Take MV-MIPI-IMX178M, 3088*2064 as an example.
v4l2-ctl --set-selection=target=crop,top=0,left=0,width=3088,height=2064
5.6.2 Frame rate statistics
In streaming mode, the following commands can be used for frame rate statistics.
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=-1 --stream-to=/dev/null
5.6.3 Save image to file
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=1 --stream-to=y8-3104x2064.yuv
Or
./yavta -c1 -Fy8-3104x2064.yuv --skip 0 -f Y8 -s 3088x2064 /dev/video0
PS. This y8 file can be used with this player: YUV Displayer Deluxe.
Since the memory requested by Raspberry Pi for the image, the width is 32-align and the height is 16-align, the 3088*2064 image will be saved as 3104*2064 size.
5.7 Trigger mode
5.7.1 Set ROI
Take MV-MIPI-IMX178M, 3088*2064 as an example.
v4l2-ctl --set-selection=target=crop,top=0,left=0,width=3088,height=2064
5.7.2 Software trigger mode
5.7.2.1 Set mode
v4l2-ctl --set-ctrl trigger_mode=1
v4l2-ctl --set-ctrl trigger_src=0
5.7.2.2 Start acquisition
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=5 --stream-to=y8-3104x2064.yuv
5.7.2.3 Perform soft trigger operation
In other shell terminals, you can execute the following command multiple times for multiple triggers.
v4l2-ctl --set-ctrl soft_trgone=1
Notes: The first image triggered in this way cannot be output and saved. I haven't found out why.
5.7.3 Hardware trigger mode
The following is an example of using Raspberry Pi GPIO21 as an trigger source with rising edge trigger.
You can use the mv_mipi_i2c.sh script for other trigger parameter setting.
5.7.3.1 Hardware Connection
(TODO picture)
5.7.3.2 Set mode
v4l2-ctl --set-ctrl trigger_mode=1
v4l2-ctl --set-ctrl trigger_src=1
5.7.3.3 Start acquisition
v4l2-ctl --set-fmt-video=width=3088,height=2064,pixelformat=GREY --stream-mmap --stream-count=5 --stream-to=y8-3104x2064.yuv
5.7.3.4 Perform hardware trigger operation
python gpio_trigger.py
Note: script link.