Skip to main content

​
uvcCamSuspend()

Suspends USB camera streaming. Use this to temporarily stop video streaming without disconnecting the camera.

​
Signature

void uvcCamSuspend(void *ctrl_value);

​
Parameters

​
ctrl_value
void*
required
Control value for suspend operation. Pass NULL for default behavior.

​
Example

// Suspend camera streaming
USBStream.uvcCamSuspend(NULL);
Serial.println("Camera streaming suspended");

​
uvcCamResume()

Resumes USB camera streaming after it has been suspended.

​
Signature

void uvcCamResume(void *ctrl_value);

​
Parameters

​
ctrl_value
void*
required
Control value for resume operation. Pass NULL for default behavior.

​
Example

// Resume camera streaming
USBStream.uvcCamResume(NULL);
Serial.println("Camera streaming resumed");

​
uvcCamGetFrameSize()

Retrieves the frame size list of the currently connected camera. This provides information about all supported frame resolutions.

​
Signature

uvc_frame_size_t *uvcCamGetFrameSize(uvc_frame_size_t *frame_size);

​
Parameters

​
frame_size
uvc_frame_size_t*
required
Pointer to a uvc_frame_size_t structure that will be populated with the frame size list.

​
Returns

Pointer to the frame size structure containing the list of supported resolutions.

​
Example

uvc_frame_size_t frameSize;
uvc_frame_size_t *result = USBStream.uvcCamGetFrameSize(&frameSize);

if (result != NULL) {
    Serial.println("Successfully retrieved frame size information");
    // Process frame size data
} else {
    Serial.println("Failed to get frame size");
}

​
uvcCamGetFrameListSize()

Retrieves the frame list size and current frame index of the connected camera.

​
Signature

void uvcCamGetFrameListSize(size_t *frame_size, size_t *frame_index);

​
Parameters

​
frame_size
size_t*
required
Pointer to a variable that will receive the total number of frames in the list.
​
frame_index
size_t*
required
Pointer to a variable that will receive the current frame index.

​
Example

size_t frameListSize = 0;
size_t currentFrameIndex = 0;

USBStream.uvcCamGetFrameListSize(&frameListSize, &currentFrameIndex);

Serial.print("Frame list size: ");
Serial.println(frameListSize);
Serial.print("Current frame index: ");
Serial.println(currentFrameIndex);

​
uvcCamFrameReset()

Resets the expected frame size and frame interval. This allows dynamic reconfiguration of video parameters.
This function should only be called when UVC streaming is in a suspended state. The new configuration will take effect after streaming resumes.

​
Signature

void uvcCamFrameReset(uint16_t frame_width, uint16_t frame_height, uint32_t frame_interval);

​
Parameters

​
frame_width
uint16_t
required
New frame width in pixels. Use FRAME_RESOLUTION_ANY to accept any width. Set to 0 (along with height) to keep current resolution.
​
frame_height
uint16_t
required
New frame height in pixels. Use FRAME_RESOLUTION_ANY to accept any height. Set to 0 (along with width) to keep current resolution.
​
frame_interval
uint32_t
required
New frame interval in 100-nanosecond units. Set to 0 to keep current frame interval. Use constants like FRAME_INTERVAL_FPS_15 or calculate with FPS2INTERVAL(fps).

​
Example

// Change resolution to 640x480 at 20 FPS
USBStream.uvcCamSuspend(NULL);
USBStream.uvcCamFrameReset(640, 480, FRAME_INTERVAL_FPS_20);
USBStream.uvcCamResume(NULL);
Serial.println("Resolution changed to 640x480 @ 20 FPS");

​
Complete Examples

​
Suspend and Resume Streaming

void pauseStreamingForProcessing() {
    // Suspend camera streaming
    USBStream.uvcCamSuspend(NULL);
    Serial.println("Camera paused");
    
    // Perform heavy processing
    performImageProcessing();
    
    // Resume streaming
    USBStream.uvcCamResume(NULL);
    Serial.println("Camera resumed");
}

​
Dynamic Resolution Change

