How to install or upgrade UV4L on Raspbian Stretch, Buster (suggested) or Bullseye (32-bit Raspberry PI OS) for Raspberry Pi
IMPORTANT UPDATES
- Packages for Raspbian Wheezy and Raspbian Jessie are no longer maintained, consider to upgrade your system to a Raspberry Pi OS Bullseye, Buster or Raspbian Stretch instead.
- For Bullseye users: before installing and using (many of) the UV4L drivers with hardware acceleration enabled, you must:
- open a terminal and run the following commands:
- sudo rpi-update
- echo /opt/vc/lib/ | sudo tee /etc/ld.so.conf.d/vc.conf
- sudo ldconfig
- enable the Legacy Camera support from the Interface Options menu of the following system command and reboot:
- sudo raspi-config
- sudo reboot
- open a terminal and run the following commands:
The following instructions explain how to install UV4L on the official Linux distributions supported by the Raspberry Pi Foundation and available for any model of the Raspberry Pi boards: Zero, Zero W (Wireless), 1, 2, 3, 4, Compute Module 1, Compute Module 3, Compute Module 4.
Although some other distributions than Raspbian/Raspberry Pi OS and other ARM-based boards different than Raspberry Pi have been reported to work, they are not officially supported.
As these instructions are updated and improved very frequently without notice, it is suggested to read them from scratch in case of problems and especially whenever a new UV4L module is announced. Important notes about specific drivers, modules, configurations, etc.. can be found at the bottom of this page.
Unless new important features or breaking changes are announced, small software and manual updates may be released without notice. This means it’s your responsibility to regularly check the repository for new versions and keep your local installation up-to-date. Preserving backward compatibility across subsequent releases is and has always been a priority.
All the software is provided “as is” and with absolutely no warranty. Exact license terms are included in each package.
The UV4L software suit consists of a series of highly configurable drivers, an optional Streaming Server module providing a RESTful API for custom development and various extensions for the server that cooperate together. The Streaming Server also provides the basic web UI for the end-users to try or use all the key functionalities directly. For maximum efficiency, each instance of UV4L runs as a single, independent system process which exploits the underlying hardware natively (whenever possible). Here is a more detailed list of features.
Below we will see how to install all the modules to get the best from UV4L, with particular focus on the driver for the Raspberry Pi camera boards for the sake of explanation, although all other drivers mentioned afterwards can be optionally installed in a similar way.
This same driver has been extended to support the TC358743 HDMI to MIPI chipset converter on all Raspberry Pi boards (this chipset is present on the B101 HDMI to CSI-2 Bridge, for example). However, instructions on how to enable the TC358743 on boards different from Raspberry Pi 3 (e.g. Zero, ZeroW, CM3, etc…) will be provided upon request only.
If you are running Raspbian Stretch, Buster or Bullseye (also known as Raspberry PI OS) instead, type the following commands:
$ curl https://www.linux-projects.org/listing/uv4l_repo/lpkey.asc | sudo apt-key add - $ echo "deb https://www.linux-projects.org/listing/uv4l_repo/raspbian/stretch stretch main" | sudo tee /etc/apt/sources.list.d/uv4l.list
Now we are ready to update the system and to fetch and install the packages:
$ sudo apt-get update $ sudo apt-get install uv4l uv4l-raspicam
The above two commands will upgrade the packages to the most recent version, in case they have been already installed.
Recently, a new driver called uv4l-raspicam-ai has been introduced into the UV4L suite. The suffix “-ai” stands for Artificial Intelligence: in facts, this driver is totally equivalent to the traditional and alternative uv4l-raspicam driver previously installed, except it enables a few new options which allow to run Tensor Flow Lite models on the CPU (slow) or, alternatively, through the Google Edge TPU USB accelerator to achieve real-time object detection. Furthermore, thanks to the native support for pan/tilt servomotors connected to the Pimoroni Pan-Tilt HAT (PIM183) and thanks to an industrial-grade PID controller built in the driver, it is possible to do accurate real-time object tracking “out-of-the-box”.
It is safe to install this driver even if you do not have the Edge TPU and the Pi Hat or do not plan to use them, as the corresponding options are disabled by default. However, the Raspberry Pi Zero is not supported by this new driver. This driver also depends on the libedgetpu debian package (available in two flavors) from Coral, thus you must install it first:
$ echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list
$ curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install libedgetpu1-max
Please follow to the official instructions for more informations or in case the above installation fails. Now, you can install the uv4l-raspicam-ai driver as follows, or, at any time, you can transparently switch from uv4l-raspicam to the uv4l-raspicam-ai driver (and viceversa):
$ sudo apt-get install uv4l-raspicam-ai
Whatever driver you decide to you use between uv4l-raspicam and uv4l-raspicam-ai, if you optionally want it to be loaded at boot, then install this package as well:
$ sudo apt-get install uv4l-raspicam-extras
As a convenience, the above package will install a service script for starting, stopping or restarting the driver at any time, for example:
$ sudo service uv4l_raspicam restart
When (re)starting the service, uv4l will be instructed to parse the configuration file /etc/uv4l/uv4l-raspicam.conf to get the default values for the driver and the server options. You can edit that file to add, remove or change the default values. This same service is started at boot.
If you are using the TC358743, the uv4l-tc358743-extras package has to be installed for it to work:
$ sudo apt-get install uv4l-tc358743-extras
The above package will automatically install the uv4l-raspicam-extras package and some other helper programs. Before using the TC358743 make sure that both the Camera interface and the I2C bus are enabled in the raspi-config system tool and that the line tc358743=yes is present or uncommented in the configuration file /etc/uv4l/uv4l-raspicam.conf.
Now the UV4L core module and the Video4Linux2 driver for the CSI Camera Board are installed. If you occasionally get unexpected errors from the driver, make sure the camera is enabled and enough memory is reserved for the GPU (256MB or more is suggested) from this menu:
$ sudo raspi-config
This is generally not required, but if you still experience problems, please consider updating the firmware with the following command:
$ sudo rpi-update
For detailed informations, options, etc… about the modules installed type accordingly:
$ man uv4l $ man uv4l-raspicam
To get the list of all available options:
$ uv4l --help --driver raspicam --driver-help
If you have not installed the optional uv4l-raspicam-extras package (which provides a convenient script for starting uv4l with the settings taken from a configuration file) and want to quickly test uv4l with the camera module, first load the driver manually:
$ uv4l --driver raspicam --auto-video_nr --width 640 --height 480 --encoding jpeg
(you might need to also set the –tc358743-i2c-dev option properly in case you have the TC358743 instead). Now you can take a JPEG snapshot from the device:
$ dd if=/dev/video0 of=snapshot.jpeg bs=11M count=1
For a list of other use cases click here.
To manually terminate a running driver, close all the applications accessing the device and kill the corresponding uv4l process:
$ pkill uv4l
Apart from the driver for the Raspberry Pi Camera Board, the following Streaming Server front-end and drivers can be optionally installed:
$ sudo apt-get install uv4l-server uv4l-uvc uv4l-xscreen uv4l-mjpegstream uv4l-dummy uv4l-raspidisp
for which the manual pages are available:
$ man uv4l-server $ man uv4l-uvc $ man uv4l-xscreen $ man uv4l-mjpegstream $ man uv4l-dummy $ man uv4l-raspidisp
The WebRTC extension for the Streaming Server is also available with two alternative packages depending on the Raspberry Pi model in use. If you have a Raspberry Pi 1, Compute Module 1, Zero or Zero W (Wireless), type:
$ sudo apt-get install uv4l-webrtc-armv6
Otherwise, if you have any other model (e.g. Raspberry Pi 2 or 3), type:
$ sudo apt-get install uv4l-webrtc
As the Streaming Server is able to serve and run any custom web applications, an optional package containing the source code of some of the demos mentioned in the examples (e.g. this one) is available. The files will be installed in /usr/share/uv4l/demos/:
$ sudo apt-get install uv4l-demos
Note that some browsers may no longer exploit many of the WebRTC functionalities over HTTP for security reasons. You will need to configure secure HTTPS in the Streaming Server instead. To do this, you must provide a password-less private key and a valid certificate via the –ssl-private-key-file and the –ssl-certificate-file server options. A private key and a self-signed certificate can be generated as follows:
$ openssl genrsa -out selfsign.key 2048 && openssl req -new -x509 -key selfsign.key -out selfsign.crt -sha256
Once you have installed and eventually configured the HTTP(S) Streaming Server module as shown above, make sure to reload uv4l for it to notice and start the server. Afterwards you can access the server with the browser at the default address and port https://raspberry:8080/ (where raspberry has to be replaced with the actual hostname or IP address of your RaspberryPi and the protocol can be either http or https).
Many of the Streaming Server and WebRTC settings can be changed on-the-fly thanks to the RESTful API without restarting UV4L.
Thanks to the WebRTC extension mentioned above, it’s also possible to broadcast both live audio and video contents from the Raspberry Pi 2 to all the participants or viewers joining a room of a Jitsi Meet conference on the Web. Furthermore, no browser and no GUI will have to be used on the Raspberry Pi. For this to be possible, it’s necessary to install the additional xmpp-bridge service, which will be automatically started once the installation has finished or when the system boots:
$ sudo apt-get install uv4l-xmpp-bridge
TC358743
As mentioned before, the TC358743 requires the uv4l-tc358743-extras package to be installed. Make sure you have both the Camera and I2C enabled with the raspi-config system tool (which essentially comments out the option dtparam=i2c_arm=on in /boot/config.txt and adds the i2c-bcm2708 and i2c-dev lines in /etc/modules).
As the support for this chip is essentially an extension of the uv4l-raspicam driver which had been originally written for image sensors primarily, the TC358743 has to be explicitly enabled with the –tc358743 driver option specified, via command line or in the uv4l-raspicam configuration file, before it can be used. Some of the options listed in the uv4l-raspicam manual page affect the TC358743 as well; you are encouraged to read the driver manual for more informations. One useful option is –tc358743-edid-file, which allows you to specify a path to a file containing a custom EDID in hex format to be used with the TC358743.
A quick test to see if capturing works if you have no device with HDMI-out ready to use can be made by simply connecting the HDMI-out port of the Raspberry Pi to the HDMI-in port of the B101 board on the same Raspberry Pi. Make sure hdmi_force_hotplug=1 is set in /boot/config.txt for the HDMI signal to be detected.
Audio configuration
By default WebRTC gets its input audio from the default recording device, which usually is the first entry that appears in the ordered list given by the arecord –list-pcms command. If you want to make use of another device, it’s enough to set the –webrtc-recdevice-index configuration option to the corresponding position in the list (starting from 0, top-down).
Alternatively, if you want, for example, to use an USB sound card as your default recording device, then do the following: edit or create /etc/asound.conf and insert:
pcm.!default {
type asym
playback.pcm "plug:hw:0"
capture.pcm "plug:dsnoop:1"
}
where “0” is usually the index of the default sound card embedded in the Raspberry Pi that will be used for playback, while “1” usually corresponds to the index of the USB sound card that will be used for capture. After you have rebooted, make sure capture volumes are unmuted and increased to the desired level. alsamixer is an handful tool for this purpose. If the quality or the volume of the captured audio is not as expected for some reasons, try with a sample rate of 44100 Hz. If the hardware does not support this sample rate natively, try with the ALSA sample rate converter plug-in.
OLD: in Raspbian Wheezy, edit /etc/modprobe.d/alsa-base.conf and modify or add the following lines and reboot the system:
options snd-usb-audio index=0 options snd_bcm2835 index=1
Note for the UVC driver users
Since recent versions of UV4L, there should be no longer need to manually load the uvc driver to use your webcam. After you have rebooted the OS for the first time after installation, it’s enough to unplug and plug in the webcam again to get it recognized by the installed system service and have an uv4l instance loaded automatically. Similarly, if you unplug the webcam, the same instance gets killed for you. At the same time, if you also installed the UV4L Streaming Server, a server instance is automatically created or destroyed. The port the server will be listening to is specified in the configuration file /etc/uv4l/uv4l-uvc.conf and should be 8090 by default. You do not typically need to modify this configuration file.
Although nothing forbids to have multiple instances of uv4l running at the same time, the above automatism will only work for one UVC-based device plugged in, at most, at the same time – which is the common case. Unfortunately, from the second webcam onwards the system service is not so smart: as it does not internally make any distinction between the uvc-based webcams and reads the same configuration file each time, any new Streaming Server instance will try to use the same port again, which might result in a conflict with the first running instance. In this case, be prepared to tweak the service script (namely /etc/init.d/uv4l_uvc) appropriately and eventually use multiple configuration files.
Raspidisp driver
The raspidisp driver turns HDMI-out into a virtual Video4Linux-compliant input device (like a camera). You do not necessarily need a display connected to the Raspberry Pi HDMI-out port. In other words, this driver can capture whatever you see or would see on the screen.
This is useful if you have an headless Raspberry Pi. With the help of the UV4L Streaming Server you can have full control of the Raspberry Pi from within any browser (running on a PC in the same network, for example). In facts, it’s possible to stream the frame buffer of Raspberry Pi to a standard web page in the browser (plugin-free) with very low latency and, at the same time, forward keyboard or mouse input events from the PC to the Raspberry Pi. If you want to try this, apart from uv4l-raspidisp, the uv4l-raspidisp-extras package has to be installed:
$ sudo apt-get install uv4l-raspidisp-extras
The above package includes a system service that automatically starts an uv4l instance at boot and, if installed, also an instance of the Streaming Server listening to port 9080 by default. The service instructs uv4l to parse the configuration file /etc/uv4l/uv4l-raspidisp.conf for the initial setting values.