This page refers to the development version of the package and releases made AFTER 01.04.2023!

The develop branch of the repository contains the code that IS NOT CURRENTLY RELEASED! Please consider it a beta release-candidate version implementing the new API and configuration policy.

ROS binary package repository is now containing version 0.3.7 available for installation!

Please note that the documentation for previously released (0.3.7 and earlier) versions of this package is available on Old versions' documentation subpage


This package provides a configurable ROS interface to the kernel API of libv4l2 library that implements a common driver for standard USB web cameras. The module uses a monopolistic way of entry point (virtual filesystem) access model with the policy "one device = one node". The ROS node running over the libv4l2 API also queries the kernel about the intrinsic parameters of the camera and provides a flexible configuration model via the standard ROS configuration model. The camera is polled over the intervals of the desired framerate, then the images are decoded and published according to image_transport package specifications in sink-on-demand operating mode. Also, the dynamic_reconfigure specifications are partially supported to publish actual frame parameters.

Supported device access models

  • Memory Mapping - for the device with direct monopolistic USB port access model implemented via libusb

  • User Pointer Exchange - for the devices supporting userspace memory pointer requests

  • Virtual Block Device - for the devices supporting block I/O model via virtual userspace filesystem kernel driver

Published message types

Topic names abbreviation policy

The node formulates topic namespaces and affixes using the following policy:

  1. Node name taken from ROS launch server

  2. Transport suffix configured with camera_transport_suffix parameter

  3. image_transport mode suffix

  4. Description suffix provided from dynamic_reconfigure API

For example, if the node runs under the name usb_cam and camera_transport_suffix is set to image_raw (default invocation case), the node will publish the following list of topics:


Hardware-accelerated decoder

The support for a hardware-accelerated decoder in the package is now experimental. It is implemented in the dedicated branch in the repository. The feature is not enabled by default and it is supported only from libavcodec library version 52.00.100.


The names mentioned <in brackets> are actually the names of parameters configuring the really used names in the ROS system namespace. Thus, most of the names of topics and services mentioned here are configurable. Please see sample config file for reference.


Opens the V4L device handler to poll the camera, recompress and publish the images on demand

Published Topics

/<node_name>/camera_info (sensor_msgs/CameraInfo)
  • Camera calibration matrices from the specified calibration YAML file provided by the camera's vendor, or obtained with tools from camera_calibration package
/<node_name>/<camera_transport_suffix> (sensor_msgs/Image)
  • Uncompressed frames
/<node_name>/<camera_transport_suffix>/compressed (sensor_msgs/CompressedImage) /<node_name>/<camera_transport_suffix>/compressed/parameter_descriptions (dynamic_reconfigure/ConfigDescription) /<node_name>/<camera_transport_suffix>/compressed/parameter_updates (dynamic_reconfigure/Config) /<node_name>/<camera_transport_suffix>/compressedDepth (sensor_msgs/CompressedImage)
  • PNG-compressed 16-bit depth frames
/<node_name>/<camera_transport_suffix>/compressedDepth/parameter_descriptions (dynamic_reconfigure/ConfigDescription)
  • Latched topic providing compressed frame's parameter descriptions for depth_image_proc
/<node_name>/<camera_transport_suffix>/compressedDepth/parameter_updates (dynamic_reconfigure/Config)
  • Latched topic providing compressed frame's actual parameters for depth_image_proc
/<node_name>/<camera_transport_suffix>/theora (theora_image_transport/Packet) /<node_name>/<camera_transport_suffix>/theora/parameter_descriptions (dynamic_reconfigure/ConfigDescription) /<node_name>/<camera_transport_suffix>/theora/parameter_updates (dynamic_reconfigure/Config)


/<node_name>/<start_service_name> (std_srvs/Empty)
  • Call this service to start the suspended capture of frames from the device
/<node_name>/<stop_service_name> (std_srvs/Empty)
  • Call this service to stop the active capture of frames from the device
/<node_name>/supported_controls (std_srvs/Trigger)
  • Returns the "|"-separated string containing the list of intrinsic controls (parameters) the camera supports, queried from V4L kernel driver. In case of presence, the first "|" symbol should be ignored.
/<node_name>/supported_formats (std_srvs/Trigger)
  • Returns the "|"-separated string containing the list of image formats/encodings the camera supports, queried from V4L kernel driver. In case of presence, the first "|" symbol should be ignored.


start_service_name (string, default: start_capture)
  • Defines name suffix for std_srvs/Empty service which restarts suspended streaming
stop_service_name (string, default: stop_capture)
  • Defines name suffix for std_srvs/Empty service which suspends camera polling timer
video_device (string, default: /dev/video0)
  • Device driver's entry point in Linux kernel's virtual filesystem
io_method (string, default: mmap) pixel_format (string, default: yuyv)
  • Pixel format for Video4linux device (also selects decoder mode). See Pixel formats for value reference
color_format (string, default: yuv422p)
  • On-chip color representation mode for the input frame encoded by hardware. See Color formats for value reference
create_suspended (bool, default: false)
  • Instructs the node whether to start streaming immediately after launch or to wait until the <start_service_name> service will be triggered
full_ffmpeg_log (bool, default: false)
  • When set to false allows to suppress warning messages generated by libavcodec during MJPEG decoding, cleans log files
camera_name (string, default: head_camera) camera_frame_id (string, default: head_camera)
  • Frame ID used to generate coordinate transformations
camera_transport_suffix (string, default: image_raw) camera_info_url (string, default: "")
  • URI for camera calibration data (likely a YML file obtained from camera_calibration tools)
