USB3 Vision camera has no V4L2 support: pick the acquisition path

Your program opens what it believes is the camera, calls VIDIOC_QUERYCAP, and gets 'not supported' back, while /dev/video0 never appears. The camera is fine and your code is fine: a USB3 Vision camera is not a USB video class (UVC) device, so Linux loads no V4L2 driver for it and never creates a video node to talk to. This guide gives you the lsusb commands that prove the device class in under a minute, explains why the ioctl can never succeed on this class of camera, and lays out the acquisition path that works: a GenICam consumer driven by the camera SDK's GenTL producer, or by the open-source Aravis library. It ends with a bandwidth worked example, so the first frame rate you promise is one the cable can keep.

The commands that settle it

Open a terminal on the Linux host the camera is plugged into and run:

lsusb          # note the VID:PID of the camera
lsusb -t       # USB tree: the driver bound to each interface

A UVC camera lists uvcvideo against its interfaces. A USB3 Vision camera lists a device with no video driver at all. Confirm the class explicitly, substituting the ID noted above:

lsusb -v -d VID:PID | grep -i bInterfaceClass

Decision: class 14 means V4L2 is the right API and the fault lives elsewhere in the video stack. Class 255 means the ioctl was never going to succeed, because there is no node for VIDIOC_QUERYCAP to reach. The fastest proof that your code is sound is to point the same program at any UVC webcam: the same handshake succeeds. If open() failed with 'no such file or directory', there was no node to open; if the node opened and VIDIOC_QUERYCAP returned ENOTTY, 'inappropriate ioctl for device', the handle was not a V4L2 device. Both answers are the expected result for a camera with no kernel driver.

Why VIDIOC_QUERYCAP can never succeed here

VIDIOC_QUERYCAP is the handshake every V4L2 program starts with: it asks the driver behind a /dev/video node for its name and capabilities. V4L2 is a kernel API, so a kernel driver has to be sitting on that node. For USB webcams it is uvcvideo, and uvcvideo binds only to devices that enumerate as USB video class. A USB3 Vision camera implements a different contract on purpose: the USB3 Vision standard defines its own control and streaming protocol over raw USB, served by a user-space library over usbfs (libusb is the common route), with GenICam as the control layer on top. No class match means no probe, no bind, no /dev/video node — and no driver on the other end of the handshake.

You will not find a V4L2 driver on the maker's download page for a USB3 Vision model; acquisition runs through the SDK the maker ships, or through a GenICam library. The same holds for GigE Vision cameras: no /dev/video node either. Which API a camera answers is decided by its receiver stack, not by its plug — the same principle that decides frame grabber SDK support.

The acquisition path that works: GenICam through GenTL

Every USB3 Vision camera exposes the same control model, GenICam, and most consumers reach it through GenTL. The moving parts:

1. Install the camera SDK and its GenTL producer — the .cti file it ships — from the maker or your distributor.
2. Point the consumer at that producer. The SDK's own viewer finds it by itself; your own code passes the path when it opens the GenTL.
3. Enumerate, then configure with GenICam features: PixelFormat, Width, Height, AcquisitionFrameRate. These are the standard's names, so the same calls drive any compliant camera.
4. Acquire into producer-managed buffers and hand each one to your processing code. If the consumer loads the .cti but sees no devices, run the GenTL enumeration validation. If settings come back wrong after a reboot, the fix is in the camera configuration after restart.

If you want one library across the fleet, Aravis is the open-source GenICam option: it implements the Gigabit Ethernet and USB3 transports, so one codebase drives GigE Vision and USB3 Vision cameras. You can read its source and release notes in its upstream project repository. The feature names are the same GenICam ones the SDKs expose, which is what lets a cross-language GenICam codebase hold cameras of every transport. Replacing an older proprietary API maps onto the same model in the legacy SDK to GenICam migration.

The class decides the API, not the part number: a 20 MP unit like the MV-CS200-10UM enumerates and streams through this exact path. The USB3 area scan cameras in the shop:

Where V4L2 does apply

V4L2 is not the wrong tool in general — it is the right tool for a different class of hardware. Kernel video drivers exist for UVC webcams, for capture cards, and for embedded boards whose sensor pipeline is wired to a platform interface; on those boards the vendor kernel driver wraps the sensor and its supplies into V4L2, with no GenICam layer anywhere. A UVC-class camera needs no proprietary driver at all, which is what makes it the natural pick on embedded boards (driver-free UVC on an embedded board).

