Add a UVC extension project for Unix and Windows by tmittet · Pull Request #56 · tmittet/UsbDotNet

tmittet · 2025-09-01T14:38:36Z

An updated version of #49, the difference is mainly that standard control request has also been moved to the extensions project.

Original PR description:
This is a suggested template for how we can do USB device class specific extensions. Let me know what you think.

The idea is that the integrator can get access to an extension, simply by adding e.g. using LibUsbSharp.Extensions.Uvc; to their implementation. This pattern can be reused for future extensions and we can choose to put each (or very large) extensions in completely separate projects and thereby separate Nuget packages.

I think this keeps a clear separation between the core project and extensions.

Adds a new UsbDotNet.Extensions.Uvc project providing cross-platform USB Video Class (UVC) control support, along with integration tests.

New addtions last 30 days:

Extension methods (UsbDeviceExtension) - ControlReadUvc, ControlWriteUvc, and most importantly OpenUvcControl to access the platform-agnostic UVC API
IUvcControl interface; a platform-agnostic API for reading/writing UVC camera and image processing controls (brightness, contrast, exposure, white balance, zoom, etc.)
Linux/macOS implementation (UnixUvcControl) - uses libusb UVC control transfers directly
UVC descriptor parsing (UsbDeviceDescriptorExtension) to reads UVC unit/node descriptors from USB device configuration to resolve entity IDs automatically; mainly for the Unix implementation
Windows implementation (WindowsUvcControl) - uses DirectShow and Kernel Streaming via P/Invoke
Integration tests covering control reads/writes for camera and image processing controls against real USB video devices
CI build step added for the new extensions project

Design decisions:

IUvcControl returns UsbResult for soft errors instead of throwing exceptions, aligning with the existing UsbDotNet error handling pattern
Entity ID (unit/node) is resolved internally from descriptors - per the USB spec, duplicate GUIDs on an interface aren't possible, so callers don't need to provide entity IDs

pkhansen

I prefer this way of doing it as the sort of baseline for uvc control requests. I think there is room for more convenience, but that should be at a higher level anyway.
Tests are a-okay on mac

tmittet · 2025-09-04T08:12:38Z

I've addressed your comments @pkhansen and split this PR into: #59 and this draft PR.

We could merge this PR too, after adding e.g. if (OperatingSystem.IsWindows()) throw new SkipException("UVC control requests inaccessible on Windows.") to the UVC tests.

Copilot

Pull request overview

This PR adds scaffolding for a UVC (USB Video Class) extension project, enabling device class-specific functionality through extension methods. The extension allows developers to interact with UVC devices using simplified APIs by importing using UsbDotNet.Extensions.ControlTransfer.Uvc.

Changes:

Introduced ControlRequestUvc enum defining UVC-specific control request codes
Added extension methods ControlReadUvc and ControlWriteUvc for simplified UVC device communication
Created comprehensive test coverage for UVC control read/write operations

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
UsbDotNet.Extensions.Tests.csproj	Added project reference to UsbDotNet.Core to support test infrastructure
Given_a_video_class_USB_device_with_UVC.cs	Added test class with read/write tests for UVC brightness control
UsbDeviceExtension.cs	Implemented extension methods for UVC control transfers
ControlRequestUvc.cs	Defined enum of UVC control request codes with detailed documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

and ControlWrite -> ControlWriteUvc

and ControUvcWrite -> ControlWriteUvc

and fix issues uncovered by tests

it was poorly structured and hard to read

type, and move it to the root of the UVC extension project

The entityId is completely redundant. According to the USB spec, having multiple nodes/units with the same GUID on a USB interface is not possible. Hence, we can always resolve the unit/node ID internally.

and fix issues uncovered by tests

for all "soft" errors. This aligns UvcControls error handling with other extensions like ControlRead, ControlWrite, ControlReadUvc and ControlWriteUvc.

Type names should not be plural.

Most of the calls will never throw that exception.

for slightly improved performance during concurrent read

and improve docs

tmittet · 2026-04-27T08:52:19Z

Rebased on main and resolved conflicts

pkhansen previously approved these changes Sep 3, 2025

View reviewed changes

Comment thread src/LibUsbSharp.Extensions/ControlTransfer/Uvc/UsbDeviceExtension.cs Outdated

tmittet dismissed pkhansen’s stale review via 7b94699 September 4, 2025 08:01

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch from cceec5a to 7b94699 Compare September 4, 2025 08:01

tmittet changed the base branch from main to add_a_LibUsbSharp.Extensions_project_and_move_standard_control_request_implementation September 4, 2025 08:01