image_width (integer, default: 640)
  • Frame width in pixels, should be supported by hardware! Please refer to supported_formats service for list of possible values
image_height (integer, default: 480)
  • Frame height in pixels, should be supported by hardware! Please refer to supported_formats service for list of possible values
framerate (integer, default: 30)
  • Camera polling frequency, Hz (integer)
intrinsic_controls (multilist, default: refer to sample config file)

I/O modes reference

The node supports the following I/O mode names for the given device:

  • read - for devices supporting virtual filesystem or block I/O

  • mmap - for devices supporting direct libusb memory mapping

  • userptr - for DMA devices supporting userspace pointer exchange

Pixel formats/encodings reference

Selection of the pixel format name automatically selects the decoder library and pixel representation for FFMPEG/libavcodec processing. The node supports the following pixel format names and decoders (all names are case-sensitive):

  • yuyv - YUV420

  • yuv - synonym for yuyv

  • uyvy - UVY240, MESECAM

  • yuvmono10 - Monochrome 10-bit pseudo-YUV

  • rgb24 - Linear 8-bit RGB matrix

  • bgr24 - OpenCV-compatible 8-bit BGR

  • grey - Grayscale 8-bit linear monochrome matrix

  • yu12 - YU-reversed YUV420

  • mjpeg - FFMPEG-decoded MotionJPEG. Requires compatible hardware

  • h264 - FFMPEG-decoded H.264. Requires compatible hardware. May also require setting color_format parameter to yuv420p

NOTE: In its current state, the node does not support hardware-accelerated decoding!

Color representation formats reference

The node supports the following color representation mode names (case-sensitive):

  • yuv422p - YUV422 - default, compatible with most MJPEG hardware encoders

  • yuv420p - YUV420 - may be required by H.264 and H.265 hardware encoders

Intrinsic control configuration

The node queries V4L kernel driver for available intrinsic control names and data types they require, in the same way, that one can query from terminal with the following command:

v4l2-ctl --device=/dev/video<ID> -L

The node supports the following types of intrinsic controls provided by libv4l2:

  • Booleans (true/false)

  • Integers (32-bit)
  • Integers (64-bit)
  • Menus (integer-indexed sets of operating modes)
  • Integer/Menu multiparams (menus with manual adjustment possibility)

The data type for the given parameter is determined automatically.

The queried names become ROS parameters and are placed under intrinsic_controls multilist of the configuration file. Its main namespace contains:

  • Unique names of the generated ROS parameters. NOTE: if the parameter name reported from V4L kernel driver exists but not mentioned here, it will be processed and set up with default value, also provided by the driver.

  • ignore - the string list containing control names that should be ignored. If the existing intrinsic control is mentioned here, its value will be left intact.

Example configuration

This example configuration is obtained using Logitech HD Pro Webcam C920 web camera with standard V4L2 kernel driver from Ubuntu 22.04 with 5.15.0 kernel installed. The manually queried control names:

v4l2-ctl --device=/dev/video0 -L
                     brightness 0x00980900 (int)    : min=0 max=255 step=1 default=128 value=128
                       contrast 0x00980901 (int)    : min=0 max=255 step=1 default=128 value=128
                     saturation 0x00980902 (int)    : min=0 max=255 step=1 default=128 value=128
 white_balance_temperature_auto 0x0098090c (bool)   : default=1 value=1
                           gain 0x00980913 (int)    : min=0 max=255 step=1 default=0 value=155
           power_line_frequency 0x00980918 (menu)   : min=0 max=2 default=2 value=1 (50 Hz)
                                0: Disabled
                                1: 50 Hz
                                2: 60 Hz
      white_balance_temperature 0x0098091a (int)    : min=2000 max=6500 step=1 default=4000 value=5485 flags=inactive
                      sharpness 0x0098091b (int)    : min=0 max=255 step=1 default=128 value=128
         backlight_compensation 0x0098091c (int)    : min=0 max=1 step=1 default=0 value=0
                  exposure_auto 0x009a0901 (menu)   : min=0 max=3 default=3 value=3 (Aperture Priority Mode)
                                1: Manual Mode
                                3: Aperture Priority Mode
              exposure_absolute 0x009a0902 (int)    : min=3 max=2047 step=1 default=250 value=200 flags=inactive
         exposure_auto_priority 0x009a0903 (bool)   : default=0 value=1
                   pan_absolute 0x009a0908 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                  tilt_absolute 0x009a0909 (int)    : min=-36000 max=36000 step=3600 default=0 value=0
                 focus_absolute 0x009a090a (int)    : min=0 max=250 step=5 default=0 value=0 flags=inactive
                     focus_auto 0x009a090c (bool)   : default=1 value=1
                  zoom_absolute 0x009a090d (int)    : min=100 max=500 step=1 default=100 value=100

The corresponding YAML configuration multilist looks like:

    focus_auto: true
    exposure_auto_priority: true
    exposure_auto: 3
    white_balance_temperature_auto: true
    power_line_frequency: 1
    ignore: [

Here are the following intrinsic controls that are mentioned in the root namespace of the intrinsic_controls multilist, so they will be processed and set up:

  • focus_auto (boolean)

  • exposure_auto_priority (boolean)

  • exposure_auto (menu)

  • white_balance_temperature_auto (boolean)

  • power_line_frequency (menu)

All the other intrinsic control names reported by v4l2-ctl are enumerated in the ignore string list, so their values will be left intact.

Wiki: usb_cam (last edited 2023-06-08 16:45:28 by Andrey Vukolov)