void changeResolution(uint16_t width, uint16_t height, uint32_t fps) {
    // Must suspend before changing frame parameters
    USBStream.uvcCamSuspend(NULL);
    
    // Calculate frame interval from FPS
    uint32_t interval = FPS2INTERVAL(fps);
    
    // Reset frame configuration
    USBStream.uvcCamFrameReset(width, height, interval);
    
    // Resume with new settings
    USBStream.uvcCamResume(NULL);
    
    Serial.printf("Resolution changed to %dx%d @ %d FPS\n", width, height, fps);
}

void setup() {
    Serial.begin(115200);
    // Initial configuration...
    
    // Later change to high resolution
    changeResolution(640, 480, 15);
}

​
Change Only Frame Rate

void changeFrameRate(uint32_t fps) {
    USBStream.uvcCamSuspend(NULL);
    
    // Keep resolution (both width and height = 0)
    // Only change frame interval
    USBStream.uvcCamFrameReset(0, 0, FPS2INTERVAL(fps));
    
    USBStream.uvcCamResume(NULL);
    
    Serial.printf("Frame rate changed to %d FPS\n", fps);
}

void loop() {
    static unsigned long lastChange = 0;
    
    // Switch between 15 and 30 FPS every 10 seconds
    if (millis() - lastChange > 10000) {
        static bool highFps = false;
        highFps = !highFps;
        changeFrameRate(highFps ? 25 : 15);
        lastChange = millis();
    }
}

​
Query Camera Capabilities

void queryCameraInfo() {
    size_t frameListSize = 0;
    size_t currentIndex = 0;
    
    // Get frame list information
    USBStream.uvcCamGetFrameListSize(&frameListSize, &currentIndex);
    
    Serial.println("=== Camera Information ===");
    Serial.printf("Supported frame formats: %d\n", frameListSize);
    Serial.printf("Current frame index: %d\n", currentIndex);
    
    // Get detailed frame size info
    uvc_frame_size_t frameSize;
    if (USBStream.uvcCamGetFrameSize(&frameSize) != NULL) {
        Serial.println("Frame size information retrieved successfully");
    }
}

void setup() {
    Serial.begin(115200);
    
    // Wait for camera to be ready
    delay(2000);
    
    // Query camera capabilities
    queryCameraInfo();
}

​
Adaptive Resolution Based on Conditions

float batteryLevel = 0.0;
bool isLowPower = false;

void adaptiveResolution() {
    batteryLevel = readBatteryLevel(); // Your battery reading function
    
    if (batteryLevel < 20.0 && !isLowPower) {
        // Switch to low power mode: lower resolution and frame rate
        Serial.println("Low battery - reducing quality");
        
        USBStream.uvcCamSuspend(NULL);
        USBStream.uvcCamFrameReset(320, 240, FRAME_INTERVAL_FPS_10);
        USBStream.uvcCamResume(NULL);
        
        isLowPower = true;
        
    } else if (batteryLevel > 50.0 && isLowPower) {
        // Switch back to normal mode
        Serial.println("Battery restored - increasing quality");
        
        USBStream.uvcCamSuspend(NULL);
        USBStream.uvcCamFrameReset(640, 480, FRAME_INTERVAL_FPS_15);
        USBStream.uvcCamResume(NULL);
        
        isLowPower = false;
    }
}

void loop() {
    static unsigned long lastCheck = 0;
    
    // Check battery every 5 seconds
    if (millis() - lastCheck > 5000) {
        adaptiveResolution();
        lastCheck = millis();
    }
}

​
Notes

Always suspend streaming before calling uvcCamFrameReset(). Attempting to change frame parameters while streaming is active may cause undefined behavior.
Setting both frame_width and frame_height to 0 in uvcCamFrameReset() keeps the current resolution unchanged while allowing you to modify only the frame interval.
After calling uvcCamFrameReset(), ensure your buffers are large enough for the new frame size. Buffer sizes are set during initial configuration and are not automatically adjusted.

Build docs developers (and LLMs) love

Get started for freeTalk to us