So if a contract line reads 'must run under V4L2' or 'must open in OpenCV's VideoCapture', that is a camera-class decision, and it belongs before the order, not after. Read the interface line on the data sheet, then confirm on a sample unit with the lsusb commands above. Once the right node exists, ordinary Linux plumbing applies — node permissions, group membership and the rest of the video and media node permission checks. A UVC camera that creates no node at all has its own diagnosis path in identifying an undetected UVC camera.

Budget the link before you promise a frame rate

A USB 3.0 port signals at 5 Gbit/s. 8b/10b encoding leaves 4 Gbit/s, and packet overhead in a USB3 Vision stream leaves roughly 3.2 Gbit/s of usable payload. That figure is the budget every pixel format and frame rate has to fit.

Worked example, at the spec sheet numbers of the LS-CMR-0166: 4000 × 3000 at 30 fps over USB3. In Mono8, one byte per pixel: 4000 × 3000 × 1 B = 12,000,000 B ≈ 12 MB per frame. At 30 fps, 12 MB × 30 = 360 MB/s, and 360 MB/s × 8 = 2,880 Mbit/s ≈ 2.9 Gbit/s of payload. Under 3.2, with about 9 % headroom — the camera holds spec.

Switch the pixel format to Mono12 packed, 1.5 bytes per pixel: 4000 × 3000 × 1.5 B = 18 MB per frame; × 30 fps = 540 MB/s; × 8 = 4,320 Mbit/s ≈ 4.3 Gbit/s. Over budget — the link cannot carry it, so the frame rate ceiling lands at 30 fps × 3.2 / 4.3 ≈ 22 fps. Three ways out: stay in Mono8 and keep 30 fps; take 12-bit depth at roughly 22 fps; or crop the ROI to 4000 × 2000, which puts the payload back at 360 MB/s and 30 fps returns.

Commit like this: Mono8 when the algorithm works on 8 bits — full frame rate, no compromise. Mono12 packed only when the extra depth buys a real defect decision, paid for with ~22 fps or a 2,000-row ROI.

If you picked V4L2 for zero-copy and GPU direct memory access

V4L2's appeal is real: kernel-managed buffers that can be exported and shared, so frames reach a GPU consumer without a library copy. On this camera class that machinery does not exist, and the same question moves into the acquisition library: does the SDK's buffer API offer zero-copy access or exportable handles, and does the host controller's driver support that path? The classic mistake — treating the user-space pointer the SDK hands over as a device DMA address — is the same trap GigE users hit, worked through in the zero-copy pointer trick on GigE.

Measure before redesigning. Copying a 12 MB frame costs under a millisecond on a modern x86 core — 12 MB read plus 12 MB written is 24 MB of traffic, and memory bandwidth runs in the tens of GB/s — against a cycle time usually measured in tens of milliseconds. Decision: keep the camera, keep the SDK, and profile. Only if a measured profile shows the copy or the hand-off eating the budget does a camera-class change earn its cost.

When this is not your problem

• A node exists, but VIDIOC_QUERYCAP describes another device. Capture sticks and webcams all claim /dev/video numbers; enumerate with v4l2-ctl --list-devices and open the node that reports your camera. The two-handles-one-camera failure is worked through in VIDIOC_S_FMT busy with two nodes opening one camera.
• The node vanished mid-run. That is USB enumeration dropping under the acquisition, the territory of VIDIOC_DQBUF error 19 on USB camera drops.
• The acquisition runs inside a container. The node and its media devices must be passed into the container explicitly — see passing V4L2 media nodes to a camera in Docker.
• The node is busy at open. Something already holds the camera; the pattern and the fix are in the device-already-in-use error.
• The grep showed class 14 (UVC). Then V4L2 is the right API after all, and the checks in the section above are your path.

More acquisition-path diagnoses sit on the systems topic page.

Checklist before you order

• Write the transport into the requirement. 'USB3' on a machine-vision camera means the GenICam path; only 'UVC' or 'USB video class' promises V4L2. One word in the spec prevents the rewrite this page describes.
• Run the lsusb class check on a sample unit before the software design locks. Five minutes on the bench beats a week rewriting acquisition code.
• Budget the pixel format and frame rate against 3.2 Gbit/s with the formula above before signing a cycle time.
• Size the host around ports first. A bench of USB3 cameras beside GigE cameras and lighting fits comfortably on a controller with 2 USB 3 ports, 3-4 LAN ports, 4 built-in light channels and 8 GB of memory:

• Name the consumer in the design document: SDK GenTL producer or Aravis for Vision-class cameras, V4L2 code only for UVC units. The grep on lsusb output then becomes your acceptance test.

To turn the decision into parts, start at the area scan cameras category or the camera finder, then pick the host in the vision controllers category, filtering by LAN and USB 3 port counts. If the class check surprises you, send the lsusb output through the contact page and we will read it with you.