I have a Logitech QuickCam Orbit/Sphere MP. Why don't the pan/tilt buttons in luvcview work?

The short version:

There are different versions of the driver and different versions of luvcview that don't always work together because at some point the IDs of the corresponding V4L2 controls changed.

The long version: (adapted from a post to linux-uvc-devel by Laurent Pinchart, author of the UVC driver)

Applications have several ways to interact with V4L2 devices. One of those is called the controls API. A control is usually any parameter that doesn't directly influence streaming: brightness, contrast, autofocus, zoom, pan, tilt, etc. User-space applications can read (get) or write (set) the value of any control the device supports at any time.

The QuickCam Orbit/Sphere MP has a single pan/tilt control. Writing a new value makes the webcam perform a pan motion (if the tilt value is zero), a tilt motion (if the pan value is zero), or a combined pan/tilt motion (if no value is zero).

The straightforward approach was to implement a pan control and a tilt control. Setting the pan control would pan the webcam, setting the tilt control would tilt it, but they was no way to pan and tilt the webcam in a single motion.

V4L2 only supported setting a single control at once, with the control value being a 32 bits integer. As there was no way to set both, the pan and tilt controls, in a single operation, I decided to hack around the limit and create a single pan/tilt control. The 32 bit value was split in two 16 bits numbers, controlling pan and tilt. The pan/tilt controls were defined as

#define V4L2_CID_PANTILT_RELATIVE   (V4L2_CID_PRIVATE_BASE+7)
#define V4L2_CID_PANTILT_RESET      (V4L2_CID_PRIVATE_BASE+8)

and the 32 bit value was assigned using the following union:

union pantilt {
        struct {
                short pan;
                short tilt;
        } s16;
        int value;
} pantilt;

Check the v4L2UpDownPan() and v4L2UpDownTilt() functions in luvcview (file v4l2uvc.c) to see how V4L2_CID_PANTILT_RELATIVE was used.

The control API has recently been enhanced with the extended control API (note: "extended" refers to the API, not the controls). This new API offers a way to set several controls at once, so the Linux UVC driver has been modified (in the split branch) to remove the V4L2_CID_PANTILT_RELATIVE control and introduce two new controls defined as

#define V4L2_CID_PAN_RELATIVE    (V4L2_CID_PRIVATE_BASE+7)
#define V4L2_CID_TILT_RELATIVE   (V4L2_CID_PRIVATE_BASE+8)
#define V4L2_CID_PANTILT_RESET   (V4L2_CID_PRIVATE_BASE+9)

to control pan and tilt, respectively. The control values are signed numbers expressed in 1/64th degrees.

luvcview (up until 20060920) still controls pan and tilt separately, and it does so using the old CID definitions. As a result, the camera receives wrong values. For example, if luvcview wants to pan by 10 degrees, it will send a value of 10*64<<16 to control ID 7 (V4L2_CID_PANTILT_RELATIVE) but the split UVC driver will interpret this as a pan value of 10*64<<16 instead of 10*64.

The fix:

Laurent Pinchart is currently preparing to submit a patch containing these new controls to the V4L2 developers. Once they are part of the official V4L2, the IDs for these custom controls will disappear from both the UVC driver and luvcview and everything will be back to normal.

In the meantime, feel free to patch luvcview and send it to the author.