feat(usb_host_uvc): support dual camera with hub (IEC-246)

[lijunru-hub]

Description

Feature:

1. Fixed the issue where connecting to the hub would automatically power it on.
2. Added a callback: When a USB camera device is inserted, notify the user with the VID, PID, and camera parameters.
3. Supported printing the complete USB descriptor for debugging when a new device is inserted.
4. Supported opening a specified device using usb_handle or dev_addr.

Related

Testing

---

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

[tore-espressif]

@lijunru-hub thank you very much for fixing this limitation.

The new open API with dev_addr looks good to me.

I left few comments for your consideration

[tore-espressif]

I'm not sure why we need to pass iface_num to the user... Do you have any example of usage?

[lijunru-hub]

I misunderstood the meaning of uvc_host_stream_config_t: uvc_stream_index. We should change iface_num to uvc_stream_index here.

If a camera supports multiple video streams, the callback will be called multiple times, with the uvc_stream_index being returned incrementally each time.

[tore-espressif]

If we do not pass iface_num to the user, this whole part can be removed, simplifying the code a lot. Do we really need it?

[lijunru-hub]

Some devices have multiple VS interfaces. I would like to notify the user about all the VS interfaces sequentially upon insertion, so that the user can open the interface they wish to use and retrieve all the supported resolutions for that VS uvc_stream_index .

[lijunru-hub]

@tore-espressif I added an API, uvc_desc_get_frame_list, to retrieve all supported resolutions within the VS interface and pass them to the user during the connection process.

[tore-espressif]

@lijunru-hub Thank you very much for this PR!

The API changes LGTM and the features are very useful. I have only one concern about memory allocation. Could you please fix it? You can contact me if anything is unclear

Thanks again!

[tore-espressif]

My main concern aligns with the issues flagged by the static analyzer: the use of dynamic memory allocation.

This violates the principle of ownership in dynamic memory management—if you allocate memory, it's your responsibility to ensure it is properly freed. Relying on others to manage memory you allocate can lead to resource leaks or undefined behavior. Consider revising this to avoid dynamic allocation or clearly define ownership and the lifecycle of the allocated memory.

[lijunru-hub]

This API needs to be designed to be called twice: the first call retrieves the list length, and after the user allocates sufficient memory, the second call fills the data.

[tore-espressif]

How about this:

1. the new device callback (uvc_host_driver_event_data_t) gives user number of frame formats.
2. In the callback, the user allocates the memory (array of uvc_host_frame_info_t) and passes pointer and size of this array to uvc_desc_get_frame_list, which fills the array
3. The user is responsible for freeing the memory when he is done

So it could look like this

typedef struct {
    enum uvc_host_driver_event type;      /**< Event type */
    union {
        struct {
            uint8_t dev_addr;             /**< Device address */
            uint8_t uvc_stream_index;     /**< Index of UVC function you want to use. Set to 0 to use first available UVC function */
            size_t frame_info_num;        /**< Number of frame information list */
        } device_connected;               /**< UVC_HOST_DEVICE_CONNECTED event */
    };
} uvc_host_driver_event_data_t;

// This is public API
esp_err_t uvc_desc_get_frame_list(
    uint8_t dev_addr;                  /**< Pass value from the callback */
    uint8_t uvc_stream_index;     /**< Pass value from the callback */ // TODO:Update these comments. This function can be also called from other places
    uvc_host_frame_info_t (*frame_info_list)[], // Pointer to array of uvc_host_frame_info_t
    size_t list_size // Size of the list - to avoid out-of-boundaries array access
);