ST VL53L8CX Low Power High Performance 8×8 Multizone
Introduction
The purpose of this Linux Start Guide is to assist Linux users, developers, and enthusiasts in a seamless integration of the ST BrightSense product line from STMicroelectronics.
ST BrightSense is a range of smart high-performance CMOS image sensors developed by STMicroelectronics for professional and consumer vision applications. Relying on proprietary innovations and processes, the ST BrightSense portfolio leverage cutting-edge pixel technologies to provide superior image quality for smart, accurate and reactive vision-based systems. Combining advanced technology nodes and well-thought-out designs, ST BrightSense products highlight tiny form factor and ultra-low power. Their rich toolbox of on-chip features allows faster and lighter processing to support the next generation of smart devices.
All ST BrightSense image sensors are provided with a range of hardware and software tools to enable simple and easy evaluation and development. Linux drivers for ST BrightSense products are available for free download on st.com for integration to Linux-based embedded processing platforms. This Linux Start Guide aims to support the use of these Linux drivers by providing essential knowledge and practical guidelines for integrating these advanced image sensors into a Linux environment. It includes indications on hardware prerequisites, basic Linux knowledge sharing and comprehensive installation procedure along with practical tips.
Acronyms and abbreviations
| Acronym/abbreviation | Definition |
| V4L2 | Video4Linux2: collection of drivers and API for realtime video capture on Linux systems |
| I2C | inter-integrated circuit (serial bus) |
| v4l2-ctl | Application to control Video4Linux2 drivers |
|
yavta |
“Yet another V4L2 test application”: Application to control Video4Linux2 camera drivers |
| gstreamer | Multimedia framework |
Before getting started
This section starts with an overview of the products supported by this Linux Start Guide. It provides also useful indications on where to find further product documentation and an overview of the compatible hardware tools that are needed to connect ST BrightSense image sensors to embedded processing platforms.
Supported devices
This Linux Start Guide covers all the products of the ST BrightSense portfolio, which includes at the time of writing the following image sensors.
Table 1. List of supported image sensors
| Sensor reference | Resolution | Color pattern | Shutter | Output |
| VD55G0 | 0.38 MP | Monochrome | Global | MIPI CSI-2 |
| VD55G1 | 0.56 MP | Monochrome | Global | MIPI CSI-2 |
| VD56G3 | 1.53 MP | Monochrome | Global | MIPI CSI-2 |
| VD66GY | 1.53 MP | RGB | Global | MIPI CSI-2 |
| VD16GZ | 1.53 MP | RGB-IR | Global | MIPI CSI-2 |
Compatible ST BrightSense hardware tools
To make integration onto Linux platform immediate, STMicroelectronics provides turnkey hardware tools enabling instant plug-and-play connection to embedded processing platforms. The Linux drivers supported by this Linux Start Guide have been developed to operate specifically on these hardware tools.
Every ST BrightSense image sensor is available with two main hardware kit options, which both contains the necessary board, optics and a 22-pin FFC/FPC cable. The S-Board is a hardware kit including a sensor board for a given image sensor, that is equipped with M12 lens holder and removable lens, enabling user to change lens at any time.
The P-Board is a hardware kit including a board with connector to evaluation any camera module provided by STMicroelectronics and its authorized partners. This kit enables to evaluate image sensors built as turnkey camera module to save the effort associated to lens selection and focus. 
Table 2. List of compatible ST BrightSense hardware tools
| Kit category | Kit reference | Sensor included? | Lens & holder? | Cable? | Output connector | Output |
|
S-Boards |
STEVAL-55G0MBI | VD55G0 | Yes | Yes | FFC/FPC | MIPI CSI-2 |
| STEVAL-55G1MBI | VD55G1 | Yes | Yes | FFC/FPC | MIPI CSI-2 | |
| STEVAL-56G3MAI | VD56G3 | Yes | Yes | FFC/FPC | MIPI CSI-2 | |
| STEVAL-66GYMAI | VD66GY | Yes | Yes | FFC/FPC | MIPI CSI-2 | |
| STEVAL-16GZMAI | VD16GZ | Yes | Yes | FFC/FPC | MIPI CSI-2 | |
| P-Board | STEVAL-CAM-M0I | None (promodule to order separately) | No | Yes | FFC/FPC | MIPI CSI-2 |
Finding further product information
To facilitate development and knowledge sharing, ST BrightSense documentation is made publicly available on st.com along with free software tools such as Linux drivers. While this Linux Start Guide focuses on the Linux driver installation and prerequisites, further information can be found regarding product specifications and features in the dedicated product documentation.
Each product webpage includes a “Documentation” section giving access to all the necessary product documentation such as data brief, datasheet, user manual or application notes. The “Tools & Software” section list all the compatible hardware and software tools available for this product and can guide you to the corresponding webpage, where further information and download are available for each hardware kit or software tool.
Introduction to Linux environment
About Linux camera stack
The Linux camera stack is a collection of open-source components that enable the interfacing and control of camera devices on Linux-based systems. It encompasses both kernel-level and user-space components, providing a comprehensive framework for different camera applications (ranging from simple webcam utilities to complex computer vision systems).
Two key components of the camera stack are the Video for Linux 2 (V4L2) framework and the libcamera library.
Introduction to V4L2 framework
At the core of the Linux camera stack is Video for Linux 2 (V4L2), which serves as the kernel API for handling video devices.
V4L2 provides a collection of (sub)device drivers and a standardized API for camera drivers, allowing applications to access and control a wide range of video capture devices, including USB cameras, embedded camera modules, as well as the different hardware IPs that are involved in image processing. V4L2 is responsible for exposing device nodes (/dev/videoX, /dev/v4l-subdevX, etc.) to user space. These nodes allow standard V4L2 applications to control and get frames from image sensors.
Many applications have V4L2 support, allowing for straightforward integration of image sensors (once they are V4L2-ready):
- v4l2-ctl: Swiss army knife for V4L2. Can be used to query or configure a V4L2 device.
- yavta: Yet Another V4L2 Test Application. A command-line tool with a very simple interface to configure and capture frames from a V4L2 device.
- VLC: A versatile media player with V4L2 support that allows capturing and streaming video from V4L2-compatible devices.
- GStreamer: A multimedia framework, providing V4L2 plugins for capturing, processing, and streaming video from V4L2-compatible devices.
- OpenCV: A popular computer vision library that includes V4L2 support for capturing and processing video streams from V4L2-compatible devices. It is widely used for image and video processing, object detection, and machine vision applications.
Introduction to Libcamera
Complementing V4L2 is libcamera. It operates as a user-space library and provides a unified interface for camera applications. Libcamera abstracts the complexity of handling the media pipeline; it offers a consistent API for camera control and image processing and enables support of advanced ISP features available in modern SOCs. (add v4l2 constraint by libcamera) As a newer addition to the Linux camera stack, libcamera is dynamic and evolving, with a focus on modernizing the camera stack and addressing the complexities of modern camera hardware and use cases.
Getting started with Raspberry Pi
This section details the installation procedure to get the image sensor streaming onto a Raspberry Pi platform using the Linux driver package available for free download on st.com. This installation procedure can be reused for other embedded platforms relying on Linux environment that uses a V4L2 framework or Libcamera library.
Hardware setup
Please Follow the instructions from Raspberrypi.com: link
Don’t forget to plug the flex in the right way and before to plug power supply: 
V4L2 driver
This section describes how to build and install the V4L2 driver on a Linux target platform. For simplicity, the driver is built directly on the target, as it needs to be:
- Built for the corresponding target architecture,
- Built against the current running Linux kernel headers.
Note: Raspberry Pi is used as an example, however the process is similar on other Linux platforms.
V4L2 driver content
The V4L2 driver corresponding to the ST BrightSense image sensor must be downloaded from st.com. Once unzipped on the target Linux platform, the following content should be available (example based on the vd55g1 driver): 
Driver installation
The next steps assume that the Raspberry Pi is up and running with an up-to-date Operating System. As of writing, the latest Raspberry Pi OS (based on Kernel 6.6) was released on March 15th, 2024.
- By default, Linux kernel headers are installed on latest RPi OS releases, if not, run the following commands:
- Compile the driver source using the Makefile (this will generate a .ko module file) :
$ make - Install the freshly built module in the kernel modules folder:
$ sudo cp *.ko /lib/modules/$(uname -r) $ sudo depmod -a - Finally, reboot to apply the modifications:
$ sudo reboot
Device tree configuration
The device tree is a tree data structure with nodes that describe the hardware components of a system. When a new hardware is connected to a system, its device tree must be updated accordingly.
- Ensure the device tree compiler tool is present on your system:
$ sudo apt update
$ sudo apt install device-tree-compiler - From the dts folder, compile the device tree overlay matching your platform and plugin board (for the example “pcb4189.dts“ is chosen):
$ cd dts
$ sudo dtc pcb4189.dts -o /boot/firmware/overlays/pcb4189.dtbo - Set the device tree overlay for your Raspberry Pi (this step may differ from platform to platform):
$ sudo sh -c “echo ‘dtoverlay=pcb4189’ >> /boot/firmware/config.txt” - Finally, reboot to apply the modifications:
$ sudo reboot
Libcamera
RPi OS Libcamera update
By default, Raspberry Pi OS comes with Libcamera library. Using Libcamera allows to benefit from Broadcom HW ISP available on the RPi SoC for image processing (debayering, 3A, etc.). Each Image Sensor must be described in Libcamera. For that reason, the RPi OS Libcamera package should be upgraded with a new version where all ST BrightSense Image Sensors are described.
Note: The below steps only target Raspberry Pi platform as the libcamera package provided is RPi OS specific.
Once the libcamera package has been downloaded from st.com it can be installed with the below command line:
$ sudo dpkg -i libcamera-ipa_0.2.0.deb
Libcamera usage
With libcamera upgraded, it’s possible to use all the rpicam-apps (please refer to RPi-OS documentation to get all details on those libcamera-apps)
For a quickstart, please find below a few one-liners:
- # List the cameras attached to the board and the sensor modes supported
- $ rpicam-hello –-list-cameras
- # Display camera preview (with default mode)
- $ rpicam-hello –timeout 0
- # Display camera preview (with chosen 640×480 mode)
- $ rpicam-hello –timeout 0 –viewfinder-width 640 –viewfinder-height 480
- # After 5 secs preview, capture raw frame (before any ISP processing) as well as jpeg
- $ rpicam-still –raw –o frame.jpg
- #Change Camera tunning
- $rpicam-hello –tuning-file path_of_file.json
Code example using Libcamera
To use the capacity of libcamera you can developpe your own application, here you will find an example to stream with python.
First of all, install the package for python 3 :
- $ sudo apt install -y python3-pyqt5 python3-opengl
- $ sudo apt install -y python3-picamera2
Example code to run at 60 fps in 1120×1360 for VD56G3/VD66GY and capture image through button. To find more control please refer to picamera manual
Getting started with other V4L2 tools
While some embedded platforms such as the Raspberry Pi series rely on Libcamera as a camera software library, other Linux-based platforms don’t benefit from it and only support V4L2. In such situation, standard V4L2 tools must be used to communicate with the image sensor. The following paragraphs present a few command-line tools along with a compilation of useful one-liners.
v4l2-ctl
Swiss army knife for v4l2: this command-line tool can be used to query, configure, or stream from a v4l2 device. Available in all distributions, on Debian-like distros it can be installed with the following:
$ sudo apt install v4l-utils
Useful one-liners:
- # List formats and controls (with their menus when available)
- $ v4l2-ctl –list-formats-ext –list-ctrls –list-ctrls-menu
- # Select Format (resolution: 640×480 and pixel format: GRBG Bayer 10Bit)
- $ v4l2-ctl –set-fmt-video width=640,height=480,pixelformat=BA10
- # Configure V4L2 controls (switch to manual mode and configure exposure (1800 lines))
- $ v4l2-ctl –set-ctrl auto_exposure=1
- $ v4l2-ctl –set-ctrl exposure=1800
- # Configure Vertical Blanking to change framerate (vblank is resolution dependant)
- $ v4l2-ctl –set-ctrl vertical_blanking=3056
- # Capture 20 frames (concatenated in one ‘capture_20f.raw10’ file)
- $ v4l2-ctl –stream-mmap –stream-count=20 –stream-to=capture_20f.raw10
yavta
Yet Another V4L2 Test Applications. A simple command-line tool supporting many of the latest V4L2 capabilities and used to interact with a V4L2 device.
On Debian-like distributions it can be installed with the following:
- $ sudo apt install yavta
Useful one-liners:
- # List formats and controls
- $ yavta –list-controls –enum-formats /dev/video0
- # Select Format (resolution: 640×480 and pixel format: GRBG Bayer 8Bit)
- $ yavta –size 640×480 –format SGRBG8 /dev/video0
- # Configure V4L2 controls (switch to manual mode and configure exposure (1800 lines))
- $ yavta –set-control ‘0x009a090 1’ /dev/video0
- $ yavta –set-control ‘0x00980911 1800’ /dev/video0
- # Configure Vertical Blanking to change framerate (vblank is resolution dependant)
- $ yavta –set-control ‘0x009e0901 3056’ /dev/video0
- # Capture (30 frames saved in 30 files)
- $ yavta –capture=30 –file=frame-#.raw8 /dev/video0
V4L2 code example
To use the capacity of V4L2 api you can developpe your own application, here you will find an example to stream with python.
First of all, install the package for python 3 :
$ pip3 install v4l2-python3 $ pip3 install opencv-python $ pip3 install python3-nmap
IMPORTANT NOTICE – READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgment. Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein. Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, refer to www.st.com/trademarks. All other product or service names are the property of their respective owners. Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2024 STMicroelectronics – All rights reserved
FAQ
Q: Where can I find further product documentation?
A: Further product documentation can be obtained by contacting your local STMicroelectronics sales office or visiting www.st.com.
Documents / Resources
 |
ST VL53L8CX Low Power High Performance 8x8 Multizone [pdf] User Guide VL53L8CX Low Power High Performance 8x8 Multizone, VL53L8CX, Low Power High Performance 8x8 Multizone, High Performance 8x8 Multizone, Performance 8x8 Multizone |