tmittet mentioned this pull request Sep 4, 2025

Control request refactor 2 #55

Closed

Base automatically changed from add_a_LibUsbSharp.Extensions_project_and_move_standard_control_request_implementation to main September 4, 2025 15:42

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch 2 times, most recently from 4986e0f to 7983a2f Compare January 19, 2026 13:00

Copilot AI review requested due to automatic review settings January 19, 2026 13:00

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Comment thread src/UsbDotNet.Extensions.Uvc/UsbDeviceExtension.cs Outdated

Comment thread src/UsbDotNet.Extensions.Uvc/UsbDeviceExtension.cs Outdated

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch from 7983a2f to e411c06 Compare January 19, 2026 15:12

tmittet force-pushed the main branch 3 times, most recently from 2b3dd7b to f967b1c Compare March 7, 2026 08:22

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch from e411c06 to de1b1db Compare March 11, 2026 06:40

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch from 9d98a82 to 89f3a5c Compare March 29, 2026 14:59

tmittet marked this pull request as ready for review March 29, 2026 15:01

tmittet changed the title ~~Add project and test scaffolding for an uvc extension 2~~ Add a UVC extension project for Unix and Windows Mar 29, 2026

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch 2 times, most recently from 1f4e0ac to 89b37d1 Compare April 13, 2026 19:07

tmittet added 9 commits April 27, 2026 10:37

Add support for UVC requests

5f310b7

UsbDeviceExtension.ControlRead -> ControlReadUvc

845d1b9

and ControlWrite -> ControlWriteUvc

Improve test names ControUvcRead -> ControlReadUvc

27213de

and ControUvcWrite -> ControlWriteUvc

Don't skip UVC write test on test setup read error

1c8db9c

Skip UVC tests on Windows OS

f7122cd

Fix conflicts: #69 Rename LibUsbSharp to UsbDotNet

86f3eac

First stab at a cross platform UVC implementation

57b32e1

Add tests to cover IUvcControls

7a74846

and fix issues uncovered by tests

Clean-up and refactor

939ba67

tmittet added 19 commits April 27, 2026 10:37

Simplify the claude generated UvcDescriptor code,

6f022c6

it was poorly structured and hard to read

Make UvcDescriptor a public IUsbDevice extension

cee50c3

type, and move it to the root of the UVC extension project

Remove overloads in IUvcControls with entityId.

5341fd0

The entityId is completely redundant. According to the USB spec, having multiple nodes/units with the same GUID on a USB interface is not possible. Hence, we can always resolve the unit/node ID internally.

Add extended unit integration tests

f9e2c54

and fix issues uncovered by tests

Add build step for all UsbDotNet.Extensions

64807eb

Improve code docs and variable naming

29e9c92

Improve error handling

562e408

Return UsbResult instead of throwing exceptions

0934dcc

for all "soft" errors. This aligns UvcControls error handling with other extensions like ControlRead, ControlWrite, ControlReadUvc and ControlWriteUvc.

Rename UvcControls types to UvcControl

342b2d3

Type names should not be plural.

Make LoggerFactory available in extension project

4b86aab

Remove redundant catch (COMException ex),

5b404bf

Most of the calls will never throw that exception.

Debug log when MapHResult maps an error

6c43564

Rename OpenUvcControls to OpenUvcControl

b426a49

Code clean-up

882ce5a

Fix redundant directShowObject release

ef11cee

Use ReaderWriterLockSlim to protect Dispose

f7eea45

for slightly improved performance during concurrent read

Make IMoniker pmkToLeft nullable instead of suppressing

6dd0070

Make SafeVideoDeviceHandle.Open overloads private

7d161a7

and improve docs

Align UsbResult documentation with main branch

48627c9

tmittet force-pushed the add_project_and_test_scaffolding_for_an_UVC_extension_2 branch from 89b37d1 to 48627c9 Compare April 27, 2026 08:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a UVC extension project for Unix and Windows#56

Add a UVC extension project for Unix and Windows#56
tmittet wants to merge 28 commits into
mainfrom
add_project_and_test_scaffolding_for_an_UVC_extension_2

tmittet commented Sep 1, 2025 •

edited

Loading

Uh oh!

pkhansen left a comment

Uh oh!

Uh oh!

tmittet commented Sep 4, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

tmittet commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tmittet commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkhansen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tmittet commented Sep 4, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

tmittet commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tmittet commented Sep 1, 2025 •

edited

Loading