UVC Controls - showmewebcam/showmewebcam Wiki

Camera controls exposed to the host

To control a USB video camera from the computer it is connected to, the USB Video Class (UVC) standard defines several sets of controls that a camera can declare to support. The computer can then command the camera via the UVC protocol.

Showmewebcam's default behaviour is to advertise all controls as available. The uvc-gadget program on the Pi then translates incoming control read or write requests to the V4L interface for the camera module attached to the Pi. The command chain is quite long, as you can see:

Therefore, there's unfortunately no direct mapping of the controls you can manipulate on your computer to what happens on the camera, although everybody involved along the chain is doing their best.

The default setup

Showmewebcam's default is to mark the following controls as exposed in the UVC descriptor (taken from uvc-gadget documentation on UVC controls):

Camera Controls (values 2, 0, 0):

bit value control
D1 2 Auto-Exposure Mode

Processing controls (values 255, 6):

Byte 1:

bit value control
D0 1 Brightness
D1 2 Contrast
D2 4 Hue
D3 8 Saturation
D4 16 Sharpness
D5 32 Gamma
D6 64 White Balance Temperature
D7 128 White Balance Component

Byte 2:

bit value control
D9 2 Gain
D10 4 Power Line Frequency

Creating a custom control definition

How to configure Showmewebcam

You can add the following parameters to cmdline.txt on the boot volume (either by mounting /boot read-write on the Pi, or after flashing while preparing the SD card on the computer) as follows:

usb_f_uvc.camera_terminal_controls=0,0,0 usb_f_uvc.processing_unit_controls=0,0

The previous example sets all controls to disabled, and should thus be safe. The parameters directly correspond to the bmControls bitfields in the descriptor, and are explained below. To compute a new value, you sum up the control bits' "value" column you want to enable.

Example 1:

For the default of usb_f_uvc.camera_terminal_controls=2,0,0 above, you sum only bit D1 (Auto-Exposure), i.e. 2 for byte 1, and leave the other bytes 0.

Example 2:

Say, you want to disable the Hue, White Balance controls. This gives you: usb_f_uvc.processing_unit_controls=59,6 (1+2+8+16+32=59, 2+4=6)

No adding nonexistent controls

Perhaps stating the obvious, you CANNOT add controls to the camera this way.

!!! Only controls properly mapped in V4L and uvc-gadget can possibly work. !!!

And even then, there's a good chance your control might not work due to camera and/or driver quirks.

Possible values for the kernel module parameters

source: USB Device Class Definition for Video Devices, Revision 1.1 Again shout-out to the uvc-gadget documentation on UVC controls

Available settings for camera_terminal_controls

This setting corresponds to the UVC_VC_INPUT_TERMINAL structure's bmControls field. It is a bitmap type. A bit set to 1 indicates that the mentioned Control is supported for the video stream.

Byte 1:

bit value control
D0 1 Scanning Mode
D1 2 Auto-Exposure Mode
D2 4 Auto-Exposure Priority
D3 8 Exposure Time (Absolute)
D4 16 Exposure Time (Relative)
D5 32 Focus (Absolute)
D6 64 Focus (Relative)
D7 128 Iris (Absolute)

Byte 2:

bit value control
D8 1 Iris (Relative)
D9 2 Zoom (Absolute)
D10 4 Zoom (Relative)
D11 8 PanTilt (Absolute)
D12 16 PanTilt (Relative)
D13 32 Roll (Absolute)
D14 64 Roll (Relative)
D15 128 Reserved

Byte 3:

bit value control
D16 1 Reserved
D17 2 Focus, Auto
D18 4 Privacy
D19..(n*8-1) ... Reserved, set to zero

Available settings for processing_unit_controls

This setting corresponds to the UVC_VC_PROCESSING_UNIT structure's bmControls field. It is a bitmap type. A bit set to 1 indicates that the mentioned Control is supported for the video stream.

Byte 1:

bit value control
D0 1 Brightness
D1 2 Contrast
D2 4 Hue
D3 8 Saturation
D4 16 Sharpness
D5 32 Gamma
D6 64 White Balance Temperature
D7 128 White Balance Component

Byte 2:

bit value control
D8 1 Backlight Compensation
D9 2 Gain
D10 4 Power Line Frequency
D11 8 Hue, Auto
D12 16 White Balance Temperature, Auto
D13 32 White Balance Component, Auto
D14 64 Digital Multiplier
D15 128 Digital Multiplier Limit

Byte 3: (NOT SUPPORTED BY KERNEL)

For reference only, the UVC descriptor for processing controls supports this third byte, which is not present in the kernel's uvc gadget implementation. As it is not relevant to webcam operation, no further work was undertaken to add support. To reiterate: The commandline flag usb_f_uvc.processing_unit_controls=<byte1>,<byte2> only takes two values!

bit value control
D16 1 Analog Video Standard
D17 2 Analog Video Lock Status
D18..(n*8-1) ... Reserved. Set to zero.