How-to Recipes

The recipes in this section provide step-by-step instructions for common tasks when working with libusb-uvc. Each example builds on the core API documented elsewhere.

USB Gadget Testing on Debian

Run Unit Tests

Install the project in editable mode (or ensure pytest is available):
```
python3 -m pip install -e .[tests]
```

Execute the emulator-backed unit suite:

python3 -m pytest tests/test_controls.py tests/test_streaming.py

tests/test_integration.py contains hardware-dependent cases tagged with @pytest.mark.integration. They are skipped by default. When you have a compatible UVC device connected, run them explicitly:

python3 -m pytest -m integration tests/test_integration.py

USB Gadget Integration Tests

For full end-to-end coverage, configure a virtual camera via FunctionFS and the dummy_hcd module. Detailed Debian instructions live in USB Gadget Testing on Debian. Once the gadget is present, enable the tests by exporting LIBUSB_UVC_ENABLE_GADGET_TESTS=1 and run python -m pytest tests/test_integration.py.

Disable Auto Exposure

Open the camera with libusb_uvc.UVCCamera.open().
Enumerate controls via libusb_uvc.UVCCamera.enumerate_controls().
Look for Auto Exposure Mode or similar, then call libusb_uvc.UVCCamera.set_control() with value 1 (manual mode).
```
auto = cam.get_control("Auto Exposure Mode")
cam.set_control(auto, 1)
```
Adjust Exposure Time, Absolute as needed.

Sweep Exposure While Streaming

Disable auto exposure (as above).
Build a list of exposure values between minimum and maximum gathered from the control metadata.
Start a stream and update the control inside the frame loop.

Refer to examples/exposure_sweep.py for a complete implementation.

Toggle an Indicator LED

Some cameras provide LED control via extension units. Use the control manager to locate relevant selectors:

for control in cam.enumerate_controls(refresh=True):
    if "led" in control.name.lower():
        cam.set_control(control, 0)

Graceful Shutdown

Always use the context manager on libusb_uvc.UVCCamera. When the with block exits, the library stops streaming, resets the device if required, and reattaches kernel drivers so V4L2 clients can resume without manual intervention.

Next Steps

Browse Example Scripts to see the recipes applied in full scripts.
Dive into API Reference for low-level control helpers and asynchronous streaming primitives.