voxl-uvc-server

Overview

voxl-uvc-server is an application which grabs video from UVC cameras and serves up the video as an MPA (Modal Pipe Architecture) pipe for other applications to pull from. This server is often used in conjunction with voxl-streamer.

There are a large array of UVC cameras on the market and we haven’t tested them all, but below is a list of some that we know voxl-uvc-server supports.

In general, voxl-uvc-server supports UVC cameras that have the ability to provide a raw frame output.

Logitech C270
Logitech C930e
Logitech Brio
Videology 5MP Micro USB 2.0 Board Camera
PureThermal Mini with Flir Lepton
Flir Boson 640
Blue Robotics h264 camera

Usage

As with all MPA services, voxl-uvc-server can be configured and enabled to run on boot using it’s configuration script. Usage is as follows:

voxl2:/$ voxl-configure-uvc -h

Tool to configure voxl-uvc-server

Shortcut configuration arguments for scripted setup.
factory_enable will reset the config file to factory defaults
before enabling the service.


voxl-configure-uvc disable
voxl-configure-uvc factory_enable
voxl-configure-uvc enable
voxl-configure-uvc boson
voxl-configure-uvc lepton
voxl-configure-uvc vga30 (same as default)
voxl-configure-uvc 1080p5 (for logitech 1080p webcam)

show this help message:
voxl-configure-uvc help

Configuring voxl-uvc-server will set up the following default configuration file:

voxl2:/$ cat /etc/modalai/voxl-uvc-server.conf
/**
 * This file contains configuration that's specific to voxl-uvc-server.
 * parameter descriptions:
 *
 * width: Desired image width. (e.g. 640)
 * Default is 640.
 *
 * height: Desired image height. (e.g. 480)
 * Default is 480.
 *
 * fps: Desired frame rate in fps (e.g. 15).
 * Default is 30.
 *
 * pipe_name: Desired MPA pipe name in /run/mpa (e.g. webcam).
 * Default is uvc.
 *
 * encoder_enable: Enable the h264/h265 hardware encoder.
 * Default is true.
 *
 * encoder_codec: "h264" or "h265".
 * Default is h265.
 *
 * encoder_bitrate_mbps: Target bitrate in megabits/sec (CBR).
 * Default is 2.0.
 *
 * encoder_gop: Number of P-frames between keyframes. 0 = auto (fps).
 * Default is 0.
 *
 * encoded_pipe_name: MPA pipe name for encoded stream. Empty = <pipe_name>_encoded.
 * Default is empty.
 *
 */
{
	"pipe_name":	"uvc",
	"width":	640,
	"height":	480,
	"fps":	30,
	"encoder_enable":	true,
	"encoder_codec":	"h265",
	"encoder_bitrate_mbps":	2,
	"encoder_gop":	0,
	"encoded_pipe_name":	""
}

Hardware Encoder

As of version 0.1.8, voxl-uvc-server can hardware-encode the camera stream and publish it on a second pipe. This is controlled by five config keys:

encoder_enable: enable the h264/h265 hardware encoder (default true)
encoder_codec: "h264" or "h265" (default "h265")
encoder_bitrate_mbps: target bitrate in megabits/sec, CBR (default 2.0)
encoder_gop: number of P-frames between keyframes, 0 = auto (fps) (default 0)
encoded_pipe_name: MPA pipe name for the encoded stream; empty means <pipe_name>_encoded (default empty)

If a camera doesn’t support the default configuration, use one of the configuration presets or edit the config file. For example, the PureThermal Mini with FLIR Lepton requires 160x120 at 9 fps, which is set up by running:

voxl-configure-uvc lepton

Presets are also available for the FLIR Boson (boson), a standard VGA webcam (vga30, same as the default), and 1080p webcams such as the Logitech 1080p models (1080p5).

After modifying the configuration file, voxl-uvc-server can be restarted by power cycling or running the following:

systemctl restart voxl-uvc-server

Tips

voxl-uvc-server also provides a few helpful debugging tools in order to troubleshoot issues or determine the required configuration for a new camera.

The Linux command line utility, lsusb, can be very helpful to see what devices have enumerated on the USB bus. One can run the command with a USB camera attached to see if the camera has enumerated.

voxl2:/$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 046d:0825 Logitech, Inc. Webcam C270
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

One can look at the above output and determine the vendor ID and Product ID of their camera, in this example the vendor ID is 046d, while the product ID is 0825

lsusb -v -d $VENDOR_ID:$PRODUCT_ID can also provide a lot more information about a specific device, for example:

voxl2:/$ lsusb -v -d 046d:0825

Bus 001 Device 002: ID 046d:0825 Logitech, Inc. Webcam C270
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass          239 Miscellaneous Device
  bDeviceSubClass         2
  bDeviceProtocol         1 Interface Association
  bMaxPacketSize0        64
  idVendor           0x046d Logitech, Inc.
  idProduct          0x0825 Webcam C270
  bcdDevice            0.12
  iManufacturer           0
  iProduct                0
  iSerial                 2 9C06CEC0
  bNumConfigurations      1
  ...

voxl-uvc-server also provides a script called show-video-device-info.sh which can be used to get useful information about any attached UVC cameras:

voxl2:/$ show-video-device-info.sh
/dev/video2: UVC Camera (046d:0825) 046d:0825

For debugging purposes, voxl-uvc-server can be ran manually from the command line and has the ability to pass in a few arguments for customization:

voxl2:/$ voxl-uvc-server -h
Usage: voxl-uvc-server <options>
Options:
-d                Show extra debug messages
-v <vendor-id>    USB vendor id of the desired UVC device in hexadecimal (e.g. 090c)
                  Default is search for any vendor id
-p <product-id>   USB product id of the desired UVC device in hexadecimal (e.g. 337b)
                  Default is search for any product id
-r <resolution>   Desired image resolution (e.g. 320x240)
                  Default is 640x480
-f <fps>          Desired frame rate in fps (e.g. 15)
                  Default is 30
-l                List all devices found then exit
-o <name>         Custom output name
                  Default is uvc
-s                Use this to launch a new instance alongside the default service
-h                Show help
-E                Disable the hardware encoder (default: enabled)
-C <h264|h265>    Codec for encoded pipe (default: h265)
-B <mbps>         Encoder target bitrate in Mbps (default: 2.0)
-G <n>            Encoder GOP size (P-frames between I-frames, 0 = fps)
-O <name>         Encoded pipe name (default: <pipe_name>_encoded)

These arguments will override the config file at /etc/modalai/voxl-uvc-server.conf

Simultaneous UVC cameras

As of version 0.1.7, the supported way to run a second UVC camera is to launch a second instance of voxl-uvc-server with the -s (standalone) flag, which lets it run alongside the default service instead of replacing it. Give the second instance its own output pipe name with -o and select the desired camera by vendor and product id:

voxl-uvc-server -s -o uvc2 -v 046d -p 0825

Due to a bug in libuvc, two USB cameras may fail to stream simultaneously if they use identical formatting options. If you run into this, make one camera use different formatting options than the other; the least intrusive way is to set a different frame rate on one instance, e.g. -f 25.