feat: Add config_by_name hardware discovery factory to OpenCVConfig

[mRangh]

feat: Add config_by_name hardware discovery factory to OpenCVConfig

Description

This PR introduces a new factory method, config_by_name, to the OpenCVConfig dataclass. It allows developers to automatically discover and map the correct V4L2 video node index (e.g., /dev/video0) on Linux systems by searching for the camera's hardware name or USB bus path via v4l2-ctl. This addresses the common issue of camera indices swapping upon system reboots due to USB initialization race conditions, making camera configuration much more robust.

Pull Request Type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Build-related changes
• Documentation content changes
• Other (please describe):

Current Behavior

Currently, developers must manually assign a generic device_index (like 0 or 2) when setting up USB webcams. If a system has multiple cameras, or is rebooted, the OS USB initialization order is non-deterministic, frequently causing these indices to swap and breaking vision pipelines (e.g., swapping the front and back cameras on a robot).

Issue Number: N/A

New Behavior

• File Name 1 : nectar/vision/camera/config.py

Changes: Added the @classmethod config_by_name to the OpenCVConfig dataclass. The method safely executes v4l2-ctl --list-devices, parses the output blocks, and supports selecting specific camera instances or USB paths. It was designed using local argument capture to maintain full IDE type hints without repeating the dataclass signature parameters.

• File Name 2 : docs/vision/camera/README.md

Changes: Added a new section under "Configuration classes" detailing how to use OpenCVConfig.config_by_name. Included code examples and added a crucial warning about handling multiple identical cameras using physical USB bus paths or UDEV rules for production environments.

Does This Introduce a Breaking Change?

• Yes
• No

Impact and Migration Path

• Impact: N/A. The default OpenCVConfig constructor remains untouched and functions exactly as before. The new feature is entirely opt-in via the factory method.
• Migration Path: N/A.

Additional Information

Note: This feature relies on the v4l2-utils package being installed on the host Linux system. A fallback to index -1 is implemented in case the camera is not found or the package is missing.

[samuellimabraz]

The idea is right direction, usb indices move after reboot, so resolving by hardware name is useful.

It should not live on OpenCVConfig. That dataclass is the field list; this is device lookup. C920Cam._find_device_and_ctrl already parses v4l2-ctl --list-devices in the driver at start(). Fold this into one helper used by OpenCVCam and C920Cam when opening, not a second factory on the config.

few issues in the current method: the grep pipeline (shell=True) is weaker than the C920 parser; locals() writes the search string into CameraConfig.name; a miss sets device_index=-1 and only fails later in OpenCVCam.start.

i would suggest keep device_index as it is. Add optional device_name; if set, resolve at start(), not on the dataclss.

If the name matches more than one node, or none, raise and log the available names/paths. Do not take the first. Product name alone is ambiguous when two cameras are the same model; /dev/v4l/by-id/ and by-path/ are how pick one