A multi-sensor camera can expose several Linux device nodes, but those nodes do not necessarily represent interchangeable video streams. One may deliver color, another infrared, and another metadata rather than image pixels. A camera index that worked on another operating system may therefore select something different on Linux.
This procedure helps you identify the color capture endpoint, verify its supported configuration, and select it reliably after reconnects. Establish the stream identity before treating a dark image as an exposure problem.
Establish a clean test environment
You need access to the camera, the Linux video-device utilities, and an application that can display a supported capture format. Obtain camera-specific software and documentation only from the manufacturer or an authorized distributor.
Close other capture applications before testing. A device-busy error means another process may own the stream; it does not establish that you selected the wrong sensor.
Record the operating system, kernel, connection topology, and camera firmware version. Keep the camera on the same port while identifying its endpoints, and change only one variable between tests.
This procedure applies when the driver exposes V4L2 capture nodes. Some cameras require a dedicated SDK or another transport instead. If your software cannot enumerate the device at all, follow the separate camera SDK discovery checks.
Map candidate endpoints to capabilities
- List the video devices and their associated nodes:
v4l2-ctl --list-devices
Record every node associated with the physical camera. A single device name can have several entries, and neighboring numbers do not guarantee a particular sensor order.
- Inspect each candidate node individually:
v4l2-ctl --device=/dev/video4 --all
v4l2-ctl --device=/dev/video4 --list-formats-ext
udevadm info --query=property --name=/dev/video4
Here, /dev/video4 is an illustrative candidate, not a prescribed RGB endpoint. Substitute each node from your actual inventory.
Look for these distinctions:
| Reported capability or behavior | What it tells you | Next action |
|---|---|---|
| Video capture capability | The node can provide image buffers | Inspect formats and frame intervals |
| Metadata capture without image capture | The node provides auxiliary records | Do not open it as an ordinary image stream |
| Streaming capability | The driver supports a streaming I/O method | Test a supported capture configuration |
| Permission denied | Access failed before stream identity was verified | Check account permissions and device rules |
| Device busy | Another process may hold the endpoint | Close that process before repeating the test |
Where the report includes both overall capabilities and per-node device capabilities, use the per-node information to classify that endpoint.
Do not solve access errors by running the production application with unrestricted privileges. The Linux video and media node permission checks explain how to separate device access from stream-selection problems.
Prove which endpoint carries color
- Choose an image-capture node and a format that it explicitly advertises. Record the pixel format, image dimensions, and frame interval together.
Formats such as YUYV and MJPG commonly carry color images, but a format name alone does not prove sensor identity. Conversely, a monochrome-looking display does not establish that you opened an infrared sensor: the application might have converted color to grayscale.
Use a stationary scene containing clearly different colors, a textured object, and a shaded area. Display the candidate stream with decoding appropriate to its negotiated format. Compare the image against the expected viewpoint and the manufacturer's documented stream descriptions.
An infrared stream may show projected texture that is absent from the color image. Treat this as supporting evidence, not a universal identification rule.
For a transport test, the following example is valid only if the node advertises YUYV at the requested dimensions and frame rate:
v4l2-ctl --device=/dev/video4 \
--set-fmt-video=width=640,height=480,pixelformat=YUYV \
--set-parm=30 \
--stream-mmap --stream-count=30 --stream-to=/dev/null
This checks buffer delivery without saving images. It does not verify correct colors, exposure, or application decoding. Some drivers require another supported I/O method.
The approximate uncompressed payload for that example is:
That estimate excludes protocol overhead and other streams. Compressed payloads depend on scene content and compression settings. If your intended profile cannot sustain its requested rate, consult the pixel-format and exposure frame-rate checks.
Select a persistent path without renumbering devices
- Once you have verified the color endpoint, inspect the available persistent links:
ls -l /dev/v4l/by-id/
ls -l /dev/v4l/by-path/
Either directory may be absent, and not every driver creates useful links. Resolve each candidate link to confirm that it currently targets the endpoint you tested.
Choose the identity mechanism according to the deployment:
| Selection method | Useful when | Limitation |
|---|---|---|
| Numeric camera index | Performing a temporary diagnostic | Enumeration and backend behavior can change |
Direct /dev/videoN path |
Testing a known endpoint during one session | Numbering may change after reconnecting |
/dev/v4l/by-id/ link |
The device exposes a suitable unique identity | Similar endpoints still need individual verification |
/dev/v4l/by-path/ link |
Physical port location defines the station role | Moving the connection changes the path |
| Custom udev symlink | Existing links cannot identify the required interface | Matching attributes must distinguish the unit and endpoint |
A persistent link can consistently select the wrong stream. An interface suffix or endpoint index in its name is not proof that it represents color.
For a custom udev rule, match attributes observed on your hardware and create a descriptive symlink. Do not attempt to force the kernel to assign your preferred video number. Matching only a shared device identifier is insufficient when several identical cameras are connected.
Use the multiple-camera device-path checks when several units or repeated device identities complicate the mapping.
Open the verified stream in your application
- Configure the application with the verified persistent path and an explicitly selected capture backend, where its API supports both.
A string containing a device path is not equivalent to an integer camera index. Some libraries interpret strings as filenames or URLs unless the intended backend is selected. Confirm the behavior documented for your installed library version.
Set the requested pixel format, dimensions, and frame rate before processing frames. Then read back the negotiated values: a successful setter call does not necessarily mean the driver accepted the requested configuration unchanged.
Log the following at startup:
- Configured path and resolved device node.
- Physical-device identity and relevant interface attributes.
- Selected capture backend.
- Requested and negotiated capture profiles.
- First valid frame dimensions, channel count, and timestamp when available.
Match decoding to the actual payload. Compressed frames need decoding; packed color formats need their corresponding conversion. Depth samples must not be interpreted as ordinary color pixels.
If a diagnostic viewer works but your application does not, compare these records before changing exposure. Differences in backend, pixel format, or buffer handling are more useful evidence than trying successive camera indices.
Verify selection before diagnosing exposure
- Reconnect the camera and restart the application. Confirm that the persistent selection still resolves to the verified color endpoint.
Repeat the test after a host restart. If the station includes other cameras, reconnect them in a different order and confirm that the selected physical unit and interface remain correct.
Use this sequence to classify the remaining symptom:
| Symptom after opening | First test | Likely next branch |
|---|---|---|
| No frames arrive | Check capture capability, access, and ownership | Endpoint or acquisition configuration |
| Frames have unexpected dimensions | Read back the negotiated profile | Backend negotiation or fallback |
| Image is monochrome or textured | Verify sensor identity and decoding | Wrong endpoint or conversion |
| Correct scene appears but remains dark | Confirm exposure controls belong to that stream | Exposure, illumination, or control support |
| Only initial frames are dark | Compare early and later frames | Startup settling or lighting timing |
A successful buffer read proves delivery, not correct sensor selection. Likewise, a nonempty image can still be decoded with the wrong pixel interpretation.
Once endpoint identity and decoding are established, use the first-frame darkness checks for startup brightness problems. If controls appear to change but the image does not, verify exposure and gain metadata where the device exposes it.
If an expected sensor never appears in the inventory, that is a different branch. The missing stereo sensor checks address incomplete multi-sensor enumeration.
Check interface requirements before replacing hardware
Replacing a camera will not automatically fix ambiguous endpoint selection. First decide whether the task requires ordinary color images, depth measurements, or both.
For a standalone color acquisition path, compare area scan cameras through the camera finder. The MV-CH120-11UC is cataloged as a color USB3 area scan camera.
- Sensor format
- 1.1"
- Lens mount
- C-mount
- Interface
- USB3
- Resolution
- 12 MP
For depth acquisition, review 3D sensors against the required measurement task. The MV-DT01WMU is cataloged as a depth / ToF camera.
- Type
- Depth / ToF camera
These listings identify different acquisition categories; they do not establish Linux support, V4L2 compatibility, or a shared color-and-depth workflow. Before ordering, confirm the supported operating system, processor architecture, SDK, capture interface, and required stream combination through official documentation.
For depth systems, also check the working-distance and positioning requirements. Correct software selection cannot compensate for unsuitable measurement geometry.
Acceptance checklist and next step
Before releasing the configuration, check that:
- The selected node advertises image capture rather than metadata alone.
- A displayed test scene confirms the intended color endpoint.
- The application reports the expected negotiated profile.
- The persistent identity selects both the correct unit and interface.
- Reconnects, restarts, and changed connection order preserve selection.
- Device access uses appropriate permissions rather than unrestricted execution.
- Failure to resolve the configured identity stops acquisition instead of silently choosing another camera.
Keep the verified mapping with the station configuration. Avoid silently falling back to the first available camera: a plausible image from the wrong endpoint can be harder to detect than an explicit startup failure.
Use the camera configurator when selecting a new acquisition path, or contact applications support with the capability report, format list, and negotiated profile when the endpoint remains uncertain.
The configurator matches a camera, lens, light, light controller and cables to each other, step by step, and lists only parts that fit what you already picked.
Questions
Why does the same camera index select a different stream on Linux?
Device numbers reflect enumeration, not a guaranteed sensor order. Connected hardware, drivers, and capture backends can expose endpoints differently. Identify the physical camera and capture interface from their capabilities and a test image, then store a verified persistent path rather than assuming an index identifies color.
Does every device node associated with a camera provide an image?
No. Multi-sensor devices may expose separate image and metadata interfaces, and some streams require a dedicated SDK. Inspect each node's effective capabilities and advertised formats. An endpoint that supplies metadata or depth data is not interchangeable with a conventional color capture endpoint.
Should I select a camera through by-id or by-path?
Use a by-id link when it uniquely identifies the required camera and interface, particularly if the device may move between ports. Use by-path when the physical connection defines the station role. In either case, verify the target stream and test reconnect behavior before deployment.
Should I change exposure immediately when the selected stream looks dark?
A dark image can result from selecting the wrong sensor, interpreting the payload incorrectly, or applying unsuitable capture settings. Confirm the endpoint, negotiated format, and displayed scene first. Once those checks pass, investigate exposure controls, illumination, and startup settling for the selected stream.